Files

Peter Steinberger 285906e546 docs: move model-split example to multi-agent

2026-01-12 06:05:39 +00:00

8.6 KiB

Raw Blame History

summary, title, read_when, status

summary	title	read_when	status
Multi-agent routing: isolated agents, provider accounts, and bindings	Multi-Agent Routing	You want multiple isolated agents (workspaces + auth) in one gateway process.	active

Multi-Agent Routing

Goal: multiple isolated agents (separate workspace + agentDir + sessions), plus multiple provider accounts (e.g. two WhatsApps) in one running Gateway. Inbound is routed to an agent via bindings.

What is “one agent”?

An agent is a fully scoped brain with its own:

Workspace (files, AGENTS.md/SOUL.md/USER.md, local notes, persona rules).
State directory (agentDir) for auth profiles, model registry, and per-agent config.
Session store (chat history + routing state) under ~/.clawdbot/agents/<agentId>/sessions.

Skills are per-agent via each workspace’s skills/ folder, with shared skills available from ~/.clawdbot/skills. See Skills: per-agent vs shared.

The Gateway can host one agent (default) or many agents side-by-side.

Workspace note: each agent’s workspace is the default cwd, not a hard sandbox. Relative paths resolve inside the workspace, but absolute paths can reach other host locations unless sandboxing is enabled. See Sandboxing.

Paths (quick map)

Config: ~/.clawdbot/clawdbot.json (or CLAWDBOT_CONFIG_PATH)
State dir: ~/.clawdbot (or CLAWDBOT_STATE_DIR)
Workspace: ~/clawd (or ~/clawd-<agentId>)
Agent dir: ~/.clawdbot/agents/<agentId>/agent (or agents.list[].agentDir)
Sessions: ~/.clawdbot/agents/<agentId>/sessions

Single-agent mode (default)

If you do nothing, Clawdbot runs a single agent:

agentId defaults to main.
Sessions are keyed as agent:main:<mainKey>.
Workspace defaults to ~/clawd (or ~/clawd-<profile> when CLAWDBOT_PROFILE is set).
State defaults to ~/.clawdbot/agents/main/agent.

Agent helper

Use the agent wizard to add a new isolated agent:

clawdbot agents add work

Then add bindings (or let the wizard do it) to route inbound messages.

Verify with:

clawdbot agents list --bindings

Multiple agents = multiple people, multiple personalities

With multiple agents, each agentId becomes a fully isolated persona:

Different phone numbers/accounts (per provider accountId).
Different personalities (per-agent workspace files like AGENTS.md and SOUL.md).
Separate auth + sessions (no cross-talk unless explicitly enabled).

This lets multiple people share one Gateway server while keeping their AI “brains” and data isolated.

One WhatsApp number, multiple people (DM split)

You can route different WhatsApp DMs to different agents while staying on one WhatsApp account. Match on sender E.164 (like +15551234567) with peer.kind: "dm". Replies still come from the same WhatsApp number (no per‑agent sender identity).

Important detail: direct chats collapse to the agent’s main session key, so true isolation requires one agent per person.

Example:

{
  agents: {
    list: [
      { id: "alex", workspace: "~/clawd-alex" },
      { id: "mia", workspace: "~/clawd-mia" }
    ]
  },
  bindings: [
    { agentId: "alex", match: { provider: "whatsapp", peer: { kind: "dm", id: "+15551230001" } } },
    { agentId: "mia",  match: { provider: "whatsapp", peer: { kind: "dm", id: "+15551230002" } } }
  ],
  whatsapp: {
    dmPolicy: "allowlist",
    allowFrom: ["+15551230001", "+15551230002"]
  }
}

Notes:

DM access control is global per WhatsApp account (pairing/allowlist), not per agent.
For shared groups, bind the group to one agent or use Broadcast groups.

Routing rules (how messages pick an agent)

Bindings are deterministic and most-specific wins:

peer match (exact DM/group/channel id)
guildId (Discord)
teamId (Slack)
accountId match for a provider
provider-level match (accountId: "*")
fallback to default agent (agents.list[].default, else first list entry, default: main)

Multiple accounts / phone numbers

Providers that support multiple accounts (e.g. WhatsApp) use accountId to identify each login. Each accountId can be routed to a different agent, so one server can host multiple phone numbers without mixing sessions.

Concepts

agentId: one “brain” (workspace, per-agent auth, per-agent session store).
accountId: one provider account instance (e.g. WhatsApp account "personal" vs "biz").
binding: routes inbound messages to an agentId by (provider, accountId, peer) and optionally guild/team ids.
Direct chats collapse to agent:<agentId>:<mainKey> (per-agent “main”; session.mainKey).

Example: two WhatsApps → two agents

~/.clawdbot/clawdbot.json (JSON5):

{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        name: "Home",
        workspace: "~/clawd-home",
        agentDir: "~/.clawdbot/agents/home/agent",
      },
      {
        id: "work",
        name: "Work",
        workspace: "~/clawd-work",
        agentDir: "~/.clawdbot/agents/work/agent",
      },
    ],
  },

  // Deterministic routing: first match wins (most-specific first).
  bindings: [
    { agentId: "home", match: { provider: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { provider: "whatsapp", accountId: "biz" } },

    // Optional per-peer override (example: send a specific group to work agent).
    {
      agentId: "work",
      match: {
        provider: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "1203630...@g.us" },
      },
    },
  ],

  // Off by default: agent-to-agent messaging must be explicitly enabled + allowlisted.
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },

  whatsapp: {
    accounts: {
      personal: {
        // Optional override. Default: ~/.clawdbot/credentials/whatsapp/personal
        // authDir: "~/.clawdbot/credentials/whatsapp/personal",
      },
      biz: {
        // Optional override. Default: ~/.clawdbot/credentials/whatsapp/biz
        // authDir: "~/.clawdbot/credentials/whatsapp/biz",
      },
    },
  },
}

Example: WhatsApp daily chat + Telegram deep work

Split by provider: route WhatsApp to a fast everyday agent and Telegram to an Opus agent.

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/clawd-chat",
        model: "anthropic/claude-sonnet-4-5"
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/clawd-opus",
        model: "anthropic/claude-opus-4-5"
      }
    ]
  },
  bindings: [
    { agentId: "chat", match: { provider: "whatsapp" } },
    { agentId: "opus", match: { provider: "telegram" } }
  ]
}