pillar

OpenClaw 서브에이전트 풀 아키텍처 마스터 가이드: FanOut/FanIn 병렬 실행과 ACP 8단계 채널바인딩 통합 구조

핵심 요약

OpenClaw의 서브에이전트 풀은 FanOut/FanIn 2단계 병렬 실행 모델을 채택하여 기본 8개의 에이전트를 동시에 격리 생성합니다. ACP 8단계 채널바인딩 프로토콜은 메시지를 결정적 경로로 라우팅하며 LLM 토큰 비용 없이 세션 분열을 방지합니다. 결함 격리와 ACP 무상태 설계의 이중 안전망이 실패 시 자동 복구를 보장하고, 3단계 인지 부담 분산을 통해 동시 작업 처리량이 단일 에이전트 대비 8배 이상 확대됩니다.

이 글의 핵심 주장과 근거

핵심 주장

서브에이전트 풀 아키텍처는 개발자의 인지 부담을 오케스트레이터의 고수준 계획, 전문 서브에이전트의 분산 실행, 자동 합성 단계의 3단계로 분리함으로써 단일 에이전트 대비 동시 작업 처리량이 8배 이상 확대된다.

출처: [1] OpenClaw Subagents Documentation [2] Orchestrator-Workers Pattern – Anthropic Cookbook

핵심 주장

워크스페이스 격리 설계에 의해 서로 다른 서브에이전트가 동일한 파일을 동시에 수정하는 경합 조건이 원천 차단되며, 각 서브에이전트가 자신에게 할당된 태스크를 완전한 격리 환경에서 자율적으로 수행할 수 있다.

출처: [1] Claude Code GAV Feedback Loop [2] OpenClaw Subagent Pool Architecture Deep Dive

서브에이전트 풀 아키텍처의 기반 구조

OpenClaw의 서브에이전트 풀 아키텍처는 다수의 에이전트를 풀링 방식으로 관리하여 대규모 작업을 효율적으로 처리합니다. 비동기 작업 큐와 워커 스레드 풀을 결합하여 각 작업마다 독립된 메모리와 고정된 CPU 할당량을 부여함으로써 단일 스레드 병목이 제거되어 대용량 데이터 처리 시에도 일관된 처리량이 유지됩니다. FanOut 단계에서는 상위 에이전트(오케스트레이터)가 하위 서브에이전트들에게 작업을 분산하고, 각 서브에이전트는 독립적인 네임스페이스에서 실행됩니다. 이 구조는 허브앤스푹 패턴을 기반으로 하며, 오케스트레이터는 리프 작업을 절대 수행하지 않고 반드시 위임과 종합만 담당합니다.

FanOut/FanIn 2단계 병렬 실행 체계

FanOut 단계에서 sessions_spawn 명령어를 통해 기본 8개의 서브에이전트가 동시에 배경 세션에 격리 생성됩니다. 각 서브에이전트는 agent:<agentId>:subagent:<uuid> 형식의 독립적 네임스페이스에서 실행되어 부모 세션의 LLM 컨텍스트와 물리적으로 완전히 분리됩니다. 이후 FanIn 단계에서 모든 서브에이전트의 결과가 ACP 채널바인딩의 8단계 우선순위 라우팅을 통해 부모 채널에 자동 회수되고, 최종 통합 결과는 pillar 문서에 자동 주입됩니다. 이 2단계 실행 체계는 병렬 처리 효율성을 극대화하면서도 결과의 일관성을 보장하며, 실패한 서브에이전트는 격리 경계 안에서 자동 재구성되어 전체 시스템에 연쇄적 영향이 전파되지 않습니다.

ACP 8단계 채널바인딩과 세션 응집력

서브에이전트 간 세션 분열을 방지하기 위해 ACP 8단계 채널바인딩 프로토콜이 적용됩니다. 이 프로토콜은 8단계 우선순위 체계(동일 채널 우선→부모 채널→길드+역할→길드→팀→계정→채널 기본값→폴백 기본값)를 통해 메시지를 결정적 경로로 설정하며, 결정적 경로 설정에는 LLM 토큰 비용이 전혀 발생하지 않는다는 것이 핵심 장점입니다. ACP 세션을 특정 통신 채널에 영구적으로 연결하여 channel:<id> 형식의 영구 식별자를 사용하며, 각 서브에이전트의 격리된 작업 결과를 부모의 채팅 채널로 자동 라우팅합니다. dmScope 격리는 컨텍스트 오염을 방지하는 핵심 메커니즘으로, 각 에이전트가 자신의 도메인 내에서만 작동하도록 제한합니다.

