How to Set Up OpenClaw Multi-Agent: Complete Step-by-Step Guide (2026)

What Is OpenClaw Multi-Agent and Why Would You Use It?

OpenClaw's multi-agent system lets you run multiple independent AI agents simultaneously from one installation, each fully isolated with its own workspace, credentials, session storage, personality, model selection, and tool permissions.

This means you can have a personal assistant, a work agent, a coding helper, and a family-friendly bot — all running on the same OpenClaw Gateway without any data or credential crossover.

How Do You Create Multiple OpenClaw Agents?

Create agents with simple CLI commands — each command automatically generates a dedicated workspace directory, a state directory with auth profiles, and a session store for chat history.

openclaw agents add home
openclaw agents add work
openclaw agents add coding

Verify your agents exist:

openclaw agents list --bindings

Critical rule: Never reuse the agentDir path across agents. Sharing state directories causes authentication collisions and session corruption.

How Do You Configure Agent Definitions in openclaw.json?

Each agent is defined in the agents.list array of openclaw.json with a unique id, workspace path, agentDir path, model selection, and an optional default flag for handling unmatched messages.

{
  "agents": {
    "list": [
      {
        "id": "home",
        "default": true,
        "name": "Home Agent",
        "workspace": "~/.openclaw/workspace-home",
        "agentDir": "~/.openclaw/agents/home/agent",
        "model": "anthropic/claude-sonnet-4-6"
      },
      {
        "id": "work",
        "name": "Work Agent",
        "workspace": "~/.openclaw/workspace-work",
        "agentDir": "~/.openclaw/agents/work/agent",
        "model": "anthropic/claude-opus-4-6"
      },
      {
        "id": "coding",
        "name": "Coding Agent",
        "workspace": "~/.openclaw/workspace-coding",
        "agentDir": "~/.openclaw/agents/coding/agent",
        "model": "anthropic/claude-opus-4-6"
      }
    ]
  }
}

How Does Message Routing Work with Bindings?

Bindings tell OpenClaw which agent handles which messages using a most-specific-wins priority system — from exact peer matches (highest) down to channel-level defaults and the fallback default agent (lowest).

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

Binding Priority (Most Specific Wins)

1. Peer match — exact DM, group, or channel ID
2. Parent peer match — thread inheritance from a matched parent
3. Guild ID + roles — Discord-specific role-based routing
4. Guild ID alone — Discord server-level routing
5. Team ID — Slack workspace routing
6. Account ID match — specific account within a channel
7. Channel-level match — all messages from a channel type
8. Default agent — fallback when nothing else matches

How Do You Set Up Multi-Account Channels?

Many channels support multiple accounts — connect separate WhatsApp phone numbers, Discord bot tokens, or Slack workspace credentials to the same channel type, then route each to different agents via bindings.

WhatsApp Multi-Account Example

{
  "channels": {
    "whatsapp": {
      "accounts": {
        "personal": {},
        "business": {}
      }
    }
  }
}

4 AI personas and 7 free skills — browse the marketplace.

How Do You Set Per-Agent Security and Tool Permissions?

Each agent can have independent sandbox and tool restrictions — essential for running a read-only family agent that can answer questions but cannot write, edit, or patch files on your system.

{
  "id": "family",
  "workspace": "~/.openclaw/workspace-family",
  "agentDir": "~/.openclaw/agents/family/agent",
  "sandbox": {
    "mode": "all",
    "scope": "agent"
  },
  "tools": {
    "allow": ["read", "exec"],
    "deny": ["write", "edit", "apply_patch"]
  }
}

How Do You Customize Agent Personalities?

Each agent's workspace contains personality files (AGENTS.md, SOUL.md, USER.md) — since each agent has its own workspace, you get complete personality isolation between formal work agents and casual home agents.

How Do You Activate Your Multi-Agent Configuration?

After configuring everything, restart the gateway and verify with --bindings and --probe flags to confirm correct agent-to-channel mapping and live channel connections.

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

What Are Some Real-World Multi-Agent Configurations?

Common configurations include personal vs. business WhatsApp routing, cross-channel specialization (WhatsApp for chat, Telegram for deep work), and per-contact routing using phone numbers as peer IDs.

Per-Contact Routing on WhatsApp

{
  "bindings": [
    {
      "agentId": "alex-agent",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "direct", "id": "+15551230001" }
      }
    },
    {
      "agentId": "mia-agent",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "direct", "id": "+15551230002" }
      }
    }
  ]
}

What Are the Most Common Multi-Agent Mistakes?

The five most common mistakes are reusing agentDir paths (causes auth collisions), not setting a default agent (drops unmatched messages), overlapping bindings, sharing credentials across agents, and skipping gateway restart after config changes.

Frequently Asked Questions

How many agents can I run simultaneously?

There is no hard limit. The practical limit depends on your hardware resources and API rate limits. Most users run 2-5 agents comfortably.

Can agents communicate with each other?

By default, no. Each agent is fully isolated. There is no automatic cross-agent communication — this is by design for security and data isolation.

Does each agent need its own API key?

Each agent has its own auth profile, but they can use the same underlying API key. The isolation is at the session and workspace level, not necessarily at the API key level.

Can multiple people share one OpenClaw Gateway?

Yes. This is one of the primary use cases for multi-agent. Each person gets their own agent with separate workspace, personality, and session storage. Bindings route messages to the correct agent.

What happens if no binding matches a message?

The message is routed to whichever agent has default: true set. If no default is configured, the message may be dropped.

Can I use different LLM models per agent?

Yes. Each agent definition includes a model field. You can run Claude Sonnet for fast responses on one agent and Claude Opus for deep reasoning on another.

How do I delete an agent?

Remove the agent from agents.list in your config, delete its workspace and state directories, remove any associated bindings, and restart the gateway.