OpenClaw 서브에이전트란? 일을 나눠 맡길 때 권한·깊이·보고가 정해지는 규칙

AI 에이전트에게 일을 시키다 보면 어느 순간 병목이 생깁니다. 자료 조사 하나 시켰는데 그게 끝날 때까지 다른 얘기를 못 꺼냅니다. 긴 작업 하나가 대화창을 통째로 붙잡고 있는 상황입니다. 그래서 나오는 발상이 “일을 나눠서 다른 애한테 맡기자”인데, OpenClaw에서는 이걸 서브에이전트(sub-agent)라고 부릅니다.

그런데 막상 붙여보면 헷갈리는 지점이 꽤 있습니다. 자식한테 권한이 어디까지 따라가는지, 자식이 또 자식을 낳을 수 있는지, 결과는 누구한테 어떻게 돌아오는지 같은 것들입니다. 이 글은 OpenClaw 공식 문서의 Sub-agents 섹션(개요, 도구 정책, 중첩과 인증, 어나운스, 동시성·복구·중지)을 바탕으로 그 규칙을 한국어 독자용으로 정리한 해설입니다. 제가 특정 구성에서 직접 돌려 같은 수치를 얻었다는 경험담이 아니라 문서가 정해둔 기준을 순서대로 풀어 쓴 글이니, 실제 동작은 쓰고 계신 버전에서 다시 확인하세요. OpenClaw 자체가 처음이시면 OpenClaw란? 카톡·텔레그램으로 AI 에이전트를 부리는 셀프호스팅 게이트웨이를 먼저 보시는 편이 낫습니다.

서브에이전트는 '새 탭'이 아니라 '새 세션'이다

가장 먼저 잡아야 할 그림은 이겁니다. 서브에이전트는 지금 돌고 있는 에이전트 실행에서 갈라져 나온 백그라운드 실행이고, 각각 자기만의 세션을 갖습니다. 세션 키 모양은 agent:<agentId>:subagent:<uuid>입니다. 그리고 모든 서브에이전트 실행은 백그라운드 태스크로 추적됩니다.

문서가 밝히는 설계 목표는 세 가지입니다. 조사나 느린 도구 작업을 본 실행을 막지 않고 병렬로 돌리는 것, 자식을 기본적으로 격리해두는 것(세션 분리, 필요하면 샌드박스), 그리고 도구 표면을 함부로 못 쓰게 좁혀두는 것입니다.

여기서 초보자가 자주 착각하는 부분이 하나 있습니다. 실행(run)은 끝나지만 세션은 끝나지 않습니다. Control UI에서 끝난 서브에이전트 실행을 열면 그 기록은 읽기 전용입니다. 거기에 이어서 말을 걸고 싶으면 작성창 쪽의 ‘부모 세션 열기’로 돌아가야 합니다. 예외적으로 visible: true로 만든 지속 세션은 평범한 세션처럼 취급돼서 직접 입력하고 방향을 틀 수 있습니다.

문서의 권고도 분명합니다. 내부 QA, 조사, 코딩, 리뷰, 테스트 레인처럼 결과가 부모에게 돌아오면 되는 일은 그냥 보통 서브에이전트를 쓰고, 사용자가 따로 떼어낸 세션을 원하거나 그 작업에 계속 돌아가 개입해야 할 때만 지속 세션을 만들라는 것입니다. 오래 걸리는 작업이라는 이유만으로 사이드바에 새 세션을 만들지는 말라는 얘기입니다.

공짜가 아니다 — 자식마다 컨텍스트가 따로 붙는다

문서가 별도 주석으로 못 박아 둔 비용 얘기가 있습니다. 서브에이전트는 기본적으로 각자의 컨텍스트와 토큰 사용량을 가집니다. 다섯 개를 띄우면 다섯 벌의 토큰이 나갑니다.

그래서 무겁거나 반복적인 작업이라면 본 에이전트는 품질 좋은 모델에 두고, 자식 쪽만 agents.defaults.subagents.model이나 에이전트별 설정으로 더 싼 모델로 내려두라고 권합니다. 반대로 자식이 정말로 요청자의 현재 대화 내용을 알아야 하는 경우에만 context: "fork"로 띄우라고 합니다. 채널 스레드에 묶이는 스레드 바인딩 세션은 지금 대화를 후속 스레드로 분기하는 성격이라 기본값이 fork입니다.

권한: 서브에이전트가 무조건 잃는 도구들

여기가 이 글에서 제일 중요한 대목이라고 봅니다. 서브에이전트는 먼저 부모나 대상 에이전트와 같은 프로필·도구 정책 파이프라인을 거치고, 그 다음에 서브에이전트 전용 제한 계층이 한 겹 더 얹힙니다.

깊이나 역할과 무관하게 항상 사라지는 도구는 이렇습니다.

• gateway, agents_list, session_status, progress_card, cron
• message, sessions_send, 그리고 conversations_* 계열

