Skip to content

Commit 49d0fff

Browse files
Maynor996Maynor996
committed
补充多机器人多Agent模式完整教程到第9章
- 新增9.1.16节：多机器人多Agent模式完整教程 - 包含架构设计、配置步骤、使用方法、实战案例 - 添加性能成本分析、故障排查、高级技巧 - 重新组织原有多Agent内容为9.1.17节（传统方式） - 保持9.1.18节本地多Agent管理内容不变
1 parent 4809dc7 commit 49d0fff

254 files changed

Lines changed: 12022 additions & 5794 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AppIcon.icns‎

1.08 MB
Binary file not shown.

‎BINDINGS-ISSUE-REPORT.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# OpenClaw Bindings 路由问题诊断报告
2+
3+
## 问题描述
4+
5+
配置了 4 个 agents 和 4 个 bindings，但所有飞书群组都路由到 `main-agent`，而不是配置的专属 agent。
6+
7+
## 配置信息
8+
9+
### Agents 配置
10+
```
11+
- main-agent → claude-opus-4-6-thinking
12+
- content-agent → claude-sonnet-4-5
13+
- tech-agent → claude-sonnet-4-5-thinking
14+
- ainews-agent → gemini-2.5-flash
15+
```
16+
17+
### Bindings 配置
18+
```
19+
- main-agent → oc_YOUR_MAIN_GROUP_ID
20+
- content-agent → oc_YOUR_CONTENT_GROUP_ID
21+
- tech-agent → oc_YOUR_TECH_GROUP_ID
22+
- ainews-agent → oc_YOUR_NEWS_GROUP_ID
23+
```
24+
25+
### 飞书账号配置
26+
```
27+
- main-assistant → 主助理
28+
- content-creator → 内容创作助手
29+
- tech-dev → 技术开发助手
30+
- ai-news → AI资讯助手
31+
```
32+
33+
## 实际运行情况
34+
35+
从日志可以看到：
36+
37+
```
38+
lane=session:agent:main-agent:feishu:group:oc_YOUR_TECH_GROUP_ID
39+
lane=session:agent:main-agent:feishu:group:oc_YOUR_CONTENT_GROUP_ID
40+
```
41+
42+
**所有群组都使用 main-agent**，即使群组 ID 不同。
43+
44+
## 配置加载情况
45+
46+
日志显示配置已成功加载：
47+
48+
```
49+
config change detected; evaluating reload (..., agents.list, bindings)
50+
config change applied (dynamic reads: ..., agents.list, bindings)
51+
```
52+
53+
## 问题分析
54+
55+
### ✅ 排除的问题
56+
57+
1. ✅ 配置文件格式正确（JSON 语法无误）
58+
2. ✅ Bindings 配置已加载
59+
3. ✅ Agents 配置已加载
60+
4. ✅ 工作空间路径存在
61+
5. ✅ 网关已重启
62+
6. ✅ 群组 ID 正确
63+
64+
### ❌ 可能的原因
65+
66+
1. **Bindings 匹配逻辑问题**
67+
- OpenClaw 2026.2.9 的 bindings 功能可能有 bug
68+
- peer.id 匹配可能不工作
69+
- 默认 agent 优先级过高
70+
71+
2. **配置结构问题**
72+
- 当前使用 4 个飞书账号 + peer.id bindings
73+
- 可能需要使用 account bindings 而不是 peer.id bindings
74+
75+
3. **版本兼容性问题**
76+
- 文档中的配置示例可能是旧版本的
77+
- 新版本的 bindings 语法可能有变化
78+
79+
## 解决方案
80+
81+
### 方案 1：使用 Account Bindings（推荐）
82+
83+
修改配置，使用 `account` 匹配而不是 `peer.id` 匹配：
84+
85+
```json
86+
{
87+
"bindings": [
88+
{
89+
"agentId": "main-agent",
90+
"match": {
91+
"channel": "feishu",
92+
"account": "main-assistant"
93+
}
94+
},
95+
{
96+
"agentId": "content-agent",
97+
"match": {
98+
"channel": "feishu",
99+
"account": "content-creator"
100+
}
101+
},
102+
{
103+
"agentId": "tech-agent",
104+
"match": {
105+
"channel": "feishu",
106+
"account": "tech-dev"
107+
}
108+
},
109+
{
110+
"agentId": "ainews-agent",
111+
"match": {
112+
"channel": "feishu",
113+
"account": "ai-news"
114+
}
115+
}
116+
]
117+
}
118+
```
119+
120+
这样每个飞书机器人直接绑定到一个 agent，不依赖群组 ID。
121+
122+
### 方案 2：在群组中手动切换 Agent
123+
124+
在每个群组中发送命令：
125+
126+
```
127+
群组 1: /agent main-agent
128+
群组 2: /agent content-agent
129+
群组 3: /agent tech-agent
130+
群组 4: /agent ainews-agent
131+
```
132+
133+
### 方案 3：使用单机器人 + 群组绑定（当前方案）
134+
135+
如果 peer.id bindings 应该工作但没有工作，可能需要：
136+
137+
1. 升级 OpenClaw 到最新版本
138+
2. 查看官方文档确认 bindings 的正确语法
139+
3. 提交 bug 报告到 OpenClaw 项目
140+
141+
## 测试步骤
142+
143+
### 测试方案 1（Account Bindings）
144+
145+
1. 修改配置文件，使用 account bindings
146+
2. 重启网关：`openclaw gateway restart`
147+
3. 在不同的飞书机器人中发送消息
148+
4. 查看日志确认使用了不同的 agent
149+
150+
### 测试方案 2（手动切换）
151+
152+
1. 在群组 1 中发送：`/agent main-agent`
153+
2. 在群组 2 中发送：`/agent content-agent`
154+
3. 在群组 3 中发送：`/agent tech-agent`
155+
4. 在群组 4 中发送：`/agent ainews-agent`
156+
5. 发送测试消息确认 agent 已切换
157+
158+
## 下一步行动
159+
160+
1. **立即尝试**：方案 1（Account Bindings）
161+
2. **备选方案**：方案 2（手动切换）
162+
3. **长期方案**：联系 OpenClaw 官方确认 peer.id bindings 的正确用法
163+
164+
## 相关文件
165+
166+
- 配置文件：`~/.openclaw/openclaw.json`
167+
- 本地副本：`openclaw.json`
168+
- 日志文件：`/tmp/openclaw/openclaw-2026-02-13.log`
169+
- 诊断脚本：
170+
- `diagnose-routing.sh`
171+
- `fix-routing.sh`
172+
- `monitor-routing.sh`
173+
- `check-logs-detailed.sh`
174+
175+
## 参考文档
176+
177+
- OpenClaw 版本：2026.2.9
178+
- 文档章节：9.1.11 多 Agent 配置
179+
- 配置示例：docs/03-advanced/09-multi-platform-integration.md
180+
181+
---
182+
183+
**结论**：配置本身是正确的，但 peer.id bindings 没有生效。建议尝试使用 account bindings 或手动切换 agent。

