Tutorial

Multi-Agent Routing

Run multiple isolated AI agents on a single OpenClaw Gateway

Intermediate20 min readLast updated: Jan 2025

In This Tutorial

1.What is Multi-Agent Routing?

Multi-Agent Routing allows you to run multiple isolated AI agents on a single OpenClaw Gateway. Each agent operates independently with its own workspace, state, and sessions - perfect for separating different contexts or sharing your setup with family.

Each Agent Has Its Own:

Workspace

AGENTS.md, SOUL.md, USER.md files defining personality and context

State Directory (agentDir)

Isolated storage for sessions, memory, and tool state

Sessions

Separate conversation history and context per agent

Common Use Cases

💼

Work/Home Separation

Keep work tasks, notes, and calendar completely isolated from personal use. Different tools and permissions for each.

👨‍👩‍👧‍👦

Family Sharing

Give each family member their own agent with personalized settings, while sharing one OpenClaw server.

🎭

Different Personalities

Create agents with different SOUL.md personalities - a formal assistant for work, casual friend for personal use.

📱

Multi-Account Routing

Route different WhatsApp accounts, Telegram bots, or Discord servers to specialized agents.

2.Key Concepts

Agent Workspace

Each agent has a workspace directory containing configuration files that define its behavior:

~/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

AGENTS.md- Define specialized sub-agents (e.g., "coder", "researcher")
SOUL.md- Personality, tone, and behavioral guidelines
USER.md- User preferences, context, and personal info

Critical: Never Reuse agentDir

Each agent must have a unique agentDir path. Reusing the same directory across agents causes:

- Session collisions (agents overwrite each other's state)
- Memory corruption and context bleeding
- Unpredictable behavior and lost conversations

Bindings

Bindings route incoming messages to specific agents based on channel, account, sender, or group. Think of them as routing rules.

// 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

Use the CLI to create a new agent with its own workspace:

openclaw agents add work

This creates a new agent named "work" with a fresh workspace at ~/openclaw/agents/work/

Configure the Workspace

Edit the workspace files to customize your agent:

Edit SOUL.md for 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

Edit USER.md for 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 Bindings in openclaw.json

Configure bindings to route messages to your agents:

{
  "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"
}

Messages not matching any binding will go to defaultAgent

Configure Per-Agent Security

Set sandbox modes and tool policies per 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 Your Setup

List all configured agents and test routing:

openclaw agents list

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

4.Configuration Examples

💬Two WhatsApp Accounts (Personal/Business)

Route personal and business WhatsApp to different agents:

{
  "agents": {
    "personal": {
      "workspace": "~/openclaw/agents/personal",
      "agentDir": "~/openclaw/state/personal",
      "model": "claude-sonnet-4-20250514"
    },
    "business": {
      "workspace": "~/openclaw/agents/business",
      "agentDir": "~/openclaw/state/business",
      "model": "claude-opus-4-20250514"
    }
  },
  "bindings": [
    {
      "agent": "personal",
      "channel": "whatsapp",
      "accountId": "personal-phone-id"
    },
    {
      "agent": "business",
      "channel": "whatsapp",
      "accountId": "business-phone-id"
    }
  ],
  "defaultAgent": "personal"
}

⚡Channel-Based Model Routing

Use fast models for WhatsApp (quick responses) and powerful models for Telegram (complex tasks):

{
  "agents": {
    "fast": {
      "workspace": "~/openclaw/agents/fast",
      "agentDir": "~/openclaw/state/fast",
      "model": "claude-3-5-haiku-20241022",
      "maxTokens": 1024
    },
    "powerful": {
      "workspace": "~/openclaw/agents/powerful",
      "agentDir": "~/openclaw/state/powerful",
      "model": "claude-opus-4-20250514",
      "maxTokens": 8192
    }
  },
  "bindings": [
    {
      "agent": "fast",
      "channel": "whatsapp"
    },
    {
      "agent": "powerful",
      "channel": "telegram"
    }
  ],
  "defaultAgent": "fast"
}

👥Group-Specific Agents

Route specific Discord servers or Telegram groups to dedicated agents:

{
  "agents": {
    "gaming": {
      "workspace": "~/openclaw/agents/gaming",
      "agentDir": "~/openclaw/state/gaming"
    },
    "study-group": {
      "workspace": "~/openclaw/agents/study",
      "agentDir": "~/openclaw/state/study"
    }
  },
  "bindings": [
    {
      "agent": "gaming",
      "channel": "discord",
      "guildId": "123456789012345678"
    },
    {
      "agent": "study-group",
      "channel": "telegram",
      "groupId": "-100123456789"
    }
  ]
}

👨‍👩‍👧‍👦Family Sharing Setup

Give each family member their own agent based on their phone number:

{
  "agents": {
    "dad": {
      "workspace": "~/openclaw/agents/dad",
      "agentDir": "~/openclaw/state/dad",
      "tools": { "allow": ["*"] }
    },
    "mom": {
      "workspace": "~/openclaw/agents/mom",
      "agentDir": "~/openclaw/state/mom",
      "tools": { "allow": ["*"] }
    },
    "kids": {
      "workspace": "~/openclaw/agents/kids",
      "agentDir": "~/openclaw/state/kids",
      "sandbox": "all",
      "tools": {
        "allow": ["notes", "calendar"],
        "deny": ["shell", "browser", "email"]
      }
    }
  },
  "bindings": [
    {
      "agent": "dad",
      "channel": "whatsapp",
      "peer": "+1234567890"
    },
    {
      "agent": "mom",
      "channel": "whatsapp",
      "peer": "+1234567891"
    },
    {
      "agent": "kids",
      "channel": "whatsapp",
      "peer": "+1234567892"
    },
    {
      "agent": "kids",
      "channel": "whatsapp",
      "peer": "+1234567893"
    }
  ],
  "defaultAgent": "dad"
}

5.Binding Priority

When multiple bindings could match a message, OpenClaw uses the most specific match. Here's the priority order (highest to lowest):

1
Peer Match
Specific sender phone number or user ID (most specific)
"peer": "+1234567890"
2
Guild ID (Discord)
Discord server-specific routing
"guildId": "123456789012345678"
3
Team ID (Slack)
Slack workspace-specific routing
"teamId": "T123ACMECORP"
4
Account ID
WhatsApp account or bot account ID
"accountId": "business-phone-id"
5
Channel Level
Route all messages from a channel type
"channel": "whatsapp"
6
Default Agent
Fallback when no bindings match (least specific)
"defaultAgent": "personal"

Example Scenario

If you have bindings for both channel: "whatsapp" and peer: "+1234567890", a message from +1234567890 on WhatsApp will match the peer binding (higher priority), not the channel binding.

6.Security Per Agent

Each agent can have its own security settings. This is especially important when sharing OpenClaw with family or running agents with different trust levels.

Sandbox Modes

Control how strictly the agent is sandboxed:

"sandbox": "off"Dangerous

No sandboxing. Agent has full system access. Only for trusted, personal use.

"sandbox": "non-main"Moderate

Sandbox sub-agents but not the main agent. Good balance for personal use.

"sandbox": "all"Recommended

Full sandboxing for all agents. Safest option for shared or untrusted use.

Tool Allow/Deny Lists

Restrict which tools each agent can access:

{
  "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 Levels

Limit file system access to specific directories:

{
  "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"
        ]
      }
    }
  }
}

Next Steps

Now that you understand multi-agent routing, explore related topics:

Learn About Skills Channel Setup Config Generator

Have questions? Join our Discord or ask on GitHub Discussions