멀티 에이전트 라우팅

하나의 Gateway 프로세스에서 여러 격리된 에이전트를 실행합니다. 각 에이전트는 자체 워크스페이스, 상태 디렉터리(agentDir), SQLite 기반 세션 기록을 가지며, 여러 채널 계정(예: 두 개의 WhatsApp 번호)도 사용할 수 있습니다. 수신 메시지는 바인딩을 통해 올바른 에이전트로 라우팅됩니다.

에이전트는 워크스페이스 파일, 인증 프로필, 모델 레지스트리, 세션 저장소를 포함하는 페르소나별 전체 범위입니다. 바인딩은 채널 계정(Slack 워크스페이스, WhatsApp 번호 등)을 이러한 에이전트 중 하나에 매핑합니다.

에이전트란 무엇인가

각 에이전트에는 다음 항목이 개별적으로 제공됩니다.

• 워크스페이스: 파일, AGENTS.md/SOUL.md/USER.md, 로컬 메모, 페르소나 규칙.
• 상태 디렉터리(agentDir): 인증 프로필, 모델 레지스트리, 에이전트별 구성.
• 세션 저장소: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite에 저장되는 채팅 기록 및 라우팅 상태.

인증 프로필은 에이전트별로 관리되며 다음 위치에서 읽습니다.

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Skills는 각 에이전트 워크스페이스와 ~/.openclaw/skills 같은 공유 루트에서 로드된 다음, 적용되는 에이전트 Skills 허용 목록에 따라 필터링됩니다. 공유 기준에는 agents.defaults.skills를 사용하고, 에이전트별 대체 항목에는 agents.list[].skills를 사용하십시오(명시적 항목은 기본값을 대체하며 병합되지 않습니다). Skills: 에이전트별 및 공유 및 Skills: 에이전트 허용 목록을 참조하십시오.

Plugin 소유 저장소는 해당 Plugin의 구성을 따릅니다. 두 번째 에이전트를 추가해도 모든 전역 Plugin 저장소가 자동으로 분리되지는 않습니다. 예를 들어 페르소나 간에 컴파일된 위키 지식을 공유하지 않아야 하는 경우 에이전트별 Memory Wiki 볼트를 구성하십시오.

경로

단일 에이전트 모드(기본값)

아무것도 구성하지 않으면 OpenClaw는 하나의 에이전트를 실행합니다.

• agentId의 기본값은 main입니다.
• 세션 키는 agent:main:<mainKey> 형식입니다(기본 mainKey는 main).
• 워크스페이스의 기본값은 ~/.openclaw/workspace입니다(OPENCLAW_PROFILE이 default 이외의 값으로 설정된 경우 workspace-<profile>).
• 상태의 기본값은 ~/.openclaw/agents/main/agent입니다.

에이전트 도우미

격리된 새 에이전트를 추가합니다.

openclaw agents add work

플래그: --workspace <dir>, --model <id>, --agent-dir <dir>, --bind <channel[:accountId]>(반복 가능), --non-interactive(--workspace 필요).

수신 메시지를 라우팅하도록 bindings를 추가한 다음(마법사가 이 작업을 제안합니다) 확인합니다.

openclaw agents list --bindings

빠른 시작

openclaw agents add codingopenclaw agents add social

openclaw channels login --channel whatsapp --account work

openclaw gateway restartopenclaw agents list --bindingsopenclaw channels status --probe

여러 에이전트, 여러 페르소나

구성된 각 agentId는 핵심 에이전트 상태에 대해 서로 구분되는 페르소나 경계입니다.

• 채널별로 서로 다른 계정(accountId별).
• 서로 다른 성격(에이전트별 AGENTS.md/SOUL.md).
• 별도의 인증 및 세션. 에이전트 간 접근은 명시적 기능이나 Plugin 구성을 통해서만 활성화됩니다.

이를 통해 여러 사람이 하나의 Gateway를 공유하면서 핵심 에이전트 상태를 서로 분리할 수 있습니다.

에이전트별 Memory Wiki 볼트

Memory Wiki는 기본적으로 하나의 전역 볼트를 사용합니다. 지원 에이전트가 컴파일한 지식을 마케팅 에이전트의 지식과 분리하려면 plugins.entries.memory-wiki.config.vault.scope를 agent로 설정합니다.

{  plugins: {    entries: {      "memory-wiki": {        enabled: true,        config: {          vault: {            scope: "agent",            path: "~/.openclaw/wiki",          },        },      },    },  },}

구성된 경로는 상위 디렉터리입니다. OpenClaw는 정규화된 에이전트 ID를 추가하여 ~/.openclaw/wiki/support 및 ~/.openclaw/wiki/marketing과 같은 경로를 생성합니다. 여러 에이전트가 구성된 경우 에이전트 범위 CLI 및 Gateway 작업에는 에이전트를 명시적으로 지정해야 합니다. 브리지 필터링, 마이그레이션 및 신뢰 경계에 관한 자세한 내용은 Memory Wiki 에이전트별 볼트를 참조하십시오.

