openclaw-multi-agent

OpenClaw Multi-Agent Setup

Guide the user through configuring multiple agents with routing, isolation, and per-agent policies.

Agent Concept

An agent in OpenClaw is an isolated brain with three components:

• Workspace - Contains personality files (SOUL.md, AGENTS.md, USER.md), local notes, and persona rules. Default working directory for tool execution.
• State directory (agentDir) - Stores auth profiles, model registry, and per-agent config at ~/.openclaw/agents/<agentId>/agent. Auth profiles are per-agent and never shared automatically.
• Session store - Chat history at ~/.openclaw/agents/<agentId>/sessions.

Never reuse agentDir across agents - causes auth/session collisions.

Creating Agents

openclaw agents add work

This creates:

• Workspace at ~/.openclaw/workspace-work
• State at ~/.openclaw/agents/work/agent
• Sessions at ~/.openclaw/agents/work/sessions

Verify: openclaw agents list --bindings

Binding Rules (Message Routing)

Messages route to agents via deterministic, most-specific-wins bindings:

1. Peer match (exact DM/group ID) - highest priority
2. Parent peer match (thread inheritance)
3. Guild ID + roles (Discord)
4. Guild ID (Discord)
5. Team ID (Slack)
6. Account ID match
7. Channel-level (accountId: "*")
8. Default agent fallback

If multiple bindings match the same tier, first in config order wins. Multiple fields in a binding use AND semantics.

{
  bindings: [
    // Most specific (peer) - wins over channel-wide
    { agentId: "opus", match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551234567" } } },
    // Channel-wide fallback
    { agentId: "chat", match: { channel: "whatsapp" } },
  ],
}

Per-Agent Configuration

{
  agents: {
    list: [
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: { primary: "anthropic/claude-opus-4-6" },
        identity: { name: "Work Bot" },
        groupChat: { mentionPatterns: ["@work", "@workbot"] },

        sandbox: {
          mode: "all",              // "off" | "non-main" | "all"
          scope: "agent",           // "session" | "agent" | "shared"
          workspaceAccess: "rw",
        },

        tools: {
          allow: ["read", "exec"],
          deny: ["browser", "cron"],
        },
      },
    ],
  },
}