Haven't installed OpenClaw yet? Click here for one-line install commands
curl -fsSL https://openclaw.ai/install.sh | bashiwr -useb https://openclaw.ai/install.ps1 | iexcurl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd- The OpenClaw tutorial provides three multi-agent collaboration mechanisms — SubAgent (child agents), Agent Teams, and AgentToAgent (cross-agent communication) — each addressing different levels of task complexity and scale[1]
- SubAgent is ideal for "parent-child delegation" scenarios: the parent agent assigns subtasks to specialized child agents for execution, and the child agents return results upon completion, making it well-suited for pipeline-style workflows[2]
- Agent Teams support multiple agents collaborating in peer-to-peer or hierarchical arrangements, sharing context and memory, making them ideal for complex tasks requiring real-time coordination[3]
- The AgentToAgent protocol enables inter-agent communication across OpenClaw instances, supporting distributed agent collaboration in heterogeneous environments[4]
- By selecting appropriate models for different roles (lightweight models for routing, advanced models for reasoning), overall token costs can be reduced by 30-50% while maintaining output quality[1]
When your AI agent needs to simultaneously crawl web pages, analyze data, generate reports, and review code — a single agent simply cannot handle it all. OpenClaw's multiagent architecture was built precisely for this: enabling multiple specialized agents to each fulfill their designated roles and collaborate as a team to accomplish complex automation tasks that were previously unimaginable.[6]
This is the eighteenth article in the OpenClaw series, focusing on the complete technical architecture of OpenClaw multi-agent collaboration. We will break down the three core mechanisms — SubAgent (child agents), Agent Teams, and AgentToAgent (cross-agent communication) — examining their design principles, configuration methods, and applicable scenarios one by one. We also provide ready-to-use openclaw.json multi-agent configuration examples, along with performance tuning and security best practices.
1. Why Do You Need Multi-Agent Collaboration?
Before diving into the technical details of OpenClaw multiagent, let us first clarify a fundamental question: when do you actually need to upgrade from a single agent to a multi-agent architecture?
1.1 Three Bottlenecks of a Single Agent
No matter how powerful the model, a single AI agent always faces the following limitations:
- Context Window Ceiling: Even with a 200K token context window, when a task requires simultaneously holding hundreds of thousands of lines of code, hundreds of documents, and real-time web data, a single agent's memory simply is not enough. A multi-agent architecture solves this through distributed memory — each child agent only needs to maintain context within its scope of responsibility.
- Cognitive Overload: When a single agent must constantly switch between legal analysis, financial calculations, and code review, output quality noticeably degrades as the task chain grows longer. Academic research refers to this as the "attention dilution effect" — the quality of earlier tasks is significantly higher than later ones.
- Sequential Latency: A single agent can only complete subtasks sequentially. If four independent subtasks each take 5 minutes, a single agent needs 20 minutes; four OpenClaw SubAgents executing in parallel, including coordination overhead, need only about 6-7 minutes.
1.2 When to Enable Multi-Agent
Not every task requires multi-agent. Here are the criteria for deciding:
- Tasks can be decomposed into independent subtasks: The fewer dependencies between subtasks, the more pronounced the acceleration from multi-agent
- Different domains of expertise are required: When a task simultaneously involves web scraping, data analysis, text generation, and other diverse skill sets, specialized child agents produce significantly better output than a generalist agent
- Cost-sensitive scenarios: Not every subtask needs the most expensive model. Using GPT-4o-mini for routing decisions and Claude Opus for deep reasoning — this "mixed model" strategy is a cost advantage unique to multi-agent systems
- High reliability requirements: Multi-agent architectures inherently support redundancy — when one child agent fails, a backup agent can take over without affecting the overall workflow
If your scenario meets two or more of the criteria above, it is worth seriously considering OpenClaw's multi-agent configuration.[1]
2. Overview of OpenClaw's Multi-Agent Architecture
OpenClaw provides three clearly tiered multi-agent collaboration mechanisms, from simple to complex: SubAgent (child agents), Agent Teams (team collaboration), and AgentToAgent (cross-agent communication). Understanding their differences and applicable scenarios is the first step toward making the right choice.[1]
2.1 Positioning of the Three Mechanisms
- SubAgent (Child Agents): A one-to-many parent-child relationship. The Parent Agent delegates subtasks to SubAgents for execution, and SubAgents report results back upon completion. Ideal for clearly defined pipeline-style workflows.[2]
- Agent Teams: A many-to-many peer-to-peer or hierarchical collaboration. Multiple agents are organized into a "team," completing complex tasks through shared context, message queues, and coordinator roles. Ideal for scenarios requiring real-time communication and dynamic task allocation.[3]
- AgentToAgent (Cross-Agent Communication): A cross-instance, cross-environment inter-agent communication protocol. When agents are distributed across different machines and different OpenClaw Gateway instances, it enables remote collaboration through a structured messaging protocol.[4]
2.2 How to Choose
The core selection principle is: use the simplest mechanism that solves the problem.
- If your need is "parent agent assigns tasks, child agents return results" → use SubAgent
- If multiple agents need to share state, communicate in real time, and dynamically adjust task allocation → use Agent Teams
- If agents are distributed across different servers or different organizations → use AgentToAgent
In practice, the three mechanisms can be used in combination: members within an Agent Team can further delegate subtasks via SubAgent, and can also communicate with external agents via AgentToAgent.
3. SubAgent: The Parent-Child Delegation Architecture
SubAgent is the most fundamental and most commonly used mechanism in OpenClaw's multi-agent system. Its core concept is straightforward: during execution, the Parent Agent can delegate specific subtasks to one or more OpenClaw SubAgents for processing, and the child agents return results to the parent agent to continue the workflow.[2]
3.1 SubAgent Workflow
The lifecycle of an OpenClaw SubAgent is as follows:
- Step 1 — Task Delegation: The parent agent calls
subagent.delegate(), passing in the task description, required skills, and context data - Step 2 — Child Agent Initialization: OpenClaw finds or creates the corresponding child agent instance based on the configuration, loading its dedicated system prompt and skills
- Step 3 — Independent Execution: The child agent completes the task within its own independent context, using its own bound tools and model
- Step 4 — Result Return: The child agent returns execution results to the parent agent in a structured format, and depending on the configuration, may retain context for subsequent reuse
3.2 SubAgent Configuration in Detail
The complete configuration for defining SubAgents in openclaw.json is as follows:
{
"agents": {
"defaults": {
"model": {
"primary": "claude-opus-4-6"
}
},
"subagents": {
"code-reviewer": {
"description": "A child agent dedicated to code review",
"model": {
"primary": "claude-sonnet-4-6",
"fallbacks": ["gpt-4o"]
},
"system_prompt": "You are a senior code reviewer. Focus on code quality, security vulnerabilities, and performance issues.",
"skills": ["code-analysis", "security-scan"],
"max_tokens": 8192,
"timeout": 120,
"context_retention": "session"
},
"web-researcher": {
"description": "A child agent responsible for web search and data collection",
"model": {
"primary": "gpt-4o",
"fallbacks": ["claude-sonnet-4-6"]
},
"system_prompt": "You are a professional web researcher. Skilled at searching, filtering, and organizing information from the internet.",
"skills": ["web-search", "web-scrape", "summarize"],
"max_tokens": 4096,
"timeout": 180,
"context_retention": "task"
},
"data-analyst": {
"description": "A child agent for data analysis and visualization",
"model": {
"primary": "claude-opus-4-6"
},
"system_prompt": "You are a data scientist. Skilled in data cleaning, statistical analysis, and chart generation.",
"skills": ["data-processing", "chart-generation", "csv-parser"],
"max_tokens": 16384,
"timeout": 300
}
}
}
}Key configuration parameters for each SubAgent:
model: The model used by the child agent, which can be independent of the parent agent. Use lightweight models for routing tasks and advanced models for analysis taskssystem_prompt: The role definition of the child agent. A clear role description significantly improves output qualityskills: The list of skills available to the child agent. OpenClaw uses this list to restrict the child agent's tool access scope[2]timeout: The maximum execution time for the child agent (in seconds). When a timeout occurs, the parent agent receives an error notification, which can trigger a fallback mechanismcontext_retention: The context retention policy for the child agent —taskmeans context is released when the task ends,sessionmeans context is retained for the entire session
3.3 Typical Use Cases for SubAgent
OpenClaw SubAgent is best suited for the following scenarios:
- Code Review Pipeline: After the parent agent receives a Pull Request, it delegates to a "security scan child agent," a "style check child agent," and a "performance analysis child agent" for parallel execution, then the parent agent consolidates the review report
- Content Production Workflow: After the parent agent plans an article outline, it delegates individual sections to different writing child agents, then the parent agent unifies proofreading and formatting
- Data Processing Pipeline: The parent agent distributes raw data in batches to multiple child agents for parallel cleaning and transformation, then merges the results
3.4 Managing SubAgents via CLI
OpenClaw provides a complete set of CLI commands for managing child agents:
# List all configured agents
openclaw agents list
# Add a child agent
openclaw agents add code-reviewer --model claude-sonnet-4-6
# View Gateway logs to trace agent execution
openclaw logs --follow
# Dynamically add a child agent configuration (writes to openclaw.json)
openclaw config set agents.subagents.translator '{"description": "Translation child agent", "model": {"primary": "gpt-4o"}, "system_prompt": "You are a professional translator", "skills": ["translation"], "timeout": 60}'4. Agent Teams: Team Collaboration
When task complexity exceeds the scope of "parent-child delegation" — requiring multiple agents to communicate in real time, share state, and dynamically adjust task allocation — it is time for OpenClaw Agent Teams to take the stage.[3]
4.1 The Fundamental Difference Between Agent Teams and SubAgent
SubAgent follows a "I tell you what to do, and you do it" parent-child model; Agent Teams follow a "let us discuss how to do it together" team model. The specific differences are as follows:
- Communication Direction: SubAgent communication is unidirectional (parent → child → parent); Agent Team members can communicate in multiple directions
- Context Sharing: SubAgents each have their own independent context; Agent Teams support shared memory
- Role Flexibility: SubAgent roles are fixed at configuration time; Agent Teams support dynamic role switching and task reassignment
- Coordination Mechanism: SubAgents are controlled by a single parent agent; Agent Teams support three coordination modes: Orchestrator, Peer-to-Peer, and Hierarchical
4.2 Agent Teams Configuration Structure
The complete configuration for defining an Agent Team in openclaw.json:
{
"agent_teams": {
"research-team": {
"description": "Market research analysis team",
"coordination": "orchestrator",
"orchestrator": "research-lead",
"shared_memory": {
"enabled": true,
"max_size": "50MB",
"persistence": "session"
},
"members": {
"research-lead": {
"role": "Team lead: responsible for task decomposition, progress tracking, and final report integration",
"model": {"primary": "claude-opus-4-6"},
"skills": ["task-planning", "report-generation"],
"can_delegate": true
},
"web-scout": {
"role": "Web scout: responsible for searching and collecting publicly available information",
"model": {"primary": "gpt-4o"},
"skills": ["web-search", "web-scrape"],
"can_delegate": false
},
"analyst": {
"role": "Data analyst: responsible for data cleaning, statistical analysis, and trend identification",
"model": {"primary": "claude-sonnet-4-6"},
"skills": ["data-analysis", "chart-generation"],
"can_delegate": false
},
"writer": {
"role": "Report writer: responsible for transforming analysis results into structured reports",
"model": {"primary": "claude-sonnet-4-6"},
"skills": ["content-writing", "formatting"],
"can_delegate": false
}
},
"workflow": {
"max_rounds": 10,
"timeout": 600,
"early_stop": {
"condition": "orchestrator_decision",
"min_rounds": 2
}
}
}
}
}4.3 Three Coordination Modes
OpenClaw Agent Teams support three coordination modes, each corresponding to a different team operation style:[3]
Orchestrator Mode: The team has a clearly designated "commander" who is responsible for distributing tasks, collecting feedback, and making decisions. Best suited for tasks with well-defined processes.
{
"coordination": "orchestrator",
"orchestrator": "research-lead",
"orchestrator_config": {
"planning_strategy": "decompose-first",
"feedback_loop": true,
"max_delegation_depth": 3
}
}Peer-to-Peer Mode: All members have equal standing and communicate freely through message queues. Ideal for brainstorming, creative collaboration, and other scenarios without fixed processes.
{
"coordination": "peer-to-peer",
"message_queue": {
"type": "broadcast",
"max_messages_per_round": 5
},
"consensus": {
"strategy": "majority-vote",
"min_particenterprise process automationtion": 0.75
}
}Hierarchical Mode: A multi-layered management structure. Top-level agents manage mid-level agents, who in turn manage bottom-level agents. Ideal for large-scale, multi-layered complex tasks.
{
"coordination": "hierarchical",
"hierarchy": {
"level_0": ["project-lead"],
"level_1": ["frontend-lead", "backend-lead", "qa-lead"],
"level_2": ["fe-dev-1", "fe-dev-2", "be-dev-1", "be-dev-2", "tester-1"]
},
"escalation_policy": "up-one-level"
}4.4 Shared Memory
State sharing among Agent Team members is the key feature that distinguishes team collaboration from SubAgent. OpenClaw provides a structured shared memory mechanism:[3]
- Key-Value Store: Team members can read and write shared key-value pairs for passing intermediate results
- Event Queue: Members can publish event notifications, while other members subscribe to event types of interest
- Document Pool: A shared document area where members can upload, read, and modify shared documents
{
"shared_memory": {
"enabled": true,
"stores": {
"kv": {
"type": "key-value",
"max_entries": 1000,
"ttl": 3600
},
"events": {
"type": "event-queue",
"max_backlog": 500,
"retention": "current-task"
},
"docs": {
"type": "document-pool",
"max_size": "100MB",
"allowed_types": ["text", "json", "csv", "image"]
}
},
"access_control": {
"default": "read-write",
"overrides": {
"writer": {"docs": "write-only"},
"analyst": {"kv": "read-write", "docs": "read-only"}
}
}
}
}4.5 Role Assignment and Skill-Based Routing
In an OpenClaw Agent Team, task routing is not only based on static role definitions but also supports dynamic routing based on skills. When the Orchestrator receives a subtask, the system determines who will execute it based on the following priority order:
- Exact Match: The subtask's required skills perfectly match a member's skills
- Best Fit: When there is no exact match, select the member who covers the most required skills
- Load Balancing: When multiple members are equally matched, select the one with the lowest current load
{
"routing": {
"strategy": "skill-based",
"skill_matching": {
"mode": "best-fit",
"fallback": "orchestrator"
},
"load_balancing": {
"enabled": true,
"strategy": "shortest-queue"
}
}
}5. AgentToAgent: Cross-Agent Communication
When your agents are no longer confined to a single OpenClaw instance — distributed across different machines, different teams, or even different organizations — you need the AgentToAgent (A2A) cross-agent communication protocol.[4]
5.1 Design Philosophy of AgentToAgent
The core design principle of the OpenClaw AgentToAgent communication protocol is: enabling agents on different OpenClaw instances to collaborate as if they were members of the same team. It addresses three pain points in distributed scenarios:
- Cross-Machine Collaboration: A "code agent" on the development server and a "deployment agent" on the production server need to coordinate
- Cross-Team Collaboration: The marketing department's "content agent" needs to obtain data from the engineering department's "data agent"
- Cross-Organization Collaboration: Your agents need to exchange information with a partner's agents (within security boundaries)
5.2 Communication Protocol and Message Format
OpenClaw AgentToAgent uses a structured message format based on HTTP/gRPC:[4]
{
"agenttoagent": {
"enabled": true,
"protocol": "grpc",
"listen": {
"host": "0.0.0.0",
"port": 9090,
"tls": {
"enabled": true,
"cert": "/etc/openclaw/certs/agent.crt",
"key": "/etc/openclaw/certs/agent.key"
}
},
"peers": {
"deploy-agent": {
"enRLHF alignmentint": "https://prod-server.internal:9090",
"auth": {
"type": "mutual-tls",
"ca_cert": "/etc/openclaw/certs/ca.crt"
},
"capabilities": ["deployment", "monitoring", "rollback"],
"timeout": 60
},
"data-agent": {
"endpoint": "https://analytics.internal:9090",
"auth": {
"type": "bearer-token",
"token_env": "DATA_AGENT_TOKEN"
},
"capabilities": ["data-query", "report-generation"],
"timeout": 120
}
}
}
}5.3 Message Delivery Patterns
AgentToAgent supports three message delivery patterns:
- Request-Response: The most common synchronous pattern. Agent A sends a request and waits for Agent B's response. Ideal for queries and short-duration tasks.
- Fire-and-Forget: An asynchronous pattern. Agent A sends a message and continues execution without waiting for a response. Ideal for notifications, log synchronization, and similar scenarios.
- Streaming: Agent B incrementally returns results in a streaming fashion. Ideal for long-running tasks where the parent agent can track progress in real time.
# Check Gateway health status (including node information)
openclaw gateway health
# View Gateway logs to trace cross-agent communication
openclaw logs --follow
# Call a remote method via Gateway RPC
openclaw gateway call health5.4 Security and Access Control
Security in cross-agent communication is of paramount importance. OpenClaw AgentToAgent provides multi-layered security mechanisms:[7]
- Authentication: Supports three authentication methods — Mutual TLS, Bearer Token, and API Key
- Authorization: Fine-grained permission control based on capabilities — each peer can only perform operations within the scope of its declared capabilities
- Encryption: All communication uses TLS encryption by default, with support for both self-signed certificates and CA-issued certificates
- Rate Limiting: Prevents a single peer from over-consuming resources
{
"agenttoagent": {
"security": {
"rate_limit": {
"requests_per_minute": 60,
"burst": 10
},
"allowed_actions": {
"deploy-agent": ["get-deployment-status", "trigger-deploy"],
"data-agent": ["query-data", "generate-report"]
},
"audit_log": {
"enabled": true,
"path": "~/.openclaw/logs/a2a-audit.log"
}
}
}
}6. Practical Configuration Examples
Below are two complete openclaw.json multi-agent configuration examples, covering real-world application scenarios from SubAgent to Agent Teams.
6.1 Example 1: Full-Stack Development Agent Team
This example configures a complete development pipeline team, including four roles: coding, review, testing, and deployment:
{
"agents": {
"defaults": {
"model": {
"primary": "claude-opus-4-6",
"fallbacks": ["claude-sonnet-4-6"]
}
}
},
"agent_teams": {
"dev-pipeline": {
"description": "Full-stack development pipeline agent team",
"coordination": "orchestrator",
"orchestrator": "tech-lead",
"shared_memory": {
"enabled": true,
"stores": {
"codebase": {
"type": "document-pool",
"max_size": "200MB"
},
"review-notes": {
"type": "key-value",
"max_entries": 500
}
}
},
"members": {
"tech-lead": {
"role": "Tech lead: decomposes development tasks, assigns work, and integrates final code",
"model": {"primary": "claude-opus-4-6"},
"skills": ["task-planning", "code-review", "git-operations"],
"can_delegate": true
},
"frontend-dev": {
"role": "Frontend developer: React/Next.js development, UI implementation, responsive design",
"model": {"primary": "claude-sonnet-4-6"},
"skills": ["frontend-coding", "css-design", "accessibility"],
"can_delegate": false
},
"backend-dev": {
"role": "Backend developer: API design, database operations, server logic",
"model": {"primary": "claude-sonnet-4-6"},
"skills": ["backend-coding", "database", "api-design"],
"can_delegate": false
},
"qa-engineer": {
"role": "QA engineer: writes test cases, executes tests, reports defects",
"model": {"primary": "gpt-4o"},
"skills": ["test-writing", "test-execution", "bug-reporting"],
"can_delegate": false
}
},
"workflow": {
"max_rounds": 15,
"timeout": 900,
"stages": [
{"name": "planning", "agents": ["tech-lead"]},
{"name": "development", "agents": ["frontend-dev", "backend-dev"], "parallel": true},
{"name": "review", "agents": ["tech-lead"]},
{"name": "testing", "agents": ["qa-engineer"]},
{"name": "integration", "agents": ["tech-lead"]}
]
}
}
}
}6.2 Example 2: Hybrid SubAgent + AgentToAgent Research System
This example demonstrates how to combine SubAgent and AgentToAgent to build a cross-environment market research system:
{
"agents": {
"defaults": {
"model": {
"primary": "claude-opus-4-6"
}
},
"subagents": {
"news-scanner": {
"description": "News scanning child agent",
"model": {"primary": "gpt-4o-mini"},
"system_prompt": "Scan news for specified keywords and return summaries with source links.",
"skills": ["web-search", "summarize"],
"timeout": 120
},
"patent-analyzer": {
"description": "Patent analysis child agent",
"model": {"primary": "claude-opus-4-6"},
"system_prompt": "Analyze patent data for specified companies or technology domains.",
"skills": ["patent-search", "technical-analysis"],
"timeout": 300
},
"report-compiler": {
"description": "Report compilation child agent",
"model": {"primary": "claude-sonnet-4-6"},
"system_prompt": "Consolidate research data from multiple sources into a structured report.",
"skills": ["report-generation", "formatting", "chart-generation"],
"timeout": 180
}
}
},
"agenttoagent": {
"enabled": true,
"protocol": "grpc",
"listen": {
"host": "0.0.0.0",
"port": 9090,
"tls": {"enabled": true}
},
"peers": {
"financial-data-agent": {
"endpoint": "https://finance-server.internal:9090",
"auth": {"type": "mutual-tls"},
"capabilities": ["stock-data", "financial-reports", "market-analysis"],
"timeout": 60
}
}
}
}With this configuration, the parent agent can: (1) delegate news scanning and patent analysis to local SubAgents for parallel processing; (2) retrieve stock prices and financial report data from a remote financial data agent via AgentToAgent; (3) finally, have the report-compiler SubAgent consolidate data from all sources to produce a complete research report.
6.3 Initializing Multi-Agent Configuration via CLI
In addition to directly editing openclaw.json, you can also use the CLI to incrementally build your multi-agent configuration:[5]
# Create agents
openclaw agents add tech-lead --model claude-opus-4-6
openclaw agents add frontend-dev --model claude-sonnet-4-6
openclaw agents add news-scanner --model gpt-4o
# Team configuration is done by directly editing openclaw.json
# Define the team structure in the agent_teams section
# Verify the configuration is correct
openclaw doctor7. Performance Tuning and Best Practices
The performance of a multi-agent system depends not only on the capabilities of individual agents but also on the design of the overall architecture. Below are battle-tested tuning strategies and best practices.[1]
7.1 Token Cost Optimization
The biggest cost trap in multi-agent systems is "context bloat" — every interaction by every agent consumes tokens, and without control, costs can grow explosively.
- Model Tiering Strategy: Select appropriate models for different roles. Use GPT-4o-mini (approximately $0.15 per million tokens) for routing decisions and simple format conversions; use Claude Opus (approximately $15 per million tokens) for deep reasoning and complex analysis. This can reduce overall costs by 30-50%.
- Context Trimming: When child agents return results, use
response_format: "summary"to request concise responses, avoiding flooding the parent agent's context with large amounts of raw data. - Selective Sharing: While Agent Team shared memory is convenient, every member reading shared data consumes tokens. Set appropriate access controls to ensure members only read data relevant to their tasks.
{
"optimization": {
"token_budget": {
"enabled": true,
"max_tokens_per_task": 100000,
"alert_threshold": 0.8,
"action_on_exceed": "warn"
},
"context_compression": {
"enabled": true,
"strategy": "extractive-summary",
"compress_after_tokens": 50000
}
}
}7.2 Error Handling and Fault Tolerance
In a multi-agent system, the failure of a single child agent should not cause the entire task to fail. Designing robust fault tolerance mechanisms is critical:
- Retry Strategy: Set
max_retriesandbackoffstrategies for each child agent. Exponential backoff is the most effective strategy for handling API rate limits. - Backup Agents: When a primary child agent fails consecutively, automatically switch to a backup agent. The backup agent can use a different model or a different approach to complete the same task.
- Graceful Degradation: When a non-critical child agent fails, the Orchestrator should be able to determine whether the workflow can continue without that child agent's output.
- Error Isolation: Errors from child agents should not contaminate shared memory. Data integrity and correctness must be verified before writing to shared memory.
{
"error_handling": {
"retry": {
"max_retries": 3,
"backoff": "exponential",
"base_delay": 2,
"max_delay": 60
},
"fallback": {
"code-reviewer": {
"fallback_agent": "backup-reviewer",
"trigger": "consecutive_failures",
"threshold": 2
}
},
"graceful_degradation": {
"non_critical_agents": ["news-scanner", "chart-generator"],
"action": "skip-and-continue"
}
}
}7.3 Security Considerations
Multi-agent systems expand the attack surface, so security boundaries must be established at every layer:[7]
- Principle of Least Privilege: Each child agent should only have the minimum skills and tool access required to complete its task. Avoid granting child agents "global" tool access permissions.
- Sandbox Execution: Child agents with code execution capabilities should run in a sandboxed environment. OpenClaw supports enabling this via the
sandbox: trueconfiguration option. - AgentToAgent Authentication: Cross-agent communication must have TLS encryption and Mutual TLS authentication enabled to prevent man-in-the-middle attacks.
- Audit Logging: Enable comprehensive audit logging that records the initiator, content, result, and timestamp of every cross-agent call.
- Sensitive Data Isolation: Use shared memory access controls to ensure that key-value pairs containing sensitive data (such as API keys and personal information) cannot be read by unauthorized agents.
7.4 Monitoring and Observability
Debugging multi-agent systems is far more difficult than debugging a single agent. Establishing a comprehensive monitoring system is the foundation of operations:
# View all agent statuses
openclaw agents list
# View real-time Gateway status
openclaw gateway status
# View usage costs
openclaw gateway usage-cost
# Follow Gateway logs
openclaw logs --follow8. Frequently Asked Questions (FAQ)
Q1: Can SubAgent and Agent Teams be used simultaneously?
Yes. An Agent Team member can have its own SubAgents. For example, the research team's Orchestrator can delegate a subtask to its own SubAgent for processing, rather than assigning it to other team members. This is particularly useful in scenarios where "private" tools are needed.[1]
Q2: Will AgentToAgent latency become a bottleneck?
It depends on network conditions and task type. AgentToAgent call latency within a local area network is typically 20-50ms; cross-region latency may reach 100-300ms. For non-real-time tasks (such as data collection and report generation), this latency is perfectly acceptable. For scenarios requiring high-frequency interaction, it is recommended to place related agents in the same Agent Team and use shared memory for communication.[4]
Q3: Will multi-agent costs be significantly higher than a single agent?
Not necessarily. While a multi-agent system's total token count may be higher (due to the overhead of coordination and communication), through model tiering strategies — using inexpensive models for routing, format conversion, and other simple tasks — the overall cost can actually be lower. Real-world testing data shows that an optimized multi-agent system can process equivalent tasks at 20-35% lower cost than a single advanced model, while delivering higher quality.
Q4: Can different SubAgents use different model providers?
Yes. This is one of the core advantages of OpenClaw's multi-agent configuration. Each SubAgent and Agent Team member can independently specify its model and provider. For example, use Claude Opus for code review, GPT-4o for web search, and Gemini for translation — each model playing to its strengths.[2]
Q5: What is the maximum number of members an Agent Team can have?
OpenClaw has no hard technical limit, but based on practical experience, 3-7 members is the most efficient range. Beyond 7 members, coordination overhead increases significantly, and the Orchestrator's context can easily become overloaded. If a task requires more roles, it is recommended to use Hierarchical mode and split the large team into multiple smaller groups.[3]
Q6: How do you ensure the security of AgentToAgent communication?
Three key steps: (1) Enable Mutual TLS to ensure both parties' identities are verified; (2) Use allowed_actions whitelists to restrict the operations each peer can perform; (3) Enable audit logging to record all cross-agent communications. In enterprise environments, it is also recommended to route AgentToAgent traffic through an internal network or VPN, keeping it off the public internet.[7]
Q7: How does the parent agent handle SubAgent failures?
OpenClaw provides a complete error handling chain: first, retries are attempted based on the max_retries setting; if retries still fail, it checks whether a fallback_agent is configured; if the backup agent also fails, the error is escalated to the Orchestrator or parent agent for decision-making. You can configure different handling strategies for different error types (timeout, api_error, capability_mismatch) in the configuration.
Q8: How do you debug "ghost issues" in multi-agent systems?
The most difficult issue to diagnose in multi-agent systems is when "results are wrong but no agent reports an error." It is recommended to use openclaw logs --follow for real-time log tracing, which records each agent's execution process and helps quickly pinpoint which step the problem occurred at.[5]
OpenClaw's multi-agent collaboration architecture — from SubAgent's lightweight delegation, to Agent Teams' team collaboration, to AgentToAgent's cross-instance communication — provides developers with a complete toolkit, enabling you to choose the most appropriate collaboration mode based on task complexity. The key is to follow the principle of "use the simplest mechanism that solves the problem": if SubAgent can handle it, do not use Agent Teams; if it can be done locally, you do not need AgentToAgent. Master the correct timing and configuration of these three mechanisms, and you will be able to build a truly efficient, reliable, and scalable AI agent army.
