Multi-Agent Systems with OpenClaw — Orchestration, Communication

When to Use Multi-Agent Systems

A single agent is the right choice for most tasks. Multi-agent systems add orchestration complexity that's only justified when tasks genuinely benefit from parallelism or role separation. Use multiple agents when:

Tasks are naturally parallelizable: Research 5 topics simultaneously rather than sequentially
Different subtasks need different system prompts: A "strict code reviewer" agent and a "friendly documentation writer" agent behave better with focused prompts
Context window limits are a concern: Split a large task across agents to avoid exceeding per-request context limits
You need verification by a second agent: One agent drafts, another critiques or fact-checks

Don't add agents just because you can. Two agents with poorly defined responsibilities often produce worse results than one well-prompted agent. Start with a single agent, and add agents only when you identify a specific bottleneck or quality issue that role separation would solve.

Pipeline Basics

OpenClaw's multi-agent system uses a pipeline — a sequence of stages where each stage can use a different agent configuration, tools, and instructions. Stages run in order by default, with the ability to pass outputs between stages.

# agents.yaml — multi-agent pipeline
pipeline:
  - id: research
    system_prompt: "You are an expert researcher. Find factual, authoritative information."
    tools: [web_search, read_url]
    output_key: research_data

  - id: analyze
    system_prompt: "You are a data analyst. Extract key insights from research data."
    input_from: research_data
    output_key: analysis

  - id: write
    system_prompt: "You are a technical writer. Create clear, structured documentation."
    input_from: analysis
    output_key: final_report
    output_file: report.md

openclaw pipeline run agents.yaml --goal "Analyze the top 5 cloud providers for AI workloads"

Parallel Agent Execution

For tasks that can run independently, configure agents to run in parallel using the parallel keyword. Parallel stages execute simultaneously and results are merged before continuing to the next stage.

pipeline:
  - id: gather_data
    parallel: true
    agents:
      - id: research_aws
        system_prompt: "Research AWS AI/ML services thoroughly."
        tools: [web_search, read_url]
        output_key: aws_data
      - id: research_azure
        system_prompt: "Research Azure AI services thoroughly."
        tools: [web_search, read_url]
        output_key: azure_data
      - id: research_gcp
        system_prompt: "Research GCP AI services thoroughly."
        tools: [web_search, read_url]
        output_key: gcp_data

  - id: compare
    system_prompt: "You are an analyst. Create a fair, comprehensive comparison."
    input_from: [aws_data, azure_data, gcp_data]
    output_file: cloud-ai-comparison.md

Running three research agents in parallel reduces total execution time from 3× sequential to approximately 1.2× (allowing for slight variation in agent duration). For research-heavy tasks, parallelism is consistently the highest-ROI performance optimization available.

Agent Communication Patterns

Agents communicate through typed outputs — one agent's output_key becomes another agent's input_from value. OpenClaw serializes outputs to JSON and provides context to downstream agents as structured data in their system context.

For agent-to-agent communication beyond simple pass-through, OpenClaw supports three patterns:

Pattern	Use case	Config
Sequential pass-through	Output of A feeds input of B	`input_from: agent_a_key`
Merge multiple inputs	Combine outputs from parallel agents	`input_from: [key_a, key_b, key_c]`
Conditional routing	Route to different next stages based on output	`condition: output.contains("error")`

Role-Based Agent Specialization

The most common multi-agent pattern in production is role specialization — giving each agent a focused system prompt that makes it genuinely better at its specific subtask than a generalist agent would be.

agents:
  - id: critic
    system_prompt: |
      You are a strict code reviewer. Your job is to find bugs, security issues,
      and performance problems. Be thorough and specific. List every issue you find.
      Do not suggest improvements — only flag problems.

  - id: suggester
    system_prompt: |
      You are a constructive mentor. Given a list of code issues, suggest the most
      important fixes in order of priority. Keep suggestions actionable and concise.

  - id: documenter
    system_prompt: |
      You are a technical writer. Given code and review notes, generate clear
      inline documentation. Focus on explaining WHY, not WHAT the code does.

Notice how each prompt gives the agent a clear role, a clear restriction, and a clear output goal. Agents with specific, constrained roles consistently produce higher-quality results than one generalist agent asked to do all three tasks simultaneously.

Error Handling in Pipelines

Multi-agent pipelines need robust error handling since a failure midway through can waste all the work done by earlier stages. OpenClaw pipelines support checkpoint saving — completed stage outputs are persisted so a partial failure can be resumed.

pipeline:
  checkpoint: true          # save each stage output before proceeding
  max_retries: 2            # retry failed stages up to N times
  on_failure: continue      # continue pipeline with empty input on failure
  # alternatives: on_failure: abort | on_failure: notify_and_abort

Orchestration Strategies

Beyond simple sequential and parallel pipelines, OpenClaw supports three distinct orchestration strategies that suit different problem types:

Hierarchical orchestration uses a coordinator agent that decomposes the goal into subtasks and delegates to specialist agents. The coordinator receives all results and synthesizes the final output. This mirrors how a senior engineer would delegate to team members — decompose, dispatch, integrate.

Competitive orchestration runs multiple agents on the same task independently, then uses a judge agent to select the best output. This works well for creative tasks (writing, code generation) where quality is hard to predict and having multiple candidates to choose from improves results. The added cost of multiple parallel runs is often justified by higher consistency.

Consensus orchestration requires agreement between multiple agents before proceeding — useful for high-stakes decisions where a single agent's output can't be fully trusted. If two agents disagree significantly, a third is called to adjudicate. This pattern is common in financial analysis and security review workflows.

Debugging Multi-Agent Pipelines

Debugging multi-agent systems requires tools for tracing what each agent did, what inputs it received, and what it produced. OpenClaw's pipeline execution log captures the full run in structured JSON:

# Run with full trace logging
openclaw pipeline run agents.yaml --goal "..." --trace-output ./trace.json

# Inspect individual agent outputs
openclaw pipeline inspect trace.json --stage research
openclaw pipeline replay trace.json --from-stage analyze  # re-run from a specific stage

The most common debugging issues in multi-agent pipelines are: context truncation (stage 2 doesn't get all of stage 1's output), role confusion (agent ignores its system prompt and tries to do everything), and silent failures (tool call fails but agent continues with empty result). The --trace-output flag is the most valuable diagnostic tool for all three.