성격을 보면 이유가 읽힙니다. 시스템 수준 도구, 부모가 소유한 진행 카드, 외부로 바로 나가는 전달 표면, 그리고 메인 에이전트가 조율해야 하는 도구들입니다. 자식이 사용자에게 직접 메시지를 쏘지 못하게 막아두면 보고가 정해진 경로로만 흐릅니다.

그리고 이건 설정으로 되돌릴 수 없습니다. 이 하드 디나이 계층은 매 턴 저장된 서브에이전트 세션 봉투에서 다시 계산되고, 재개된 세션이나 대시보드에 보이는 세션에도 똑같이 적용됩니다. 평범한 allow/alsoAllow 항목으로는 덮어쓰지 못합니다. 숨은 실행은 한 술 더 떠서 도구를 구성하기도 전에 message를 꺼버립니다.

여기에 더해, 설정된 깊이 상한에 도달한 서브에이전트는 subagents, sessions_list, sessions_history, sessions_spawn까지 잃습니다. 말단 작업자는 더 이상 일을 쪼개지도, 남의 세션을 들여다보지도 못하고 보고만 올리게 됩니다. 기본값 기준으로 깊이 5 미만의 자식들은 이 네 가지를 받아서 자기 자식을 관리할 수 있습니다.

반대로 도구를 더 좁히고 싶다면 tools.subagents.tools의 deny/allow를 씁니다. 여기서 규칙이 하나 있는데, allow는 이미 결정된 도구 집합을 더 좁히는 최종 필터일 뿐 tools.profile 단계에서 빠진 도구를 다시 불러오지는 못합니다. 예를 들어 coding 프로필에는 웹 검색과 페치는 있지만 browser는 없어서, 코딩 프로필 자식에게 브라우저 자동화를 주려면 프로필 단계에서 alsoAllow: ["browser"]로 얹어야 합니다. 이 도구 정책·샌드박스·Elevated 권한이 서로 어떻게 다른지는 OpenClaw 도구가 막힐 때｜샌드박스·도구 정책·Elevated 권한을 구분하는 법에 정리해뒀습니다.

깊이(depth): 자식이 또 자식을 낳는 문제

서브에이전트는 기본적으로 깊이 5까지 재귀적으로 일을 다시 나눠 맡길 수 있습니다. 구조는 이렇습니다.

• 깊이 0 — agent:<id>:main, 메인 에이전트. 언제나 스폰 가능
• 깊이 1 — 오케스트레이터. maxSpawnDepth: 1로 막지 않는 한 자식을 만들 수 있음
• 깊이 2~4 — 기본값에서는 여전히 오케스트레이터
• 깊이 5 — 기본 경계에서의 말단(leaf). 더는 스폰 불가

관련 설정값의 기본값도 문서에 적혀 있습니다. maxSpawnDepth는 기본 5(범위 1~5), 한 에이전트 세션이 동시에 가질 수 있는 활성 자식 수 maxChildrenPerAgent는 기본 5(범위 1~20), 전역 동시 실행 maxConcurrent는 기본 8, sessions_spawn의 기본 타임아웃 runTimeoutSeconds는 900초(0이면 무제한), 게이트웨이 어나운스 타임아웃 announceTimeoutMs는 120000밀리초입니다. 자식 수 제한은 오케스트레이터 하나가 폭주해서 작업을 무한정 퍼뜨리는 걸 막는 장치입니다.

깊이를 낮게 잡으면 말단 작업자가 더 빨리 만들어집니다. 실제로 조직도를 깊게 팔 이유가 없다면 maxSpawnDepth: 2 정도로 내려두는 편이 관리하기 쉽습니다.

결과는 한 단계씩 올라온다

보고 경로도 정해져 있습니다. 문서는 이걸 어나운스 체인이라고 부릅니다.

1. 자손이 일을 끝내면 직속 부모에게 보고합니다.
2. 그 부모는 자기 자식들의 결과를 종합한 뒤에 마무리하고 다시 위로 보고합니다.
3. 메인 에이전트가 마지막 보고를 받아 사용자에게 전달합니다.

각 단계는 직속 자식의 보고만 봅니다. 손자가 무슨 말을 했는지 할아버지가 직접 보지 못한다는 뜻이고, 그래서 중간 단계의 종합이 부실하면 위에서는 알 길이 없습니다. 어나운스 단계 자체는 요청자 세션이 아니라 자식 세션 안에서 돕니다.

몇 가지 변형도 있습니다. expectsCompletionMessage: false로 띄운 실행은 어나운스 단계를 아예 건너뛰고, 정확히 ANNOUNCE_SKIP이라고 응답하면 출력이 억제됩니다. 완료 보고가 필요한 실행인데 자식이 NO_REPLY만 뱉거나 아무 출력도 없으면, 그건 조용한 성공이 아니라 누락된 산출물로 취급돼 요청자나 부모에게 넘어갑니다.

