OpenClaw多Agent解决方案

OpenClaw 多 Agent 配置方案文档

一、概述

OpenClaw 是一个支持多 Agent 协作的智能助手平台。通过配置多个专业化的 Agent，可以实现不同领域的任务处理，主 Agent 可以调用子 Agent 完成特定任务，形成高效的协作网络。

本文档详细记录了 Agent 的能力定义、创建过程、模型推荐、配置方法以及使用指南。

二、当前 Agent 架构

2.1 整体架构

当前系统配置了 1 个主 Agent 和 6 个子 Agent，形成主从协作模式：

                    +------------------+
                    |   Main Agent     |
                    |   (主控制器)      |
                    +--------+---------+
                             |
        +--------------------+--------------------+--------------------+--------------------+--------------------+
        |                    |                    |                    |                    |                    |
+-------v-------+   +--------v-------+   +--------v-------+   +--------v-------+   +--------v-------+   +--------v-------+
| Code Helper   |   | Meeting        |   | Project        |   | Tech Writer    |   | Researcher     |   | Content        |
|               |   | Secretary      |   | Assistant      |   |                |   |                |   | Assistant      |
+---------------+   +----------------+   +----------------+   +----------------+   +----------------+   +----------------+

2.2 Agent 列表

Agent ID	名称	模型	专注领域
main	Main	glm-5	主助手，通用任务处理，可调度其他 Agent
code-helper	Code Helper	qwen3-coder-480b	代码编写、调试、代码审查
meeting-secretary	Meeting Secretary	kimi-k2.5	会议记录、日程安排、会议总结
project-assistant	Project Assistant	glm-4.7	项目管理、任务跟踪、进度汇报
tech-writer	Tech Writer	glm-5	技术文档编写、API 文档、技术博客
researcher	Researcher	glm-5	信息调研、资料搜集、研究报告
content-assistant	Content Assistant	kimi-k2.5	内容创作、文案写作、编辑润色

三、Agent 能力详解

3.1 Main Agent (主助手)

核心职责：

作为用户的主要交互入口
理解用户意图并分配任务给合适的子 Agent
处理通用任务和日常问答
协调多个子 Agent 的协作

能力范围：

通用问答和任务处理
文件管理和编辑
网页浏览和信息提取
系统监控和管理
多渠道通信

推荐模型： glm-5

理由：通用能力强，支持 202K 上下文，适合处理多样化任务

3.2 Code Helper (代码助手)

核心职责：

代码编写和生成
代码调试和错误修复
代码审查和优化建议
技术方案设计

能力范围：

多语言编程支持
代码解释和文档生成
算法实现和优化
单元测试编写

推荐模型： qwen3-coder-480b-a35b-instruct

理由：专为代码设计，262K 上下文，支持大规模代码分析和生成

3.3 Meeting Secretary (会议秘书)

核心职责：

会议记录和整理
日程安排和提醒
会议纪要生成
待办事项提取

能力范围：

长文本处理和总结
关键信息提取
时间管理和调度
多语言支持

推荐模型： kimi-k2.5

理由：262K 超长上下文，擅长处理长文档和会议记录

3.4 Project Assistant (项目助手)

核心职责：

项目规划和任务分解
进度跟踪和汇报
风险识别和预警
资源协调建议

能力范围：

项目文档管理
数据分析和报告生成
团队协作支持
项目复盘总结

推荐模型： glm-4.7

理由：平衡能力和成本，适合项目管理场景

3.5 Tech Writer (技术写作)

核心职责：

技术文档编写
API 文档生成
技术博客撰写
用户手册编写

能力范围：

Markdown 排版
图表生成建议
文档结构优化
多语言文档

推荐模型： glm-5

理由：写作能力强，表达清晰准确

3.6 Researcher (研究员)

核心职责：

信息调研和分析
资料搜集整理
研究报告撰写
竞品分析

能力范围：

网络搜索和信息提取
数据收集和整理
趋势分析和预测
引用和参考文献管理

推荐模型： glm-5

理由：信息处理能力强，逻辑清晰

3.7 Content Assistant (内容助手)

