Multi-Agent Routing 가이드

하나의 서버에서 여러 개의 AI 에이전트를 운영하다 보면 금방 한계에 부딪히곤 해요. 업무용 계정과 개인용 계정의 메시지가 섞이거나, 특정 에이전트에게만 허용해야 할 도구가 다른 곳에서 실행되는 식이죠. 특히 여러 사용자가 하나의 Gateway를 공유해야 할 때는 데이터와 설정의 완벽한 격리가 필수적이에요.

이런 복잡한 상황을 해결하기 위해 OpenClaw는 Multi-Agent Routing 기능을 제공해요. 각 에이전트에게 독립된 ‘두뇌’를 부여하고, 들어오는 메시지를 규칙에 따라 정확한 에이전트에게 전달할 수 있습니다.

필요한 것

시작하기 전에 다음 항목들이 준비되었는지 확인해 주세요.

~/.openclaw/openclaw.json 설정 파일 (또는 OPENCLAW_CONFIG_PATH)
~/.openclaw 상태 디렉토리
에이전트별 Workspace 폴더
에이전트별 agentDir 및 Session 저장소

빠른 시작

새로운 독립 에이전트를 추가하는 가장 빠른 방법은 에이전트 마법사를 사용하는 거예요. 5분 안에 설정을 마칠 수 있습니다.

새로운 에이전트(예: work)를 추가합니다.

openclaw agents add work

설정된 에이전트와 Binding 상태를 확인합니다.

openclaw agents list --bindings

에이전트를 추가하면 Gateway가 메시지를 어디로 보낼지 결정하는 bindings가 생성됩니다.

에이전트의 구성 요소

OpenClaw에서 Agent는 완전히 독립된 실행 단위를 의미해요. 각 에이전트는 다음 요소들을 개별적으로 가집니다.

Workspace: AGENTS.md, SOUL.md 등 페르소나 규칙과 로컬 메모가 담긴 폴더입니다.
State directory (agentDir): 인증 프로필, 모델 레지스트리, 개별 설정이 저장됩니다.
Session store: 채팅 기록과 라우팅 상태가 ~/.openclaw/agents/<agentId>/sessions 아래에 저장됩니다.
Auth profiles: 인증 정보는 에이전트마다 별도로 관리됩니다.

주의할 점은 agentDir를 여러 에이전트가 공유하면 안 된다는 거예요. 인증 충돌이나 세션 꼬임이 발생할 수 있거든요. 인증 정보를 공유하고 싶다면 auth-profiles.json 파일을 다른 에이전트의 agentDir로 복사해서 사용하세요.

Routing 규칙 (메시지 전달 순서)

Gateway는 메시지가 들어오면 결정론적(Deterministic)인 규칙에 따라 에이전트를 선택해요. 가장 구체적인 조건이 우선권을 가집니다.

peer 일치 (특정 DM, 그룹, 채널 ID)
guildId 일치 (Discord)
teamId 일치 (Slack)
채널의 accountId 일치
채널 레벨 일치 (accountId: "*")
기본 에이전트로 폴백 (default 설정된 에이전트, 없으면 리스트의 첫 번째 에이전트)

주요 활용 예시

1. 하나의 WhatsApp 번호를 여러 명이 공유하기

하나의 WhatsApp 계정을 쓰더라도 발신자 번호에 따라 다른 에이전트에게 연결할 수 있어요.

{
  agents: {
    list: [
      { id: "alex", workspace: "~/.openclaw/workspace-alex" },
      { id: "mia", workspace: "~/.openclaw/workspace-mia" },
    ],
  },
  bindings: [
    {
      agentId: "alex",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } },
    },
    {
      agentId: "mia",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } },
    },
  ],
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551230001", "+15551230002"],
    },
  },
}

2. 채널별로 다른 모델 사용하기

WhatsApp은 가벼운 모델로, Telegram은 고성능 모델로 라우팅하는 설정도 가능합니다.

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-5",
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.openclaw/workspace-opus",
        model: "anthropic/claude-opus-4-6",
      },
    ],
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}

에이전트별 Sandbox 및 도구 설정

v2026.1.6 버전부터는 각 에이전트마다 독립적인 Sandbox와 도구 제한을 걸 수 있어요. 이를 통해 얻을 수 있는 장점은 다음과 같습니다.

보안 격리: 신뢰할 수 없는 에이전트의 도구 사용을 제한합니다.
리소스 제어: 특정 에이전트만 컨테이너 환경에서 실행합니다.
유연한 정책: 에이전트마다 다른 권한을 부여합니다.
데이터 보호: 에이전트 간의 간섭을 방지합니다.

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",
          scope: "agent",
          docker: {
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],
          deny: ["exec", "write", "edit", "apply_patch"],
        },
      },
    ],
  },
}

문제 해결

인증/세션 충돌: 여러 에이전트가 동일한 agentDir를 바라보고 있지 않은지 확인하세요. 각 에이전트는 반드시 고유한 디렉토리를 가져야 합니다.
메시지 라우팅 실패: bindings의 우선순위를 확인하세요. peer 매칭이 채널 전체 매칭보다 위에 있어야 의도한 대로 작동합니다.

설정 과정에서 도움이 필요하다면 AI Setup Assistant에게 물어보세요!

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.