Add a Second Agent
James checked his WhatsApp. A customer had asked about a property listing. His agent replied with a voice note (the inbound mode from Lesson 9 matched the customer's voice message). Good. But the reply started with "I have completed the overnight lead follow-up for 14 Oak Lane" before getting to the property question. The customer heard an internal status update that was meant for James.
"One dispatcher handling walk-ins and phone calls," he said. At his old warehouse, they started with a single person at the front desk. Drivers, customers, suppliers, all in one queue. "We split the desk. Inbound shipments on the left, customer pickups on the right. Different queues, different people. Fixed it in a day."
"What was the split?" Emma asked. "Different scripts, or different permissions?"
"Permissions. The customer pickup person could release inventory. The inbound person could not. You would not want the inbound clerk accidentally releasing a shipment to the wrong driver."
"So it is not about personality."
"No. Both desks were friendly. The split was about what each person was allowed to do." James looked at his phone. "My agent needs the same thing. A customer-facing agent that cannot touch the lead database. An operations agent that does not talk to customers."
Emma set down her coffee. "Create one. Bind it to your WhatsApp. Set its identity. When I come back, tell me which agent answered and how you know."
You are doing exactly what James is doing: one agent handles everything on one WhatsApp number. Now you split the desk.
Step 1: Create the Second Agent
openclaw agents add helper-agent
The wizard walks you through setup. It asks for a workspace directory (accept the default), whether to copy auth profiles from your main agent (say yes), and whether to configure channels now. Select WhatsApp when prompted. If WhatsApp shows "already configured," skip it.
Verify both agents exist:
openclaw agents list --bindings
You should see main (default) and helper-agent. The helper has no routing rules yet.
Step 2: Bind It to WhatsApp and Test
Bind the helper agent to your WhatsApp channel:
openclaw agents bind --agent helper-agent --bind whatsapp
openclaw gateway restart
Now send a message from your other phone on WhatsApp. Two things to check:
- On WhatsApp: A new agent replies. It will not introduce itself as your main agent. The name, tone, or greeting will be different (generic, since you have not set its identity yet).
- On the dashboard: Open the Control UI (
openclaw dashboard). You will see the conversation under thehelper-agenttab, notmain. The dashboard shows which agent handled each message.
If helper-agent answered, the binding works. If main answered, the binding did not take effect. Run openclaw agents list --bindings and verify the routing rule exists.
Both agents share the same WhatsApp number. The routing layer decides which agent handles each message. When you bound helper-agent to WhatsApp, it became the handler for all incoming WhatsApp messages. Your main agent now only handles messages on channels that have no binding.
Step 3: Set Its Identity
Your helper agent introduces itself as a generic assistant because it has no identity set. Tell it who it is on WhatsApp:
Update your IDENTITY.md. Your name is Helper, your role is research
assistant, and your emoji is 🔍. You help me find information and
summarize documents.
Verify it took:
Show me your IDENTITY.md
You should see the name, role, and emoji you specified. Now start a new session and send a message:
/new
Introduce yourself
The agent should introduce itself with the new identity. If it still uses the old name, you are in a cached session. The /new command starts a fresh one.
This is how state works in OpenClaw: identity changes take effect at session boundaries, not mid-conversation. In production, customers in active conversations keep the old persona until their session expires.
Step 4: Customize the Workspace
Your helper agent has its own workspace with the same files as your main agent:
ls ~/.openclaw/workspace-helper-agent/
SOUL.md, IDENTITY.md, AGENTS.md, TOOLS.md, USER.md, HEARTBEAT.md. Each file is independent. Edit helper-agent's SOUL.md to define its specialization. If your main agent is a generalist, make this one a specialist.
Gateway-level settings (plugins, TTS, model config) are shared across both agents. Workspace files are per-agent. This means both agents have access to the same tools and plugins, but they have different personalities, memories, and instructions.
Skills installed in one agent's workspace are NOT available to the other. This is intentional: a customer-facing agent should not have admin-only skills.
Step 5: Route by Sender (Same Number, Different Agents)
Right now, ALL WhatsApp messages go to helper-agent because of the binding. What if you want some contacts to reach main and others to reach helper-agent?
Unbind the channel-wide rule first:
openclaw agents unbind --agent helper-agent --bind whatsapp
openclaw gateway restart
Send a message. It should go back to main (the fallback). Now add a sender-specific rule. The CLI does not support per-sender binding; this requires editing the config file directly.
Open ~/.openclaw/openclaw.json in any editor. Add a bindings key at the top level (at the same level as agents, gateway, channels). Replace the phone number with the number you message FROM:
{
"bindings": [
{
"agentId": "helper-agent",
"match": {
"channel": "whatsapp",
"peer": { "kind": "direct", "id": "+923001234567" }
}
}
],
"agents": { ... },
"gateway": { ... }
}
Save the file, then restart:
openclaw gateway restart
Send a message from that phone number. It goes to helper-agent. Send from a different number. It goes to main. Peer-specific bindings always win over channel-wide bindings, so the order in the array does not matter for priority, though placing more specific rules first is good practice.
Step 6: Different WhatsApp Numbers (Optional)
If you have two phones or two SIMs, you can link separate WhatsApp accounts and give each its own agent:
openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account business
Then bind each account to its agent:
{
bindings: [
{ agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
{ agentId: "work", match: { channel: "whatsapp", accountId: "business" } },
],
}
Two phone numbers, two agents, one gateway. Each account maintains its own authentication and sessions.
Try With AI
Exercise 1: Give Your Helper a Real Specialization
You set the helper's identity in Step 3. Now give it a real specialization via SOUL.md. Message the helper agent on WhatsApp:
Update your SOUL.md to specialize in research. Your job is to help
me find information, summarize documents, and answer questions with
sources. You are thorough and always cite where you found things.
Now ask both agents the same question. Message the helper:
What are the top 3 trends in AI agents for 2026?
Then switch routing back to main and ask the same question. Compare the answers. Does the specialized SOUL.md produce a better response?
What you are learning: SOUL.md is not cosmetic. It shapes how the agent responds, what it prioritizes, and what it remembers. Two agents with different SOUL.md files give different answers to the same question.
Exercise 2: Explore the Dashboard
Open the Control UI (openclaw dashboard). Click between your two agent tabs. Compare their workspaces, identities, and session histories.
Ask the helper on WhatsApp:
What tools do you have access to?
Ask the main agent the same question. Are the tool lists the same? They should be: gateway-level plugins and tools are shared. The difference is in workspace files, not tool access.
What you are learning: The dashboard is where you see both agents side by side. Gateway config (plugins, TTS, model) is shared. Workspace files (SOUL.md, IDENTITY.md, skills) are per-agent. Understanding this split prevents confusion when one agent has a capability and the other does not.
Exercise 3: Design Your Split
Think about your own use case. Write down 3 tasks you want automated. For each one, decide: which agent should handle it?
Ask your main agent: I want to split my work between you and a
helper agent. Here are my three tasks: [list them]. Which ones
should you handle, and which should the helper handle? Why?
Compare the agent's recommendation with your own judgment.
What you are learning: Multi-agent design is about boundaries, not personalities. The split should be based on what each agent is allowed to do and what context it needs, not just how it talks.
When Emma came back, James had the dashboard open with two agent tabs side by side.
"I told the helper who it was on WhatsApp," he said. "Updated IDENTITY.md, updated SOUL.md. Then I messaged it and it still introduced itself with the old name." He paused. "Took me three tries before I figured out I needed /new to start a fresh session."
"When did it click?"
"When I thought about shift rotation at the warehouse. We reassigned people to different zones, but the schedule board did not update until the next shift. Same thing. The session is the shift. The identity change is the reassignment. It takes effect at the boundary, not in the middle."
Emma nodded. "That is actually clearer than how I usually explain session caching. I might steal that."
James pulled up both agent tabs. "Two agents. Different workspaces, different identities. But same tools, same plugins." He pointed at the screen. "The gateway config is shared. The workspace is separate. So if I install a plugin, both agents get it. If I edit SOUL.md, only one agent changes."
"Right. Gateway is infrastructure. Workspace is identity."
James looked at the two tabs. "They work independently. But at the warehouse, inbound passed shipments to outbound. They did not just sit in their own lanes. What if I need one agent to hand work to the other?"
"That is Lesson 12," Emma said. "Your agents learn to delegate."