OpenClaw 多飞书机器人与多 Agent 团队协作实践

OpenClaw 多飞书机器人与多 Agent 团队协作实践 | 极客日志

OpenClaw 多飞书机器人与多 Agent 团队实战复盘

在这里插入图片描述

这篇文章完整记录一次从单机安装到多机器人协作落地的真实过程：包括 Windows 安装报错、Gateway 连通、模型切换、Feishu 配对、多 Agent 路由、身份错位修复，以及最终形成'产品 - 开发 - 测试 - 评审 - 文档 - 运维'团队。

一、目标与结果

这次实践的目标很明确：

在 Windows 上稳定跑通 OpenClaw
接入飞书机器人
做到一个机器人对应一个 Agent 角色
支持多模型并行（OpenAI + Ollama）
最终形成可执行的多 Agent 团队

最终落地状态（已验证）：

渠道：Feishu 多账号在线
路由：按 accountId 精确绑定到对应 Agent
角色：产品经理、技术开发、测试质保、代码评审、文档维护、发布运维
模型：默认 openai-codex/gpt-5.2，文档 Agent 使用 ollama/gpt-oss:20b-cloud

二、第一阶段：跨系统安装与 Gateway 排障

这一段改成'可直接复现'的跨系统安装手册，覆盖 Windows、macOS、Linux。同时把 Feishu 接入步骤也接在安装闭环后，避免'装好了但渠道跑不起来'。

0) 从零安装 OpenClaw（Windows / macOS / Linux）

Step 1. 环境前置检查

先确认 Node 和 npm：

node -v && npm -v

建议：

Node.js >= 22
npm >= 10

如果版本过低，先升级再安装 OpenClaw。

Step 2. 按系统执行安装命令

macOS / Linux：

curl -fsSL https://openclaw.ai/install.sh | bash

Windows（PowerShell）：

iwr -useb https://openclaw.ai/install.ps1 | iex

安装完成后统一验证：

openclaw --version

通过标准：能返回版本号（如 2026.x.x）。

Step 3. 首次初始化（推荐）

openclaw onboard --install-daemon

在向导里完成三件事：

选择模型供应商（OpenAI / OpenAI-Codex / Ollama 等）
完成认证（API Key 或 OAuth）
写入本地配置

Step 4. 安装后健康检查

openclaw doctor
openclaw status
openclaw health
openclaw gateway status
openclaw gateway probe

通过标准：

doctor 无致命错误
gateway probe 出现 Reachable: yes
本地网关目标通常是 ws://127.0.0.1:18789

Step 5. 最小可用调用测试

openclaw agent --agent main -m "你好，请回复：安装连通通过" --json

通过标准：

命令返回 JSON
无致命报错（即使出现 gateway fallback，也要看最终是否成功返回）

Step 6. 解决 `openclaw` 命令找不到（PATH）

先诊断：

macOS / Linux：

npm prefix -g && echo "$PATH"

Windows（PowerShell）：

npm prefix -g; $env:Path

修复原则：

macOS / Linux：把 $(npm prefix -g)/bin 加入 PATH
Windows：把 npm prefix -g 输出目录加入系统 PATH

Step 7. 打开控制台确认运行态

openclaw dashboard

默认地址一般为：

http://127.0.0.1:18789/

Step 8. 接入 Feishu（安装后马上做）

安装 Feishu 插件：

openclaw plugins install @openclaw/feishu

添加 Feishu 渠道：

openclaw channels add

按提示选择 Feishu，填入飞书开放平台里的 App ID 与 App Secret。

重启并检查网关：

openclaw gateway restart
openclaw gateway status
openclaw logs --follow

首次私聊机器人后完成配对：

openclaw pairing list feishu --json
openclaw pairing approve feishu <配对码>

到这一步，OpenClaw 的'安装 + 网关 + 渠道 + 配对'闭环才算完整。

1) 安装报错：`npm error code 1`

安装命令：

iwr -useb https://openclaw.ai/install.ps1 | iex

首次报错表现为 npm error code 1。继续查看日志后，安装最终成功，版本可用：

openclaw --version # 2026.2.24

经验：安装阶段先看'最终版本是否可查询'，不要被中间 warning 直接误导。

2) Gateway 状态异常：`Scheduled Task (missing)` + RPC 失败

典型现象：

openclaw gateway status 显示服务缺失
openclaw gateway probe 报 1006 或 RPC 失败

后续通过前台启动确认服务本体可运行：

openclaw gateway run --verbose

观察到 listening on ws://127.0.0.1:18789 后，说明 Gateway 主进程正常。

3) Windows 下 `--force` 报 `lsof not found`

命令：

