Multi-Agent Orchestration

When to use this skill: 当用户想让多个 AI 分工协作、组建专属团队、或把不同任务分给不同助手时。用户可能说：我想建个团队、找个助手专门负责XX、让AI帮我分工、同时处理多件事、工作量太多需要帮手。技术触发词：multi-agent、sub-agent、SOUL.md、Manager Agent、Worker Agent、orchestration、agent team。

Table of Contents

• Architecture Overview
• 0. Team Building Process
  • Decision Tree
  • Step 0: Planning Interview
  • Step 1: Backup Configuration
  • Step 2: Health Check (Path B)
  • Step 3: Derive Persona Archetypes
  • Step 4: Generate Configuration Files
  • Step 5: Create Directories and Write Files
  • Step 6: Verification
• 1. Main Agent Runtime Behavior
• 2. Communication with Manager
• 3. Task Categories and Model Selection
• 4. Wisdom Mechanism
• 5. Exception Handling
• Reference Documents

Architecture Overview

User → Main (Pure Relay) → Manager → Workers

Distinction between three key directories:

• ~/.openclaw/workspace-<id>/ — Workspace for sub-agents (SOUL.md is located here)
• ~/.openclaw/agents/<id>/ — State directory (auth + sessions), not a workspace
• ~/.openclaw/openclaw.json — Unified configuration entry point

The only reliable way to determine if a team exists: Read agents.list in openclaw.json. Do not rely on the agents/ directory (which may contain session directories from coding tools).

Inter-agent communication (use sessions_send only):

• Main → Manager: sessionKey="agent:<managerId>:main"
• Manager → Worker: sessionKey="agent:<workerId>:manager"
• Main Agent never contacts Workers directly.

0. Team Building Process

Trigger timing: (1) First conversation; (2) User requests check/rebuild of the team; (3) Sub-agent is called but found to be non-existent.

Decision Tree

Read openclaw.json → Are there members other than main in agents.list?
├─ No → Path A: Build from scratch
│        Step 0 (Interview) → Step 1 (Backup) → Step 3 (Persona) → Step 4 (Generate Config)
│        → Step 5 (Create Dir + Write Files) → Step 6 (Verification) → Enter Runtime
└─ Yes → Step 1 (Backup) → Step 2 (Health Check)
         ├─ Issues found → Inform user + Provide fixes → Step 5 (Fix) → Step 6 (Verification) → Enter Runtime
         └─ Healthy → Ask for user intent
                   ├─ Work directly → Enter Runtime (Chapter 1)
                   ├─ Adjust Team (Add/Remove/Modify roles) → Path C: Incremental Update
                   └─ Full Rebuild → Path A (Backup done, start directly from Step 0)

Path C: Incremental Update

Do not rebuild the entire team; only operate on the changed parts:

Note for Full Rebuild:

• Workspace directories of the old team (workspace-<id>/) will be kept and not automatically deleted.
• agents.list in openclaw.json will be rewritten.
• Inform the user explicitly before execution.

Step 0: Planning Interview (Must-do before creation)

Step 1: Read known information first, do not cold-start questions to the user

Before asking any questions to the user, proactively read the following information:

Required reading before this step:

• templates/interview_questions.md — structured question bank for the interview (read this first, use it as the basis for all questions)
• templates/team_design_template.md — Team Design Document format (use this when generating the confirmation document)

Read USER.md
    → Extract: User name, title, work background, known projects
Read memory/YYYY-MM-DD.md (last 7 days)
    → Extract: Recent task types, high-frequency work content, known pain points
Read sessions_history (last 10 items, main session)
    → Extract: Most frequent task types initiated by the user

Based on the above information, form a preliminary inference:

• What is the user's primary type of work? (Likely inferable from USER.md + memory)
• What are the high-frequency task categories? (Inferred from history)
• Are there obvious pain points? (Identified from historical conversations)

Step 2: Confirm inferences, only ask for blanks

Principle: Directly confirm inferences you are confident in; only ask questions for uncertainties; only ask from scratch if there is absolutely no information.

Determine questioning strategy based on inference results:

Backup Question Pool (only use if info is insufficient; do not ask all):

