🤖 Multi-Agent Setup

Run multiple isolated AI agents from a single Gateway. Different personalities, different channels, complete isolation.

What is Multi-Agent?

By default, OpenClaw runs a single agent. But you can configure multiple agents, each with:

📁
Separate Workspace

Each agent has its own files, AGENTS.md, SOUL.md, and persona configuration.

🧠
Isolated Memory

Sessions and chat history are completely separate. No cross-talk between agents.

🔐
Per-Agent Auth

Each agent can have its own auth profiles for services like Google, GitHub, etc.

⚙️
Different Models

Use a high-thinking model for deep work and a faster model for everyday chat — route by channel, account, user, or thread.

Why Use Multiple Agents?

👨‍👩‍👧‍👦 Shared Server

Multiple people using one Gateway server, each with their own private AI brain.

🏢 Work vs Personal

Route WhatsApp to a personal agent and Slack to a work agent with different personalities.

⚡ Fast vs Deep

Use a fast model for everyday chat and a high-thinking/reasoning model for complex tasks.

👥 Family Bot

Dedicated agent for a family group chat with restricted tools and kid-friendly responses.

Quick Start

Use the agent wizard to add a new isolated agent:

# Add a new agent
openclaw agents add work

# List agents and their bindings
openclaw agents list --bindings

# Verify routing
openclaw agents list

The wizard will prompt you for workspace location and create the necessary directories.

Configuration Examples

Example 1: Two WhatsApp Numbers → Two Agents

Route different WhatsApp accounts to different agents:

{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        name: "Home",
        workspace: "~/.openclaw/workspace-home"
      },
      {
        id: "work",
        name: "Work",
        workspace: "~/.openclaw/workspace-work"
      }
    ]
  },

  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }
  ],

  channels: {
    whatsapp: {
      accounts: {
        personal: {},
        biz: {}
      }
    }
  }
}

Example 2: WhatsApp Quick + Telegram Deep

Use a fast model for everyday WhatsApp and a high-thinking model for Telegram deep work:

{
  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" } },
    { agentId: "opus", match: { channel: "telegram" } }
  ]
}

Example 3: One DM to Deep Work

Keep WhatsApp on the fast agent, but route one specific person to the deep-work agent:

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        model: "anthropic/claude-sonnet-4-6"
      },
      {
        id: "opus",
        name: "Deep Work",
        model: "anthropic/claude-opus-4-6"
      }
    ]
  },

  bindings: [
    // Peer bindings always win, so keep them first
    { agentId: "opus", match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551234567" } } },
    { agentId: "chat", match: { channel: "whatsapp" } }
  ]
}

Example 4: Family Bot with Restrictions

Dedicated agent for a family group chat with sandboxing and limited tools:

{
  agents: {
    list: [
      {
        id: "family",
        name: "Family Bot",
        workspace: "~/.openclaw/workspace-family",
        identity: { name: "Family Bot" },
        groupChat: {
          mentionPatterns: ["@family", "@familybot"]
        },
        sandbox: {
          mode: "all",
          scope: "agent"
        },
        tools: {
          allow: ["exec", "read", "web_search"],
          deny: ["write", "edit", "browser", "nodes", "cron"]
        }
      }
    ]
  },

  bindings: [
    {
      agentId: "family",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "123456789@g.us" }
      }
    }
  ]
}

Routing Rules

Bindings are evaluated in order of specificity. Most specific wins:

1 Peer match

Exact DM, group, or channel ID

2 Guild/Team ID

Discord guildId or Slack teamId

3 Account match

Channel + specific accountId

4 Channel match

Channel-wide (accountId: "*")

5 Default agent

Fallback when nothing matches

💡 Tip: Put more specific bindings (peer matches) before general ones (channel-wide) to ensure they take priority.

Path Reference

Understanding where things live in a multi-agent setup:

Path Description
~/.openclaw/openclaw.json Main config (agents, bindings, channels)
~/.openclaw/workspace-{id} Per-agent workspace (files, SOUL.md, etc.)
~/.openclaw/agents/{id}/agent Per-agent state (auth, registry)
~/.openclaw/agents/{id}/sessions Per-agent session store (chat history)
~/.openclaw/skills Shared skills (visible to all agents)
{workspace}/skills Per-agent skills (highest priority)

🔐 Security Notes

  • Auth profiles are per-agent. Each agent reads from its own auth-profiles.json. Main agent credentials are not shared automatically.
  • Never reuse agentDir across agents — it causes auth and session collisions.
  • Workspaces aren't sandboxed by default. Agents can access other host locations via absolute paths unless sandboxing is enabled.
  • Per-agent sandboxing is available — each agent can have its own sandbox settings and tool restrictions.

Ready to set up multiple agents?

Check the official documentation for the complete multi-agent reference.

Multi-Agent Docs → Security Guide