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
• 6. Post-Restart Self-Check
• Reference Documents

---

Architecture Overview

CODEBLOCK0

Distinction between three key directories:

• - ~/.openclaw/workspace-<id>/ — Workspace for sub-agents (SOUL.md is located here)
• INLINECODE1 — State directory (auth + sessions), not a workspace
• INLINECODE2 — 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: INLINECODE6
• Manager → Worker: INLINECODE7
• 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

CODEBLOCK1

Path C: Incremental Update

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

Action	Steps
Add Worker	Step 3 (Derive Persona) → Step 4③ (Generate Config for this Worker) → Step 5 (Create Dir + Write) → Update agents.list and agentToAgent.allow in openclaw.json → Update Workers list in Manager's SOUL.md → Step 6 (Verify new member)
Remove Worker

Remove from agents.list and agentToAgent.allow in openclaw.json → Update Workers list in Manager's SOUL.md → Workspace directory is kept (inform user they can clean up manually) |
| Replace Role | Remove first (as above) → Then add (as above) |
| Modify Persona | Directly edit SOUL.md in the corresponding workspace → Ask user to run openclaw gateway restart in their terminal (⚠️ AI must not exec this) → Step 6 (Verify Persona) |

Note for Full Rebuild:

• - Workspace directories of the old team (workspace-<id>/) will be kept and not automatically deleted.
• INLINECODE16 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)
• INLINECODE19 — Team Design Document format (use this when generating the confirmation document)

CODEBLOCK2

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:

Information Status	Action
Sufficient info exists	State inference directly and ask for confirmation: "I see you've been focused on product development lately, is that correct?"
Incomplete info

Ask targeted questions for the blanks, 1-2 questions. |
| No historical info | Ask from scratch, select 3-5 core questions. |

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

1. 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:

User-described work	Task Category	Required Worker Type
Writing plans, planning, writing PRDs	INLINECODE20	Planning (e.g., Munger)
Writing code, debugging, building features

deep | Development (e.g., Feynman) |
| Reviewing code, testing, quality control | unspecified-high | Review (e.g., Deming) |
| Writing documents, copy, marketing | writing / artistry | Writing/Creative (e.g., Ogilvy) |
| Data analysis, user research | ultrabrain | Analysis (e.g., Kahneman) |
| Managing projects, tracking progress, coordination | unspecified-low | Coordination (e.g., Drucker) |

Step 2: Determine Scale by Coverage

CODEBLOCK3

Example Derivation:
CODEBLOCK4

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:

CODEBLOCK5

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:

Check Item	Standard
Workspace directory exists	INLINECODE30 exists
SOUL.md exists and has content

Has persona archetype and role definition |
| AGENTS.md exists | Has communication specifications |
| Number of members is reasonable | Including Manager, 2-5 people total |
| Manager role exists | There is a clearly defined Manager Agent in agents.list |

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

Responsibility	Recommended Figure (Full English Name)	Signature Traits
Team Orchestration / Manager	Henry Gantt	Systematic planning, task visualization, delegation and verification
Strategic Planning / PRD

Charlie Munger | "Invert, always invert" |
| Feature Dev / Debugging | Richard Feynman | "What I cannot create, I do not understand" |
| Code Review / Quality | W. Edwards Deming | "In God we trust, all others bring data" |
| Product Design / Experience | Steve Jobs | "Simplicity is the ultimate sophistication" |
| Marketing Copy | David Ogilvy | "The consumer is not a moron" |
| Data Analysis | Daniel Kahneman | Behavioral economics, dual-system thinking |

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.

CODEBLOCK6

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.

💡 The name field (display name) is entirely up to the user — use any name you like. The persona archetype is defined in SOUL.md and is independent of the display name.

CODEBLOCK7

---

② 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:

