2026년 OpenClaw 멀티 에이전트 오케스트레이션 가이드

멀티 에이전트 오케스트레이션이 중요한 이유

하나의 장수명 에이전트 컨텍스트는 노이즈가 누적됩니다. 리서치 덤프, 실패 시도, 도구 로그가 윈도우를 부풀려 품질이 떨어집니다. OpenClaw는 오케스트레이션을 일급 문제로 취급합니다 — 부모 에이전트가 계획하고 라우팅하며, 워커는 좁은 프롬프트와 격리된 워크스페이스를 받습니다.

팀이 멀티 에이전트 OpenClaw를 도입하는 경우:

• CI/CD 생성이 여러 repo 또는 서비스를 병렬로 건드려야 할 때(벤치마크 데이터에 따르면 유사 작업에서 단일 에이전트 Claude Code 대비 병렬 코드 생성이 약 3.2배 빠름)
• 코드 리뷰에 하나의 모델이 모든 역할을 맡지 않고 독립적 렌즈(보안, 스타일, 커버리지)가 필요할 때
• 장문 문서에서 하나의 에이전트가 리서치, 개요, 초안, 감사를 단일 스레드에 모두 담지 않아도 될 때

실패 모드도 아키텍처적입니다. 격리 없이 같은 메모리 키에 쓰는 다섯 개의 「에이전트」는 경쟁 상태를 만듭니다 — 오케스트레이션 계층이 병합 로직과 타임아웃을 소유해야 합니다.

OpenClaw 오케스트레이션 모델

런타임에 OpenClaw는 게이트웨이 데몬과 설정의 명명된 에이전트 ID로 구성됩니다. 멀티 에이전트 흐름은 다음을 사용합니다:

깊이 경험칙: 두 단계(오케스트레이터 → 워커)가 워크로드의 약 95%를 커버합니다. 세 단계(오케스트레이터 → 팀 리드 → 리프)는 하위 팀이 진정 독립적일 때만 도움이 됩니다 — 디버깅 비용이 급격히 증가합니다.

외부 참고: OpenClaw GitHub 및 maxSpawnDepth / cascade stop 동작에 대한 커뮤니티 아키텍처 노트.

세 가지 오케스트레이션 패턴

패턴 1 — 병렬 팬아웃

적용 시점: 하위 작업이 서로의 출력에 의존하지 않을 때.

형태: 오케스트레이터가 한 턴에 여러 spawn을 발행; 경과 시간 ≈ 가장 느린 워커, 워커 합이 아님.

예시:

• 세 패키지를 동시에 lint
• 세 경쟁사 URL 리서치
• 세 서비스용 단위 테스트 생성

안티패턴: 파이프라인(리서치 + 초안)에 팬아웃 — 리서치가 진행 중인데 초안 작성자가 빈 입력으로 시작.

Orchestrator
 ├── spawn worker-a (scope: package-frontend)
 ├── spawn worker-b (scope: package-api)
 └── spawn worker-c (scope: package-worker)
      → merge summaries → single PR plan

패턴 2 — 순차 파이프라인

적용 시점: 단계 B가 단계 A의 산출물을 필요로 할 때.

형태: 리서치 → 개요 → 구현 → 감사 → 게시. 각 워커는 이전 단계 산출물만 붙여 넣은 깨끗한 컨텍스트를 받습니다.

장점: 초안 작성자가 3,000줄의 원시 리서치 토큰을 끌고 다니지 않음; 감사자는 감사 전 초안 이력을 보지 않음.

비용: 경과 시간은 가산적 — 의존성이 실제일 때만 사용.

패턴 3 — 검증 팬아웃

적용 시점: 정확도가 속도보다 중요할 때(컴플라이언스 텍스트, 인프라 diff, 가격표).

형태: 동일 프롬프트를 2~3 워커에 전달; 오케스트레이터 또는 모니터 에이전트가 출력을 비교; 불일치 시 재시도 또는 사람 에스컬레이션.

비용: 단일 워커 대비 토큰 소비 약 2~3배 — 고위험 병합에만 정당화.

설정 런북

OpenClaw가 이미 설치되어 있다고 가정합니다 — 아니면 먼저 설정 가이드를 완료하세요.

1단계 — openclaw.json에서 에이전트 명단 정의

일반 경로: ~/.openclaw/openclaw.json(릴리스에 맞게 확인).

{
  "agents": {
    "list": [
      {
        "id": "orchestrator",
        "default": true,
        "workspace": "~/.openclaw/workspace-orchestrator",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "coder",
        "workspace": "~/.openclaw/workspace-coder",
        "sandbox": { "mode": "all", "scope": "agent" },
        "skills": ["git", "nodejs", "testing"]
      },
      {
        "id": "researcher",
        "workspace": "~/.openclaw/workspace-research",
        "sandbox": { "mode": "all", "scope": "agent" },
        "skills": ["web", "docs"]
      }
    ]
  },
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["orchestrator", "coder", "researcher"]
    }
  }
}

2단계 — 워커별 워크스페이스 격리

각 워커 ID는 별도 워크스페이스 디렉터리에 매핑되어야 합니다. 병렬 팬아웃 워커 간 쓰기 가능 워크스페이스를 공유하지 마세요 — 파일 경쟁이 병합을 손상시킵니다.

