Skip to main content

config 섹션 레퍼런스

.moai/config/sections/ 의 주요 설정 파일(handoff/delegation/llm/statusline/security/workflow/crosssession) 키 레퍼런스.

업데이트 2026-10-27 11분 분량 GitHub에서 수정 ↗

MoAI-ADK의 프로젝트 설정은 .moai/config/sections/ 아래 여러 YAML 파일로 나뉘어 있습니다. settings.json 가이드가 Claude Code 런타임 설정을 다룬다면, 이 페이지는 MoAI-ADK 자체 동작을 제어하는 주요 섹션 파일의 키를 정리합니다.

정보
한 줄 요약: settings.json은 Claude Code에게 무엇을 허용할지 정하고, .moai/config/sections/*.yaml은 MoAI-ADK가 어떻게 오케스트레이션할지 정합니다.

handoff.yaml — auto-resume 핸드오프

세션 경계에서 저장된 핸드오프를 어떻게 처리할지 제어합니다.

yaml
handoff:
    mode: manual   # manual | auto
    guide: false
키값설명
modemanual (기본)저장된 핸드오프를 자동 주입하지 않음 (opt-in 베이스라인 UX)
modeauto/clear 시 저장된 핸드오프를 세션 컨텍스트로 주입한 뒤 audit-trail 복사본으로 이동
guidefalse (기본)true면 /clear가 아닌 세션 시작(startup/resume/compact)에서 대기 중인 핸드오프가 있다는 best-effort stderr 힌트를 띄움. 알림일 뿐 세션을 막지는 않음

관련: 자율 연속 루프, moai handoff.

delegation.yaml — 에이전트 라우팅 SSOT

/moai 서브커맨드마다 기본으로 쓸 스킬과 에이전트를 배정한 맵입니다. 오케스트레이터는 실행 계획을 짤 때(Analyze-First) 이 맵을 읽고 어떤 에이전트를 spawn할지, 어떤 스킬을 주입할지 정합니다.

yaml
delegation:
    version: 1
    learning:
        observe: routing-ledger
        propose_via: harness-tier-ladder
        auto_apply: false          # Tier-4 게이트 — 사용자 승인 필요
    subcommands:
        plan:
            agents: [manager-spec, plan-auditor, Explore]
            skills: [moai-workflow-spec, moai-foundation-thinking]
        # run / sync / project / fix / loop / ...
    domain_skills:
        backend:  [moai-ref-api-patterns, moai-domain-backend]
        security: [moai-ref-owasp-checklist, moai-ref-llm-security, ...]
    agents:
        manager-spec: [moai-workflow-spec, moai-foundation-thinking]
블록설명
learning라우팅 사용 내역을 append-only 원장(.moai/state/routing-ledger.jsonl, opt-in·fail-open)에 남기고, 하네스 학습 서브시스템이 4-tier 제안 사다리로 갱신을 제안. auto_apply: false — Tier-4 변경은 AskUserQuestion 사용자 승인 필요
subcommands서브커맨드마다 agents(spawn할 13개 retained 에이전트) + skills(spawn 시 주입할 workflow 스킬). 하나도 배정하지 않아도 유효 (오케스트레이터가 직접 실행)
domain_skills미션 도메인에 맞춰 주입할 스킬 (spawn당 0-3개). 도메인 신호와 매칭
agents에이전트마다 두는 conditional 스킬 (트리거가 발생하면 on-demand 로드)

관련: 에이전트 가이드, 스킬 가이드.

llm.yaml — 백엔드·GLM 매핑

하네스 백엔드, GLM 환경, GLM 모델 매핑을 정의합니다. 에이전트가 실행되는 모델과 effort는 세션 수준에서 정해집니다 — 서브에이전트는 메인 세션의 모델과 추론 깊이를 그대로 따르므로, 이 파일이 에이전트별 모델 배정을 담는 일은 없어졌습니다. 예전의 프로필 매트릭스 키들(profile, profiles, performance_tier, harness_agents, agent_overrides)은 물러났으며, moai update가 다음 실행 때 사용자 파일에서 이 키들을 걷어 냅니다. 메인 세션의 추론 강도는 선호 프로필 (moai profile setup)에서 옵니다 — 이 파일에서 오지 않습니다.

yaml
llm:
  harness: "claude"            # claude | gpt | both — 초기화 때 고른 에이전트 하네스
  team_mode: ""                # glm이면 z.ai 백엔드로 전환
  glm_env_var: "GLM_API_KEY"
  glm:
    base_url: "https://api.z.ai/api/anthropic"
    models:
      high: "glm-5.3-flash"   # 1M context — Opus 슬롯
      medium: "glm-5.3-flash" # 1M context   — Sonnet 슬롯
      low: "glm-5.3-flash"    # 1M context   — 경량 슬롯
      fable: "glm-5.3-flash"
키설명
harness초기화 때 배포한 에이전트 하네스 (claude 기본값, gpt는 Codex 전용 배포)
team_mode비어 있으면 Claude, glm이면 세션을 z.ai 백엔드로 보냅니다
claude_binClaude Code 바이너리 고정 핀 (선택; 환경변수 MOAI_CLAUDE_BIN이 실행별로 우선)
glm.base_urlZ.AI Anthropic 호환 프록시 엔드포인트
glm.models슬롯별 GLM 모델 매핑. GLM은 Claude의 5단계 effort를 3개 reasoning 상태(thinking-off / reasoning-high / reasoning-max)로 collapse

관련: 프로필 매트릭스, 3-티어 에이전트 아키텍처.

statusline.yaml — 상태 표시줄

statusline 테마, github 세그먼트가 셀 호스팅 서비스, 그리고 16개 세그먼트 토글을 제어합니다.

yaml
statusline:
  theme: "catppuccin-mocha"   # catppuccin-mocha | catppuccin-latte
  # forge: gitlab             # github | gitlab | none (미지정이면 origin 호스트로 판별)
  segments:
    model: true
    context: true
    # ... 총 16개 세그먼트 (모두 기본 on)
    task: true
    pr: true
키설명
theme테마는 딱 두 개: catppuccin-mocha(기본) 또는 catppuccin-latte
forgegithub · gitlab · none 중 하나. github 세그먼트가 열린 작업을 어느 호스팅 서비스에서 세는지 정합니다. 값을 비워 두면 origin 원격의 호스트로 판별합니다 — github.com이면 gh, gitlab.com이면 glab. 자체 호스팅 인스턴스는 이름에 단서가 없으므로 반드시 직접 적어야 합니다. 인식할 수 없는 값은 판별로 되돌아가지 않고 아무것도 렌더하지 않습니다 — 오타는 틀린 숫자가 아니라 세그먼트 부재로 드러납니다
segments16개 세그먼트를 하나씩 켜고 끄는 토글 (런타임에 조절할 수 있는 유일한 값). 모두 기본 on이며, 꺼진 세그먼트는 아무것도 출력하지 않고 조용히 빠짐

세그먼트는 세 줄에 나눠 배치합니다 — 1행(모델·버전·세션 메타), 2행(컨텍스트 윈도우·API 사용량 바), 3행(디렉터리·git·워크플로우·PR).

관련: Statusline 시스템 및 PR 세그먼트.

security.yaml — 보안 강화

내장 DefaultSecurityPolicy 패턴을 덧붙이는 (교체가 아닌) 추가 보안 설정입니다. SOLID의 개방-폐쇄 원칙에 따라 core를 건드리지 않고 config만으로 확장합니다.

yaml
security:
  extra_dangerous_bash_patterns:
    - 'curl\s+.*\|\s*(ba)?sh'
  extra_deny_patterns: []
  extra_ask_patterns: []
  permission:
    strict_mode: true
    session_rules: []
  sandbox:
    required: false
    network_allowlist: []
    env_scrub_extra: []
    docker_image: "alpine:latest"
키설명
extra_dangerous_bash_patterns내장 deny 패턴에 덧붙일 위험 Bash 커맨드 정규식 (대소문자 무시)
extra_deny_patterns / extra_ask_patterns추가로 둘 파일 deny/ask 패턴
permission.strict_modetrue면 bypassPermissions 모드의 에이전트 spawn을 거부
sandbox.requiredtrue면 sandbox: none 에이전트를 sandbox.justification 없이 거부 (기본 false)
sandbox.network_allowlist기본 8개 호스트에 덧붙일 허용 네트워크 호스트
sandbox.env_scrub_extra기본 scrub 목록에 덧붙일 env 변수명 (AWS_*, GITHUB_TOKEN 등)
sandbox.docker_imagedocker 백엔드 기본 이미지

관련: 보안 노트, settings.json 가이드.

workflow.yaml — branch_guard

주 체크아웃(primary checkout)의 브랜치 상태를 지키는 opt-in 가드입니다. 한 체크아웃을 여러 세션이 동시에 쓸 때, 한쪽에서 실행한 git switch · git checkout · git reset --hard · git stash · git rebase 는 다른 세션의 작업 트리를 아무 신호 없이 바꿔 놓습니다. 이 가드는 그 명령들을 주 체크아웃에서만 거부합니다.

yaml
workflow:
    branch_guard:
        enabled: false   # 배포 기본값
키값설명
enabledfalse (기본)가드가 완전히 비활성입니다. 판정을 위한 git rev-parse 조차 실행하지 않으므로 부가 비용이 없습니다
enabledtrue주 체크아웃에서 브랜치 상태를 바꾸는 명령을 거부합니다. 워크트리 안에서는 그대로 허용됩니다

기본값이 꺼짐인 이유. 이 가드가 막는 위험은 한 체크아웃을 여러 세션이 공유할 때만 생깁니다. 혼자 쓰는 저장소에서는 발생하지 않는 문제이므로, 배포판은 가드를 끈 채로 나갑니다. 여러 세션을 동시에 굴리는 저장소의 관리자가 위 키를 직접 적어 켭니다.

동작 범위. 가드는 주 체크아웃과 워크트리를 구분해서, 워크트리 안의 브랜치 조작은 막지 않습니다. git status · git log · git diff · git fetch 같은 읽기 명령과 git stash list · git merge-base 는 켜져 있어도 통과합니다.

예외와 실패 방향. 브랜치를 만들어야 하는 git 담당 에이전트는 신원으로 예외 처리되며, MOAI_BRANCH_GUARD_EXEMPT=1 환경변수로도 우회할 수 있습니다. 판정이 불확실할 때(저장소가 아님, git 실행 실패 등)는 막지 않고 통과시킨 뒤 감사 로그만 남깁니다 — 확실한 근거가 있을 때만 거부합니다.

브랜치를 바꿔야 하는 작업은 막는 대신 워크트리로 옮기는 것이 정석입니다. 자세한 절차는 moai worktree 를 참조하세요.

workflow.yaml — drift_cache_fill

MoAI는 세션을 시작할 때 SPEC 생명주기 드리프트 알림을 보여줍니다. 이 계산에는 1초 남짓이 걸려서 세션 시작이 기다릴 수 있는 시간을 한참 넘기기 때문에, 결과를 현재 커밋에 묶어 캐시에 저장해 둡니다. 커밋이 바뀌면 캐시가 더 이상 맞지 않고, 알림은 보여줄 것이 없어집니다.

이 키가 켜져 있으면 세션 시작 처리기는 캐시가 맞지 않을 때 짧게 사는 백그라운드 프로세스를 하나 띄워 거기서 드리프트를 계산하게 하고, 기다리지 않고 바로 돌아옵니다. 저장된 결과는 다음 세션이 읽어서 알림을 다시 보여줍니다.

yaml
workflow:
    drift_cache_fill:
        enabled: true   # 배포 기본값
키값설명
enabledtrue(기본)캐시가 맞지 않으면 채우기 프로세스를 하나 띄우고 기다리지 않고 돌아옵니다. 알림은 다음 세션에서 다시 나타납니다
enabledfalse채우기 프로세스를 전혀 띄우지 않습니다. 알림은 캐시에 이미 들어 있는 것만으로 판단하므로, 커밋 이후에는 다른 무언가가 캐시를 채우기 전까지 계속 나타나지 않습니다

이 키만 켜진 채로 나가는 이유. 이 문서의 다른 가드들은 관리자가 필요로 하기 전까지 아무 일도 하지 않기 때문에 꺼진 채로 나갑니다. 이 키는 켜져 있으면 실제로 자식 프로세스를 띄우므로 아무 일도 하지 않는 기본값이 아니며, 그 비용을 감수하는 쪽을 택한 것입니다 — 채우지 않으면 커밋 이후 드리프트 알림이 영영 돌아오지 않기 때문입니다. 자식 프로세스는 짧게 살고, 자체 기한이 있고, 락으로 한 번에 하나만 돌며, 아무것도 출력하지 않습니다.

실패했을 때의 방향. 어떤 실패 경로도 세션에 영향을 주지 않습니다. 자식이 뜨지 못하거나, 끝내지 못하거나, 아무것도 쓰지 못해도 처리기는 이미 돌아온 뒤이고 알림은 그대로 유지될 뿐입니다 — 실패한 채우기가 세션 시작을 지연시키거나 망가뜨리지 않습니다.

workflow.yaml — audit

크로스모델 감사 백엔드(codex_audit · glm_audit · audit_multi)가 실제로 어떤 모델과 effort로 돌지 지정합니다. 백엔드마다 {model, effort} 쌍 하나이고, 배포 기본값은 전부 비어 있습니다.

yaml
workflow:
    audit:
        codex:
            model: ""   # 예: gpt-6.1-terra — codex가 서빙할 수 있는 모델 id
            effort: ""  # 예: xhigh — none | low | medium | high | xhigh | max
        glm:
            model: ""   # 예: glm-5.3
            effort: ""  # 예: max — low | high | max (z.ai reasoning 상태 이름)
키설명
audit.codex.{model, effort}codex 감사가 세션 열기와 리뷰 턴에 실어 보내는 쌍. model이 비었거나 codex가 서빙할 수 없는 id면 핀을 버리고 기존 SSOT 해석으로 되돌아갑니다
audit.glm.{model, effort}GLM 감사가 z.ai 요청에 실어 보내는 쌍. effort는 z.ai reasoning 상태 이름 low · high · max만 받으며, 그 외 값을 적으면 reasoning 지시어를 빼고 모델 핀만 적용합니다
두 쌍 모두 비었을 때이 키가 생기기 전과 동일하게 해석합니다. 핀을 적은 적 없는 프로젝트는 아무 것도 바뀌지 않습니다

핀은 감사 진입점에만 적용됩니다. codex_task · glm_task 같은 작업 위임 경로의 모델 해석은 영향을 받지 않으며, 웹 콘솔의 Audit 패널에서 같은 필드를 직접 편집할 수도 있습니다.

workflow.yaml — todo

백로그 큐(todo)의 안내 표면을 끄는 스위치입니다. 세션이 시작될 때 큐 요약 줄이 뜨는 것, 상태 표시줄의 TODO 세그먼트, 자연어 요청을 todo 워크플로우로 추론 라우팅하는 것 — 이 세 가지가 이 키 하나로 조용해집니다.

yaml
workflow:
    todo:
        enabled: false   # 명시적 끔 — 키가 없으면 켜진 것으로 봅니다
키값설명
todo.enabled(키 없음, 기본)켜짐. 배포 템플릿에는 이 블록이 아예 없어서, 대부분의 프로젝트가 사는 상태입니다
todo.enabledfalse세션 시작 요약 · 상태 표시줄 TODO 세그먼트 · 스킬의 자동 라우팅이 꺼집니다

끄더라도 명령은 지워지지 않습니다. moai todo CLI는 등록된 채로 남고 모든 동사가 동작하며, 이름으로 직접 부른 /moai todo도 그대로 실행됩니다. 이 경계는 의도된 것입니다 — 스위치는 “모르는 사용자에게 큐를 보여 주는 표면"만 끄고, 큐를 실제로 쓰는 사람의 경로는 건드리지 않습니다. 설정 파일을 읽지 못하는 실패 경로에서도 켜짐으로 해석됩니다(fail-open).

크기가 크지 않은 일회성 프로젝트에서 세션마다 뜨는 백로그 요약이 소음으로 느껴질 때 이 키를 씁니다. 큐 자체의 운영법은 moai todo 페이지에 있습니다.

workflow.yaml — autonomy

SPEC 자율 실행 계약(contract.yaml)을 어떻게 서명하고 어디까지 묶을지 정합니다. 계약을 다루는 명령은 moai contract 입니다. 이름이 비슷한 자율성 티어(MOAI_AUTONOMY_TIER)와는 서로 무관한 설정입니다.

yaml
workflow:
    autonomy:
        mode: guided              # guided | contract
        contract:
            batch_sign: false       # 여러 SPEC 을 확인 한 번으로 서명
            second_review: required # required | advisory | off
            push_develop: false     # 계약에서 push-develop 작업 허용
        kickoff:
            # decider: human | llm | llm+jev   (생략 시 guided 는 human, contract 는 llm)
            jev_min_confidence: 0.50
        escalation:
            budget_default: { turns: 60, operations: 40, audit_retries: 2 }
키설명
modeguided(기본) 또는 contract. 영수증 기반 서명(--signer llm)은 contract 에서만 열립니다
contract.batch_signtrue 이면 여러 SPEC 을 확인 한 번으로 서명합니다. 기본 false
contract.second_reviewrequired 이면 계약의 review.second_model 이 none 이거나 비어 있을 때 무효로 판정합니다. advisory · off 는 이 검사를 하지 않습니다
contract.push_developfalse(기본)이면 계약의 push-develop 작업을 무효로 판정합니다
kickoff.decider착수 결정 주체. human · llm · llm+jev. 생략하면 모드에서 파생됩니다. jev 단독은 설정 오류이며 영수증 서명이 거부됩니다
kickoff.jev_min_confidence착수 영수증을 발급하는 쪽이 Jev 판단을 받아들일 최소 신뢰도로 쓰도록 예약된 값. 이번 릴리스에서는 값을 읽어 형식만 검사하며, 서명과 검증에는 영향을 주지 않습니다. 기본 0.50
escalation.budget_default계약에 budget 이 없을 때 서명 시점에 채워 넣는 기본 예산

값이 틀렸을 때. 키가 없으면 위 기본값을 씁니다. mode · second_review · decider · jev_min_confidence 에 허용되지 않은 값을 적으면 더 엄격한 기본값(guided · required · human · 0.50)으로 되돌리고, 어느 키를 바꿨는지 경고로 알립니다.

crosssession.yaml — 세션 간 메시지

내 다른 Claude Code 세션이 보내는 메시지를 이 세션이 어떻게 다룰지 정합니다. moai cc · moai glm 런처가 실행 시점에 이 값을 임시 --settings 파일로 옮겨 담고, 웹 콘솔은 설정 seam을 통해 이 파일을 편집합니다. 런처를 거치지 않고 맨손으로 claude를 실행한 세션은 이 파일을 읽지 않습니다.

yaml
crosssession:
  inbound: ""             # "" | accept | hold | refuse
  isolate_machines: false # 기본값 — 머신 밖으로 나가는 메시지에 승인을 요구하지 않음
  dialog_expiry: ""       # "" | 60s | 5m | 10m | never
키값설명
inbound""(기본)Claude Code가 두 세션의 권한 모드 등급을 보고 메시지마다 스스로 판단합니다
inboundaccept메시지를 그대로 전달합니다. 사람이 지켜보지 않는 작업 세션에 메시지를 받게 하려면 이 값이 필요합니다
inboundhold메시지마다 승인을 받도록 붙잡아 둡니다. 이렇게 붙잡힌 메시지는 만료되지 않고, accept가 적용될 때 전달됩니다
inboundrefuse메시지를 버립니다
isolate_machinesfalse (기본)이 머신 밖의 세션으로 메시지가 나갈 때 승인을 요구하지 않습니다. 같은 머신 안의 세션끼리는 어떤 값이든 머신을 벗어나지 않지만, 머신 밖의 세션으로 가는 메시지는 Anthropic 서버를 거칩니다 — 그 경로를 승인 없이 허용한다는 뜻이므로 기본값을 그대로 둘지 판단해서 결정하세요
isolate_machinestrue메시지가 머신을 벗어나기 전에 반드시 승인을 받습니다(bypassPermissions 모드에서도). 어느 설정 범위든 하나가 true면 적용되므로, 저장소에 체크인된 프로젝트 파일이 요구를 켤 수는 있어도 끌 수는 없습니다 — 끄려면 true를 적은 범위를 전부 지워야 합니다
dialog_expiry""(기본)Claude Code의 5분 기본값을 그대로 씁니다
dialog_expiry60s · 5m · 10m · never기본 판단으로 붙잡힌 메시지의 승인 창 기한입니다. never는 세션이 끝날 때까지 붙잡아 둡니다. inbound: hold로 명시해 붙잡은 메시지에는 적용되지 않습니다

관련 문서