Building an AI Dream Team with OpenClaw: A Hands‑On Multi‑Agent Guide

Why Multi‑Agent?

Single large‑model agents encounter three problems on complex tasks: context explosion (long contexts cause forgetting), role confusion (frequent switching between programmer, product manager, etc.), and low efficiency (serial processing blocks progress).

Task handling: parallel instead of serial.

Role focus: each agent has a dedicated role.

Context management: isolated per agent, avoiding overflow.

Cost optimization: models allocated on demand rather than a single expensive model.

Scalability: unlimited expansion by adding agents.

OpenClaw Multi‑Agent Architecture Overview

Agent Types

Persistent Agent : resident, long‑running scenarios such as a customer‑service bot or coding assistant.

Sub‑Agent : created for a temporary sub‑task and destroyed after completion; typical for information search or test execution.

ACP Agent : communicates via a defined protocol, suitable for cross‑platform micro‑service calls.

Core Architecture Components

┌─────────────────────────────────────────────────────────┐
│               Gateway (网关层)                         │
│ 统一入口，负责路由和调度                                 │
└─────────────────────────────────────────────────────────┘
        │
        ▼
   ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
   │   Manager      │   │   Coder       │   │   Tester      │
   │ (调度员)       │   │ (开发专家)    │   │ (测试专家)    │
   └───────────────┘   └───────────────┘   └───────────────┘
        │                     │                     │
        │- 任务拆解            │- 代码实现            │- 测试用例
        │- 任务分配            │- 代码审查            │- Bug 报告
        │- 结果汇总            │- 技术方案            │- 质量评估
        ▼                     ▼                     ▼
   ┌───────────────────────┐
   │   Shared Memory        │
   │ (共享记忆空间)          │
   └───────────────────────┘

Workspace Isolation

~/.openclaw/
├── agents/
│   ├── manager/
│   │   ├── agent.md        # role definition
│   │   ├── MEMORY.md        # long‑term memory
│   │   └── workspace/      # work directory
│   ├── coder/
│   │   ├── agent.md
│   │   ├── MEMORY.md
│   │   └── workspace/
│   └── tester/
│       ├── agent.md
│       ├── MEMORY.md
│       └── workspace/
└── openclaw.json          # global configuration

File‑system isolation: an agent cannot directly access another agent's files.

Memory isolation: each agent maintains its own MEMORY.md.

Configuration isolation: models, tools, and permissions can be set per agent.

Practical Walk‑through: Building a 3‑Person AI Development Team

Scenario Definition

Roles: Product Manager (PM) – requirement analysis and task decomposition; Developer (Coder) – code implementation; Tester (QA) – test creation and validation.

Step 1 – Create Agents

# create product‑manager agent
openclaw agents add product-manager
# create developer agent
openclaw agents add code-developer
# create tester agent
openclaw agents add test-engineer

Step 2 – Define Roles (agent.md)

Product Manager ~/.openclaw/agents/product-manager/agent.md :

# Role: Product Manager
You are an experienced product manager skilled at requirement analysis and task decomposition.
Responsibilities:
1. Deeply understand user needs
2. Break requirements into executable tasks
3. Coordinate developers and testers
4. Control schedule and quality
Collaboration rules:
- Mention @code-developer for coding tasks
- Mention @test-engineer for testing tasks
- Do not write code yourself; only assign and summarize results
Output format:
1. Requirement summary
2. Task list with priorities
3. Specific instructions for each role

Developer ~/.openclaw/agents/code-developer/agent.md :

# Role: Senior Developer
You are a full‑stack engineer proficient in React, Node.js, and Python.
Responsibilities:
1. Write high‑quality code
2. Conduct code review and refactoring
3. Propose technical solutions
Work principles:
- Code first, explanation later
- Follow best practices and design patterns
- Consider edge cases and error handling
Output format:
1. Technical solution (if needed)
2. Complete code implementation
3. Usage examples

Tester ~/.openclaw/agents/test-engineer/agent.md :

# Role: QA Engineer
You specialize in test case design and automated testing.
Responsibilities:
1. Write test cases based on requirements
2. Execute tests and report results
3. Evaluate code quality and coverage
Test types:
- Unit tests
- Integration tests
- Boundary tests
- Exception tests
Output format:
1. Test plan
2. Test case code
3. Test report (pass/fail items)

Step 3 – Configure Models (openclaw.json)

