Install
openclaw skills install @porkapple/openclaw-multi-agentsOpenclaw Multi Agents
别再用一个 AI 单打独斗。这个 Skill 帮你在 OpenClaw 里组建专属 AI 团队：Manager 规划派活，Worker 各自执行，每个交付物强制过质量门。61 个历史人物人格可选，你的团队做完任务不会直接交卷。 Stop relying on a single AI. This skill helps you build a dedicated AI team inside OpenClaw: a Manager that plans and delegates, Workers that specialize, and a mandatory QA gate on every deliverable. 61+ historical persona options — your team actually checks its work before handing it over.
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
- 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
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:
| 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. agents.listinopenclaw.jsonwill 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:
| 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):
- What is your primary job? What does a typical workday look like?
- What part of your work gives you the most trouble?
- What problems do you want the AI team to solve?
- Do you prefer proactive push or passive response?
- 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 | ultrabrain | 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
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:
| Check Item | Standard |
|---|---|
| Workspace directory exists | ~/.openclaw/workspace-<id>/ 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
namefield 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.
💡 The
namefield (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.
{
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.allow 必须包含 "main"，否则 Main Agent 无法发送消息
agentToAgent: { enabled: true, allow: ["main", "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)
## ⚠️ Iron Rule: Must Forward to Main After Quality Gate Passes
After the Quality Gate passes, you MUST use `sessions_send` to forward the result to Main Agent:
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 })
**Never just run the Quality Gate and stop. You MUST send the result to Main Agent.**
For full templates, see
templates/manager_soul_template.md. For Manager's AGENTS.md template, seetemplates/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:
curl "https://prompts.chat/api/prompts?q=<Responsibility Keywords>&perPage=3"
| Responsibility | Search Term |
|---|---|
| Feature Development | software engineer |
| 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:
# 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 — 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:mainfor reporting) - Iron Rule: must use
sessions_sendafter task completion - Communication specifications and safety principles
⑤ 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.
## ⚠️ Iron Rule: Must Notify User After Receiving Manager Report
When receiving a report from Manager, TWO steps are required — both are mandatory:
1. **Notify the user immediately** (MUST — extract key info and push to user in plain language)
2. **Reply to Manager** (optional — acknowledge receipt)
Only replying to Manager without notifying the user = serious Pure Relay failure.
**Standard flow after receiving Manager report:**
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:
```bash
# 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
# ⚠️ IMPORTANT: Do NOT run this command via exec tool — it restarts the gateway process
# that the AI itself runs inside, causing the session to freeze/die.
# Instead, tell the user to run it manually in their terminal:
echo "Please run the following command manually in your terminal:"
echo " openclaw gateway restart"
⚠️ AI must NOT execute
openclaw gateway restartvia 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 | Your persona archetype is **<Full English Name>** 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 | agent:<myId>:manager 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 agents.list | 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:
📋 Content Self-Check Results
manager (甘特):
SOUL.md: ✅ archetype ✅ reinforcement ✅ responsibilities ✅ no cross-boundary ✅ output format
AGENTS.md: ✅ session keys correct ✅ no direct Main contact ✅ memory instruction
Manager extras: ✅ workers table ✅ quality gate ✅ reporting format
feynman (费曼):
SOUL.md: ✅ archetype ✅ reinforcement ✅ responsibilities ✅ no cross-boundary ✅ output format
AGENTS.md: ✅ session keys correct ✅ no direct Main contact ✅ memory instruction
openclaw.json: ✅ all agents registered ✅ agentToAgent.allow correct ✅ workspace paths exist
Issues found: 0 — Proceeding to Step 6.
If issues are found, fix them before moving to Step 6. Do not skip to live testing with broken config.
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
)
| ✅ 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
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
Format: agent:<owner>:<creator>
<owner>= who is listening (receiver)<creator>= who created/bound this session (sender's context)
| Direction | Session Key | Explanation |
|---|---|---|
| Main → Manager (Assign task) | agent:manager:main | 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
# ❌ 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_sendto 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:
| Task Type | Category | Required Model Traits |
|---|---|---|
| Planning, PRD, Strategy | ultrabrain | 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:
- Find the models that best fit the task category traits from the user's
primary+fallbackslist. - If the user only has one model, use the same one for all Agents to avoid blocking work.
- 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
Team Wisdom is stored in the Main Agent's workspace — shared and accessible by all agents:
~/.openclaw/workspace/memory/wisdom/
├── conventions.md # Unified team agreements
├── successes.md # Effective approaches
├── failures.md # Mistakes already made
└── gotchas.md # Traps easily stepped into
⚠️ 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 relativememory/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 | conventions.md | 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: - **【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:
- Main → Manager: Inject experience relevant to the overall task (conventions, failures).
- Manager → Worker: Inject experience relevant to the Worker's specific responsibility (gotchas, successes).
【History】(from Wisdom):
- <Relevant Entry 1>
- <Relevant Entry 2>
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 →
failures.md - Non-obvious trap →
gotchas.md - Effective pattern →
successes.md
Sub-agents are active participants in the Wisdom system, not just recipients.
5. Exception Handling
| Issue | Handling |
|---|---|
Manager missing in agents.list | Go to Step 0 (Team Building) first. |
sessions_send 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:
- All agents are registered and reachable
- All personas are active (not defaulting to generic "I am an AI assistant")
- Communication channels work
Self-Check Procedure
Step 1: Confirm agents are registered
openclaw agents list
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:
For each agent in [manager, <worker1>, <worker2>, ...]:
sessions_send(
sessionKey="agent:<agentId>:manager",
message="Introduce yourself in one sentence: Who are you, what is your persona archetype?",
timeoutSeconds=60
)
⚠️ 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:
✅ Post-Restart Self-Check Complete
Agent Status:
- 甘特 (Manager) → ✅ Henry Gantt persona active
- 芒格 (Worker) → ✅ Charlie Munger persona active
- 费曼 (Worker) → ✅ Richard Feynman persona active
- 德明 (Worker) → ✅ W. Edwards Deming persona active
Team is ready. You can now assign tasks.
If any agent fails:
⚠️ Self-Check: 1 issue found
- 费曼 (Worker) → ❌ Persona not active (responded as generic AI)
Fix: SOUL.md already has archetype line. Please run `openclaw gateway restart` once more.
Other agents: ✅ healthy
Reference Documents
| File | Content | When to Read |
|---|---|---|
references/planning_guide.md | Full interview template + Team Design Document format | During Step 0 Planning Interview |
references/persona-library.md | 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
Related skills
- Downloads
- Security audit
- Review
- Last updated
- 4mo ago
- Current version
- v1.1.0
- License
- MIT-0