多 Agent 配置指南

帮助你的 Bot 引导主人一步步配置 OpenClaw 多 Agent 系统

🔍 执行前：自动切换到高智能模型

多 Agent 配置涉及修改系统配置文件、重启 Gateway，操作风险较高。执行此 skill 前，必须先检查并切换模型：

1. 调用 session_status 检查当前模型
2. 如果是轻量模型（Haiku、Kimi、Flash 等，模型名含 haiku、kimi、flash、mini）→ 立即调用 session_status(model="deepv-easyclaw/claude-sonnet-4-6") 切换到 Sonnet，然后告知用户：「检测到当前使用轻量模型，多 Agent 配置操作风险较高，已自动切换到 Sonnet，继续配置。」
3. 如果已经是 Sonnet 或 Opus → 直接继续，无需切换，无需告知

什么是多 Agent？

OpenClaw 支持运行多个 Agent，每个 Agent 有独立角色、workspace 和飞书机器人。主 Agent 负责和主人日常对话，子 Agent 负责专项任务（调研、写作、代码等）。主 Agent 可以把任务 spawn 给子 Agent，子 Agent 完成后结果自动回传。

配置文件核心结构（看懂再动手）

多 Agent 配置涉及 openclaw.json 里三个关键字段：

agents.list — 定义所有 Agent

执行 openclaw agents add 后，agents.list 会自动生成：

"agents": {
  "list": [
    {
      "id": "main",
      "subagents": {
        "allowAgents": ["researcher", "writer"]
      }
    },
    {
      "id": "researcher",
      "name": "researcher",
      "workspace": "~/.openclaw/workspace-researcher",
      "agentDir": "~/.openclaw/agents/researcher/agent"
    }
  ]
}

字段	说明
id	Agent 唯一标识，英文小写
subagents.allowAgents	主 Agent 可调度哪些子 Agent
model	可单独为子 Agent 指定模型（省成本）

bindings — 绑定 Agent 到飞书账号（方案 B 专用）

"bindings": [
  {
    "agentId": "main",
    "match": { "channel": "feishu", "accountId": "default" }
  },
  {
    "agentId": "researcher",
    "match": { "channel": "feishu", "accountId": "researcher" }
  }
]

channels.feishu.accounts — 多飞书账号（方案 B 专用）

"channels": {
  "feishu": {
    "accounts": {
      "default": {
        "appId": "cli_xxx",
        "appSecret": "xxx",
        "botName": "大橘"
      },
      "researcher": {
        "appId": "cli_yyy",
        "appSecret": "yyy",
        "botName": "大橘-调研员"
      }
    }
  }
}

主 Agent 调度子 Agent 的三种方式

方式	适用场景	特点
sessions_spawn	一次性独立任务（调研、写作）	最常用，完成后自动回传结果
sessions_send	持续对话、传递上下文	给已有 session 发消息
共享文件读写	异步协作、数据共享	最简单，多 Agent 读写同一文件

最常用示例（sessions_spawn）：

sessions_spawn(agentId="researcher", task="帮我调研2026年AI行业最新动态")

主 Agent 派出任务后不需要等待，子 Agent 完成后结果自动回传。

⚠️ 执行前必须问清楚主人

1. 子 Agent 的角色和分工

• 你希望加哪些子 Agent？每个负责什么？
• 例：调研员（搜索信息）、写作助手（写文章）、代码助手（看代码）

2. 飞书入口方案

• 方案 A（推荐新手）：所有 Agent 共用一个飞书机器人，主 Agent 统一对外，子 Agent 在后台工作
• 方案 B（进阶）：每个 Agent 有独立飞书机器人，主人可直接和各角色对话
• 方案 C（多平台）：主 Agent 绑飞书，部分子 Agent 同时绑 Discord，适合同时运营多个社群

如果主人选方案 B，必须先让主人去飞书开放平台为每个子 Agent 创建独立应用，并提供 App ID + App Secret，再继续配置。

3. 子 Agent 的模型

• 子 Agent 是否可以用轻量模型节省成本？同系列轻量模型通常比旗舰模型便宜 3-5 倍。例如 Claude 系列用 Haiku、Gemini 系列用 Flash、GPT 系列用 mini。对话简单、任务明确的子 Agent 优先选轻量模型。

配置步骤

第零步：确认当前状态

openclaw agents list
openclaw gateway status

汇报给主人：当前有哪些 Agent、Gateway 是否正常。

第一步：添加子 Agent

openclaw agents add <子AgentId> --workspace ~/.openclaw/workspace-<子AgentId>

示例（调研员）：

openclaw agents add researcher --workspace ~/.openclaw/workspace-researcher

验证：

openclaw agents list

新 Agent 出现在列表中即成功。

第二步：初始化子 Agent 人设

写 SOUL.md（根据实际角色调整内容）：

cat > ~/.openclaw/workspace-researcher/SOUL.md << 'EOF'
# SOUL.md - 调研员

## 角色
我是调研助手，专注信息搜索、网页查询和内容整理。

## 职责
- 根据任务搜索和整理相关信息
- 输出结构清晰、有据可查的调研报告

## 风格
- 简洁客观，结论在前
- 不确定的信息注明来源，不编造
EOF

写专属 AGENTS.md（根据实际角色调整"角色名"）：

