本指南将详细介绍如何在 OpenClaw 中构建一个多智能体协作系统（Multi-Agent System）。我们将通过命令行创建多个专用智能体（代码专家、测试专家、项目经理等），为它们赋予独特的角色与技能，并配置自动路由策略，实现从“单兵作战”到“团队协同”的升级。

🏗️ 核心架构设计

在开始之前，我们规划以下智能体团队结构：

智能体 ID	名称	角色定位	核心技能	触发场景
project-manager-agent	项目经理 (PM)	团队老大 (Leader)	架构设计、任务拆解、进度协调、代码审查	复杂项目需求、“开发一个完整系统”
code-agent	代码专家	核心开发	Python/JS/Go 编码、算法实现、API 对接	“写个脚本”、“修复这个 Bug”、“实现某功能”
test-agent	测试专家	质量保障	单元测试生成、边界测试、自动化测试脚本	“写测试”、“检查代码漏洞”、“验证功能”
ui-service-agent	UI/服务专家	前端与部署	React/Vue 组件、Docker 配置、Nginx 部署	“做个界面”、“部署服务”、“优化样式”

---

🚀 第一步：创建智能体工作区

OpenClaw 使用 workspace 隔离不同智能体的上下文和记忆。我们将为每个智能体创建独立的工作目录。

请在终端执行以下命令（以 Linux/macOS 路径为例，Windows 用户请将 ~ 替换为 C:\Users\<用户名>）：

1. 创建代码专家 (Code Agent)

openclaw agents add --workspace ~/.openclaw/workspace-code code-agent

系统将在 ~/.openclaw/workspace-code 初始化该智能体的专属环境。

2. 创建测试专家 (Test Agent)

openclaw agents add --workspace ~/.openclaw/workspace-test test-agent

3. 创建项目经理 (Project Manager Agent) - 团队核心

openclaw agents add --workspace ~/.openclaw/workspace-pm project-manager-agent

4. 创建 UI/服务专家 (UI Service Agent)

openclaw agents add --workspace ~/.openclaw/workspace-ui ui-service-agent

💡 提示：创建完成后，您可以在 ~/.openclaw/agents/ 目录下看到对应的配置文件和提示词模板。

---

🧠 第二步：定义角色与技能 (Prompt Engineering)

创建只是第一步，关键在于赋予灵魂。我们需要编辑每个智能体的 system_prompt.md (或 agent.json 中的 instructions 字段)，明确其职责。

1. 配置项目经理 (Project Manager) - 设定为 Leader

编辑文件：~/.openclaw/agents/project-manager-agent/agent/system_prompt.md

# Role: 首席技术项目经理 (CTO/PM)

## Profile
你是由 OpenClaw 驱动的高级项目经理，是整个开发团队的**领导者 (Leader)**。你的目标是将模糊的用户需求转化为可执行的工程方案，并协调其他智能体完成交付。

## Skills
1. **架构设计**：根据需求选择最佳技术栈，设计系统架构图。
2. **任务拆解**：将大项目拆解为原子任务（Task），分配给 code-agent, test-agent 等。
3. **代码审查**：审核下属提交的代码，确保符合规范。
4. **进度管理**：跟踪任务状态，解决阻塞问题。

## Workflow
1. 接收用户需求。
2. **思考与规划**：分析需求，生成详细的项目计划（Plan）。
3. **分发任务**：
   - 调用 `code-agent` 进行核心逻辑开发。
   - 调用 `test-agent` 编写测试用例。
   - 调用 `ui-service-agent` 处理前端或部署。
4. **整合与交付**：收集各子任务结果，整合成最终方案回复用户。

## Constraints
- 你**不直接编写具体代码**，除非没有合适的子智能体可用。
- 必须明确指定调用的子智能体 ID（如 `@code-agent`）。
- 保持专业、条理清晰的沟通风格。

2. 配置代码专家 (Code Agent)

编辑文件：~/.openclaw/agents/code-agent/agent/system_prompt.md

# Role: 高级全栈工程师

## Profile
你是团队中的核心开发者，擅长 Python, JavaScript, Go 等多种语言。你只负责**高质量代码的实现**。

## Skills
- 快速编写高效、可读性强的代码。
- 遵循最佳实践和设计模式。
- 解释代码逻辑，修复 Bug。

## Constraints
- 听从 `project-manager-agent` 的调度。
- 输出代码时必须包含必要的注释。
- 如果不确定需求，请先询问 PM 或用户，不要盲目猜测。

3. 配置测试专家 (Test Agent)

编辑文件：~/.openclaw/agents/test-agent/agent/system_prompt.md

# Role: 资深测试工程师 (QA)

## Profile
你是质量守门员。你的任务是发现代码中的缺陷，确保系统稳定。

## Skills
- 编写单元测试 (Pytest, Jest)。
- 设计边界测试和压力测试场景。
- 审查代码安全性。

## Constraints
- 仅在代码完成后介入，或根据 PM 指令提前介入设计测试计划。
- 报告 Bug 时必须提供复现步骤。

(同理配置 ui-service-agent，侧重前端和运维)

---

⚙️ 第三步：注册智能体到全局配置

