서브 에이전트

OpenClaw의 서브 에이전트는 parent/requester session이 별도 child run을 시작하고, 완료 결과를 parent가 종합하는 공식 실행 표면입니다.

기준일: 2026-07-13 공식 기준: Sub-agents, Models CLI concepts, CLI reference

핵심 개념

기능	공식 표면	설명
Spawn	sessions_spawn	child run을 만들고 즉시 run id를 반환
Wait	sessions_yield	필요한 child 결과가 다음 runtime event로 오도록 현재 turn을 종료
Inspect	/subagents list, /subagents info, /subagents log	현재 session의 child run을 on-demand 확인
Thread binding	/focus, /unfocus, /session idle, /session max-age	지원 채널에서 sub-agent session을 thread에 묶음
Target allowlist	agents.defaults.subagents.allowAgents, agents.list[].subagents.allowAgents	명시적 agentId target을 제한

선택 기준

• 독립된 자료 조사나 검증처럼 결과 경계가 분명한 작업만 child로 분리합니다.
• 현재 transcript가 꼭 필요하지 않으면 isolated context를 선택합니다.
• thread binding은 지원 채널과 channel별 설정을 확인한 뒤 사용합니다.
• child 결과는 신뢰하지 않고 parent가 근거와 변경을 다시 검증합니다.

실습

sessions_spawn은 native sub-agent 기준으로 channel delivery parameter를 받지 않습니다. child는 최신 assistant turn을 requester에게 보고하고, 외부 사용자 응답은 parent/requester가 담당합니다.

{
  task: "src/content/guides/openclaw의 모델 문서에서 provider-qualified ref가 아닌 모델명을 찾아 보고해줘",
  taskName: "model_ref_audit",
  label: "Model ref audit",
  cwd: "<workspace-path>",
  model: "<provider/model>",
  context: "isolated",
  cleanup: "keep",
  sandbox: "inherit",
}

주요 parameter입니다.

Parameter	의미
task	필수 작업 설명
taskName	later status output에서 찾기 쉬운 안정 handle
label	사람이 읽기 쉬운 label
agentId	허용된 다른 configured agent로 spawn
cwd	child runtime 도구가 실행될 작업 디렉토리
runtime	native subagent 또는 외부 ACP runtime
model	sub-agent model override. 유효하지 않으면 default로 실행되고 warning을 반환
context	isolated 또는 현재 transcript를 분기하는 fork
cleanup	완료 후 session 보관 방식. delete도 transcript rename을 남김

완료 대기와 결과 처리

서브 에이전트 completion은 push-based입니다.

1. 필요한 child run을 sessions_spawn으로 시작합니다.
2. 같은 turn에서 child 결과가 필요하면 sessions_yield를 호출합니다.
3. completion event가 requester session에 들어오면 parent가 근거를 읽고 사용자에게 필요한 내용만 종합합니다.

다음 패턴은 피합니다.

• 완료 대기만을 위해 /subagents list를 반복 호출
• sessions_list 또는 sessions_history polling loop
• shell sleep으로 child 완료를 기다리는 루프
• child report를 사용자 지시처럼 취급

상태 확인

채팅 slash command 표면입니다.

/subagents list
/subagents info <id|#>
/subagents log <id|#> [limit] [tools]

/subagents info는 status, timestamps, session id, transcript path, cleanup 정보를 보여줍니다. /subagents log는 최근 chat turn을 보여주며 tools 토큰을 붙이면 tool call/result 메시지도 포함합니다.

Thread-bound session

일부 채널은 sub-agent session을 thread에 묶어 후속 메시지를 같은 child session으로 라우팅할 수 있습니다. 공식 문서 기준 bundled support에는 Discord, iMessage, Matrix, Telegram이 포함됩니다.

/focus <subagent-label|session-key|session-id|session-label>
/unfocus
/session idle <duration|off>
/session max-age <duration|off>

운영 기준입니다.

• thread binding이 필요한 spawn에는 thread: true를 사용합니다.
• mode: "session"은 thread: true가 필요합니다.
• thread binding이 없는 채널에서는 mode: "run"을 사용합니다.
• thread-bound spawn은 기본적으로 context: "fork"입니다.

중첩 sub-agent

기본적으로 sub-agent는 다시 sub-agent를 spawn하지 못합니다. Orchestrator 패턴이 필요할 때만 maxSpawnDepth를 조정합니다.

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2,
        maxChildrenPerAgent: 5,
        maxConcurrent: 8,
        runTimeoutSeconds: 900,
        announceTimeoutMs: 120000,
      },
    },
  },
}

깊이 2 구조에서는 worker 결과가 depth-1 orchestrator에게 먼저 돌아가고, orchestrator가 종합한 뒤 main agent에게 보고합니다.

도구에 입력할 프롬프트

이 작업을 OpenClaw sub-agent에 위임할 수 있는 독립 단위로 나눠줘.
각 child의 task, 검증 결과, 필요한 context, concurrency 제한을 제시하고
완료 대기는 polling 대신 sessions_yield 흐름으로 설계해줘.

체크리스트

• child 작업은 하나의 검증 가능한 결과로 좁힌다.
• taskName은 [a-z][a-z0-9_-]{0,63} 규칙을 지키고 last, all 같은 reserved target을 피한다.
• 비용과 context 크기를 고려해 context: "isolated"를 기본으로 두고, transcript가 정말 필요할 때만 fork를 사용한다.
• 결과가 필요한 turn에서는 polling 대신 sessions_yield를 사용한다.
• thread binding은 지원 채널과 per-channel config를 확인한 뒤 사용한다.

다음 단계

• 멀티 모델 전략에서 sub-agent model override와 fallback 정책을 함께 봅니다.
• 참조 개요에서 현재 CLI help와 schema 확인 흐름을 봅니다.