OpenClaw 多飞书机器人与多 Agent 团队实战复盘
这次实践完整记录了一次从单机安装到多机器人协作落地的真实过程，涵盖了 Windows 环境下的安装报错、Gateway 连通性调试、模型切换策略、Feishu 配对流程，以及最终构建'产品 - 开发 - 测试 - 评审 - 文档 - 运维'的自动化团队。
一、目标与结果
这次实践的目标很明确：在 Windows 上稳定跑通 OpenClaw，接入飞书机器人，实现一个机器人对应一个 Agent 角色，支持多模型并行（OpenAI + Ollama），最终形成可执行的多 Agent 团队。
落地状态已验证：
- 渠道：Feishu 多账号在线
- 路由：按 accountId 精确绑定到对应 Agent
- 角色：产品经理、技术开发、测试质保、代码评审、文档维护、发布运维
- 模型：默认 openai-codex/gpt-5.2，文档 Agent 使用 ollama/gpt-oss:20b-cloud
二、第一阶段：跨系统安装与 Gateway 排障
1. 从零安装 OpenClaw（Windows / macOS / Linux）
Step 1. 环境前置检查 先确认 Node 和 npm 版本是否达标。建议 Node.js >= 22，npm >= 10。如果版本过低，请先升级再安装 OpenClaw。
node -v && npm -v
Step 2. 按系统执行安装命令 macOS / Linux：
curl -fsSL https://openclaw.ai/install.sh | bash
Windows（PowerShell）：
iwr -useb https://openclaw.ai/install.ps1 | iex
安装完成后统一验证版本号，如返回 2026.x.x 即通过。
openclaw --version
Step 3. 首次初始化（推荐） 运行 onboard 向导完成三件事：选择模型供应商、完成认证（API Key 或 OAuth）、写入本地配置。
openclaw onboard --install-daemon
Step 4. 安装后健康检查 依次执行 doctor、status、health 等命令。重点看 gateway probe 是否显示 Reachable: yes，本地网关目标通常是 ws://127.0.0.1:18789。
openclaw doctor
openclaw status
openclaw health
openclaw gateway status
openclaw gateway probe
Step 5. 最小可用调用测试 发送一条测试消息，确保能返回 JSON 且无致命报错。
openclaw agent --agent main -m "你好，请回复：安装连通通过" --json
Step 6. 解决 openclaw 命令找不到（PATH） 如果提示 command not found，需将 npm 全局 bin 目录加入 PATH。
macOS / Linux：
export PATH="$PATH:$(npm prefix -g)/bin"
Windows（PowerShell）：
$env:Path += ";$(npm prefix -g)"
Step 7. 打开控制台确认运行态 默认地址一般为 http://127.0.0.1:18789/。
openclaw dashboard
Step 8. 接入 Feishu（安装后马上做）
- 安装插件：
openclaw plugins install @openclaw/feishu
- 添加渠道：填入飞书开放平台的 App ID 与 App Secret。
openclaw channels add
- 重启并检查网关：
openclaw gateway restart
openclaw gateway status
openclaw logs --follow
- 首次私聊机器人后完成配对：
openclaw pairing list feishu --json
openclaw pairing approve feishu <配对码>
到这一步，OpenClaw 的'安装 + 网关 + 渠道 + 配对'闭环才算完整。
2. 常见报错处理
安装报错：npm error code 1 首次运行安装脚本时可能会报 npm error code 1。经验是不要慌，继续查看日志，只要最终版本可查询（如 openclaw --version 返回 2026.2.24），说明安装成功。中间警告有时可以忽略。
Gateway 状态异常：Scheduled Task (missing) + RPC 失败 现象是 gateway status 显示服务缺失，probe 报 1006 或 RPC 失败。尝试前台启动确认服务本体：
openclaw gateway run --verbose
观察到 listening on ws://127.0.0.1:18789 后，说明主进程正常。
Windows 下 --force 报 lsof not found Windows 没有 lsof 工具，遇到 Force: Error: lsof not found 时，直接去掉 --force 参数即可。
openclaw gateway run --verbose
三、第二阶段：模型连通与会话参数问题
Agent 命令缺少会话选择参数 直接运行 agent 命令可能会报错，提示必须提供会话定位参数。修复方式是加上 --agent 标识。
openclaw agent --agent main -m "你好，请回复：连通测试通过" --json
网关失败但回退 embedded 成功 你会看到这类提示：Gateway agent failed; falling back to embedded。这不等于请求失败，关键看最终 JSON 是否 status: ok。
四、第三阶段：Feishu 集成与配对机制
常见首次消息 飞书首次私聊机器人时常见返回 access not configured，并给出 Pairing code。
审批命令实践 通用审批方式：
openclaw pairing approve feishu <配对码>
按账号审批方式：
openclaw pairing approve --channel feishu --account <accountId> <配对码>
实践中要注意，某些请求在全局队列里可见，但在 --account 过滤下为空。最稳妥做法是配合检查 pending 列表：
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。这样做的好处是成本可控、任务与模型能力匹配更清晰、故障隔离更好。
七、踩坑重点：为什么机器人会'自称错角色'
实际出现过：在终端 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 才真正从'会聊天'进入'可协作生产'的阶段。