Lesson 3. Multiple Assistants#

Why you need this#

Imagine having one secretary who handles both work and personal questions, and also talks to your family. Inconvenient. It’s better to split responsibilities: one assistant for work, another for home, a third for a public bot. In OpenClaw, this is called multi-agent — multiple isolated “brains” in one system.

What is an “agent”#

An agent is a fully independent assistant with its own:

• Workspace — files, AGENTS.md, personality settings
• State storage (agentDir) — authorization, history
• Conversation history (sessions) — each agent only remembers its own chats
• Skills — its own set of abilities

By default, OpenClaw works with one agent — main. But you can add as many as you want.

How to add a new agent#

Step 1. Creating an agent#

openclaw agents add work
openclaw agents add family

Each agent gets its own folder with files and settings.

Step 2. Channel bindings#

Bindings are rules that say: “messages from this channel go to this agent.”

Example configuration in ~/.openclaw/openclaw.json:

{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "work", workspace: "~/.openclaw/workspace-work" }
    ]
  },
  bindings: [
    { agentId: "main", match: { channel: "whatsapp" } },
    { agentId: "work", match: { channel: "telegram" } }
  ]
}

In this example: WhatsApp → main agent, Telegram → work agent.

Step 3. Restart and verify#

openclaw gateway restart
openclaw agents list --bindings

Routing rules#

How OpenClaw decides which agent gets a message:

1. Specific chat (peer) — most precise: “this number → this agent”
2. Channel account (accountId) — “everything from this WhatsApp account → this agent”
3. Channel — “everything from Telegram → this agent”
4. Default — the agent with default: true or the first in the list

More specific rules always beat general ones.

Configuration examples#

Different Telegram bots for different tasks#

{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "alerts", workspace: "~/.openclaw/workspace-alerts" }
    ]
  },
  bindings: [
    { agentId: "main", match: { channel: "telegram", accountId: "default" } },
    { agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } }
  ],
  channels: {
    telegram: {
      accounts: {
        default: { botToken: "123456:ABC..." },
        alerts: { botToken: "987654:XYZ..." }
      }
    }
  }
}

One WhatsApp, different people — different agents#

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

Quick chat + deep work#

{
  agents: {
    list: [
      { id: "chat", model: "anthropic/claude-sonnet-4-5" },
      { id: "opus", model: "anthropic/claude-opus-4-6" }
    ]
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } }
  ]
}

Sub-agents#

A sub-agent is a background helper that the main agent creates to handle a separate task. It’s like your assistant telling an intern: “Figure this out while I work on something else.”

Sub-agents:

• Work in a separate session (don’t interfere with the main conversation)
• When finished, report the result back to your chat
• Can use a different model (a cheaper one for simpler tasks)

Managing sub-agents#

/subagents list              — view active sub-agents
/subagents kill all           — stop all
/subagents log 1              — view the first one's log
/subagents spawn work "Find information about..."  — launch manually

Configuration#

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 8,        // maximum simultaneous
        maxSpawnDepth: 2,        // allow nesting
        archiveAfterMinutes: 60  // remove after an hour
      }
    }
  }
}

Nested sub-agents#

By default, sub-agents can’t create their own sub-agents. But if you set maxSpawnDepth: 2, you get a chain:

You → Main agent → Sub-agent (orchestrator) → Sub-sub-agent (worker)

Maximum depth: 5 levels (but 2 is recommended).

Isolation and security#

Each agent:

• Has its own authorization files (doesn’t share passwords with others)
• Can have its own sandbox and tool restrictions
• Can’t see other agents’ conversation history

Example — a public agent with restrictions:

{
  agents: {
    list: [
      {
        id: "public",
        sandbox: { mode: "all" },
        tools: {
          allow: ["read"],
          deny: ["write", "exec", "browser"]
        }
      }
    ]
  }
}

Lesson summary#

• An agent is an isolated “brain” with its own files, history, and settings
• Bindings route messages from channels to the right agent
• More specific routing rules beat general ones
• Sub-agents are background helpers for parallel tasks
• Each agent can have its own sandbox and tool set
• Use openclaw agents list --bindings to check settings