核心职责：

内容创作和策划
文案写作和润色
社交媒体内容
营销文案

能力范围：

创意写作
风格调整和优化
多平台内容适配
文案迭代优化

推荐模型： kimi-k2.5

理由：创意能力强，支持长文本创作

四、可用模型详解

4.1 模型列表

模型 ID	提供商	上下文窗口	最大输出	特点
glm-5	千帆	202K	131K	通用大模型，能力均衡
glm-4.7	千帆	202K	131K	百度 GLM 系列，综合能力强
glm-4.7-internal	GLM Internal	200K	8K	百度内部模型，内部服务集成
qwen3-coder-480b	千帆	262K	66K	代码专用，超大规模
kimi-k2.5	千帆	262K	32K	超长上下文，创意写作
deepseek-v3.2	千帆	131K	96K	深度推理，支持图文
qwen3-vl-32b	千帆	131K	32K	视觉理解，图文处理
minimax-m2.1	千帆	205K	131K	长上下文，通用能力

4.2 模型选择建议

通用任务：

首选：glm-5
备选：glm-4.7、minimax-m2.1

代码任务：

首选：qwen3-coder-480b
备选：glm-4.7-internal

长文本处理：

首选：kimi-k2.5（262K 上下文）
备选：qwen3-coder-480b

复杂推理：

首选：deepseek-v3.2（支持深度推理）

图像理解：

首选：qwen3-vl-32b
备选：deepseek-v3.2

五、Agent 创建过程

5.1 方法一：使用命令行向导（推荐）

OpenClaw 提供了交互式的 Agent 创建向导，这是最简单的方式：

步骤 1：创建新 Agent

bash

openclaw agents add <agent-id>

例如，创建一个代码助手：

bash

openclaw agents add code-helper

向导会引导你完成以下配置：

Agent 名称
工作目录路径
模型选择
基础文件初始化

步骤 2：验证创建结果

bash

openclaw agents list --bindings

步骤 3：重启 Gateway 使配置生效

bash

openclaw gateway restart

5.2 方法二：手动编辑配置文件

如果需要更精细的控制，可以手动编辑配置文件。

步骤 1：编辑主配置文件

编辑 ~/.openclaw/openclaw.json 文件，在 agents.list 数组中添加新的 Agent 配置：

json

{
  "agents": {
    "list": [
      {
        "id": "new-agent-id",
        "name": "New Agent Name",
        "workspace": "~/.openclaw/workspace-new-agent-id",
        "agentDir": "~/.openclaw/agents/new-agent-id/agent",
        "model": {
          "primary": "qianfan/glm-5"
        }
      }
    ]
  }
}

步骤 2：创建工作目录

bash

mkdir -p ~/.openclaw/workspace-new-agent-id
mkdir -p ~/.openclaw/agents/new-agent-id/agent

步骤 3：创建基础文件

在工作目录创建必要的配置文件：

bash

# 创建 SOUL.md（定义 Agent 的性格和能力）
cat > ~/.openclaw/workspace-new-agent-id/SOUL.md << 'EOF'
# SOUL.md - Agent 定义

## 身份

我是 [Agent名称]，专注于 [专注领域]。

## 核心能力

1. [能力1]
2. [能力2]
3. [能力3]

## 工作方式

- [工作方式描述]

## 输出风格

- [输出风格描述]
EOF

# 创建 AGENTS.md（定义 Agent 的工作流程）
cat > ~/.openclaw/workspace-new-agent-id/AGENTS.md << 'EOF'
# AGENTS.md - 工作指南

## 工作流程

1. 接收任务
2. 分析需求
3. 执行处理
4. 输出结果

## 注意事项

- 保持专业
- 准确响应
- 及时反馈
EOF

# 创建 TOOLS.md（定义本地配置和工具）
touch ~/.openclaw/workspace-new-agent-id/TOOLS.md

# 创建 USER.md（定义用户信息）
cat > ~/.openclaw/workspace-new-agent-id/USER.md << 'EOF'
# USER.md - 用户信息

## 用户

