config 섹션 레퍼런스
.moai/config/sections/ 의 주요 설정 파일(handoff/delegation/llm/statusline/security) 키 레퍼런스.
MoAI-ADK의 프로젝트 설정은 .moai/config/sections/ 아래 여러 YAML 파일로 나뉘어 있습니다. settings.json 가이드가 Claude Code 런타임 설정을 다룬다면, 이 페이지는 MoAI-ADK 자체 동작을 제어하는 주요 섹션 파일의 키를 정리합니다.
정보한 줄 요약:settings.json은 Claude Code에게 무엇을 허용할지 정하고,.moai/config/sections/*.yaml은 MoAI-ADK가 어떻게 오케스트레이션할지 정합니다.
세션 경계에서 저장된 핸드오프를 어떻게 처리할지 제어합니다.
handoff:
mode: manual # manual | auto
guide: false| 키 | 값 | 설명 |
|---|---|---|
mode | manual (기본) | 저장된 핸드오프를 자동 주입하지 않음 (opt-in 베이스라인 UX) |
mode | auto | /clear 시 저장된 핸드오프를 세션 컨텍스트로 주입한 뒤 audit-trail 복사본으로 이동 |
guide | false (기본) | true면 /clear가 아닌 세션 시작(startup/resume/compact)에서 대기 중인 핸드오프가 있다는 best-effort stderr 힌트를 띄움. 알림일 뿐 세션을 막지는 않음 |
관련: 자율 연속 루프, moai handoff.
/moai 서브커맨드마다 기본으로 쓸 스킬과 에이전트를 배정한 맵입니다. 오케스트레이터는 실행 계획을 짤 때(Analyze-First) 이 맵을 읽고 어떤 에이전트를 spawn할지, 어떤 스킬을 주입할지 정합니다.
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할 11개 retained 에이전트) + skills(spawn 시 주입할 workflow 스킬). 하나도 배정하지 않아도 유효 (오케스트레이터가 직접 실행) |
domain_skills | 미션 도메인에 맞춰 주입할 스킬 (spawn당 0-3개). 도메인 신호와 매칭 |
agents | 에이전트마다 두는 conditional 스킬 (트리거가 발생하면 on-demand 로드) |
프로필, 프로필 매트릭스, 에이전트별 override, GLM 모델 매핑을 정의합니다.
llm:
profile: "medium" # high | medium | low (활성 매트릭스 열, max는 high로 읽힘)
performance_tier: "medium" # legacy 별칭 (profile 부재 시 읽힘, 동일 어휘)
profiles: # 프로필 열 → 11개 에이전트 → {model, effort}
high: { ... } # 상세 표: 프로필 매트릭스 페이지
medium: { ... }
low: { ... }
agent_overrides: {} # 에이전트별 {model, effort} override (선택)
glm:
base_url: "https://api.z.ai/api/anthropic"
models:
high: "glm-5.3" # 1M context — Opus 슬롯
medium: "glm-5.3" # 1M context — Sonnet 슬롯
low: "glm-5.3" # 1M context — 경량 슬롯
fable: "glm-5.3"| 키 | 설명 |
|---|---|
profile | 활성 프로필 매트릭스 열 (high/medium/low, 과거 max는 high의 별칭으로 읽힘). 비어 있으면 medium으로 해석. 모든 서브에이전트 spawn의 model+effort 출처 |
performance_tier | legacy 별칭 필드. profile이 없을 때만 읽히며, high/medium/low 어휘를 그대로 쓰므로 별도 정규화가 필요 없음 |
profiles | 프로필 열마다 에이전트 → {model, effort}를 적은 매트릭스 (에이전트 11개 × 열 3개 = 33셀). 빠진 셀은 Go 기본값(template.DefaultProfileMatrix)이 최종 fallback |
agent_overrides | 정규 에이전트 이름을 키로 하는 {model, effort} override. 활성 프로필의 에이전트 셀보다 우선 (카탈로그+enum 검증) |
glm.base_url | Z.AI Anthropic 호환 프록시 엔드포인트 |
glm.models | 슬롯별 GLM 모델 매핑. GLM은 Claude의 5단계 effort를 3개 reasoning 상태(thinking-off / reasoning-high / reasoning-max)로 collapse |
관련: 프로필 매트릭스, 3-티어 에이전트 아키텍처.
statusline 테마와 16개 세그먼트 토글을 제어합니다.
statusline:
theme: "catppuccin-mocha" # catppuccin-mocha | catppuccin-latte
segments:
model: true
context: true
# ... 총 16개 세그먼트 (모두 기본 on)
task: true
pr: true| 키 | 설명 |
|---|---|
theme | 테마는 딱 두 개: catppuccin-mocha(기본) 또는 catppuccin-latte |
segments | 16개 세그먼트를 하나씩 켜고 끄는 토글 (런타임에 조절할 수 있는 유일한 값). 모두 기본 on이며, 꺼진 세그먼트는 아무것도 출력하지 않고 조용히 빠짐 |
세그먼트는 세 줄에 나눠 배치합니다 — 1행(모델·버전·세션 메타), 2행(컨텍스트 윈도우·API 사용량 바), 3행(디렉터리·git·워크플로우·PR).
내장 DefaultSecurityPolicy 패턴을 덧붙이는 (교체가 아닌) 추가 보안 설정입니다. SOLID의 개방-폐쇄 원칙에 따라 core를 건드리지 않고 config만으로 확장합니다.
security:
extra_dangerous_bash_patterns:
- 'curl\s+.*\|\s*(ba)?sh'
- 'rm\s+-rf\s+/[^.]'
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_mode | true면 bypassPermissions 모드의 에이전트 spawn을 거부 |
sandbox.required | true면 sandbox: none 에이전트를 sandbox.justification 없이 거부 (기본 false) |
sandbox.network_allowlist | 기본 8개 호스트에 덧붙일 허용 네트워크 호스트 |
sandbox.env_scrub_extra | 기본 scrub 목록에 덧붙일 env 변수명 (AWS_*, GITHUB_TOKEN 등) |
sandbox.docker_image | docker 백엔드 기본 이미지 |
관련: 보안 노트, settings.json 가이드.
주 체크아웃(primary checkout)의 브랜치 상태를 지키는 opt-in 가드입니다. 한 체크아웃을 여러 세션이 동시에 쓸 때, 한쪽에서 실행한 git switch · git checkout · git reset --hard · git stash · git rebase 는 다른 세션의 작업 트리를 아무 신호 없이 바꿔 놓습니다. 이 가드는 그 명령들을 주 체크아웃에서만 거부합니다.
workflow:
branch_guard:
enabled: false # 배포 기본값| 키 | 값 | 설명 |
|---|---|---|
enabled | false (기본) | 가드가 완전히 비활성입니다. 판정을 위한 git rev-parse 조차 실행하지 않으므로 부가 비용이 없습니다 |
enabled | true | 주 체크아웃에서 브랜치 상태를 바꾸는 명령을 거부합니다. 워크트리 안에서는 그대로 허용됩니다 |
기본값이 꺼짐인 이유. 이 가드가 막는 위험은 한 체크아웃을 여러 세션이 공유할 때만 생깁니다. 혼자 쓰는 저장소에서는 발생하지 않는 문제이므로, 배포판은 가드를 끈 채로 나갑니다. 여러 세션을 동시에 굴리는 저장소의 관리자가 위 키를 직접 적어 켭니다.
동작 범위. 가드는 주 체크아웃과 워크트리를 구분해서, 워크트리 안의 브랜치 조작은 막지 않습니다. git status · git log · git diff · git fetch 같은 읽기 명령과 git stash list · git merge-base 는 켜져 있어도 통과합니다.
예외와 실패 방향. 브랜치를 만들어야 하는 git 담당 에이전트는 신원으로 예외 처리되며, MOAI_BRANCH_GUARD_EXEMPT=1 환경변수로도 우회할 수 있습니다. 판정이 불확실할 때(저장소가 아님, git 실행 실패 등)는 막지 않고 통과시킨 뒤 감사 로그만 남깁니다 — 확실한 근거가 있을 때만 거부합니다.
브랜치를 바꿔야 하는 작업은 막는 대신 워크트리로 옮기는 것이 정석입니다. 자세한 절차는 moai worktree 를 참조하세요.
- settings.json 가이드 — Claude Code 런타임 설정
- 하네스 프로필과 평가 — harness.yaml / evaluator-profiles
- moai doctor —
moai doctor config로 병합 설정 검사