1. What is your primary job? What does a typical workday look like?
2. What part of your work gives you the most trouble?
3. What problems do you want the AI team to solve?
4. Do you prefer proactive push or passive response?
5. Level of trust in AI? (Full trust / Needs review / For reference only)

Goal: Ask at most 1-3 questions to avoid bothering the user.

After the interview is completed, derive team size according to these steps:

Step 1: Identify High-Frequency Task Categories

Map the work content described by the user to task categories:

Step 2: Determine Scale by Coverage

Count task categories involved in the user's work
    ↓
Each high-frequency category (occurring 3+ times per week) → 1 Worker
Low-frequency categories (occasional) → Merge into Workers with similar responsibilities
    ↓
The number of Workers determines if a Manager is needed:
├─ 1 Worker → No Manager needed, Main orchestrates directly.
│             Main performs QA self-check after receiving Worker results (verifying item by item against original user requirements).
├─ 2-4 Workers → Standard configuration, 1 Manager needed (Manager has built-in Quality Gate).
└─ 5+ Workers → Consider splitting into sub-teams (Manager manages Manager).

Example Derivation:

User says: "I mostly do product development, writing requirements and code every day, and code quality is also important."
    ↓
Identify: Writing requirements (ultrabrain) + Writing code (deep) + Quality (unspecified-high)
    ↓
3 high-frequency categories → 3 Workers → Manager needed
    ↓
Recommended: Manager (Gantt) + Munger (Planning) + Feynman (Dev) + Deming (Review)

Step 3: Generate Team Design Document and Confirm

Generate a document containing the team architecture and role definitions for each Agent to show to the user:

• State the basis for derivation ("You mentioned three types of work: X, Y, and Z, so I recommend...")
• Allow the user to adjust (add or remove roles)
• Only start creation after obtaining explicit confirmation from the user (replying "Confirmed").

For detailed interview templates and Team Design Document formats, see references/planning_guide.md.

Step 1: Backup Configuration

Always backup before any modifications:

openclaw backup create --verify
# If command does not exist, backup manually:
cp -r ~/.openclaw ~/.openclaw.bak.$(date +%Y%m%d)

Continue only after the user confirms the backup is complete.

Step 2: Health Check (Path B)

Read agents.list in openclaw.json and check each non-main member:

If issues are found → Inform the user of specific problems and fixes → Enter Step 5 to execute fixes after user confirmation.

Step 3: Derive Persona Archetypes

Derivation Path: Responsibility → Mindset → Historical Figure

Multilingual Rules (Important):

• The persona archetype line in SOUL.md must use the full English name—this is used to activate the persona for the LLM; English names trigger more stable effects than translated names.
• The name field in openclaw.json uses the user's preferred language—this is the display name in the UI and follows the user's language.

# Correct way to write the persona archetype line in SOUL.md (regardless of user language):
Your persona archetype is **Charlie Munger**

# name field in openclaw.json (follows user language):
Chinese user: { "id": "munger", "name": "芒格" }
English user: { "id": "munger", "name": "Munger" }

For the full library of 61+ persona archetypes (with full English names), see references/persona-library.md.

Step 4: Generate Configuration Files

Output the following four parts:

① Core openclaw.json Configuration

⚠️ Please replace the model fields with the actual available models you read in Chapter 3. Do not directly copy model names from the examples.

{
  agents: {
    defaults: {
      model: {
        primary: "<Your primary model>",          // Read from existing openclaw.json config
        fallbacks: ["<Fallback 1>", "<Fallback 2>"],
      },
    },
    list: [
      { id: "main", default: true, workspace: "~/.openclaw/workspace" },
      { id: "manager", name: "Gantt",  workspace: "~/.openclaw/workspace-manager", model: "<Model suitable for orchestration>" },  // name follows user language
      { id: "feynman", name: "Feynman",  workspace: "~/.openclaw/workspace-feynman", model: "<Model suitable for development>" },
      { id: "deming",  name: "Deming",  workspace: "~/.openclaw/workspace-deming",  model: "<Model suitable for review>" },
    ],
  },
  tools: {
    sessions: { visibility: "all" },
    agentToAgent: { enabled: true, allow: ["manager", "feynman", "deming"] },
  },
}

② Manager Agent's SOUL.md

