OpenClaw Multi-Agents

# 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](#architecture-overview) - [0. Team Building Process](#0-team-building-process) - [Decision Tree](#decision-tree) - [Step 0: Planning Interview](#step-0-planning-interview-must-do-before-creation) - [Step 1: Backup Configuration](#step-1-backup-configuration) - [Step 2: Health Check (Path B)](#step-2-health-check-path-b) - [Step 3: Derive Persona Archetypes](#step-3-derive-persona-archetypes) - [Step 4: Generate Configuration Files](#step-4-generate-configuration-files) - [Step 5: Create Directories and Write Files](#step-5-create-directories-and-write-files) - [Step 6: Verification](#step-6-verification) - [1. Main Agent Runtime Behavior](#1-main-agent-runtime-behavior) - [2. Communication with Manager](#2-communication-with-manager) - [3. Task Categories and Model Selection](#3-task-categories-and-model-selection) - [4. Wisdom Mechanism](#4-wisdom-mechanism) - [5. Exception Handling](#5-exception-handling) - [6. Post-Restart Self-Check](#6-post-restart-self-check) - [Reference Documents](#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.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: | 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. 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 | `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: ```bash 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 `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. ```markdown # 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 `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. ```json5 { 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:** ```markdown # 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\n**Verification 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, 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: ```bash 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: ```markdown # 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: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** ```markdown ## 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 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 | `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 ```bash 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_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: ```json { "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:** 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 **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 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 | `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:** 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> ``` ### 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: 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** ```bash 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