CODEBLOCK8
sessions_send({
sessionKey: "agent:main:manager",
message: "## Task Completed\n\n[Result summary]\n\n### Quality Gate Status\nSelf-check ✅\n\nVerification Results:\n- Completeness: ✅ [covers all requirements]\n- Constraints met: ✅ [constraints satisfied]\n- Output format: ✅ [format correct]\n- Known risks: [none or description]\n\n[Review ✅ if applicable]\n\n### Overall Progress\n100%",
timeoutSeconds: 0
})
CODEBLOCK9

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)

Use templates/worker_soul_template.md as the base. First, use prompts.chat API to search by work content to enrich working principles and output formats:

CODEBLOCK10

Responsibility	Search Term
Feature Development	INLINECODE39
Code Review

code reviewer |
| Strategic Planning | product manager |
| Data Analysis | data analyst |
| Marketing Copy | copywriter |

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:

CODEBLOCK11

---

④ Worker Agent's AGENTS.md (one for each Worker — use templates/worker_agents_template.md as base)

Read templates/worker_agents_template.md and fill in the placeholders for this specific Worker. Key points already included in the template:

• - Correct session keys (agent:manager:main for reporting)
• Iron Rule: must use sessions_send after task completion
• Communication specifications and safety principles

---

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

CODEBLOCK12
Receive Manager report (via agent:main:manager)
↓
Extract key info (progress, result, decisions needed)
↓
IMMEDIATELY send to user via message tool (NOT sessions_send — user is not an agent)
↓ (optional)
Reply to Manager confirming receipt

> ⚠️ "Notify user" means **send a message NOW using the `message` tool**. It does NOT mean "mention it next time the user asks." 
> Waiting for the user to ask = Pure Relay failure.

Always notify user FIRST, then (optionally) confirm to Manager. Never the reverse.

**How to notify the user (use `message` tool, let OpenClaw auto-route):**

javascript
// ✅ Correct: omit channel/to — OpenClaw routes to wherever the user is (WeChat, Feishu, etc.)
message({
action: "send",
message: "甘特汇报内容，整理后转达给用户"
})

// ❌ Wrong: hardcoding channel breaks users on other platforms
message({
action: "send",
channel: "openclaw-weixin", // ← don't hardcode!
message: "..."
})

---

Step 5: Create Directories and Write Files

Inform the user to perform the following operations:

CODEBLOCK15

⚠️ AI must NOT execute openclaw gateway restart via exec tool.
The AI runs inside the gateway — restarting it from within will kill the current session.
Always ask the user to run this command manually in their own terminal.

For detailed operation steps, see INSTALL.md.

---

Step 5.5: Content Self-Check (Run before Step 6)

Purpose: After writing all files, read them back and verify content is correct before testing with live agents. Catch issues early — wrong persona names, missing sections, broken session keys — without needing to send any messages.

For each agent created, read its SOUL.md and AGENTS.md and verify the following checklists:

SOUL.md Checklist (check each item):

#	Check Item	What to Look For
1	English archetype line exists	INLINECODE51 near the top
2

Reinforcement line exists | You must always think and express yourself in the style of <Full English Name> |
| 3 | Responsibilities defined | "I am responsible for" and "I am NOT responsible for" sections present |
| 4 | Coordination relationship clear | States who the coordinator is (Manager for Workers; Main for Manager) |
| 5 | No cross-boundary communication | Does NOT say "contact Main directly" or "contact other Workers" |
| 6 | Output format defined | Has a concrete output format section |

AGENTS.md Checklist (check each item):

#	Check Item	What to Look For
1	Session key is correct	INLINECODE53 for receiving tasks, agent:manager:main for reporting results — not reversed
2

No direct Main contact | Does NOT instruct to contact Main Agent directly |
| 3 | Memory instruction present | Mentions writing to memory/YYYY-MM-DD.md |

Manager-specific additional checks:

#	Check Item	What to Look For
1	Workers table complete	Lists all Workers with correct session keys (agent:<workerId>:manager)
2

Quality Gate workflow present | Non-skippable QA flow described |
| 3 | Reporting format defined | States what to include when reporting to Main |

openclaw.json checks:

#	Check Item	What to Look For
1	All agent IDs in INLINECODE57	main + manager + all Workers
2