- 名称：[用户名称]
- 偏好：[用户偏好]
EOF

步骤 4：配置模型（可选）

如果需要为 Agent 指定特定的模型配置，创建 models.json：

bash

cat > ~/.openclaw/agents/new-agent-id/agent/models.json << 'EOF'
{
  "providers": {
    "qianfan": {
      "baseUrl": "https://qianfan.baidubce.com/v2",
      "api": "openai-completions",
      "models": [
        {
          "id": "glm-5",
          "name": "glm-5",
          "contextWindow": 202000,
          "maxTokens": 131072
        }
      ]
    }
  }
}
EOF

步骤 5：配置子 Agent 访问权限

如果需要让 Main Agent 可以调用这个新 Agent，在主配置中添加权限：

json

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "Main",
        "subagents": {
          "allowAgents": [
            "new-agent-id"
          ]
        }
      }
    ]
  },
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": [
        "main",
        "new-agent-id"
      ]
    }
  }
}

步骤 6：重启 Gateway

bash

openclaw gateway restart

5.3 配置字段详解

字段	类型	必填	说明
id	string	是	Agent 唯一标识符，只能包含字母、数字和连字符
name	string	是	Agent 显示名称，用于日志和 UI 显示
default	boolean	否	是否为默认 Agent，只能有一个默认 Agent
workspace	string	是	工作目录路径，Agent 的主工作空间
agentDir	string	是	Agent 配置目录路径，存储认证和模型配置
model.primary	string	否	主模型，格式为 "provider/model-id"
model.imageModel	string	否	图像理解模型
subagents.allowAgents	array	否	允许调用的子 Agent ID 列表
sandbox.mode	string	否	沙箱模式：off/all/session
sandbox.scope	string	否	沙箱范围：shared/agent/session
tools.allow	array	否	允许使用的工具列表
tools.deny	array	否	禁止使用的工具列表

5.4 创建示例：完整的代码助手配置

bash

# 1. 使用向导创建
openclaw agents add code-helper

# 2. 创建工作目录
mkdir -p ~/.openclaw/workspace-code-helper
mkdir -p ~/.openclaw/agents/code-helper/agent

# 3. 创建 SOUL.md
cat > ~/.openclaw/workspace-code-helper/SOUL.md << 'EOF'
# SOUL.md - Code Helper

## 身份

我是代码助手，专注于软件开发和编程任务。

## 核心能力

1. 代码编写：多种编程语言的代码生成
2. 代码调试：错误分析和修复建议
3. 代码审查：代码质量检查和优化建议
4. 技术方案：架构设计和技术选型

## 工作方式

- 先理解需求，再编写代码
- 提供清晰的代码注释
- 遵循最佳实践和编码规范
- 考虑性能和可维护性

## 输出风格

- 代码块使用正确的语法高亮
- 提供使用示例
- 解释关键实现细节
EOF

# 4. 配置模型（可选，如果与默认不同）
cat > ~/.openclaw/agents/code-helper/agent/models.json << 'EOF'
{
  "providers": {
    "qianfan": {
      "baseUrl": "https://qianfan.baidubce.com/v2",
      "api": "openai-completions",
      "models": [
        {
          "id": "qwen3-coder-480b-a35b-instruct",
          "name": "Qwen3 Coder",
          "contextWindow": 262144,
          "maxTokens": 65536
        }
      ]
    }
  }
}
EOF

# 5. 重启 Gateway
openclaw gateway restart

六、配置文件详解

6.1 目录结构

~/.openclaw/
├── openclaw.json              # 主配置文件
├── agents/
│   ├── main/
│   │   └── agent/
│   │       ├── models.json    # 模型配置
│   │       └── auth-profiles.json  # 认证配置
│   ├── code-helper/
│   │   └── agent/
│   │       └── models.json
│   └── [other-agents]/
│       └── agent/
├── workspace/                  # Main Agent 工作目录
│   ├── SOUL.md                # Agent 性格定义
│   ├── AGENTS.md              # 工作指南
│   ├── MEMORY.md              # 长期记忆
│   ├── TOOLS.md               # 工具配置
│   ├── USER.md                # 用户信息
│   ├── IDENTITY.md            # 身份信息
│   ├── HEARTBEAT.md           # 心跳任务
│   └── memory/                # 日记目录
│       └── YYYY-MM-DD.md
├── workspace-code-helper/      # Code Helper 工作目录
└── workspace-[agent-id]/       # 其他 Agent 工作目录

