Multi-agent routing

기준일: 2026-07-26
공식 기준: Multi-agent routing

Multi-agent routing 문서는 OpenClaw 공식 문서(concepts/multi-agent)를 한국어로 정리한 가이드입니다. Multi-agent routing: agent boundaries, channel accounts, and bindings 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Multi-agent routing: agent boundaries, channel accounts, and bindings

한국어 가이드 범위: concepts/multi-agent 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• What is one agent
• Paths
• Single-agent mode (default)
• Agent helper
• 빠른 시작
• Multiple agents, multiple personas
• Per-agent Memory Wiki vaults
• Cross-agent QMD memory search
• One WhatsApp number, multiple people (DM split)
• Routing rules
• Multiple accounts / phone numbers
• 개념
• Platform examples
• Common patterns
• Per-agent sandbox and tool configuration
• 관련 문서

상세 내용

본문

Run multiple isolated agents in one Gateway process, each with its own workspace, state directory (agentDir), and SQLite-backed session history, plus multiple channel accounts (e.g. two WhatsApp numbers). Inbound messages route to the right agent through bindings.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

What is one agent

sessions_history is the safer cross-session recall path: it returns a bounded, redacted view, not a raw transcript dump. It strips thinking-block signatures, tool-result payload details, scaffolding, tool-call XML tags (, ``, and their plural/downgraded forms), and MiniMax tool-call XML, then truncates and caps output by byte size.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Workspace: files, AGENTS.md/SOUL.md/USER.md, local notes, persona rules.
• State directory (agentDir): auth profiles, model registry, per-agent config.
• Session store: chat history and routing state in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.

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

Paths

What	Default	Override
Config	~/.openclaw/openclaw.json	OPENCLAW_CONFIG_PATH
State dir	~/.openclaw	OPENCLAW_STATE_DIR
Default agent's workspace	~/.openclaw/workspace (or workspace-<profile> when OPENCLAW_PROFILE is set)	agents.entries.*.workspace, then agents.defaults.workspace, or OPENCLAW_WORKSPACE_DIR
Other agents' workspace	<stateDir>/workspace-<agentId> (or <agents.defaults.workspace>/<agentId> when set)	agents.entries.*.workspace
Agent dir	~/.openclaw/agents/<agentId>/agent	agents.entries.*.agentDir
Sessions and transcripts	~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite	—
Legacy/archive session artifacts	~/.openclaw/agents/<agentId>/sessions	—

Single-agent mode (default)

If you configure nothing, OpenClaw runs one agent:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• agentId defaults to main.
• Sessions key as agent:main:<mainKey> (default mainKey is main).
• Workspace defaults to ~/.openclaw/workspace (or workspace-<profile> when OPENCLAW_PROFILE is set to something other than default).
• State defaults to ~/.openclaw/agents/main/agent.

Agent helper

Flags: --workspace , --model , --agent-dir , --bind (repeatable), --non-interactive (requires --workspace).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw agents add work

openclaw agents list --bindings

빠른 시작

Each agent gets its own workspace with SOUL.md, AGENTS.md, and optional USER.md, plus a dedicated agentDir and session store under ~/.openclaw/agents/.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Discord: one bot per agent, enable Message Content Intent, copy each token.
• Telegram: one bot per agent via BotFather, copy each token.
• WhatsApp: link each phone number per account.

openclaw agents add coding
    openclaw agents add social

openclaw channels login --channel whatsapp --account work

openclaw gateway restart
    openclaw agents list --bindings
    openclaw channels status --probe

Multiple agents, multiple personas

Each configured agentId is a distinct persona boundary for core agent state:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Different accounts per channel (per accountId).
• Different personalities (per-agent AGENTS.md/SOUL.md).
• Separate auth and sessions, with cross-agent access enabled only through explicit features or plugin configuration.

Per-agent Memory Wiki vaults

Memory Wiki uses one global vault by default. To keep a support agent's compiled knowledge separate from a marketing agent's, set plugins.entries.memory-wiki.config.vault.scope to agent:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

Cross-agent QMD memory search

To let one agent search another agent's QMD session transcripts, add extra collections under agents.entries.*.memory.search.qmd.extraCollections. Use memory.search.qmd.extraCollections when every agent should share the same collections.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  agents: {
    defaults: {
      workspace: "~/workspaces/main",
    },
    entries: {
      main: {
        workspace: "~/workspaces/main",
        memory: {
          search: {
            qmd: {
              extraCollections: [{ path: "notes" }], // resolves inside workspace -> collection named "notes-main"
            },
          },
        },
      },
      family: { workspace: "~/workspaces/family" },
    },
  },
  memory: {
    backend: "qmd",
    search: {
      qmd: {
        extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],
      },
    },
    qmd: { includeDefaultMemory: false },
  },
}