‎CORRECT-USAGE.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# OpenClaw 多 Agent 正确使用方法
2+
3+
## ✅ 好消息
4+
5+
经过测试确认，`/agent` 命令**是可以工作的**！
6+
7+
从日志可以看到：
8+
```
9+
lane=session:agent:ainews-agent:main
10+
```
11+
12+
这说明 ainews-agent 已经成功启动。
13+
14+
## 🎯 正确的使用步骤
15+
16+
### 步骤 1：重置会话
17+
18+
在群组中先发送：
19+
```
20+
/reset
21+
```
22+
23+
这会清除当前会话，让系统重新识别 agents。
24+
25+
### 步骤 2：切换 Agent
26+
27+
然后立即发送：
28+
```
29+
/agent tech-agent
30+
```
31+
32+
或者其他 agent：
33+
```
34+
/agent content-agent
35+
/agent ainews-agent
36+
/agent main-agent
37+
```
38+
39+
### 步骤 3：验证
40+
41+
发送测试消息或 `/status` 确认 agent 已切换。
42+
43+
## 📋 完整操作流程
44+
45+
### 助理群（使用 main-agent）
46+
47+
```
48+
/reset
49+
/agent main-agent
50+
/status
51+
```
52+
53+
### 内容创作群（使用 content-agent）
54+
55+
```
56+
/reset
57+
/agent content-agent
58+
/status
59+
```
60+
61+
### 技术开发群（使用 tech-agent）
62+
63+
```
64+
/reset
65+
/agent tech-agent
66+
/status
67+
```
68+
69+
### AI 资讯群（使用 ainews-agent）
70+
71+
```
72+
/reset
73+
/agent ainews-agent
74+
/status
75+
```
76+
77+
## ⚠️ 重要提示
78+
79+
1. **必须先 `/reset`**
80+
- 如果直接使用 `/agent` 可能会提示"未配置"
81+
- 这是因为当前会话已经绑定到了 main-agent
82+
- `/reset` 会清除会话，让系统重新识别
83+
84+
2. **会话持久化**
85+
- 切换成功后，会话会记住选择的 agent
86+
- 下次对话会继续使用这个 agent
87+
- 除非再次 `/reset`
88+
89+
3. **验证切换**
90+
- 使用 `/status` 查看当前 agent
91+
- 应该看到正确的 agent ID 和模型
92+
93+
## 🔍 故障排查
94+
95+
### 问题：提示"未配置"
96+
97+
**原因**：当前会话已绑定到 main-agent
98+
99+
**解决**：
100+
```
101+
/reset
102+
/agent tech-agent
103+
```
104+
105+
### 问题：切换后还是旧 agent
106+
107+
**原因**：没有先 `/reset`
108+
109+
**解决**：
110+
```
111+
/reset
112+
/agent tech-agent
113+
/status
114+
```
115+
116+
### 问题：不确定当前 agent
117+
118+
**解决**：
119+
```
120+
/status
121+
```
122+
123+
查看输出中的 `Session:` 行，应该显示：
124+
```
125+
Session: agent:tech-agent:feishu:group:oc_xxx
126+
```
127+
128+
## ✅ 成功标志
129+
130+
切换成功后，`/status` 应该显示：
131+
132+
```
133+
🧵 Session: agent:tech-agent:feishu:group:oc_497bcc045e75228209e5030481a6fef7
134+
🧠 Model: local-antigravity/claude-sonnet-4-5-thinking
135+
```
136+
137+
注意 Session 中的 agent ID 应该是 `tech-agent` 而不是 `main-agent`。
138+
139+
## 🎉 开始使用
140+
141+
现在请在每个飞书群组中执行：
142+
143+
1. `/reset`
144+
2. `/agent <agent-id>`
145+
3. `/status` （验证）
146+
4. 发送测试消息
147+
148+
---
149+
150+
## 📊 Agent 对应关系
151+
152+
| 群组 | Agent ID | 模型 | 特点 |
153+
|------|----------|------|------|
154+
| 助理群 | main-agent | claude-opus-4-6-thinking | 最强推理 |
155+
| 内容创作群 | content-agent | claude-sonnet-4-5 | 擅长创作 |
156+
| 技术开发群 | tech-agent | claude-sonnet-4-5-thinking | 技术专家 |
157+
| AI 资讯群 | ainews-agent | gemini-2.5-flash | 快速响应 |
158+
159+
---
160+
161+
**配置完成！`/agent` 命令是可以工作的，只需要先 `/reset` 清除旧会话。** 🎉

0 commit comments

Comments
 (0)