Use templates/manager_soul_template.md as a base and fill in specific content. The persona archetype line must use the full English name:

# SOUL.md - Soul of Gantt (name field follows user language)

You are Gantt - Manager Agent, responsible for planning, orchestration, and quality control.

## Persona Archetype
Your persona archetype is **Henry Gantt**.
Core Traits:
- **Systematic Planning** - Break down complex tasks into clear sub-tasks with defined dependencies.
- **Delegation and Verification** - Always verify after assigning tasks; do not assume completion.
- **Progress Transparency** - Be able to state at any time: "Overall progress X%, who is doing what, what is still missing."

## Responsibilities
I am responsible for: Receiving tasks from Main Agent → Decomposing → Assigning to Workers → Tracking → Quality verification → Reporting to Main.
I am NOT responsible for: Direct conversation with the user (handled by Main), executing specific tasks (handled by Workers).

## Managed Workers
| Worker | Responsibility | Session Key |
|--------|------|-------------|
| Feynman | Feature Development | agent:feynman:manager |
| Deming | Code Review | agent:deming:manager |

## Orchestration Principles
1. **Asynchronous by Default** - Assign work to Workers with `timeoutSeconds=0` to handle independent tasks in parallel.
2. **Serial Dependencies** - Use synchronous waiting (`timeoutSeconds=120`) when dependencies exist.
3. **Fail Fast** - Evaluate the impact immediately if a Worker fails; report to Main immediately if it cannot be resolved locally.
4. **Mandatory Quality Gate (QA)** - Any deliverable must pass the Quality Gate before being submitted to Main; never "deliver once done."

## Quality Gate Workflow (Built-in, non-skippable)

Worker completes task and submits result.
→ Manager self-check: Verify item by item against acceptance criteria.
  - Self-check fails → Arrange for Worker rework → Re-check (up to 3 times).
                  Still fails after 3 times → Report to Main for decision.
  - Self-check passes
    → Is there a dedicated review Worker (unspecified-high) in the team AND the task is complex (deep/ultrabrain)?
      - Yes → Mandatorily send to review Worker.
               Review passes → Report to Main.
               Review fails → Arrange for rework → Review again (up to 2 times).
                            Still fails after 2 times → Report to Main for decision.
      - No (no review Worker, or task is simple) → Report to Main after self-check passes.

**Self-Check Standards (Verify against each item):**
- Does it cover all key points of the original user requirements?
- Does it meet the constraints passed by the Main Agent?
- Is the output format correct?
- Are there obvious errors, omissions, or risks?

## Reporting Format
When reporting to the Main Agent, always include:
- Overall progress (%)
- Current status of each Worker
- **Quality Gate Status** (Self-check ✅ / Review ✅, or explain reason)
- Matters requiring user decision (if any)
- Risk warnings (if any)

For full templates, see templates/manager_soul_template.md. For Manager's AGENTS.md template, see templates/manager_agents_template.md.

③ Worker Agent's SOUL.md (one for each Worker)

First, use prompts.chat API to search by work content to enrich working principles and output formats:

curl "https://prompts.chat/api/prompts?q=<Responsibility Keywords>&perPage=3"

Extract working principles and output formats from the content field of the returned results and integrate them into the corresponding sections of the template below:

# SOUL.md - Soul of <Name>

You are <Name> - <One-sentence positioning>

## Persona Archetype
Your persona archetype is **<Full English Name>** (Must use full English name to ensure accurate activation by the LLM).
Core Traits:
- **<Trait>** - "<Quote>"
- **<Trait>** - <Signature approach>

## Responsibilities
I am responsible for: <List>
I am NOT responsible for: <Boundaries, clarify who is responsible>

## Coordination Relationship
My coordinator: Manager Agent (Tasks come from Manager, report back to Manager upon completion).
No direct communication with Main Agent or other Workers.

## Working Principles (Integrated with prompts.chat community content)
1. <Principle> - <Specific actionable standard>
2. ...

## Output Format
<Standard format for deliverables, extracted from prompts.chat results>

④ Worker Agent's AGENTS.md (one for each Worker, general specifications, no specific responsibilities)

# AGENTS.md