6.2 主配置文件结构

配置文件路径：~/.openclaw/openclaw.json

json

{
  "meta": {
    "lastTouchedVersion": "版本号",
    "lastTouchedAt": "最后修改时间"
  },
  "models": {
    "mode": "merge",
    "providers": {
      "qianfan": {
        "baseUrl": "API地址",
        "apiKey": "API密钥",
        "api": "openai-completions",
        "models": [...]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "默认模型"
      },
      "imageModel": {
        "primary": "图像模型"
      },
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "1h"
      },
      "heartbeat": {
        "every": "30m"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    },
    "list": [
      // Agent 列表配置
    ]
  },
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["允许互相调用的 agent 列表"]
    }
  },
  "gateway": {
    "port": 8081,
    "mode": "local",
    "bind": "lan"
  },
  "bindings": [
    // 消息路由绑定配置
  ]
}

6.3 模型配置继承机制

Agent 的模型配置采用三层继承：

全局默认配置 (agents.defaults)
Agent 目录下的 models.json
主配置文件中的 agents.list[].model

优先级：3 > 2 > 1

6.4 子 Agent 调用配置

启用 Agent 之间的互相调用：

json

{
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": [
        "main",
        "code-helper",
        "meeting-secretary",
        "project-assistant",
        "tech-writer",
        "researcher",
        "content-assistant"
      ]
    }
  }
}

6.5 消息路由绑定

配置消息如何路由到不同的 Agent：

json

{
  "bindings": [
    {
      "agentId": "work",
      "match": {
        "channel": "whatsapp",
        "accountId": "biz"
      }
    },
    {
      "agentId": "home",
      "match": {
        "channel": "whatsapp",
        "accountId": "personal"
      }
    }
  ]
}

七、使用方法

7.1 直接调用

通过 Web Chat 或其他渠道直接与特定 Agent 对话：

请帮我写一段 Python 代码实现快速排序

Main Agent 会自动识别任务类型并可能调用 Code Helper 来完成。

7.2 显式指定 Agent

通过会话切换命令指定 Agent：

/agent code-helper

7.3 通过 Main Agent 调度

Main Agent 会根据任务类型自动调度：

用户：帮我整理一下今天的会议记录
Main Agent：[自动调用 meeting-secretary]

7.4 子 Agent 独立运行

每个子 Agent 可以独立启动会话，通过 API 调用：

bash

# 使用 curl 调用特定 Agent
curl -X POST http://localhost:8081/v1/chat/completions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "code-helper",
    "messages": [{"role": "user", "content": "写一个 Hello World"}]
  }'

7.5 OpenAI 兼容接口

OpenClaw 提供 OpenAI 兼容的 API 接口：

python

import openai

client = openai.OpenAI(
    base_url="http://localhost:8081/v1",
    api_key="YOUR_TOKEN"
)

response = client.chat.completions.create(
    model="code-helper",  # 指定 Agent ID
    messages=[
        {"role": "user", "content": "帮我写一个 Python 函数"}
    ]
)

7.6 命令行调用

使用 openclaw agent 命令直接与 Agent 交互：

bash

# 与默认 Agent 对话
openclaw agent --message "帮我总结一下这个文档"

# 指定 Agent
openclaw agent --agent code-helper --message "写一个排序算法"

# 启用深度思考
openclaw agent --message "分析这个架构设计" --thinking high

八、常用命令速查

8.1 Agent 管理

bash

# 创建新 Agent（推荐方式）
openclaw agents add <agent-id>

# 列出所有 Agent 和绑定
openclaw agents list --bindings

# 验证 Agent 状态
openclaw status

# 重启 Gateway
openclaw gateway restart

# 查看 Gateway 状态
openclaw gateway status

