Tutorial

Multi-Agent Routing

Run multiple isolated agents on a single Gateway for work/home separation, family sharing, or different AI personalities.

Intermediate20 min readJanuary 2026

On This Page

1.What is Multi-Agent Routing?

Multi-agent routing lets you run multiple isolated AI agents on a single OpenClaw Gateway. Each agent has its own identity, memory, and configuration - but shares the same infrastructure.

Each agent has:

Own Identity

Separate name, personality, and system prompt

Isolated Memory

Independent conversation history and context

Custom Tools

Different tool permissions per agent

Channel Bindings

Route specific channels to specific agents

Common Use Cases

💼

Work/Home Separation

Keep work Slack separate from personal Telegram. Different personalities, different memories.

👨‍👩‍👧

Family Sharing

Each family member gets their own agent with personalized responses and private memory.

🎭

Different Personalities

A professional assistant for email, a casual friend for Discord, a creative writer for brainstorming.

📱

Multi-Account

Handle multiple WhatsApp numbers or Telegram accounts with isolated agents.

2.Key Concepts

Workspaces

Each agent lives in a 'workspace' - a directory containing its configuration, memory, and files.

~/openclaw/agents/work/
├── AGENTS.md    # Define sub-agents and their specialties
├── SOUL.md      # Agent personality and communication style
├── USER.md      # Information about the user
└── skills/      # Agent-specific skills

soul.md— Agent personality and system prompt
user.md— User preferences and context
memory/— Conversation history and facts
skills/— Custom skills for this agent

Important

Agents share the same Gateway process and API keys. For true isolation (separate API keys, separate processes), run multiple Gateway instances.

- Rate limits are shared across all agents
- API costs are combined
- A crash affects all agents

Channel Bindings

Bindings route incoming messages to the right agent based on channel, user, or group.

// Example: Route WhatsApp business account to work agent
{
  "bindings": [{
    "agent": "work",
    "channel": "whatsapp",
    "accountId": "business-account-id"
  }]
}

3.Step-by-Step Setup

Create a New Agent

Create a workspace directory for your new agent:

openclaw agents add work

This creates a new agent with its own workspace directory.

Configure the Workspace

Create the agent's personality and user files:

soul.md - Agent personality:

# Work Assistant Soul

You are a professional work assistant. Be formal, concise,
and focused on productivity. Avoid casual language.

## Communication Style
- Use professional language
- Be direct and efficient
- Focus on actionable items
- Respect work-life boundaries

user.md - User context:

# User Profile - Work Context

- Role: Software Engineer at Acme Corp
- Working hours: 9 AM - 6 PM PST
- Key projects: Project Alpha, Customer Portal
- Slack workspace: acme-corp.slack.com

Set Up Channel Bindings

Route channels to your new agent in openclaw.json:

{
  "agents": {
    "default": {
      "workspace": "~/openclaw/agents/default",
      "agentDir": "~/openclaw/state/default"
    },
    "work": {
      "workspace": "~/openclaw/agents/work",
      "agentDir": "~/openclaw/state/work"
    }
  },
  "bindings": [
    {
      "agent": "work",
      "channel": "whatsapp",
      "accountId": "work-phone-id"
    },
    {
      "agent": "work",
      "channel": "slack",
      "teamId": "T123ACMECORP"
    }
  ],
  "defaultAgent": "default"
}

Bindings tell OpenClaw which agent should handle messages from each channel.

Configure Security (Optional)

Set sandbox mode and tool restrictions for the agent:

{
  "agents": {
    "work": {
      "workspace": "~/openclaw/agents/work",
      "agentDir": "~/openclaw/state/work",
      "sandbox": "all",
      "tools": {
        "allow": ["calendar", "email", "notes"],
        "deny": ["shell", "browser"]
      }
    },
    "home": {
      "workspace": "~/openclaw/agents/home",
      "agentDir": "~/openclaw/state/home",
      "sandbox": "non-main",
      "tools": {
        "allow": ["*"],
        "deny": []
      }
    }
  }
}

Verify Setup

Restart OpenClaw and test your multi-agent setup:

openclaw agents list

openclaw agents test --channel whatsapp --from +1234567890

4.Configuration Examples

