One agent is powerful. Multiple specialized agents working together is infrastructure. Today you stop running a solo assistant and start running a coordinated team — each agent with its own workspace, its own tools, and its own role.
~/.openclaw/agents/<agentId>/agent/ for auth profiles and config. sessions/ for conversation history. Each agent = isolated state.
~/.openclaw/workspace-<agentId>/ per agent. Own AGENTS.md, SOUL.md, MEMORY.md, tools, and skills. Complete isolation from other agents.
openclaw agents add to create, openclaw agents list to view, openclaw agents delete to remove. Clean lifecycle management.
Never reuse agentDir across agents. Each agent must have its own directory for auth profiles, model registry, and session state. Sharing causes auth collisions and session corruption.
Routing follows strict priority order. First match wins:
Match fields: channel, accountId, peer (kind + id), guildId, roles.
When multiple bindings match at the same precedence tier, config order wins — the first binding listed in openclaw.json takes priority.
Each agent must have a unique agentDir. Sharing directories between agents causes auth-profiles.json collisions and corrupted session state.
Set shared baseline config under agents.defaults. Individual agents inherit these values and can override any property. Use defaults for model, sandbox mode, and common tool policies.
One bot per agent. Message Content Intent required. Bind by peer for DMs, guildId for server-wide, roles for Discord role-based routing.
One bot per agent via BotFather. Bind by peer for DM routing, guildId for group-wide routing. Each bot token maps to one agent.
Login with openclaw channels login --channel whatsapp --account <id>. Multi-account: channels.whatsapp.accounts with authDir per account.
Route specific users to specific agents via peer: { kind: "user", id: "..." }. Highest precedence — always wins over server or channel bindings.
Run multiple WhatsApp accounts by defining each under channels.whatsapp.accounts with a separate authDir per account.
Agent-to-agent communication is off until you explicitly enable it. Opt-in per agent with an allowlist:
Sessions are keyed as agent:<agentId>:<mainKey>. Each agent maintains its own conversation history, even when communicating with the same user.
Let agents search each other’s memory stores without sharing session context:
Communication is explicit and auditable. Agents can only talk to agents on their allow list, and cross-agent memory access is read-only. No implicit sharing, no hidden state transfer.
Relative paths stay inside the workspace. Absolute paths breach the sandbox. If an agent can write to an absolute path outside its workspace, sandbox isolation is meaningless. Audit your tool configs.
DM sessions collapse to main per agent. Each agent sees only its own session history. Cross-agent sessions are keyed separately — no bleed-through between agents handling the same user.
For maximum isolation: one agent per person. Each user gets a dedicated agent with its own workspace, memory, session store, and auth. This is the gold standard when data separation is non-negotiable.
This bears repeating: sharing agentDir between agents is the most common multi-agent misconfiguration. It causes silent auth collisions and session corruption that are extremely difficult to debug.
Run openclaw agents add to create a new agent with its own ID, workspace, and agentDir. Verify it appears in openclaw agents list. Make sure the agentDir is unique.
Configure a binding in openclaw.json so your new agent handles a specific channel, server, or user. Test that messages route to the correct agent based on your binding rules.
Give each agent a different tool allow/deny list and different skill allowlists. One agent might have full exec access while the other is read-only. Verify the restrictions hold.
Send messages from different channels, users, or roles and confirm the routing precedence matches what you configured. Check that the default agent handles unmatched traffic.
You’ve built the full stack — personality, memory, tools, skills, heartbeats, sub-agents, and now multi-agent orchestration. Day 16 ties it all together with the complete workspace files reference. Every file, every config, every interaction — one definitive guide to running your OpenClaw system in production.