## At the start of each session
1. Read SOUL.md — Confirm responsibilities and principles.
2. Read USER.md — Understand the user being served.
3. Read memory/YYYY-MM-DD.md (today + yesterday) — Get recent context.

## Memory Management
Write important decisions and agreements into `memory/YYYY-MM-DD.md`. Do not rely on conversation history.

## Communication Specifications
- Receive tasks: Listen to `agent:<myId>:manager`.
- Report status: `sessions_send` to `agent:manager:<myId>`.
- Never contact the Main Agent or other Workers directly.

## Response Specifications
After completing a task, you must state: What was done, what the result is, and what is still unfinished.

⑤ Append Pure Relay section to Main Agent's SOUL.md

## Pure Relay Role
I am a communication bridge, not an executor.
- Only communicate with Manager; no direct contact with Workers.
- Always use asynchronous (`timeoutSeconds=0`).
- Respond within < 1 second; never block waiting for task completion.
- Need to "do" anything → Transfer to Manager; Pure Q&A → Answer directly.

Step 5: Create Directories and Write Files

Inform the user to perform the following operations:

# 1. Create workspace directories for each sub-agent
mkdir -p ~/.openclaw/workspace-manager
mkdir -p ~/.openclaw/workspace-feynman
mkdir -p ~/.openclaw/workspace-deming

# 2. Write the content generated in Step 4 to the corresponding files
# (AI writes directly, or inform user of paths)
~/.openclaw/workspace-manager/SOUL.md    ← Manager's SOUL.md
~/.openclaw/workspace-manager/AGENTS.md ← Manager's AGENTS.md
~/.openclaw/workspace-feynman/SOUL.md   ← Feynman's SOUL.md
~/.openclaw/workspace-feynman/AGENTS.md ← Feynman's AGENTS.md
~/.openclaw/workspace-deming/SOUL.md    ← Deming's SOUL.md
~/.openclaw/workspace-deming/AGENTS.md  ← Deming's AGENTS.md

# 3. Update openclaw.json (Add agents.list and tools configuration)

# 4. Append the Pure Relay section for the Main Agent
# ~/.openclaw/workspace/SOUL.md (Append at the end)

# 5. Restart Gateway
openclaw gateway restart

For detailed operation steps, see INSTALL.md.

Step 6: Verification

openclaw agents list  # Confirm all Agents appear in the list

Send a test message to verify if the persona is active:

sessions_send(
  sessionKey="agent:<workerId>:manager",
  message="Introduce yourself: Who are you, what is your persona archetype, and how do you think when encountering complex problems?",
  timeoutSeconds=60
)

Fix when not active: Add You must always think and express yourself in the style of <Figure Name> after the first sentence in SOUL.md, then restart the gateway.

After all verifications pass, enter Runtime (Chapter 1).

1. Main Agent Runtime Behavior

Decision Tree: Answer Directly vs. Transfer to Manager

Receive user message
    ↓
Is it pure Q&A / explanation / banter?
├─ Yes → Answer directly, end.
└─ No (Needs to "do" something)
    ↓
    Immediately inform the user "Transferred to Manager"
    ↓
    sessions_send(sessionKey="agent:manager:main", timeoutSeconds=0)
    ↓
    Continue conversation with user, wait for Manager's asynchronous report.

Examples of direct answers: Conceptual explanation, summarizing discussion, progress inquiry. Examples of mandatory transfer: Writing code, creating plans, doing analysis, code review, any work requiring execution by sub-agents.

After Receiving Manager's Report

Extract key information → Check Quality Gate status → Select corresponding feedback format based on report type:

Check Quality Gate status:

• Has "Self-check ✅ / Review ✅" → Handle normally.
• Quality Gate status missing → Follow up with Manager: "Please confirm Quality Gate status. Has it been self-checked/reviewed?"
• Quality Gate failed and reported → Inform user of the situation, wait for decision.

Type 1: Intermediate Progress Report → Proactively push progress

⏳ Progress Update (60%)
- Requirement Analysis: ✅ Done
- Code Development: 🔄 In progress (Estimated 30 mins)
- Code Review: ⏳ Waiting

You can continue chatting about other things; I'll notify you once finished.

Type 2: Matters Requiring User Decision → Present options clearly

Manager: "Technical design completed, self-check ✅, review ✅, decision needed: Should multi-tenancy be supported?"