One WhatsApp number, multiple people (DM split)

Route different WhatsApp DMs to different agents on one WhatsApp account by matching sender E.164 (+15551234567) with peer.kind: "direct". Replies still come from the same WhatsApp number — there is no per-agent sender identity.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

Routing rules

Bindings are deterministic and most-specific wins. See Channel routing for the full tier order (exact peer, parent peer, peer wildcard, guild+roles, guild, team, account, channel, default agent). A few rules worth calling out here:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• If multiple bindings match within the same tier, the first one in config order wins.
• If a binding sets multiple match fields (for example peer + guildId), all specified fields must match (AND semantics).
• A binding that omits accountId matches only the default account, not every account. Use accountId: "*" for a channel-wide fallback, or accountId: "<name>" for one account. Adding the same binding again with an explicit account id upgrades the existing channel-only binding instead of duplicating it.

Multiple accounts / phone numbers

Channels that support multiple accounts (e.g. WhatsApp) use accountId to identify each login. Each accountId routes to its own agent, so one server can host multiple phone numbers without mixing sessions.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

개념

주요 항목:

• agentId: one "brain" (workspace, per-agent auth, per-agent session store).
• accountId: one channel account instance (e.g. WhatsApp account personal vs biz).
• binding: routes inbound messages to an agentId by (channel, accountId, peer), and optionally guild/team ids.
• Direct chats collapse to agent:<agentId>:<mainKey> (per-agent "main"; see session.mainKey).

Platform examples

Each Discord bot account maps to a unique accountId. Bind each account to an agent and keep allowlists per bot.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Invite each bot to the guild and enable Message Content Intent.
• Tokens live in channels.discord.accounts.<id>.token (default account can use DISCORD_BOT_TOKEN).
• Create one bot per agent with BotFather and copy each token.
• Tokens live in channels.telegram.accounts.<id>.botToken (default account can use TELEGRAM_BOT_TOKEN).
• For multiple bots in the same Telegram group, invite each bot and mention the one that should answer.
• Disable BotFather Privacy Mode for each group bot (/setprivacy -> Disable), then remove and re-add the bot so Telegram applies the setting.
• Allow groups with channels.telegram.groups, or use groupPolicy: "open" only for trusted group deployments.
• Put sender user IDs in groupAllowFrom. Group and supergroup IDs belong in channels.telegram.groups, not groupAllowFrom.
• Bind by accountId so each bot routes to its own agent.

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

      // Deterministic routing: first match wins (most-specific first).
      bindings: [
        { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
        { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },

        // Optional per-peer override (example: send a specific group to work agent).
        {
          agentId: "work",
          match: {
            channel: "whatsapp",
            accountId: "personal",
            peer: { kind: "group", id: "1203630...@g.us" },
          },
        },
      ],

      // Off by default: agent-to-agent messaging must be explicitly enabled + allowlisted.
      tools: {
        agentToAgent: {
          enabled: false,
          allow: ["home", "work"],
        },
      },

      channels: {
        whatsapp: {
          accounts: {
            personal: {
              // Optional override. Default: ~/.openclaw/credentials/whatsapp/personal
              // authDir: "~/.openclaw/credentials/whatsapp/personal",
            },
            biz: {
              // Optional override. Default: ~/.openclaw/credentials/whatsapp/biz
              // authDir: "~/.openclaw/credentials/whatsapp/biz",
            },
          },
        },
      },
    }

Common patterns

Split by channel: route WhatsApp to a fast everyday agent and Telegram to an Opus agent.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

Per-agent sandbox and tool configuration

Each agent can have its own sandbox and tool restrictions:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Security isolation: restrict tools for untrusted agents.
• Resource control: sandbox specific agents while keeping others on host.
• Flexible policies: different permissions per agent.

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off",  // No sandbox for personal agent
        },
        // No tool restrictions - all tools available
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",     // Always sandboxed
          scope: "agent",  // One container per agent
          docker: {
            // Optional one-time setup after container creation
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],                    // Only read tool
          deny: ["exec", "write", "edit", "apply_patch"],    // Deny others
        },
      },
    ],
  },
}

관련 문서

주요 항목:

• ACP agents — running external coding harnesses
• Channel routing — how messages route to agents
• Presence — agent presence and availability
• Session — session isolation and routing
• Sub-agents — spawning background agent runs

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/multi-agent
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

openclaw agents add work

openclaw agents list --bindings

openclaw agents add coding
    openclaw agents add social

openclaw channels login --channel whatsapp --account work

openclaw gateway restart
    openclaw agents list --bindings
    openclaw channels status --probe

관련 링크

• 공식 원문: concepts/multi-agent
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.