All non-main IDs in agentToAgent.allow | Must include "main" + all Worker IDs (list of strings) |
| 3 | Workspace paths exist on disk | ~/.openclaw/workspace-<id>/ directories present |

Self-Check Report Format:

After reading all files, report findings before proceeding to Step 6:

CODEBLOCK16

If issues are found, fix them before moving to Step 6. Do not skip to live testing with broken config.

---

Step 6: Verification

CODEBLOCK17

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

CODEBLOCK18

✅ Persona Active	❌ Persona Not Active
Mentions the figure's name	Says "I am an AI assistant"
Style matches the figure's traits

General polite clichés |
| Uses signature thinking frameworks | No figure traits at all |

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 ask the user to run openclaw gateway restart in their terminal (⚠️ AI must not exec this command — it kills the current session).

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

---

1. Main Agent Runtime Behavior

Decision Tree: Answer Directly vs. Transfer to Manager

CODEBLOCK19

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

CODEBLOCK20

Type 2: Matters Requiring User Decision → Present options clearly

CODEBLOCK21

Type 3: Task Fully Completed → Standard completion feedback

CODEBLOCK22

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

Format: agent:<owner>:<creator>

• - <owner> = who is listening (receiver)
• INLINECODE64 = who created/bound this session (sender's context)

Direction	Session Key	Explanation
Main → Manager (Assign task)	INLINECODE65	Manager listens, created by Main
Manager → Main (Report)

agent:main:manager | Main listens, created by Manager |
| Manager → Worker (Assign work) | agent:<workerId>:manager | Worker listens, created by Manager |
| Worker → Manager (Report) | agent:manager:main | Manager listens; Workers are under Main context, same key as Main→Manager |

Key point: Worker → Manager and Main → Manager use the same session key (agent:manager:main). Using agent:manager:<workerId> is wrong—that session doesn't exist and Manager will never receive it.

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

Message Writing

CODEBLOCK23

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:

CODEBLOCK24

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

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:

Task Type	Category	Required Model Traits
Planning, PRD, Strategy	INLINECODE77	Strong reasoning, long context
Development, Refactor, Debug

deep | Strong coding ability, stable tool use |
| Interface, UI, Frontend | visual-engineering | Multimodal / Visual understanding |
| Copy, Marketing, Creative | artistry | Creative writing, language expression |
| Review, Quality Control | unspecified-high | Meticulous analysis, strict reasoning |
| Project Management, Coordination | unspecified-low | Balanced capabilities, cost-effective |
| Documents, Tech Writing | writing | Fluent language, clear structure |
| Quick search, small modifications | quick | Fast, low latency, low cost — e.g. Grok Code Fast / minimax/minimax-m2.5 / Claude Haiku / Gemini Flash |

Recommendation Logic:

1. 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:
CODEBLOCK26

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

---

4. Wisdom Mechanism

Storage Location

Team Wisdom is stored in the Main Agent's workspace — shared and accessible by all agents:

CODEBLOCK27

⚠️ Workers and Manager have their own workspaces (~/.openclaw/workspace-<id>/). Always use the absolute path ~/.openclaw/workspace/memory/wisdom/ to access team Wisdom — not the relative memory/wisdom/ path, which resolves to each agent's own workspace.

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:

Type	Write to File	Determination Standard
Agreements affecting future dev	INLINECODE96	Decision needs to be followed by the whole team.
Methods worth reusing

successes.md | Good results, can be used next time. |
| Fixed errors | failures.md | Mistakes made, prevent recurrence. |
| Non-obvious traps | gotchas.md | Easy to step into, hard to find. |

Format: INLINECODE100

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. 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).

CODEBLOCK28

Sub-Agent Responsibility (Workers and Manager)

At session start: Workers and Manager must read memory/wisdom/failures.md and memory/wisdom/gotchas.md to avoid repeating past mistakes.

After task completion: If anything new was learned, write it to the appropriate wisdom file:

• - New mistake discovered → INLINECODE103
• Non-obvious trap → INLINECODE104
• Effective pattern → INLINECODE105