{
  "agents": {
    "list": [
      {
        "id": "product-manager",
        "name": "产品经理",
        "model": "claude-sonnet-4",
        "workspace": "~/.openclaw/agents/product-manager",
        "systemPrompt": "file://~/.openclaw/agents/product-manager/agent.md",
        "tools": ["web_search", "file_read"],
        "subagents": {"allowAgents": ["code-developer", "test-engineer"], "maxConcurrent": 2}
      },
      {
        "id": "code-developer",
        "name": "开发工程师",
        "model": "gpt-5.4",
        "workspace": "~/.openclaw/agents/code-developer",
        "systemPrompt": "file://~/.openclaw/agents/code-developer/agent.md",
        "tools": ["file_read", "file_write", "shell_execute", "web_search"]
      },
      {
        "id": "test-engineer",
        "name": "测试工程师",
        "model": "deepseek-v3",
        "workspace": "~/.openclaw/agents/test-engineer",
        "systemPrompt": "file://~/.openclaw/agents/test-engineer/agent.md",
        "tools": ["file_read", "file_write", "shell_execute"]
      }
    ]
  }
}

Configuration highlights:

Manager uses Claude Sonnet for strong reasoning in task decomposition.

Coder uses GPT‑5.4 for best code generation.

Tester uses DeepSeek V3 for cost‑effective testing.

Manager may spawn Coder and Tester sub‑agents concurrently.

Step 4 – Run Collaboration

User request: "Build a Todo List app with React + TypeScript, CRUD, LocalStorage persistence, and completion status."

Understand requirements – identify core functions (CRUD, persistence, state management).

Task decomposition

Task 1: Design data structures and component hierarchy.

Task 2: Implement core CRUD functionality.

Task 3: Add LocalStorage persistence.

Task 4: Write tests.

Parallel dispatch using @mentions.

@code-developer – implement components TodoApp, TodoItem, TodoForm with add, delete, edit, complete, full TypeScript typing.

@test-engineer – create unit tests (component rendering, event handling), integration tests (full user flow), boundary tests (empty input, overly long text).

Result aggregation – PM collects code, test suite, and usage instructions.

Advanced Collaboration Modes

Hierarchical Sub‑Agents

Sub‑agents can be nested up to two levels (e.g., PM → Coder → UI Designer or API Developer).

{
  "subagents": {
    "maxSpawnDepth": 2,
    "maxConcurrent": 8,
    "runTimeoutSeconds": 600
  }
}

Message Routing & Binding

Bind agents to different communication channels.

{
  "channels": {
    "telegram": {
      "bindings": [
        {"agentId": "product-manager", "chatId": "123456789"},
        {"agentId": "code-developer", "chatId": "-1009876543210"}
      ]
    },
    "slack": {
      "bindings": [
        {"agentId": "product-manager", "channelId": "#product"}
      ]
    }
  }
}

Shared Memory

Enable a shared directory for key information across agents.

{
  "sharedMemory": {
    "enabled": true,
    "path": "~/.openclaw/shared/",
    "agents": ["product-manager", "code-developer", "test-engineer"]
  }
}

Project specification documents

API definitions

Database schemas

Cost‑Optimization Strategies

Model Layering

Architect – system design – Claude Opus 4 – $$$

Product Manager – requirement analysis – Claude Sonnet 4 – $$

Developer – code implementation – GPT‑5.4 Mini – $$

Tester – test case creation – DeepSeek V3 – $

Documentation Engineer – doc writing – Gemini 3 Flash – $

Dynamic Model Switching

{
  "models": {
    "strategy": "adaptive",
    "rules": [
      {"condition": "task.complexity > 0.8", "model": "claude-opus-4"},
      {"condition": "task.type == 'code_review'", "model": "gpt-5.4-mini"}
    ]
  }
}

Estimated monthly cost for a 5‑person AI team: $30–$80 depending on workload.

FAQ

How do agents communicate?

Use the @agent-id mention syntax, e.g., @code-developer to request code and @test-engineer for tests.

What if a sub‑agent times out?

{"subagents": {"runTimeoutSeconds": 1200}}

CLI alternative:

openclaw run --timeout 1200

How to view all agent statuses?

# List all agents
openclaw agents list
# Show agent details
openclaw agents status
# List sub‑agents
openclaw subagents list

How to resolve agent conflicts?

{"agents": {"concurrency": {"lockMode": "file", "timeout": 30}}}

Case Study: Automated Content Production Pipeline

Topic Curator – Gemini 3 Pro – trend tracking and topic planning.

Researcher – Perplexity API – data collection and organization.

Writer – Claude Sonnet 4 – drafting and polishing.

Editor – GPT‑5.4 Mini – proofreading and title optimization.

Illustrator – DALL‑E 3 – cover and inline images.

Workflow: topic curation → research → drafting → editing → illustration → final aggregation.

Production speed increased from 1 article per day to 5–10 articles per day.