mkdir -p ~/.openclaw/workspace-{orchestrator,coder,researcher}

3단계 — 라우팅 테이블이 있는 오케스트레이터 시스템 프롬프트 작성

오케스트레이터 프롬프트에 다음을 나열해야 합니다:

1. 사용 가능한 워커 ID와 스킬
2. 팬아웃 vs 파이프라인 선택 기준
3. spawn당 타임아웃(예: 리서치 120초, 코드 생성 300초)
4. 실패 정책: 한 번 재시도 후 에스컬레이션

서브 에이전트 컨텍스트 규칙: 워커는 AGENTS.md + TOOLS.md + 작업 페이로드만 받아야 합니다 — 전체 오케스트레이터 스레드가 아닙니다.

4단계 — 신뢰하지 않는 워커에 샌드박스 활성화

조율 도구를 위해 오케스트레이터는 sandbox.mode: off 유지; 워커가 셸 또는 네트워크를 실행할 수 있으면 coder/researcher에 mode: all 샌드박스 적용.

5단계 — spawn 한도 설정

OpenClaw 버전 문서에 따라 maxChildren / maxSpawnDepth를 구성하세요. RAM과 API 속도 제한을 측정할 때까지 최대 3개 병렬 자식으로 시작.

6단계 — openclaw doctor로 테스트

openclaw doctor
openclaw status

CI에서 팬아웃을 실행하기 전에 중복 hook 또는 충돌하는 에이전트 바인딩을 해결하세요.

7단계 — 제어된 팬아웃 작업 실행

오케스트레이터 지시 예시(개념적):

Task: Review modules auth/, billing/, notify/ in parallel.
Spawn researcher once per directory with identical rubric.
Merge into one markdown report with per-module sections.
Timeout: 180s per worker. If one worker fails, continue with partial merge and flag gaps.

테스트 중 피크 RSS를 기록 — 벤치마크 메모리 사용량과 비교.

8단계 — CI 트리거 연결(선택)

게이트웨이를 로컬에 노출; 파이프라인에서 SSH + REST로 트리거. 산출물은 작업 범위 경로에 저장:

export TASK_ID="${GITHUB_RUN_ID}"
mkdir -p "/tmp/openclaw-runs/${TASK_ID}"

메모리, 상태, 병합 규율

병합 계약: 오케스트레이터는 출력 스키마(JSON 섹션, 필수 제목)를 사전에 정의해야 합니다. 워커는 인계 전 스키마에 대해 검증.

하드웨어 및 RAM 예산

Apple Silicon M4급 호스트에서 측정(벤치마크 글 참조):

오케스트레이션에 GPU는 필요 없습니다 — 병목은 API 속도 제한과 워크스페이스 동기화의 디스크 I/O입니다. 서울 노드는 Anthropic API까지 중앙값 RTT 29ms입니다. 리전별 노드 크기(API 지연만)는 M4 리전 매트릭스를 참조하세요.

장애 처리

오케스트레이터 프롬프트에 명시적으로 정의:

야간 CI 실패는 종종 타임아웃 누락에서 비롯됩니다 — 기본 「영구 대기」가 게이트웨이를 멈춥니다.

권장 경로

한 줄 규칙: 워커 B 프롬프트가 워커 A 출력을 필요로 하면 파이프라인. 아니면 팬아웃.

FAQ

OpenClaw는 몇 개의 에이전트를 병렬로 실행할 수 있나요?

고정된 전역 상한은 없습니다 — 실질적 제한은 RAM, API 속도 제한, 병합 복잡도입니다. 병렬 워커 3개로 시작해 ps 또는 활성 상태 보기로 피크 RSS를 측정한 뒤 확장하세요.

팬아웃은 항상 속도를 높이나요?

작업이 서로 독립적일 때만 그렇습니다. 의존 단계에 팬아웃을 잘못 적용하면 조용히 실패합니다(빈 초안, 중복 작업). 패턴을 선택하기 전에 항상 의존 관계를 매핑하세요.

agentToAgent와 서브 에이전트 spawn의 차이는 무엇인가요?

agentToAgent는 명명된 영속 에이전트(영업 vs 지원 봇)에 메시지를 보냅니다. 서브 에이전트 spawn은 단일 작업 분기를 위한 임시 워커를 만듭니다. CI 오케스트레이션은 보통 spawn에 의존하고, 멀티테넌트 챗봇은 agentToAgent와 bindings를 사용합니다.

클라우드 렌탈 없이 Mac Mini에서 오케스트레이션을 실행할 수 있나요?

예. Node 22.19+, 충분한 RAM, 안정적인 네트워크를 갖춘 상시 가동 Mac이면 됩니다. 노트북이 절전 모드로 긴 게이트웨이 세션을 끊을 때 팀은 로컬 또는 호스팅 전용 Mac mini를 사용합니다.

TradingAgents나 MiroFish와는 어떤 관계인가요?

TradingAgents는 트레이딩 회사 토론(LangGraph)을 오케스트레이션합니다. MiroFish는 예측을 위한 소셜 swarm을 오케스트레이션합니다. OpenClaw는 개발 워크플로(코드, CI, 리뷰)를 오케스트레이션합니다. 도메인에 맞는 프레임워크를 선택하세요 — 상호 보완적이며 교체 가능하지 않습니다.