8.2 配置管理

bash

# 查看当前配置
openclaw config get

# 交互式配置向导
openclaw configure

# 健康检查
openclaw doctor

# 查看日志
openclaw logs

8.3 模型管理

bash

# 查看可用模型
openclaw models list

# 配置模型
openclaw models configure

九、最佳实践

9.1 Agent 设计原则

单一职责：每个 Agent 专注于一个领域
明确边界：清晰定义 Agent 的能力范围
合理分工：避免 Agent 功能重叠
模型匹配：根据任务特点选择合适的模型

9.2 模型选择建议

任务类型	推荐模型	原因
代码编写	qwen3-coder-480b	专业代码模型，262K 上下文
长文本处理	kimi-k2.5	262K 超长上下文
通用问答	glm-5	能力均衡，202K 上下文
复杂推理	deepseek-v3.2	深度推理能力
图像理解	qwen3-vl-32b	视觉理解专用

9.3 配置管理建议

版本控制：将配置文件纳入 Git 管理
环境隔离：开发和生产环境使用不同配置
定期备份：定期备份 workspace 目录
监控日志：关注 Agent 运行日志，及时发现异常

9.4 资源管理配置

json

{
  "agents": {
    "defaults": {
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "1h"
      },
      "compaction": {
        "mode": "safeguard"
      }
    }
  }
}

9.5 安全配置建议

json

{
  "agents": {
    "list": [
      {
        "id": "restricted-agent",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit"]
        }
      }
    ]
  }
}

十、故障排查

10.1 Agent 无法启动

检查步骤：

确认配置文件语法正确
确认工作目录存在且有权限
检查模型 API 密钥是否有效
查看日志：openclaw gateway status

解决方案：

bash

# 检查配置
openclaw doctor

# 查看详细日志
openclaw logs --verbose

# 重新初始化
openclaw setup --workspace ~/.openclaw/workspace

10.2 子 Agent 调用失败

检查步骤：

确认 tools.agentToAgent.enabled 为 true
确认 Agent ID 在 allow 列表中
确认子 Agent 配置正确
检查并发数是否达到上限

解决方案：

bash

# 列出所有 Agent
openclaw agents list --bindings

# 检查权限配置
openclaw config get tools.agentToAgent

10.3 模型调用失败

检查步骤：

确认模型 ID 正确
确认 API 密钥有效
确认网络连接正常
查看模型提供商服务状态

解决方案：

bash

# 检查模型配置
openclaw models list

# 测试模型连接
openclaw agent --message "Hello" --model glm-5

10.4 工作目录问题

检查步骤：

确认目录路径正确
确认有读写权限
确认必需文件存在

解决方案：

bash

# 重新创建必需文件
openclaw setup --workspace ~/.openclaw/workspace-code-helper

# 检查目录权限
ls -la ~/.openclaw/workspace-code-helper/

十一、附录

11.1 完整配置示例

当前系统的完整配置示例：

json

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "qianfan/glm-5"
      },
      "imageModel": {
        "primary": "qianfan/qwen3-vl-32b-instruct"
      },
      "heartbeat": {
        "every": "30m"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    },
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "Main",
        "workspace": "~/.openclaw/workspace",
        "agentDir": "~/.openclaw/agents/main/agent",
        "subagents": {
          "allowAgents": [
            "code-helper",
            "meeting-secretary",
            "project-assistant",
            "tech-writer",
            "researcher",
            "content-assistant"
          ]
        }
      },
      {
        "id": "code-helper",
        "name": "Code Helper",
        "workspace": "~/.openclaw/workspace-code-helper",
        "agentDir": "~/.openclaw/agents/code-helper/agent",
        "model": {
          "primary": "qianfan/qwen3-coder-480b-a35b-instruct"
        }
      }
    ]
  },
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": [
        "main",
        "code-helper",
        "meeting-secretary",
        "project-assistant",
        "tech-writer",
        "researcher",
        "content-assistant"
      ]
    }
  }
}

11.2 相关文档