cat > ~/.openclaw/workspace-researcher/AGENTS.md << 'EOF'
# AGENTS.md - 调研员

## 我是谁
我是主 Agent 的调研助手，不是主 Agent。

## 行为规范

### ✅ 收到任务直接执行
- 不反问，不问确认，直接干
- 模糊需求先做，做完再补充说明

### ✅ 输出格式
- 结论在前，细节在后
- 标注信息来源

### ❌ 禁止
- 不说"我是主 Agent"
- 不问"需要我创建子 Agent 吗"
- 不模仿主 Agent 的交互风格
EOF

第三步：配置主 Agent 调度权限

openclaw config get agents.list

找到 "id": "main" 对应的序号（通常是 0），然后执行：

openclaw config set agents.list[0].subagents.allowAgents '["researcher"]' --json

多个子 Agent 时：

openclaw config set agents.list[0].subagents.allowAgents '["researcher","writer"]' --json

第四步（可选）：为子 Agent 指定轻量模型

openclaw config set agents.list[1].model 'deepv-easyclaw/claude-haiku-4-5' --json

第五步（方案 B 专用）：添加独立飞书账号并绑定

先备份：

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

第一步：先读取并记录当前需要保留的字段（操作前必做）

python3 -c "
import json, os
c = json.load(open(os.path.expanduser('~/.openclaw/openclaw.json')))
f = c['channels']['feishu']
keep = {k: v for k, v in f.items() if k not in ['appId', 'appSecret', 'botName']}
print('迁移时需要保留的字段：')
for k, v in keep.items():
    print(f'  {k}: {v}')
"

把输出的所有字段记下来，编辑 openclaw.json 时原样放回 channels.feishu 里，一个都不能少。

迁移后的 channels.feishu 结构示例（保留字段因人而异，以上一步输出为准）：

"feishu": {
  "defaultAccount": "default",
  "allowFrom": ["*"],        ← 原来有就保留，原来没有就不加
  "dmPolicy": "open",        ← 同上
  "groupPolicy": "open",     ← 同上
  "accounts": {
    "default": {
      "appId": "原主Agent的appId",
      "appSecret": "原主Agent的appSecret",
      "botName": "主Agent名字"
    },
    "researcher": {
      "appId": "主人提供的子Agent appId",
      "appSecret": "主人提供的子Agent appSecret",
      "botName": "子Agent名字"
    }
  }
}

同时在顶层（与 channels、agents 同级）添加 bindings：

"bindings": [
  {
    "agentId": "main",
    "match": { "channel": "feishu", "accountId": "default" }
  },
  {
    "agentId": "researcher",
    "match": { "channel": "feishu", "accountId": "researcher" }
  }
]

验证 JSON 格式正确：

python3 -c "import json, os; json.load(open(os.path.expanduser('~/.openclaw/openclaw.json'))); print('JSON格式正确')"

改完后再次运行第一步的脚本，对比字段是否与操作前一致，有缺失立即从备份恢复：

cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

第六步：验证配置已生效

多 Agent 配置（agents、bindings、飞书账号）均支持 热重载，Gateway 会自动检测配置文件变化并应用，无需重启。

第七步：验证连通性

openclaw agents list
openclaw channels status

预期结果：

• agents list 显示所有已配置的 Agent
• channels status 显示每个飞书账号状态为 running, works

验证通过后再告知主人配置完成。

测试

测试 1：spawn 测试

sessions_spawn(agentId="researcher", task="你好，请介绍一下你自己是谁，你的角色是什么。")

预期：子 Agent 回复"我是主 Agent 的调研助手"，不说"我是主 Agent"。

如果子 Agent 还是自称主 Agent → 检查 AGENTS.md 是否写对，重新写入后无需重启，下次对话自动生效。

测试 2：直接飞书对话（方案 B）

让主人在飞书找到子 Agent 机器人，直接发消息，确认正常回复。

已知踩坑

问题	原因	解决
子 Agent 自称"我是主 Agent"	复制了主 Agent 的 AGENTS.md	为子 Agent 写专属 AGENTS.md
子 Agent 反问一堆问题	AGENTS.md 未明确"直接执行"	AGENTS.md 加"收到任务直接执行，不反问"
openclaw agents bind 报错	此命令不存在	手动编辑 bindings 字段
config get agents.list 报 path not found	agents add 还没执行，list 未生成	先执行第一步再执行第三步
config set ... --strict-json 报错	参数名错误	改用 --json
子 Agent 飞书不响应	未发布应用或未配置事件订阅	完成飞书开放平台发布流程
子 Agent 想主动汇报给主 Agent 但失败	spawn 外的子 Agent 无 session 工具	让主 Agent spawn 任务，结果自动回传
Bot 执行 gateway restart 后无回复、卡住	restart 会重启承载 Bot 自身的进程	不需要重启！多 Agent 配置全部支持热重载
openclaw agents delete 非交互环境报错	需要确认提示	加 --force 参数：openclaw agents delete <id> --force
迁移飞书多账号后 Bot 完全不响应、每 30 分钟重启	清理顶层字段时误删了 allowFrom、dmPolicy、groupPolicy	恢复备份，补回这三个字段（参考第五步 JSON 示例）
迁移后飞书 Bot 响应 "terminated"	同上，健康监控 stuck 导致反复重启	同上