Multi-Agent Routing

Run multiple isolated OpenClaw agents with separate workspaces, agent directories, auth profiles, session stores, and channel bindings.

OpenClaw can host one agent or many agents behind the same Gateway. A multi-agent setup is not just a prompt switch: each agent can have its own workspace, state directory, auth profiles, model config, sessions, skills, and channel bindings.

What Counts as One Agent?

An agent is a scoped persona with:

• a workspace for context files and local notes
• an agentDir for agent-specific state
• auth profiles
• model registry/config
• session store
• optional skill allowlists
• optional sandbox and tool restrictions

Default paths look like this:

~/.openclaw/workspace
~/.openclaw/agents/main/agent
~/.openclaw/agents/main/sessions

Secondary agents should use distinct paths.

Add an Agent

Use the helper when possible:

openclaw agents add work
openclaw agents add personal
openclaw agents list --bindings

Manual config can still define agents.list, but the helper reduces path and binding mistakes.

{
  "agents": {
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "model": "anthropic/claude-opus-4-6"
      },
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work",
        "agentDir": "~/.openclaw/agents/work/agent",
        "model": "openai/gpt-5"
      }
    ]
  }
}

Bind Channels to Agents

Bindings map a channel account, room, sender, or route to an agent. Use this when one Gateway handles multiple identities:

• one WhatsApp number for personal tasks
• one Slack workspace for work tasks
• one Discord bot for community tasks
• one coding agent for ACP-backed workflows

Verify bindings after changes:

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

Subagents vs Multi-Agent Routing

Multi-agent routing runs durable, named agents side by side. Subagents are temporary delegated runs for isolated subtasks.

Per-Agent Skills and Tools

Use shared defaults for common behavior, then narrow each agent:

{
  "agents": {
    "defaults": {
      "skills": ["timezone", "message-style"]
    },
    "list": [
      {
        "id": "work",
        "skills": ["release-review", "incident-summary"],
        "tools": {
          "profile": "messaging",
          "exec": { "security": "ask" }
        }
      }
    ]
  }
}

Keep high-risk tools off agents that handle group rooms or broad external input.

Memory Isolation

Each agent has its own session store. Cross-agent memory search should be explicit, not accidental. If one agent should search another agent's QMD transcript collection, configure that deliberately and document why.

Workspace Is Not Isolation

The workspace is the default cwd. Without sandboxing, absolute paths may still reach host locations. Use sandboxing, separate OS users, or separate hosts for strong trust boundaries.

Use Cases