为了让主程序识别这些新智能体，需要更新全局配置文件 ~/.openclaw/openclaw.json。

打开 openclaw.json，找到 agents 部分，确保列表中包含所有新创建的智能体：

"agents": {
  "defaults": {
    "model": {
      "primary": "local-ollama/qwen2.5:7b" 
    },
    "workspace": "~/.openclaw/workspace-default",
    "timeoutSeconds": 1800
  },
  "list": [
    {
      "id": "main",
      "name": "Default Assistant"
    },
    {
      "id": "project-manager-agent",
      "name": "Project Manager",
      "workspace": "~/.openclaw/workspace-pm",
      "agentDir": "~/.openclaw/agents/project-manager-agent/agent",
      "role": "leader" 
    },
    {
      "id": "code-agent",
      "name": "Code Expert",
      "workspace": "~/.openclaw/workspace-code",
      "agentDir": "~/.openclaw/agents/code-agent/agent"
    },
    {
      "id": "test-agent",
      "name": "Test Expert",
      "workspace": "~/.openclaw/workspace-test",
      "agentDir": "~/.openclaw/agents/test-agent/agent"
    },
    {
      "id": "ui-service-agent",
      "name": "UI Service",
      "workspace": "~/.openclaw/workspace-ui",
      "agentDir": "~/.openclaw/agents/ui-service-agent/agent"
    }
  ]
}

注意：project-manager-agent 被标记为关键节点，虽然 JSON 标准中没有强制 role 字段，但我们在 Prompt 中已定义其领导地位。部分 OpenClaw 版本支持在配置中显式设置 "isLeader": true。

---

🤖 第四步：实现自动路由与协作机制

如何让系统知道什么时候调用谁？我们有两种策略：

策略 A：基于意图的自动路由 (推荐)

利用 OpenClaw 的 Router Agent 或主入口的意图识别功能。在主入口 (main agent) 的 Prompt 中加入路由逻辑：

编辑 main agent 的 Prompt:

# Router Logic
你是一个智能路由助手。请分析用户输入：
1. 如果用户请求**开发完整项目、系统设计、复杂任务** -> 转交给 `@project-manager-agent` 处理。
2. 如果用户请求**具体的代码片段、函数实现、Bug 修复** -> 转交给 `@code-agent`。
3. 如果用户请求**写测试、找 Bug** -> 转交给 `@test-agent`。
4. 如果用户请求**界面、部署** -> 转交给 `@ui-service-agent`。

请直接调用对应智能体，不要自己尝试回答复杂工程问题。

策略 B：手动指定调用 (显式触发)

用户在发送消息时，直接 @ 智能体名称：

• @project-manager-agent 帮我设计一个电商后台系统
• @code-agent 用 Python 写一个快速排序

---

🎬 第五步：场景演示

场景一：开发完整项目 (自动协作)

用户输入:

“帮我开发一个基于 Python Flask 的待办事项 (Todo) API，需要数据库存储，并且要包含单元测试。”

系统执行流程:

1. Main Agent 识别为复杂项目，转发给 project-manager-agent。
2. PM Agent 启动：
   • 思考: “需要 Flask 后端 + SQLite + Pytest。”
   • 行动 1: 调用 @code-agent -> “请编写 Flask 骨架和 CRUD 接口代码。”
   • 行动 2: (等待 Code Agent 返回后) 调用 @test-agent -> “请为上述代码编写 Pytest 测试用例。”
   • 行动 3: 整合代码和测试文件，生成项目结构树。
3. 最终回复: 输出完整的项目文件结构和代码块，并告知用户如何运行。

场景二：单独调用 (精准打击)

用户输入:

“@code-agent 帮我写一个 Python 脚本，批量重命名文件夹下的图片文件。”

系统执行流程:

1. Main Agent 识别到 @code-agent 标签，直接路由。
2. Code Agent 接收指令，忽略项目管理逻辑，直接输出 Python 脚本代码。
3. 最终回复: 仅包含代码和简要使用说明。

---

🔍 调试与监控

在多智能体协作中，观察日志至关重要。

1. 查看实时日志:

   openclaw logs --follow
   

   您将看到类似这样的交互链：

   [INFO] User -> Main: "开发一个 Todo API..."
   [ROUTE] Main -> Project-Manager-Agent
   [TASK] PM -> Code-Agent: "Write Flask API..."
   [DONE] Code-Agent -> PM: (Code returned)
   [TASK] PM -> Test-Agent: "Write tests..."
   [DONE] Test-Agent -> PM: (Tests returned)
   [RESPONSE] PM -> User: (Final Project Structure)
   

2. 重置智能体记忆:
   如果某个智能体陷入死循环或记忆混乱，可以清除其 workspace：

   rm -rf ~/.openclaw/workspace-code/*
   # 重启服务后，该智能体将拥有全新的上下文
   

✅ 总结

通过以上步骤，您成功构建了一个具备分工明确、自动协作、层级管理的 OpenClaw 多智能体系统：

• PM 是大脑，负责统筹。
• Code/Test/UI 是手脚，负责执行。
• Router 是神经，负责传递信号。