OpenClaw

OpenClaw Multi-Agent Systems👨‍💻

Multi-agent systems in OpenClaw go beyond simple routing. While the binding system directs messages to the right agent based on channel, role, or account, multi-agent architectures enable agents to collaborate: a triage agent classifies and delegates, a coordinator orchestrates workflows across specialists, and agents share context through explicit handoff mechanisms. This page covers the patterns for building production multi-agent systems -- from basic routing to triage classification, agent-to-agent delegation, shared knowledge bases, and the security considerations that come with agents spawning and communicating with other agents.

Key Takeaways

  • 1The triage pattern is the most common multi-agent architecture. A lightweight classifier agent (using a cheap model like GPT-4o-mini) receives all messages, determines intent, and routes to the appropriate specialist agent. This is more cost-effective and produces better results than a single general-purpose agent.
  • 2Agent-to-agent delegation uses the `agent-router` tool, which allows one agent to forward a message (with context) to another agent. The delegating agent can include instructions and receive the specialist's response to relay back to the user.
  • 3Shared context between agents is explicit, not automatic. Each agent has an isolated workspace. To share knowledge, use a shared knowledge base tool, a shared file path, or include context in the delegation payload. Implicit sharing would be a security risk.
  • 4Sandbox scope: tree is critical for multi-agent setups. When an orchestrator agent spawns or delegates to sub-agents, the tree scope ensures the orchestrator's sandbox restrictions propagate to all sub-agents. Without it, a sub-agent could have more permissions than its parent.
  • 5The coordinator pattern extends triage by adding orchestration. A coordinator agent breaks complex tasks into subtasks, delegates each to a specialist, collects results, and synthesizes a final response. This is useful for multi-step workflows like incident response or code review pipelines.
  • 6Routing priority determines which agent handles a message when multiple bindings match. The eight-tier hierarchy (peer > parent peer > guild+roles > guild > team > account > channel > default) is evaluated top-to-bottom. Understanding this hierarchy prevents routing surprises in complex setups.

Master openclaw multi-agent systems

Take the OpenClaw for Production & Advanced Use course with hands-on lessons and challenges.

Examples

Triage agent with specialist delegation

json

The triage agent receives all messages (default binding) and only has the agent-router tool -- it cannot take any actions itself. It classifies intent and delegates to the right specialist. The triage agent uses strict sandbox with tree scope, ensuring any delegation inherits restrictions. Specialists have focused tool sets matching their domain.

Agent-to-agent delegation with context

bash

The agent-router tool provides structured delegation with context passing. The delegating agent includes the original user message and any relevant metadata. The returnResponse flag means the specialist's answer comes back to the triage agent, which can then relay it to the user. Delegation is logged for auditing.

Coordinator pattern for multi-step workflows

json

The coordinator breaks incident response into subtasks and delegates to specialists: diagnostics for root cause analysis, comms for status updates, and fix for implementing the solution. The coordinator synthesizes results into a final report. This pattern is powerful for complex workflows that require different expertise at each step.

Shared knowledge base between agents

json

Both support agents share access to the same knowledge base directory. L1 handles common questions using the knowledge base and escalates to L2 via agent-router when the issue requires deeper investigation. The shared knowledge base is a read-only file search tool -- agents cannot modify each other's data, maintaining isolation while sharing reference material.

Monitoring multi-agent interactions

bash

Monitoring reveals delegation patterns, response times, and routing failures. Chain tracking shows the full delegation path for complex workflows. Per-agent stats help you identify bottlenecks and optimize model selection. Routing misses indicate messages that fell through without matching any agent binding.

Common Mistakes

Mistake:

Using scope: agent instead of scope: tree for orchestrator agents, allowing delegated sub-agents to bypass the orchestrator's sandbox restrictions

Fix:

Always use scope: tree for any agent that delegates to other agents. Without tree scope, a sub-agent inherits the default sandbox mode, which may be less restrictive than intended. This is a common security gap in multi-agent setups.

Mistake:

Giving the triage agent access to action tools (bash, file_write, deploy) in addition to agent-router, allowing it to take actions directly instead of delegating

Fix:

The triage agent should only have the agent-router tool. Its sole job is classification and delegation. If it has action tools, it may attempt to handle requests itself instead of routing to specialists, producing lower-quality results.

Mistake:

Assuming agents automatically share conversation context or memory when one delegates to another

Fix:

Agent workspaces are fully isolated. Context must be explicitly passed in the delegation payload. If agents need shared knowledge, configure a shared knowledge base tool or shared file path. Implicit sharing would be a security vulnerability.

Mistake:

Creating circular delegation chains where Agent A delegates to Agent B, which delegates back to Agent A, causing infinite loops

Fix:

Design delegation as a directed acyclic graph (DAG). The triage agent delegates to specialists, but specialists should never delegate back to the triage agent. Use clear hierarchies: triage -> specialist, coordinator -> workers.

Mistake:

Using an expensive model (Claude Sonnet, GPT-4o) for the triage agent when it only performs simple message classification

Fix:

The triage agent does basic intent classification -- it does not need deep reasoning. Use GPT-4o-mini or a similar lightweight model. Reserve expensive models for specialist agents that generate detailed responses.

Best Practices

  • Use the triage pattern as the default multi-agent architecture. A lightweight classifier routing to focused specialists is more cost-effective, produces better responses, and is easier to maintain than a single general-purpose agent.
  • Always set scope: tree on orchestrator and triage agents. Sandbox restrictions must propagate down the delegation chain to prevent sub-agents from gaining more permissions than their parent.
  • Give the triage agent only the agent-router tool. It should classify and delegate, never take actions directly. This separation of concerns keeps the architecture clean and predictable.
  • Pass relevant context in delegation payloads. Include the original user message, channel metadata, and any classification results. The specialist agent performs better with context than with a bare forwarded message.
  • Monitor delegation chains and per-agent response times. Long chains or slow specialists indicate architectural problems that may need restructuring or model changes.
  • Design delegation as a DAG (directed acyclic graph). Triage delegates down to specialists, coordinators delegate to workers. Never allow circular delegation paths.

Summary

Multi-agent systems in OpenClaw enable sophisticated collaboration patterns beyond basic routing. The triage pattern uses a cheap classifier to route messages to expensive specialists. Agent-to-agent delegation via the agent-router tool passes context explicitly. The coordinator pattern orchestrates multi-step workflows across specialist agents. Shared knowledge bases enable read-only data sharing without breaking workspace isolation. Always use scope: tree for orchestrators, restrict triage agents to agent-router only, pass context in delegation payloads, and design delegation as a DAG to prevent circular loops.

Practice OpenClaw with hands-on challenges

Learn openclaw multi-agent systems hands-on in your IDE

Interactive lessons and challenges on Stanza, practice in VS Code, Cursor, or the web.

Related Concepts

Openclaw Multi Agent RoutingOpenclaw AgentsOpenclaw Security SandboxingOpenclaw ChannelsOpenclaw Tools

Related Cheatsheets

Openclaw Cli Cheatsheet

Master OpenClaw with Stanza

Interactive lessons and challenges, right in your code editor.

Check the free courses. No credit card.