Multi-Agent Routing
Goal: multiple isolated agents (separate workspace +agentDir + sessions), plus multiple channel 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
~/.openclaw/agents/<agentId>/sessions.
agentDir
across agents (it causes auth/session collisions). If you want to share creds,
copy auth-profiles.json into the other agent’s agentDir.
Skills are per-agent via each workspace’s skills/ folder, with shared skills
available from ~/.openclaw/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:
~/.openclaw/openclaw.json(orOPENCLAW_CONFIG_PATH) - State dir:
~/.openclaw(orOPENCLAW_STATE_DIR) - Workspace:
~/.openclaw/workspace(or~/.openclaw/workspace-<agentId>) - Agent dir:
~/.openclaw/agents/<agentId>/agent(oragents.list[].agentDir) - Sessions:
~/.openclaw/agents/<agentId>/sessions
Single-agent mode (default)
If you do nothing, WednesdayAI runs a single agent:agentIddefaults tomain.- Sessions are keyed as
agent:main:<mainKey>. - Workspace defaults to
~/.openclaw/workspace(or~/.openclaw/workspace-<profile>whenOPENCLAW_PROFILEis set). - State defaults to
~/.openclaw/agents/main/agent.
Agent helper
Use the agent wizard to add a new isolated agent:bindings (or let the wizard do it) to route inbound messages.
Verify with:
Quick start
1
Create each agent workspace
Use the wizard or create workspaces manually:Each agent gets its own workspace with
SOUL.md, AGENTS.md, and optional USER.md, plus a dedicated agentDir and session store under ~/.openclaw/agents/<agentId>.2
Create channel accounts
3
Add agents, accounts, and bindings
Add agents under
agents.list, channel accounts under channels.<channel>.accounts, and connect them with bindings (examples below).4
Restart and verify
Multiple agents = multiple people, multiple personalities
With multiple agents, eachagentId becomes a fully isolated persona:
- Different phone numbers/accounts (per channel
accountId). - Different personalities (per-agent workspace files like
AGENTS.mdandSOUL.md). - Separate auth + sessions (no cross-talk unless explicitly enabled).
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: "direct". 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:
- 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:peermatch (exact DM/group/channel id)parentPeermatch (thread inheritance)guildId + roles(Discord role routing)guildId(Discord)teamId(Slack)accountIdmatch for a channel- channel-level match (
accountId: "*") - fallback to default agent (
agents.list[].default, else first list entry, default:main)
peer + guildId), all specified fields are required (AND semantics).
Important account-scope detail:
- A binding that omits
accountIdmatches the default account only. - Use
accountId: "*"for a channel-wide fallback across all accounts. - If you later add the same binding for the same agent with an explicit account id, WednesdayAI upgrades the existing channel-only binding to account-scoped instead of duplicating it.
Multiple accounts / phone numbers
Channels that support multiple accounts (e.g. WhatsApp) useaccountId to identify
each login. Each accountId can be routed to a different agent, so one server can host
multiple phone numbers without mixing sessions.
If you want a channel-wide default account when accountId is omitted, set
channels.<channel>.defaultAccount (optional). When unset, WednesdayAI falls back
to default if present, otherwise the first configured account id (sorted).
Common channels supporting this pattern include:
whatsapp,telegram,discord,slack,signal,imessageirc,line,googlechat,mattermost,matrix,nextcloud-talkbluebubbles,zalo,zalouser,nostr,feishu
Concepts
agentId: one “brain” (workspace, per-agent auth, per-agent session store).accountId: one channel account instance (e.g. WhatsApp account"personal"vs"biz").binding: routes inbound messages to anagentIdby(channel, accountId, peer)and optionally guild/team ids.- Direct chats collapse to
agent:<agentId>:<mainKey>(per-agent “main”;session.mainKey).
Agent-to-agent communication and handoffs
When running multiple agents, agents can interact using two distinct patterns:agents_nudge(durable handoffs): Fire-and-forget wake signal. Wakes the target agent to run one turn in its direct main session (agent:<agentId>:main) with your message. The nudge is enqueued durably as anagent.turnwork row, surviving gateway restarts and recovering automatically. Useagents_nudgefor task handoffs, background notifications, and triggers where the caller does not wait for a synchronous reply.sessions_send(session messaging): Synchronous message delivered directly into a specific target session (sessionKeyorsessionId). WhentimeoutSeconds > 0, the caller waits for the run to finish and can engage in a multi-turn ping-pong dialogue before returning.
tools.agentToAgent.enabled: true and the target listed under tools.agentToAgent.allow), and cross-agent calls require tools.sessions.visibility: "all" (clamped to tree in sandboxed sessions).
For detailed grant rules, idempotency keys, and chained hop caps, see Agent coordination.
Agent teams
agents.teams[] declares a named group of agents with one lead. The lead may spawn every
member with sessions_spawn (in addition to its own subagents.allowAgents), and when it has the
sessions_spawn tool its system prompt gets a ## Team section listing each member’s id, name,
and description, so it can pick the right delegate. Members get no new rights from the team.
Teams do not change tools.agentToAgent (sessions_send, agents_nudge) or ACP targets.
Teams pair well with internal specialists: set agents.list[].userFacing: false on a member
and people cannot reach it directly — config validation refuses it as the default agent, a
bindings[] target, or a broadcast target (and rejects any internal agent when session.scope
is "global"), and user clients such as the web client do not see it at all. Other agents, cron,
hooks, and operator clients keep full access.
- Each agent belongs to at most one team, as lead or member; teams do not nest.
leadand everymembersentry must be an id inagents.list; the lead is not also a member.- Team ids are unique, lowercase letters/digits/
-/_.
userFacing: true and inheritRequesterIdentity: true. With
inheritRequesterIdentity: false on an agent, turns delegated to it (sessions_spawn,
sessions_send) run without the requesting person’s identity.
Agent config is not hot-reloaded: restart the gateway after changing agents.list or
agents.teams.
See agents.teams in the Configuration Reference
and Sub-agents for spawn semantics.
Platform examples
Discord bots per agent
Each Discord bot account maps to a uniqueaccountId. Bind each account to an agent and keep allowlists per bot.
- Invite each bot to the guild and enable Message Content Intent.
- Tokens live in
channels.discord.accounts.<id>.token(default account can useDISCORD_BOT_TOKEN).
Telegram bots per agent
- Create one bot per agent with BotFather and copy each token.
- Tokens live in
channels.telegram.accounts.<id>.botToken(default account can useTELEGRAM_BOT_TOKEN).
WhatsApp numbers per agent
Link each account before starting the gateway:~/.openclaw/openclaw.json (JSON5):
Example: WhatsApp daily chat + Telegram deep work
Split by channel: route WhatsApp to a fast everyday agent and Telegram to an Opus agent.- If you have multiple accounts for a channel, add
accountIdto the binding (for example{ channel: "whatsapp", accountId: "personal" }). - To route a single DM/group to Opus while keeping the rest on chat, add a
match.peerbinding for that peer; peer matches always win over channel-wide rules.
Example: same channel, one peer to Opus
Keep WhatsApp on the fast agent, but route one DM to Opus:Family agent bound to a WhatsApp group
Bind a dedicated family agent to a single WhatsApp group, with mention gating and a tighter tool policy:- Tool allow/deny lists are tools, not skills. If a skill needs to run a
binary, ensure
execis allowed and the binary exists in the sandbox. - For stricter gating, set
agents.list[].groupChat.mentionPatternsand keep group allowlists enabled for the channel.
Per-Agent Sandbox and Tool Configuration
Starting with v2026.1.6, each agent can have its own sandbox and tool restrictions:setupCommand lives under sandbox.docker and runs once on container creation.
Per-agent sandbox.docker.* overrides are ignored when the resolved scope is "shared".
Benefits:
- Security isolation: Restrict tools for untrusted agents
- Resource control: Sandbox specific agents while keeping others on host
- Flexible policies: Different permissions per agent
tools.elevated is global and sender-based; it is not configurable per agent.
If you need per-agent boundaries, use agents.list[].tools to deny exec.
For group targeting, use agents.list[].groupChat.mentionPatterns so @mentions map cleanly to the intended agent.
See Multi-Agent Sandbox & Tools for detailed examples.
Tool profiles per agent
Setagents.list[].tools.profile to apply a baseline tool set:
minimal— read, write, edit, exec onlycoding— coding-oriented toolsmessaging— messaging-oriented toolsfull— all tools
Additive allowlists (alsoAllow)
Use tools.alsoAllow or agents.list[].tools.alsoAllow to add tool entries without replacing an existing allowlist or profile. The same field re-enables default-denied gateway actions such as gateway.config_apply (bare * does not). See Config writes.
Per-provider tool policy
tools.byProvider and agents.list[].tools.byProvider scope tool policy to a specific model provider or provider/model pair:
Exec configuration per agent
agents.list[].tools.exec overrides exec tool defaults for that agent:
Filesystem restrictions per agent
agents.list[].tools.fs.workspaceOnly: true restricts filesystem tools to the agent workspace directory.