결함 격리와 무상태 설계의 이중 안전망

서브에이전트 풀의 안정성을 위해 결함 격리 메커니즘이 적용됩니다. 개별 서브에이전트의 실패나 비정상 출력이 전체 시스템에 파급되지 않도록 각 에이전트의 실행 영역이 독립적 네임스페이스에서 격리 실행됩니다. 실패한 서브에이전트는 메시지 패싱 기반의 자동 재배치 및 복구 메커니즘에 의해 즉시 재시작되고, 상태가 복구된 워커에게 작업이 재할당되어 파이프라인의 연속성이 보장됩니다. ACP 무상태 설계에 의해 Pause/Resume 단계에서 세션 상태가 명시적 경로에 저장되므로 비정상 종료 상황에서도 Stateless Reconnect가 가능하며, 고아 프로세스 없이 리소스가 자동 정리됩니다.

인지 부담 3단계 분산과 오케스트레이터 패턴

서브에이전트 풀 아키텍처의 핵심 설계 원리 중 하나는 인지 부담의 분산입니다. 개발자의 인지 부담을 오케스트레이터의 고수준 계획, 전문 서브에이전트의 분산 실행, 자동 합성 단계의 3단계로 분리함으로써 단일 에이전트 대비 동시 작업 처리량이 8배 이상 확대됩니다. 오케스트레이터는 원본 작업을 분석하여 동적으로 분해하고 서브에이전트에게 역할별 태스크를 위임하는 중앙 조정자이며, 모든 컨텍스트를 태스크 프롬프트에 명시적으로 전달해야 한다는 설계 원칙이 병렬 실행의 인지 부담 분산 효과를 극대화합니다. 워크스페이스 격리 설계에 의해 서로 다른 서브에이전트가 동일한 파일을 동시에 수정하는 경합 조건이 원천 차단됩니다.

이 주제의 최종 원문 탐색하기

이 지식 허브의 가장 깊고 권위 있는 아키텍처 원문과 전체 맥락은 [여기에서 확인하실 수 있습니다](https://brunch.co.kr/@955079bf143b468/8).

자주 묻는 질문

서브에이전트 풀의 FanOut/FanIn 구조는 어떻게 작동하나요?

FanOut 단계에서 sessions_spawn 명령어로 기본 8개의 서브에이전트가 동시에 배경 세션에 격리 생성되며, 각 에이전트는 독립 네임스페이스에서 태스크를 수행합니다. FanIn 단계에서 ACP 8단계 채널바인딩의 우선순위 라우팅을 통해 모든 결과가 부모 채널에 자동 회수되고 최종 통합 출력으로 변환됩니다.

ACP 8단계 채널바인딩의 핵심 장점은 무엇인가요?

ACP 8단계 채널바인딩은 세션을 특정 통신 채널에 영구 연결하여 메시지를 결정적 경로로 라우팅합니다. 동일 채널 우선→부모 채널→길드+역할→길드→팀→계정→채널 기본값→폴백 기본값의 8단계 우선순위 체계를 갖추고 있으며, 이 과정에서 LLM 토큰 비용이 전혀 발생하지 않는다는 것이 핵심 장점입니다.

서브에이전트 장애 발생 시 시스템은 어떻게 대응하나요?

결함 격리 메커니즘에 의해 장애가 발생한 서브에이전트는 격리 경계 안에서 자동 재구성되며, 메시지 패싱 기반의 자동 재배치 및 복구 메커니즘에 의해 즉시 재시작됩니다. ACP 무상태 설계도 함께 작용하여 비정상 종료 상황에서도 Stateless Reconnect가 가능하며 고아 프로세스 없이 리소스가 자동 정리됩니다.

인지 부담 3단계 분산이란 무엇인가요?

오케스트레이터가 고수준 계획을 세우고, 전문 서브에이전트가 작업을 분산 실행하며, 자동 합성 단계에서 결과를 통합하는 3단계 구조를 통해 개발자의 인지 부담을 분산합니다. 이 설계에 의해 단일 에이전트 대비 동시 작업 처리량이 8배 이상 확대됩니다.