OpenClaw 官方文档：https://docs.openclaw.ai
GitHub 仓库：https://github.com/openclaw/openclaw
社区支持：https://discord.com/invite/clawd
多 Agent 路由文档：https://docs.openclaw.ai/concepts/multi-agent

11.3 更新日志

日期	版本	更新内容
2026-02-28	v1.0	初始版本，记录当前 Agent 配置方案
2026-02-28	v1.1	补充 Agent 创建命令，优化文档结构

文档维护者： OpenClaw Main Agent最后更新： 2026-02-28

OpenClaw 多 Agent 配置方案文档 ​

一、概述 ​

二、当前 Agent 架构 ​

2.1 整体架构 ​

2.2 Agent 列表 ​

三、Agent 能力详解 ​

3.1 Main Agent (主助手) ​

3.2 Code Helper (代码助手) ​

3.3 Meeting Secretary (会议秘书) ​

3.4 Project Assistant (项目助手) ​

3.5 Tech Writer (技术写作) ​

3.6 Researcher (研究员) ​

3.7 Content Assistant (内容助手) ​

四、可用模型详解 ​

4.1 模型列表 ​

4.2 模型选择建议 ​

五、Agent 创建过程 ​

5.1 方法一：使用命令行向导（推荐） ​

5.2 方法二：手动编辑配置文件 ​

5.3 配置字段详解 ​

5.4 创建示例：完整的代码助手配置 ​

六、配置文件详解 ​

6.1 目录结构 ​

6.2 主配置文件结构 ​

6.3 模型配置继承机制 ​

6.4 子 Agent 调用配置 ​

6.5 消息路由绑定 ​

七、使用方法 ​

7.1 直接调用 ​

7.2 显式指定 Agent ​

7.3 通过 Main Agent 调度 ​

7.4 子 Agent 独立运行 ​

7.5 OpenAI 兼容接口 ​

7.6 命令行调用 ​

八、常用命令速查 ​

8.1 Agent 管理 ​

8.2 配置管理 ​

8.3 模型管理 ​

九、最佳实践 ​

9.1 Agent 设计原则 ​

9.2 模型选择建议 ​

9.3 配置管理建议 ​

9.4 资源管理配置 ​

9.5 安全配置建议 ​

十、故障排查 ​

10.1 Agent 无法启动 ​

10.2 子 Agent 调用失败 ​

10.3 模型调用失败 ​

10.4 工作目录问题 ​

十一、附录 ​

11.1 完整配置示例 ​

11.2 相关文档 ​

11.3 更新日志 ​

OpenClaw 多 Agent 配置方案文档

一、概述

二、当前 Agent 架构

2.1 整体架构

2.2 Agent 列表

三、Agent 能力详解

3.1 Main Agent (主助手)

3.2 Code Helper (代码助手)

3.3 Meeting Secretary (会议秘书)

3.4 Project Assistant (项目助手)

3.5 Tech Writer (技术写作)

3.6 Researcher (研究员)

3.7 Content Assistant (内容助手)

四、可用模型详解

4.1 模型列表

4.2 模型选择建议

五、Agent 创建过程

5.1 方法一：使用命令行向导（推荐）

5.2 方法二：手动编辑配置文件

5.3 配置字段详解

5.4 创建示例：完整的代码助手配置

六、配置文件详解

6.1 目录结构

6.2 主配置文件结构

6.3 模型配置继承机制

6.4 子 Agent 调用配置

6.5 消息路由绑定

七、使用方法

7.1 直接调用

7.2 显式指定 Agent

7.3 通过 Main Agent 调度

7.4 子 Agent 独立运行

7.5 OpenAI 兼容接口

7.6 命令行调用

八、常用命令速查

8.1 Agent 管理

8.2 配置管理

8.3 模型管理

九、最佳实践

9.1 Agent 设计原则

9.2 模型选择建议

9.3 配置管理建议

9.4 资源管理配置

9.5 安全配置建议

十、故障排查

10.1 Agent 无法启动

10.2 子 Agent 调用失败

10.3 模型调用失败

10.4 工作目录问题

十一、附录

11.1 完整配置示例

11.2 相关文档

11.3 更新日志