OpenClaw 安装与飞书机器人配置全流程及避坑指南

openclaw dashboard

浏览器会自动打开 http://127.0.0.1:18789，这是 OpenClaw 的控制面板。

飞书机器人配置全流程

飞书配置分三步：飞书侧建应用 → OpenClaw 侧配置 → 联调测试。

1. 安装飞书插件

OpenClaw 的飞书支持通过插件提供，先安装：

openclaw plugins install @openclaw/feishu

安装完重启 Gateway：

openclaw gateway restart

2. 飞书开放平台：创建应用

登录平台

打开 https://open.feishu.cn/app，用飞书账号登录。

创建企业自建应用

1. 点击「创建企业自建应用」
2. 填写应用名称（如'我的 AI 助手'）、描述和图标

获取凭证

进入「凭证与基础信息」页面，复制：

• App ID（格式：cli_xxxxxxxxx）
• App Secret

*注意：App Secret 务必妥善保管，不要泄露或提交到 Git。

配置权限

进入「权限管理」，点击「批量开通」，粘贴以下 JSON：

{"scopes":{"tenant":["im:message","im:message.group_at_msg:readonly","im:message.p2p_msg:readonly","im:message:readonly","im:message:send_as_bot","im:resource","im:chat.access_event.bot_p2p_chat:read","im:chat.members:bot_access","contact:user.employee_id:readonly"],"user":["im:chat.access_event.bot_p2p_chat:read"]}}

这是基本权限集。如需操作文档或多维表格，可追加 docx:document、bitable:app 等。

开启机器人能力

进入「应用能力」→「机器人」，开启能力并设置名称。

配置事件订阅（⚠️ 关键步骤）

进入「事件与回调」：

1. 选择「使用长连接接收事件」（WebSocket 方式）
2. 添加事件：搜索并勾选 im.message.receive_v1

*大坑警告：一定要选「长连接」而不是「Webhook」。长连接不需要公网 IP 和域名，对个人开发者更友好。配置前确保 OpenClaw Gateway 已在运行，否则飞书检测不到 WebSocket 端点，可能导致保存失败。

发布应用

1. 进入「版本管理与发布」
2. 创建版本并提交审核
3. 等待管理员审批（企业自建应用通常秒批）

*不发布 = 不生效！很多人配完权限就以为搞定，结果发消息没反应。

3. OpenClaw 侧配置

方式一：交互式向导（推荐）

openclaw channels add

选择 Feishu，按提示输入 App ID 和 App Secret。

方式二：手动编辑配置文件

编辑 ~/.openclaw/openclaw.json，添加飞书配置：

{"channels":{"feishu":{"enabled":true,"dmPolicy":"pairing","accounts":{"main":{"appId":"cli_xxxxxxxxx","appSecret":"你的 AppSecret"}}}}}

配置完重启 Gateway：

openclaw gateway restart

4. 首次联调

1. 在飞书里找到机器人，发一条消息（如'你好'）
2. 机器人回复一个 配对码（Pairing Code）
3. 终端执行配对确认：

openclaw pairing approve feishu <配对码>

4. 配对成功后再次发消息，AI 即可正常回复。

踩坑实录 & 避坑指南

以下是实际配置中常见的问题及排查思路。

坑 1：事件订阅保存失败

现象：飞书平台配置长连接事件时，点保存无反应或报错。

原因：OpenClaw Gateway 未运行，飞书检测不到 WebSocket 连接。

解决：

openclaw gateway start
openclaw gateway status # 确认是 running
# 然后再去飞书平台配置事件订阅

坑 2：机器人不回复消息

现象：飞书发消息，机器人无响应。

排查清单：

1. 应用有没有 发布？（最常见原因）
2. 事件订阅里有没有添加 im.message.receive_v1？
3. 是否选择了「长连接」方式？
4. 权限是否全部开通？
5. Gateway 是否在运行？

实时查看日志观察输出：

openclaw logs --follow

坑 3：群聊里机器人不回复

现象：私聊正常，群聊里@机器人没反应。

原因：默认配置下，群聊需要@mention 机器人才会响应。且机器人必须被添加到群里。

解决：

1. 确认机器人已加入群聊
2. 发消息时@机器人
3. 如果想不@也能回复，修改配置：

{"channels":{"feishu":{"groups":{"oc_你的群 ID":{"requireMention":false}}}}}

群 ID 怎么获取？启动 Gateway 后在群里@机器人，然后 openclaw logs --follow 里找 chat_id。

坑 4：权限不足导致报错

现象：消息发送失败、无法读取文件、操作飞书文档报错。

原因：飞书权限细粒度，缺什么报什么错。

解决：回到飞书开放平台 → 权限管理，按需补充。常用权限如下：

*添加新权限后，需要重新发布应用版本才能生效！

坑 5：配对码一直等不到

现象：发消息后机器人没有回复配对码。

原因：Gateway 没有成功连接飞书 WebSocket。

解决：查看详细日志 openclaw logs --follow，看有没有 feishu 连接成功的日志。如果有 error，根据错误信息排查（通常是 App ID/Secret 填错了）。

坑 6：Node.js 版本太低

现象：安装报错，或启动后各种奇怪问题。

原因：OpenClaw 要求 Node.js 22+，很多系统默认装的是 18 或 20。

解决：

node --version # 检查版本
nvm install 22 # 升级到 22
nvm use 22
openclaw gateway restart # 重启

验证一切正常

跑完流程后，用这个清单逐项确认：

# 1. OpenClaw 安装正常
openclaw --version
# 2. Gateway 在运行
openclaw gateway status
# 3. 飞书插件已安装
openclaw plugins list # 应该能看到 @openclaw/feishu
# 4. 飞书连接正常
openclaw status # 应该显示 feishu: connected
# 5. 在飞书里发一条消息测试
# → 收到 AI 回复 = 全部搞定 ✅

进阶：常用命令速查

在飞书里可以发的命令

核心要点记住：

1. 先装插件，后配飞书
2. 先跑 Gateway，后配事件订阅
3. 配完权限，别忘了发布应用
4. 有问题先看日志：openclaw logs --follow