Sub-agents are active participants in the Wisdom system, not just recipients.

---

5. Exception Handling

Issue	Handling
Manager missing in INLINECODE106	Go to Step 0 (Team Building) first.
INLINECODE107 timeout

Check sessions_history(sessionKey="agent:main:manager") for updates. |
| "Permission denied" in inter-agent communication | Check if agentToAgent.allow contains "main" and all Agent IDs (list of strings). Without "main", Main Agent cannot send messages to Manager. |
| Persona not active | Add reinforcement text after the first sentence in SOUL.md, ask user to run openclaw gateway restart in their terminal (⚠️ AI must not exec this). |
| Unsatisfactory deliverable | Package the gaps and send to Manager; Manager arranges rework. Main does not contact Worker directly. |
| Only main exists (no team) | Do not force orchestration; go to Step 0 first. |

---

6. Post-Restart Self-Check

Trigger: When the user says "gateway restarted", "just restarted", or re-invokes this skill after a restart — run this self-check automatically before doing anything else.

Purpose

After openclaw gateway restart, all agent sessions reset. This check verifies:

1. 1. All agents are registered and reachable
2. All personas are active (not defaulting to generic "I am an AI assistant")
3. Communication channels work

Self-Check Procedure

Step 1: Confirm agents are registered

CODEBLOCK29

Expected: main, manager, and all Workers appear in the list.
If any are missing → Go to Step 5 to recreate missing agents.

---

Step 2: Ping each non-main agent

Send a persona activation test to each Worker and the Manager:

CODEBLOCK30

⚠️ Use timeoutSeconds=60 (synchronous) here — we need the response to evaluate it.

Step 3: Evaluate each response

Response contains	Result
The historical figure's name + signature trait/phrase	✅ Persona active
"I am an AI assistant" / generic reply

❌ Persona not active |
| No response / timeout | ❌ Agent unreachable |

Step 4: Fix issues

Issue	Fix
Persona not active	Confirm Your persona archetype is **<Full English Name>** exists near the top of the agent's SOUL.md. Ask user to run openclaw gateway restart again (⚠️ AI must not exec this).
Agent unreachable

Check agents.list in openclaw.json, verify workspace path exists, ask user to restart. |
| All agents healthy | Report summary to user and enter Runtime (Chapter 1). |

Self-Check Report Format

After completing the check, report to the user:

CODEBLOCK31

If any agent fails:

CODEBLOCK32

---

Reference Documents

File	Content	When to Read
INLINECODE119	Full interview template + Team Design Document format	During Step 0 Planning Interview
INLINECODE120

Detailed descriptions of 61+ persona archetypes | During Step 3 Selecting Personas |
| references/architecture_guide.md | Workspace config specs + full path structure | During Step 4/5 Generating Config |
| references/task_categories_and_model_matching.md | Breakdown of 8 task categories | When refining model selection |
| templates/interview_questions.md | Structured question bank for user interview | Must read at the start of Step 0 |
| templates/manager_soul_template.md | Full SOUL.md template for Manager Agent | During Step 4 Generating Manager Config |
| templates/manager_agents_template.md | Full AGENTS.md template for Manager Agent | During Step 4 Generating Manager Config |
| templates/worker_soul_template.md | Full SOUL.md template for Worker Agent (includes Iron Rule) | During Step 4 Generating Worker Config |
| templates/worker_agents_template.md | Full AGENTS.md template for Worker Agent (includes Iron Rule + correct session keys) | During Step 4 Generating Worker Config |
| templates/team_design_template.md | Template for Team Design Document | Must read during Step 0 when generating confirmation doc |
| examples/setup_example.md | Full end-to-end workflow demonstration | Reference when uncertain about process |
| examples/wisdom/ | Wisdom file examples | During Chapter 4 Recording Wisdom |
| INSTALL.md | openclaw.json config guide (User manual) | During Step 5 Informing user operations |

---

Version: 6.4.0
Updated: 2026-03-25
Author: AiTu