전달 방식은 요청자의 깊이에 따라 갈립니다. 최상위 요청자 세션은 외부 전달이 붙은 후속 호출을 쓰고, 중첩된 서브에이전트 요청자는 내부 주입을 받아 오케스트레이터가 세션 안에서 결과를 종합합니다. completionTarget: "parent"를 쓰면 결과가 원 요청자 세션의 비공개 턴으로 돌아오는데, 이 경우 OpenClaw는 자식 결과나 생성된 미디어를 채널로 자동 전송하지 않습니다.

동시성, 그리고 재시작 후에 벌어지는 일

서브에이전트는 subagent라는 전용 큐 레인을 씁니다. 동시 실행은 앞서 본 기본값 8입니다. 여기에 안전장치가 하나 더 있는데, 전달 백로그가 25에 도달하면 경고하고, 50에서는 새 서브에이전트 스폰을 막습니다. 운영자가 밀린 전달을 처리하거나 해제할 때까지입니다. 자리를 만들려고 결과를 알아서 지우지는 않습니다.

살아 있는지 판정하는 기준도 생각보다 조심스럽습니다. 종료 시각이 없다는 사실만으로 아직 살아 있다고 보지 않고, 실행 소유자나 정확한 대기열 예약을 확인할 수 있을 때만 활성으로 셉니다. 그 밖의 경우에는 오래된 실행 판정 창(2시간, 또는 설정된 실행 타임아웃에 짧은 유예를 더한 값 중 긴 쪽)이 지나면 활성·대기 집계에서 빠집니다.

게이트웨이가 재시작되면 중단됐던 서브에이전트는 기존 자식 기록에서 자동으로 이어서 돌아갑니다. 사용자가 다시 프롬프트를 넣을 필요가 없고, 어나운스가 있는 실행이면 “게이트웨이 재시작 후 중단된 작업을 재개했습니다”라는 알림을 원 요청자에게 보내려 시도합니다. 다만 같은 자식이 짧은 시간 안에 반복해서 복구 대상이 되면 그 세션에 복구 툼스톤이 남고 이후 재시작에서는 자동 재개를 멈춥니다. 이때는 openclaw tasks maintenance --apply로 태스크 기록을 맞추거나, openclaw doctor --fix로 남아 있는 중단 플래그를 정리하라고 안내합니다.

운영 지침 중에 실무에서 제일 자주 어기게 되는 게 하나 있습니다. 자식 작업은 한 번 시작하고 완료 이벤트를 기다리라는 것입니다. sessions_list나 /subagents list, exec의 sleep 같은 걸로 폴링 루프를 짜지 말라는 얘기입니다. 목록 쪽도 살아 있는 작업 위주로 정리돼서, 끝난 자식은 짧은 기간만 보이고 오래된 연결은 무시됩니다. 재시작 후에 유령 자식이 되살아나는 걸 막기 위한 설계입니다.

처음 붙일 때 확인할 순서

문서를 죽 읽고 나서 정리하면 점검 순서는 이렇게 됩니다.

1. 진짜 나눌 일인가. 본 실행을 막지 않아야 하는 느린 작업, 병렬 조사, 격리해서 돌려야 하는 일이면 맞습니다. 그냥 길기만 한 작업은 아닙니다.
2. 모델과 비용. 자식 수만큼 컨텍스트가 붙습니다. 반복 작업이면 자식 모델을 내립니다.
3. 깊이. 재귀 위임이 필요 없으면 maxSpawnDepth를 낮춰 말단으로 만듭니다.
4. 도구. 하드 디나이 목록은 되돌릴 수 없고, 더 좁히는 건 deny/allow로 합니다. 프로필에서 빠진 도구는 alsoAllow로 프로필 단계에서 얹습니다.
5. 완료 경로. 결과를 사용자에게 보낼지, 부모가 비공개로 받을지, 아예 보고를 생략할지 먼저 정합니다.

정리하면 OpenClaw의 서브에이전트는 “일꾼을 더 부른다”보다 “권한이 줄어든 복제본을 정해진 깊이까지만 만들고, 보고는 한 줄로 올린다”에 가깝습니다. 직접 말할 수 있는 도구를 먼저 빼앗고 시작한다는 점이 이 설계의 성격을 잘 보여준다고 생각합니다. 한 대 안에서 세션을 나누는 이 구조와, 폰이나 다른 PC를 물리적으로 붙이는 구조는 서로 다른 얘기인데, 후자는 OpenClaw 노드란? 폰·다른 PC를 붙였을 때 권한이 열리는 순서에서 다뤘습니다.

이 글의 내용은 모두 OpenClaw 공식 문서 docs.openclaw.ai의 Sub-agents 문서와 그 하위 페이지(도구 정책, 중첩과 인증, 어나운스, 동시성·복구·중지)를 근거로 정리했습니다. 설정 기본값과 도구 목록은 버전에 따라 달라질 수 있으니, 실제 적용 전에는 쓰고 계신 버전의 문서를 한 번 더 확인하시길 권합니다.