📱Two WhatsApp Numbers

Route different WhatsApp numbers to different agents:

{
  "agents": {
    "personal": { "workspace": "~/.openclaw/personal" },
    "business": { "workspace": "~/.openclaw/business" }
  },
  "bindings": [
    { "channel": "whatsapp:+1234567890", "agent": "personal" },
    { "channel": "whatsapp:+0987654321", "agent": "business" }
  ]
}

🤖Different Models per Channel

Use GPT-4 for work, Claude for personal:

{
  "agents": {
    "work": {
      "workspace": "~/.openclaw/work",
      "model": "gpt-4o"
    },
    "personal": {
      "workspace": "~/.openclaw/personal",
      "model": "claude-3-5-sonnet-20241022"
    }
  }
}

👥Group-Specific Agents

Different agents for different Discord servers or Slack workspaces:

{
  "bindings": [
    { "channel": "discord", "guild": "gaming-server-id", "agent": "gaming-buddy" },
    { "channel": "discord", "guild": "work-server-id", "agent": "work-assistant" },
    { "channel": "slack", "workspace": "company-workspace", "agent": "work-assistant" }
  ]
}

👨‍👩‍👧‍👦Family Sharing

Each family member gets their own agent via Telegram user ID:

{
  "agents": {
    "dad": { "workspace": "~/.openclaw/dad" },
    "mom": { "workspace": "~/.openclaw/mom" },
    "kids": { "workspace": "~/.openclaw/kids", "sandbox": "all" }
  },
  "bindings": [
    { "channel": "telegram", "userId": "123456", "agent": "dad" },
    { "channel": "telegram", "userId": "789012", "agent": "mom" },
    { "channel": "telegram", "userId": "345678", "agent": "kids" }
  ]
}

5.Binding Priority

When multiple bindings could match, OpenClaw uses the most specific one:

1
User-specific
Bindings with userId match first
{ "channel": "telegram", "userId": "123", "agent": "personal" }
2
Group-specific
Bindings with group/guild/workspace match second
{ "channel": "discord", "guild": "abc", "agent": "gaming" }
3
Channel-specific
Channel-only bindings match last
{ "channel": "telegram", "agent": "default" }

Example

If you have bindings for 'telegram' (default) and 'telegram + userId:123' (personal), messages from user 123 go to 'personal', all others go to 'default'.

6.Security & Sandboxing

Control what each agent can do with sandbox modes and tool policies.

Sandbox Modes

Limit agent capabilities based on trust level:

"sandbox": "off"Full Access

Agent can use all tools. Use for trusted personal agents.

"sandbox": "non-main"Limited

Restrict file/shell access to workspace directory only.

"sandbox": "all"Strict

No file system or shell access. Chat and web only.

Tool Policy

Fine-grained control over which tools an agent can use:

{
  "agents": {
    "restricted": {
      "workspace": "~/openclaw/agents/restricted",
      "agentDir": "~/openclaw/state/restricted",
      "tools": {
        // Only allow these specific tools
        "allow": ["calendar", "notes", "reminders"],
        // Explicitly block dangerous tools
        "deny": ["shell", "filesystem", "browser", "email"]
      }
    },
    "trusted": {
      "workspace": "~/openclaw/agents/trusted",
      "agentDir": "~/openclaw/state/trusted",
      "tools": {
        // Allow everything except...
        "allow": ["*"],
        "deny": ["shell"]  // Still block shell for safety
      }
    }
  }
}

Workspace Access

By default, agents can only access files within their workspace directory. This prevents one agent from reading another's memory or files.

{
  "agents": {
    "work": {
      "workspace": "~/openclaw/agents/work",
      "agentDir": "~/openclaw/state/work",
      "filesystem": {
        // Only allow access to these directories
        "allowedPaths": [
          "~/Documents/Work",
          "~/Projects",
          "/tmp"
        ],
        // Block access to sensitive areas
        "blockedPaths": [
          "~/.ssh",
          "~/.aws",
          "~/Documents/Personal"
        ]
      }
    }
  }
}

Multi-Agent Ready!

You now have isolated agents for different use cases.

Create Custom Skills Connect More Channels Config Generator

Questions? Join Discord or Open GitHub Issue