에이전트 간 QMD 메모리 검색

한 에이전트가 다른 에이전트의 QMD 세션 트랜스크립트를 검색할 수 있도록 하려면 agents.list[].memorySearch.qmd.extraCollections 아래에 추가 컬렉션을 추가합니다. 모든 에이전트가 동일한 컬렉션을 공유해야 하는 경우 agents.defaults.memorySearch.qmd.extraCollections를 사용합니다.

{  agents: {    defaults: {      workspace: "~/workspaces/main",      memorySearch: {        qmd: {          extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],        },      },    },    list: [      {        id: "main",        workspace: "~/workspaces/main",        memorySearch: {          qmd: {            extraCollections: [{ path: "notes" }], // 워크스페이스 내부에서 해석됨 -> "notes-main"이라는 이름의 컬렉션          },        },      },      { id: "family", workspace: "~/workspaces/family" },    ],  },  memory: {    backend: "qmd",    qmd: { includeDefaultMemory: false },  },}

추가 컬렉션 경로는 에이전트 간에 공유할 수 있지만, 경로가 에이전트 워크스페이스 외부에 있으면 name을 명시적으로 유지해야 합니다. 워크스페이스 내부의 경로는 에이전트 범위로 유지되므로 각 에이전트가 자체 트랜스크립트 검색 세트를 보유합니다.

하나의 WhatsApp 번호, 여러 사용자(DM 분리)

하나의 WhatsApp 계정에서 발신자의 E.164(+15551234567)를 peer.kind: "direct"와 일치시켜 서로 다른 WhatsApp DM을 서로 다른 에이전트로 라우팅합니다. 응답은 여전히 동일한 WhatsApp 번호에서 전송되며, 에이전트별 발신자 ID는 없습니다.

{  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"],    },  },}

DM 접근 제어(페어링/허용 목록)는 에이전트별이 아니라 WhatsApp 계정별로 전역 적용됩니다. 공유 그룹의 경우 그룹을 하나의 에이전트에 바인딩하거나 브로드캐스트 그룹을 사용합니다.

라우팅 규칙

바인딩은 결정론적이며 가장 구체적인 항목이 우선합니다. 전체 계층 순서(정확한 피어, 상위 피어, 피어 와일드카드, 길드+역할, 길드, 팀, 계정, 채널, 기본 에이전트)는 채널 라우팅을 참조하십시오. 여기서 강조할 만한 몇 가지 규칙은 다음과 같습니다.

• 동일한 계층에서 여러 바인딩이 일치하면 구성 순서상 첫 번째 바인딩이 우선합니다.
• 바인딩에 여러 일치 필드(예: peer + guildId)가 설정되어 있으면 지정된 모든 필드가 일치해야 합니다(AND 의미 체계).
• accountId가 생략된 바인딩은 모든 계정이 아니라 기본 계정에만 일치합니다. 채널 전체 대체 경로에는 accountId: "*"를, 하나의 계정에는 accountId: "<name>"을 사용합니다. 동일한 바인딩을 명시적 계정 ID와 함께 다시 추가하면 기존 채널 전용 바인딩을 중복 생성하지 않고 업그레이드합니다.

여러 계정/전화번호

여러 계정을 지원하는 채널(예: WhatsApp)은 accountId를 사용하여 각 로그인을 식별합니다. 각 accountId는 자체 에이전트로 라우팅되므로 하나의 서버에서 세션을 혼합하지 않고 여러 전화번호를 호스팅할 수 있습니다.

accountId가 생략될 때 사용할 계정을 선택하려면 channels.<channel>.defaultAccount를 설정합니다. 설정하지 않으면 OpenClaw는 default가 있는 경우 이를 사용하고, 그렇지 않으면 구성된 첫 번째 계정 ID(정렬 기준)를 사용합니다.

여러 계정을 지원하는 채널: discord, feishu, googlechat, imessage, irc, line, mattermost, matrix, nextcloud-talk, nostr, signal, slack, telegram, whatsapp, zalo, zalouser.

개념

• agentId: 하나의 "두뇌"(워크스페이스, 에이전트별 인증, 에이전트별 세션 저장소).
• accountId: 하나의 채널 계정 인스턴스(예: WhatsApp 계정 personal과 biz).
• binding: (channel, accountId, peer) 및 선택적으로 길드/팀 ID를 기준으로 수신 메시지를 agentId에 라우팅합니다.
• 직접 채팅은 agent:<agentId>:<mainKey>로 통합됩니다(에이전트별 "메인", session.mainKey 참조).

플랫폼 예시

{  agents: {    list: [      { id: "main", workspace: "~/.openclaw/workspace-main" },      { id: "coding", workspace: "~/.openclaw/workspace-coding" },    ],  },  bindings: [    { agentId: "main", match: { channel: "discord", accountId: "default" } },    { agentId: "coding", match: { channel: "discord", accountId: "coding" } },  ],  channels: {    discord: {      groupPolicy: "allowlist",      accounts: {        default: {          token: "DISCORD_BOT_TOKEN_MAIN",          guilds: {            "123456789012345678": {              channels: {                "222222222222222222": { allow: true, requireMention: false },              },            },          },        },        coding: {          token: "DISCORD_BOT_TOKEN_CODING",          guilds: {            "123456789012345678": {              channels: {                "333333333333333333": { allow: true, requireMention: false },              },            },          },        },      },    },  },}

{  agents: {    list: [      { id: "main", workspace: "~/.openclaw/workspace-main" },      { id: "alerts", workspace: "~/.openclaw/workspace-alerts" },    ],  },  bindings: [    { agentId: "main", match: { channel: "telegram", accountId: "default" } },    { agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } },  ],  channels: {    telegram: {      accounts: {        default: {          botToken: "123456:ABC...",          dmPolicy: "pairing",        },        alerts: {          botToken: "987654:XYZ...",          dmPolicy: "allowlist",          allowFrom: ["tg:123456789"],        },      },    },  },}

openclaw channels login --channel whatsapp --account personalopenclaw channels login --channel whatsapp --account biz

{  agents: {    list: [      {        id: "home",        default: true,        name: "Home",        workspace: "~/.openclaw/workspace-home",        agentDir: "~/.openclaw/agents/home/agent",      },      {        id: "work",        name: "Work",        workspace: "~/.openclaw/workspace-work",        agentDir: "~/.openclaw/agents/work/agent",      },    ],  },   // 결정론적 라우팅: 첫 번째 일치 항목이 우선합니다(가장 구체적인 항목부터).  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },     // 선택적 피어별 재정의(예: 특정 그룹을 업무용 에이전트로 전송).    {      agentId: "work",      match: {        channel: "whatsapp",        accountId: "personal",        peer: { kind: "group", id: "1203630...@g.us" },      },    },  ],   // 기본적으로 꺼짐: 에이전트 간 메시징은 명시적으로 활성화하고 허용 목록에 추가해야 합니다.  tools: {    agentToAgent: {      enabled: false,      allow: ["home", "work"],    },  },   channels: {    whatsapp: {      accounts: {        personal: {          // 선택적 재정의. 기본값: ~/.openclaw/credentials/whatsapp/personal          // authDir: "~/.openclaw/credentials/whatsapp/personal",        },        biz: {          // 선택적 재정의. 기본값: ~/.openclaw/credentials/whatsapp/biz          // authDir: "~/.openclaw/credentials/whatsapp/biz",        },      },    },  },}

일반적인 패턴

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

{  agents: {    list: [      {        id: "chat",        name: "Everyday",        workspace: "~/.openclaw/workspace-chat",        model: "anthropic/claude-sonnet-4-6",      },      {        id: "opus",        name: "Deep Work",        workspace: "~/.openclaw/workspace-opus",        model: "anthropic/claude-opus-4-6",      },    ],  },  bindings: [    {      agentId: "opus",      match: { channel: "whatsapp", accountId: "*", peer: { kind: "direct", id: "+15551234567" } },    },    { agentId: "chat", match: { channel: "whatsapp", accountId: "*" } },  ],}

{  agents: {    list: [      {        id: "family",        name: "Family",        workspace: "~/.openclaw/workspace-family",        identity: { name: "Family Bot" },        groupChat: {          mentionPatterns: ["@family", "@familybot", "@Family Bot"],        },        sandbox: {          mode: "all",          scope: "agent",        },        tools: {          allow: [            "exec",            "read",            "sessions_list",            "sessions_history",            "sessions_send",            "sessions_spawn",            "session_status",          ],          deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"],        },      },    ],  },  bindings: [    {      agentId: "family",      match: {        channel: "whatsapp",        peer: { kind: "group", id: "120363999999999999@g.us" },      },    },  ],}

에이전트별 샌드박스 및 도구 구성

각 에이전트는 자체 샌드박스 및 도구 제한을 가질 수 있습니다.

{  agents: {    list: [      {        id: "personal",        workspace: "~/.openclaw/workspace-personal",        sandbox: {          mode: "off",  // 개인 에이전트에는 샌드박스 없음        },        // 도구 제한 없음 - 모든 도구 사용 가능      },      {        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"],    // 그 외 도구 거부        },      },    ],  },}

이 구성은 다음과 같은 이점을 제공합니다.

• 보안 격리: 신뢰할 수 없는 에이전트의 도구를 제한합니다.
• 리소스 제어: 일부 에이전트는 샌드박스에서 실행하면서 나머지는 호스트에서 유지합니다.
• 유연한 정책: 에이전트마다 서로 다른 권한을 적용합니다.

자세한 예시는 다중 에이전트 샌드박스 및 도구를 참조하십시오.

관련 항목

• ACP 에이전트 — 외부 코딩 하네스 실행
• 채널 라우팅 — 메시지가 에이전트로 라우팅되는 방식
• 프레즌스 — 에이전트의 프레즌스 및 가용성
• 세션 — 세션 격리 및 라우팅
• 하위 에이전트 — 백그라운드 에이전트 실행 생성