openclaw gateway run --force --verbose

报错：

Force: Error: lsof not found; required for --force

这是平台差异问题。Windows 无 lsof 时，直接不用 --force，改用：

openclaw gateway run --verbose

三、第二阶段：模型连通与会话参数问题

1) Agent 命令缺少会话选择参数

命令：

openclaw agent -m "你好，做一次连通性自检并简短回复" --json

报错提示要求必须提供会话定位参数。修复方式：

openclaw agent --agent main -m "你好，请回复：连通测试通过" --json

2) 网关失败但回退 embedded 成功

你会看到这类提示：

Gateway agent failed; falling back to embedded

这不等于请求失败。关键看最终 JSON 是否 status: ok。

四、第三阶段：Feishu 集成与配对机制

1) 常见首次消息

飞书首次私聊机器人时常见返回：

OpenClaw: access not configured. Your Feishu user id: ou_xxx Pairing code: XXXXXXXX Ask the bot owner to approve with: openclaw pairing approve feishu XXXXXXXX

2) 审批命令实践

通用审批方式：

openclaw pairing approve feishu <配对码>

按账号审批方式：

openclaw pairing approve --channel feishu --account <accountId> <配对码>

实践中的关键细节：

某些请求在全局 feishu 队列里可见，但在 --account 过滤下为空
出现 No pending pairing request found 不一定是失败，可能是配对码已被消费
最稳妥做法是配合检查：

openclaw pairing list feishu --json

五、第四阶段：多机器人 + 多 Agent 团队搭建

我们最终搭建了 6 个飞书机器人角色，并做了账号到 Agent 的一一绑定。

1) 角色设计

总控（产品经理）
技术开发
测试质保
代码评审（架构把关）
文档与知识库维护
发布运维

2) 路由原则

核心不是'一个默认 Agent'，而是'按渠道账号精确路由'：

{"agentId":"pm-agent","match":{"channel":"feishu","accountId":"pm"}}

同理分别配置 dev / qa / review / docs / ops 对应各自 Agent。

3) 结果验证命令

openclaw channels status --json --probe
openclaw config get bindings --json
openclaw agents list --json

验证标准：

所有目标账号 probe.ok = true
bindings 包含每个 accountId -> agentId
各 Agent 可独立响应

六、第五阶段：模型分工与'专用 Agent'策略

1) 默认模型策略

团队主体使用：

openai-codex/gpt-5.2

2) 单独模型策略（文档 Agent）

文档机器人专门使用：

ollama/gpt-oss:20b-cloud

即把'模型选择'从全局配置下沉到具体 Agent。这样做的好处：

成本可控
任务与模型能力匹配更清晰
故障隔离更好（某个 provider 出问题，不拖垮全部机器人）

七、踩坑重点：为什么机器人会'自称错角色'

实际出现过：在终端 pm-agent 自测正常，但飞书里却回答成'默认小爪'。

排查后发现核心原因通常有两类：

路由没命中目标 Agent，实际走到了 main
Agent 身份文件是模板，未完成角色固化

修复动作

看渠道日志中的 dispatching to agent (session=...)
校验 bindings 是否确实匹配 channel + accountId
在该 Agent 工作区写明 IDENTITY.md
在 AGENTS.md 加'身份锁定规则'
必要时重启 Gateway，清旧进程缓存

八、当前可复用的团队运维命令

1) 服务与连通

openclaw gateway start
openclaw gateway status
openclaw gateway probe
openclaw channels status --json --probe

2) Agent 调试

openclaw agent --agent pm-agent -m "你是谁？只回复名称。"
openclaw agent --agent dev-agent -m "你是谁？只回复名称。"
openclaw agent --agent review-agent -m "你是谁？只回复名称。"

3) 配对与审批

openclaw pairing list feishu --json
openclaw pairing approve feishu <配对码>
openclaw pairing approve --channel feishu --account ops <配对码>

4) 启停

openclaw gateway stop
openclaw gateway restart

九、落地建议（给准备搭团队的人）

先做单机器人闭环，再扩成多机器人
每加一个机器人就立刻做'配对 + 路由 + 身份自检'
不要把'身份定义'只放在口头约定，必须写入工作区文件
把日志检查变成固定动作：status -> probe -> logs -> bindings
模型策略按角色拆分，不要盲目全员同模型

十、结语

这次实践最大的收获不是'把机器人接上了'，而是把整套方法跑通了：

能安装
能排障
能路由
能分工
能稳定运营

当你把'渠道账号、Agent 角色、模型策略、身份文件、日志验证'这 5 件事统一起来，OpenClaw 才真正从'会聊天'进入'可协作生产'的阶段。