Practical AI Guides

English

简体中文

English

简体中文

Appearance

Multi-agent collaboration: run multiple experts in one Gateway ​

OpenClaw's multi-agent architecture can run multiple mutually isolated agents in one Gateway process: each agent has its own workspace, state directory (agentDir), and SQLite-based session history, and can also be attached to multiple channel accounts at the same time (for example, two WhatsApp numbers). Inbound messages are routed to the correct agent via binding.

When to use this ​

  • You want a "work Claw" and a "life Claw" with persona, memory, and credentials that never interfere with each other.
  • You have multiple channel accounts of the same kind—two WhatsApp numbers, two Slack workspaces—and want to connect each to a different expert.
  • A team shares one deployment, with different members or business lines each having a dedicated agent.

First, distinguish the concepts: this page covers multi-agent routing by channel account. The repository also has documentation for the subagents and agent-send tools, which describe another way for agents to cooperate with each other.

Prerequisites ​

  • Read Scenario walkthroughs: choose your route and confirm that multi-agent is the route you want.
  • Have a Gateway already running—multi-agent does not require a second process.
  • Plan the division of labor clearly: which channel account belongs to which agent, and write each expert's persona rules into its own AGENTS.md/SOUL.md.

Follow along: get multiple experts running in three steps ​

Step 1: use openclaw agents add to create multiple expert agents ​

Why create a separate agent for each expert? Because an agent is a complete persona scope that comes with three things:

  • Workspace: files, AGENTS.md/SOUL.md/USER.md, local notes, persona rules.
  • State directory agentDir: auth profiles, model registry, per-agent configuration, by default under ~/.openclaw/agents/<agentId>/agent.
  • Session store: chat history and routing state, stored in <agentDir>/openclaw-agent.sqlite, which under the default layout is ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.

Run agents add once for each expert—the example creates a "life Claw" and a "work Claw":

bash
openclaw agents add home
openclaw agents add work

Common flags: --role <role> (apply a role template), --workspace <dir>, --model <id>, --agent-dir <dir>, --bind <channel[:accountId]> (repeatable, creates the binding in passing at creation time); --non-interactive must be paired with --workspace unless --role is specified.

You should see: each agent gets its own workspace (including SOUL.md, AGENTS.md, optionally USER.md), an independent agentDir and session store, with agent files landing under ~/.openclaw/agents/<agentId> by default. The creation wizard will also ask whether to add a binding right now—you can skip it and write it by hand in the next step.

Step 2: use bindings to connect channel accounts to the corresponding agents ​

A binding only decides "which agent this message belongs to"—it does not create a channel account or grant access, so configure the accounts first, then bind. One Gateway can host multiple accounts, for example two WhatsApp numbers bound to two experts respectively.

First, prepare a channel account for each agent:

bash
openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account biz

Then connect agents and accounts in ~/.openclaw/openclaw.json (JSON5): agents.entries lists the agents, bindings declares the routing.

json5
{
  agents: {
    entries: {
      home: {
        workspace: "~/.openclaw/workspace-home",
        agentDir: "~/.openclaw/agents/home/agent",
      },
      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" } },
  ],
}

The difference between account-level and session-level bindings—choose as needed:

  • Account-level: just write channel + accountId, and all messages on the account belong to this agent. accountId: "*" is the channel-level fallback; omitting accountId matches only the default account of that channel.
  • Session-level: add match.peer (kind takes direct/group/channel, using the channel's stable peer ID, not the display name) to route only a single conversation to the expert.
  • Priority: specific conversations and group matches win over account-level and channel fallbacks; within the same level, first-come-first-served by configuration order.

You should see: valid binding changes take effect automatically under the default hybrid hot-reload mode; if gateway.reload.mode is off, the Gateway must be restarted for changes to take effect. Bindings pointing to accounts the channel never accepts will not work.

Step 3: send messages to verify routing and isolation ​

Writing the configuration doesn't mean the routing is correct—first check the roster and bindings with commands, then verify each one with real messages:

bash
openclaw agents list --bindings
openclaw channels status --probe

Then send one message from each bound account and confirm three things: the message went to the correct agent; each session history is independent; each persona rule takes effect on its own.

You should see: agents list --bindings lists the agent roster and the "channel account → agent" bindings, and channels status --probe shows which accounts are online. If no binding matches and there is no available default assignment, routing reports AGENT_SELECTION_REQUIRED, prompting you to add a binding. Once all three checks pass, your multiple experts are each in place within the same Gateway.

Checkpoints ​

  • Never reuse agentDir. Two agents pointing to the same directory will cause auth and session state conflicts.
  • OAuth has inheritance behavior: when a secondary agent's local OAuth credentials expire or fail to refresh, OpenClaw reads the primary's credentials for the same profile, uses the more recent token, and does not copy the refresh token into the secondary agent's storage. For fully independent OAuth accounts, log in once from that agent itself.
  • Manually copying credentials only copies static items: api_key/token type profiles can be copied; OAuth refresh material is not portable by default unless explicitly opted in with copyToAgents.
  • Skills are loaded from two paths: each agent loads Skills from its own workspace and also reads the shared root (such as ~/.openclaw/skills).

Boundaries ​

  • Multiple agents still run inside the same Gateway process, so the trust boundary is unchanged; both the model and the agent harness are swappable plugins.
  • Channel capabilities depend on the plugin: the WeChat plugin only supports direct messages, not group chats, so don't count "binding a WeChat group" into your plan.
  • Session history provides bounded cross-session recall, not unlimited memory.

Next Steps ​