OpenClaw 서브에이전트 아키텍처: 팬아웃/팬인 패턴으로 구현하는 병렬 에이전트 오케스트레이션
OpenClaw 서브에이전트는 기존에 한 명의 AI와 순차적으로 대화하던 방식을, 여러 독립 AI 작업자(서브에이전트)를 동시에 풀어놓고 결과만 취합하는 팬아웃/팬인 패턴으로 전환하게 만드는 핵심 기능입니다. 첫 번째 서브에이전트를 실행하는 방법은 크게 두 가지로, /subagents spawn 슬래시 명령어와 openclaw agent CLI 명령어입니다. 핵심 파라미터는 task(실행할 작업), mode(run은 1회 실행 후 종료, session은 세션 유지), cleanup(delete는 실행 후 즉시 삭제, keep은 60분 후 자동 아카이브), runTimeoutSeconds(권장값 120~900초)입니다. 서브에이전트는 기본적으로 sessions_list, sessions_history, sessions_send, sessions_spawn 세션 도구를 사용할 수 없으며(도구 정책 격리), 최대 동시 실행 수는 8개, 각 에이전트 세션당 최대 5개의 자식 서브에이전트를 생성할 수 있습니다.announce는 best-effort 방식이므로 게이트웨이 재시작 시 유실될 수 있으며, expectsCompletionMessage: true 설정이나 cleanup: keep 옵션으로 보완할 수 있습니다. 프로덕션 환경에서는 cascade stop 기능으로失控된 서브에이전트를 한 번에 정리할 수 있습니다.
팬아웃/팬인 패턴: 병렬 에이전트 오케스트레이션의 핵심 구조
OpenClaw의 서브에이전트 시스템은 하나의 메인 작업이 여러 독립 서브작업으로 분해되어 동시 실행된 후, 각 결과가 상위 레벨로 취합되는 팬아웃/팬인 디자인 패턴을 기반으로 동작합니다. 이 구조는 메인 에이전트가 sessions_spawn 도구를 호출하여 여러 개의 독립 서브에이전트를 동시에 생성하는 팬아웃 단계와, 각 서브에이전트 작업 완료 시 announce 체인을 통해 결과를 비동기 통보하는 팬인 단계로 구성됩니다. depth-2 leaf worker(최종 작업 수행자)에서 depth-1 orchestrator(중간 오케스트레이터)를 거쳐 main agent(메인 에이전트) 순서로 결과가 상향 전달되며, 각 레벨의 orchestrator는 하위 모든 자식의 announce를 취합한 후 상위 레벨에 보고하는 계층적 구조를 가집니다. 이러한 아키텍처는 복잡한 작업을 독립적인 하위 작업으로 분해하여 병렬 처리함으로써 전체 작업 시간을 단축하고, 시스템의 확장성과 내결함성을 동시에 확보합니다.
세션 격리와 도구 정책: 보안과 독립성의 균형
서브에이전트는 메인 에이전트 세션과 완전히 분리된 세션에서 실행되며, 독립된 세션 키, 작업 디렉터리, 인증 정보를 가집니다. 각 서브세션은 개별적으로 관리되는 컨텍스트와 도구 사용 권한을 가지며, 이는 메인 세션의 보안과 안정성을 보장합니다. 특히 도구 정책 격리 메커니즘은 서브에이전트가 사용할 수 있는 도구를 세션 수준에서 거부하는 보안 가드로 작동하며, 기본 거부 도구(sessions_list, sessions_history, sessions_send, sessions_spawn)에 더해 config의 도구 거부 배열로 추가 도구를 명시적으로 차단할 수 있습니다. 이러한 격리 구조는 서브에이전트가 메인 세션의 민감한 데이터나 설정에 접근하는 것을 방지하면서도 필요한 작업은 독립적으로 수행할 수 있는 유연성을 제공합니다.
실전 적용: 명령어 및 설정 예시
OpenClaw 서브에이전트를 실제로 활용하려면 메인 에이전트 세션 내부에서 sessions_spawn 도구를 호출해야 합니다. CLI에서 직접 실행할 수 없으며, /subagents spawn 슬래시 명령어나 openclaw agent --agent <id> --message "<task>" 명령어를 통해 간접적으로 사용해야 합니다. 예를 들어, 메인 에이전트가 여러 데이터 소스를 병렬로 수집하는 작업을 수행하려면 다음과 같이 sessions_spawn을 호출합니다. 각 서브에이전트는 고유한 세션 키를 부여받으며, 이 키를 통해 메인 세션과 서브세션 간의 부모-자식 관계가 추적됩니다. 동시 실행 수 제한을 제어하려면 config의 maxConcurrent(기본 8개)와 maxChildrenPerAgent(기본 5개) 파라미터를 조정할 수 있으며, 모델 선택 전략을 통해 메인 에이전트와 서브에이전트에 서로 다른 모델을 할당하여 비용과 성능을 최적화할 수 있습니다.
한계점 및 주의사항
서브에이전트 시스템은 여러 장점이 있지만, 몇 가지 중요한 한계점과 주의사항을 고려해야 합니다. 먼저, 최대 중첩 깊이 파라미터로 인해 서브에이전트가 또 다른 서브에이전트를 생성할 수 있는 깊이가 제한되며, depth-2 이상은 leaf worker로 분류되어 사용할 수 있는 세션 도구가 제한됩니다. 이는 복잡한 작업을 여러 단계로 분해해야 하는 경우 유연성을 저하시킬 수 있습니다. 또한 동시 실행 수 제한은 시스템 리소스를 보호하지만, 대량의 병렬 작업을 처리할 때 병목 현상이 발생할 수 있습니다. 게이트웨이 재시작 시 결과가 유실될 수 있으므로, expectsCompletionMessage 설정이나 세션 유지 옵션으로 보완할 수 있으며, 프로덕션 환경에서는 cascade stop 기능으로失控된 서브에이전트를 한 번의 명령으로 정리할 수 있습니다. > 이 주제의 전체 맥락 방향성은 **8. 나는 더 이상 예전 방식으로 일하지 않는다.** 원본 글에 세밀하게 정리되어 있습니다. 더 깊게 탐구하고 싶다면 관련 내부 대표 문서(Pillar/Entity)를 참조하세요.