feishu-multi-agent — 飞书多 Agent 编排实战指南
从 0 到 1 搭建一个包工头 + N 个下属 agent 的自动化团队，通过飞书与用户交互，文件驱动任务分发，cron 驱动持续工作。
本技能总结了在生产环境中运行 7 个飞书 agent（包工头 + 游戏工厂 + 龙虾出版社 + 小秘虾妹 + 炒币哥 + 炒股姐 + Agent猎头）的全部经验，涵盖架构设计、沙箱踩坑、任务队列、cron 编排、故障排查。
适用场景
- - 用 OpenClaw 管理多个 AI agent，每个 agent 绑定一个飞书 bot
- 需要一个"包工头"agent 自动给其他 agent 派活
- 希望 agent 持续工作（不是做一件事就停）
- 需要文件驱动的任务队列（而非纯消息驱动）
架构总览
CODEBLOCK0
核心概念
| 概念 | 说明 |
|---|
| 包工头 | 只管人不干活，通过文件派活 + openclaw agent 催活 |
| 任务队列 |
每个下属 workspace 下
tasks/pending/ +
tasks/done/ |
| 持续工作 | cron 高频触发 + HEARTBEAT.md 指示"做完一件做下一件" |
| 沙箱限制 | Write 工具只能写 workspace 内，跨 workspace 必须用 bash |
Step 1: 飞书应用准备
每个 agent 需要一个独立的飞书自建应用（bot）。参考 feishu-app-setup 技能完成：
- 1. 在 open.feishu.cn 创建 N 个企业自建应用
- 每个应用添加机器人能力 + 批量导入权限
- 配置事件订阅（WebSocket 长连接）
- 发布上线
批量创建技巧：用 agent-browser --cdp-endpoint 连接已登录浏览器，循环创建+配置，免重复登录。
Step 2: OpenClaw 多账号配置
CODEBLOCK1
Agent 列表配置
CODEBLOCK2
配置后重启 Gateway：
CODEBLOCK3
首次对话需配对：
CODEBLOCK4
Step 3: 创建任务队列目录
CODEBLOCK5
任务文件格式
INLINECODE5 ：
CODEBLOCK6
完成后 agent 把文件从 pending/ 移到 done/。
Step 4: 配置包工头 SOUL.md
文件: INLINECODE8
关键内容：
CODEBLOCK7
Step 5: 配置下属 HEARTBEAT.md
游戏工厂（buyer）
CODEBLOCK8
龙虾出版社（kb）
CODEBLOCK9
小秘虾妹（gf）
CODEBLOCK10
Step 6: 配置 Cron Jobs
包工头巡查（每 30 分钟）
CODEBLOCK11
注意：--session main 的 job 必须用 --system-event，不能用 --message！
包工头汇报（每 4 小时）
CODEBLOCK12
游戏工厂持续开发（每 20 分钟）
CODEBLOCK13
小秘虾妹互动（每 2 小时）
CODEBLOCK14
Cron 管理
CODEBLOCK15
⚠️ 关键踩坑与解决方案
坑 1: Write 工具受 workspace 沙箱限制
症状: INLINECODE12
原因: OpenClaw 的 Write/Read 工具使用 fs.realpath() 解析路径，严格限制在 workspace 目录内。Symlink 也无效（会被 realpath 解析为真实路径）。
解决方案:
| 场景 | 解决方案 |
|---|
| Agent 需要写 workspace 外的目录 | 把目录移进 workspace，原位置留 symlink |
| 包工头写其他 agent 的 workspace |
用 bash
cat > file 而非 Write 工具 |
| Agent 需要读其他 workspace | 用 bash
cat file 或
ls dir |
示例：buyer 需要写 ~/game-factory/：
CODEBLOCK16
坑 2: --session main 必须用 --system-event
症状: INLINECODE20
原因: main session 的 cron job 只接受 --system-event，不接受 --message。--message 仅用于 --session isolated。
对比:
CODEBLOCK17
坑 3: 飞书 WebSocket 静默断连
症状: Agent 不再收到飞书消息，但 gateway 进程仍在运行。日志中最后一条飞书消息后无新消息。
诊断:
CODEBLOCK18
解决: 重启 gateway 重新连接：
CODEBLOCK19
验证:
CODEBLOCK20
坑 4: 飞书消息发太快导致 replies=0
症状: dispatch complete 显示 queuedFinal=false, replies=0，部分消息无回复。
原因: 用户在 5 秒内连续发多条消息，后面的消息被跳过（skipping duplicate message）或模型来不及处理。
缓解: 发消息后等几秒再发下一条。这是飞书 WebSocket SDK 的去重机制。
坑 5: Cron job 触发时 session 正忙
症状: openclaw cron run 返回 INLINECODE28
原因: 目标 session 正在处理其他请求，cron job 排队等待。
这是正常行为，job 会在 session 空闲后自动执行。不需要重试。
坑 6: Agent 上下文溢出
症状: Agent 回复质量下降或不回复。openclaw sessions 显示 context 使用率 > 70%。
诊断:
CODEBLOCK21
解决: 让 agent 开新 session。对于 cron job，使用 --session isolated 每次启动新上下文。对于 main session，可能需要手动清理。
坑 7: failed to obtain token 连续报错
症状: gateway.err.log 中大量 failed to obtain token 警告。
原因: 某个 model provider 的 OAuth token 过期或失效。
解决: 检查 auth-profiles.json 中哪个 provider 有问题，重新认证：
openclaw auth login <provider>
运维 Checklist
每日检查
CODEBLOCK23
故障快速恢复
CODEBLOCK24
工作流总结
CODEBLOCK25
依赖
- - OpenClaw Gateway (运行中，带飞书 WebSocket 连接)
- INLINECODE33 技能（用于创建飞书应用）
- INLINECODE34 技能（可选，用于批量飞书应用配置）
- 飞书企业管理员权限
License
MIT
feishu-multi-agent — 飞书多 Agent 编排实战指南
从 0 到 1 搭建一个包工头 + N 个下属 agent 的自动化团队，通过飞书与用户交互，文件驱动任务分发，cron 驱动持续工作。
本技能总结了在生产环境中运行 7 个飞书 agent（包工头 + 游戏工厂 + 龙虾出版社 + 小秘虾妹 + 炒币哥 + 炒股姐 + Agent猎头）的全部经验，涵盖架构设计、沙箱踩坑、任务队列、cron 编排、故障排查。
适用场景
- - 用 OpenClaw 管理多个 AI agent，每个 agent 绑定一个飞书 bot
- 需要一个包工头agent 自动给其他 agent 派活
- 希望 agent 持续工作（不是做一件事就停）
- 需要文件驱动的任务队列（而非纯消息驱动）
架构总览
用户 ──飞书──→ 包工头(main) ──任务文件──→ buyer / kb / gf
│ ↑
│ cron 触发心跳
└── cron 巡查 ──检查状态──┘
不受包工头管理的 agent（用户直接控制）:
coach / travel / edu
核心概念
| 概念 | 说明 |
|---|
| 包工头 | 只管人不干活，通过文件派活 + openclaw agent 催活 |
| 任务队列 |
每个下属 workspace 下 tasks/pending/ + tasks/done/ |
| 持续工作 | cron 高频触发 + HEARTBEAT.md 指示做完一件做下一件 |
| 沙箱限制 | Write 工具只能写 workspace 内，跨 workspace 必须用 bash |
Step 1: 飞书应用准备
每个 agent 需要一个独立的飞书自建应用（bot）。参考 feishu-app-setup 技能完成：
- 1. 在 open.feishu.cn 创建 N 个企业自建应用
- 每个应用添加机器人能力 + 批量导入权限
- 配置事件订阅（WebSocket 长连接）
- 发布上线
批量创建技巧：用 agent-browser --cdp-endpoint 连接已登录浏览器，循环创建+配置，免重复登录。
Step 2: OpenClaw 多账号配置
json
{
channels: {
feishu: {
enabled: true,
accounts: {
main: { appId: cliaaa, appSecret: secretaaa, name: 包工头 },
buyer: { appId: clibbb, appSecret: secretbbb, name: 游戏工厂 },
kb: { appId: cliccc, appSecret: secretccc, name: 龙虾出版社 },
gf: { appId: cliddd, appSecret: secretddd, name: 小秘虾妹 }
}
}
},
bindings: [
{ agentId: main, match: { channel: feishu, accountId: main } },
{ agentId: buyer, match: { channel: feishu, accountId: buyer } },
{ agentId: kb, match: { channel: feishu, accountId: kb } },
{ agentId: gf, match: { channel: feishu, accountId: gf } }
]
}
Agent 列表配置
json
{
agents: {
list: [
{ id: main, name: main, workspace: ~/.openclaw/workspace },
{ id: buyer, name: buyer, workspace: ~/.openclaw/workspace-buyer },
{ id: kb, name: kb, workspace: ~/.openclaw/workspace-kb },
{ id: gf, name: gf, workspace: ~/.openclaw/workspace-gf }
]
}
}
配置后重启 Gateway：
bash
launchctl stop ai.openclaw.gateway && sleep 3 && launchctl start ai.openclaw.gateway
首次对话需配对：
bash
openclaw pairing approve feishu <配对码>
Step 3: 创建任务队列目录
bash
为每个受管 agent 创建任务目录
mkdir -p ~/.openclaw/workspace-buyer/tasks/{pending,done}
mkdir -p ~/.openclaw/workspace-kb/tasks/{pending,done}
mkdir -p ~/.openclaw/workspace-gf/tasks/{pending,done}
任务文件格式
tasks/pending/001-task-name.md：
markdown
任务标题
优先级: 高/中/低
下达时间: 2026-03-01 10:00
描述: 具体要做什么
完成后 agent 把文件从 pending/ 移到 done/。
Step 4: 配置包工头 SOUL.md
文件: ~/.openclaw/workspace/SOUL.md
关键内容：
markdown
包工头（监工/调度中心）
管辖范围
| Agent | 角色 |
|---|
| buyer | 持续开发 HTML5 教育游戏 |
| kb |
深度研究 + 写书 |
| gf | 陪聊互动 + 内容推荐 |
不归你管的 agent：coach、travel、edu
巡查方式
- - openclaw sessions --agent --active 60 检查活动
- ls ~/.openclaw/workspace-/tasks/pending/ 检查任务队列
⚠️ 派活方式（重要）
必须用 bash 命令写任务文件，不要用 Write 工具！
cat > ~/.openclaw/workspace-buyer/tasks/pending/003-xxx.md << EOF
# 任务标题
优先级: 中
描述: ...
EOF
踢屁股
openclaw agent --agent
--message 检查 tasks/pending，有活就干
Step 5: 配置下属 HEARTBEAT.md
游戏工厂（buyer）
markdown
工作循环
- 1. 检查 tasks/pending/，有任务就做第一个（按文件名排序）
- 执行任务（cd game-factory && git pull → 开发 → commit && push）
- 完成后移到 tasks/done/
- 再检查 pending，有就继续
- 没有待办时自主开发新游戏
- 不要停，保持持续产出
龙虾出版社（kb）
markdown
工作循环
- 1. 检查 tasks/pending/，有任务就执行
- 新话题 → 生成大纲 → 逐章写作
- 催进度 → 继续上次未完成的章节
- 完成后移到 tasks/done/
- 有进行中的项目就主动往前写
小秘虾妹（gf）
markdown
Heartbeat
先检查待办
查看 tasks/pending/，有任务优先做，完成后移到 tasks/done/
无待办时随机做一件事
- 1. 分享一首歌
- 推荐有趣的东西
- 分享趣闻
- 发一张自拍
- 随便聊聊
Step 6: 配置 Cron Jobs
包工头巡查（每 30 分钟）
bash
openclaw cron add \
--name foreman-patrol \
--every 30m \
--agent main \
--session main \
--timeout-seconds 300 \
--thinking low \
--system-event 执行巡查。检查 buyer/kb/gf 状态和任务队列，为空闲的下属派新任务。
注意：--session main 的 job 必须用 --system-event，不能用 --message！
包工头汇报（每 4 小时）
bash
openclaw cron add \
--name foreman-report \
--every 4h \
--agent main \
--session main \
--timeout-seconds 300 \
--thinking low \
--system-event 向老板汇报。统计 buyer/kb/gf 过去 4 小时的产出和状态。
游戏工厂持续开发（每 20