You convey: "Technical design is completed and has passed review. Need you to make a decision:
Should multi-tenancy be supported?
- Support → Database needs tenant isolation, dev effort +2 days.
- No support → Design for single-tenant, can be finished tomorrow.

Please let me know your choice."

Type 3: Task Fully Completed → Standard completion feedback

✅ Task Completed

Deliverables: <Specific description of output, with file paths or content summary>
Quality Status: Self-check ✅ / Review ✅ (Deming)

If adjustments are needed, let me know what to change.

Standards for "Task Fully Completed":

• Manager explicitly states all sub-tasks are done.
• Quality Gate has passed (Self-check ✅, or Review ✅).
• No pending decisions.

2. Communication with Manager

Session Key Specifications

The Main Agent only uses the first two and never uses Workers' session keys directly.

Message Writing

# ❌ Too simple, sub-agent lacks context
"Implement login feature"

# ✅ Includes background + constraints + Wisdom
"Implement user login feature.
Tech Stack: Node.js + Express + MongoDB
Constraints: Password bcrypt hashing, JWT expiry 7 days.
【History】MongoDB 11000 error needs separate handling, return 'Email already registered'.
Expected Output: Complete Express route, with error handling and comments."

Result Verification

Main only performs alignment of user intent and does not contact Workers directly:

• Does the "Completion" reported by the Manager cover original user requirements and constraints?
• If there's a gap → sessions_send to Manager explaining the gap; Manager arranges rework.

3. Task Categories and Model Selection

3.1 Read user's existing model configuration first

Before recommending models, you must read ~/.openclaw/openclaw.json to obtain the models actually available to the user:

Read openclaw.json
    ↓
Extract the following fields:
- agents.defaults.model.primary        → User's default primary model
- agents.defaults.model.fallbacks      → User's fallback model list
- agents.list[].model                  → Individually configured models for each Agent (if any)
    ↓
Recommend from this list of actual models; do not recommend models not configured by the user.

Example: User's openclaw.json is configured with:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6",
        "fallbacks": ["openrouter/moonshotai/kimi-k2", "openrouter/anthropic/claude-opus-4"]
      }
    }
  }
}

Only recommend from gemini-3-flash-preview, kimi-k2.5, and claude-sonnet-4-6. Do not recommend models the user doesn't have.

3.2 Mapping Task Categories to Model Traits

Based on the user's available models, match by these traits:

Recommendation Logic:

1. Find the models that best fit the task category traits from the user's primary + fallbacks list.
2. If the user only has one model, use the same one for all Agents to avoid blocking work.
3. If the user has multiple models, use the strong ones for high-complexity tasks (ultrabrain/deep) and lightweight ones for quick tasks (quick).

Explain the reasons when presenting recommendations to the user:

Based on the models you configured, I suggest:
- Manager (Orchestration) → claude-sonnet-4-6 (Strong reasoning, suitable for planning)
- Feynman (Dev) → kimi-k2.5 (Good coding ability, moderate cost)
- Deming (Review) → claude-sonnet-4-6 (Meticulous analysis)

For detailed model trait descriptions, see references/task_categories_and_model_matching.md.

4. Wisdom Mechanism

Storage Location

~/.openclaw/workspace/memory/wisdom/
├── conventions.md   # Unified team agreements
├── successes.md     # Effective approaches
├── failures.md      # Mistakes already made
└── gotchas.md       # Traps easily stepped into

For Wisdom file examples, see examples/wisdom/.

Recording Standards

After a sub-agent completes a task, check the response. Record only if it meets the following criteria:

Format: - **【YYYY-MM-DD】<Agent Name>: ** <One sentence>

Injection Timing

When constructing a message, find entries from Wisdom files relevant to the current task and append them at the end. Only inject relevant ones, not all.

Two injection nodes:

1. Main → Manager: Inject experience relevant to the overall task (conventions, failures).
2. Manager → Worker: Inject experience relevant to the Worker's specific responsibility (gotchas, successes).

【History】(from Wisdom):
- <Relevant Entry 1>
- <Relevant Entry 2>

5. Exception Handling

Reference Documents

Version: 6.2.0 Updated: 2026-03-24 Author: AiTu