OpenClaw 安装与飞书机器人配置实战指南

配置完成后检查状态：

openclaw gateway status

若显示 running，基础安装即完成。此时可通过 Web UI 聊天：

openclaw dashboard

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

飞书机器人配置全流程

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

5.1 安装飞书插件

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

openclaw plugins install @openclaw/feishu

安装完后重启 Gateway：

openclaw gateway restart

5.2 飞书开放平台：创建应用

Step 1：登录飞书开放平台

打开 https://open.feishu.cn/app，使用飞书账号登录。（国际版地址为 https://open.larksuite.com/app）

Step 2：创建企业自建应用

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

Step 3：获取凭证

进入「凭证与基础信息」页面，复制 App ID（格式：cli_xxxxxxxxx）和 App Secret。

🔐 App Secret 务必妥善保管，切勿泄露或提交到 Git。

Step 4：配置权限

进入「权限管理」，点击「批量开通」，粘贴以下 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 等权限。

Step 5：开启机器人能力

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

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

进入「事件与回调」：

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

🚨 避坑提示：一定要选「长连接」而不是「Webhook」。长连接不需要公网 IP 和域名，对个人开发者更友好。配置前必须确保 OpenClaw Gateway 正在运行，否则飞书检测不到 WebSocket 连接可能导致保存失败。先执行 openclaw gateway status 确认在线后再配。

Step 7：发布应用

进入「版本管理与发布」，创建版本并提交审核。企业自建应用通常秒批。

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

5.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

5.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
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 回复 = 全部搞定

进阶：常用命令速查

飞书内可用命令

搭建本地 AI 助手的关键在于顺序：先装插件，后配飞书；先跑 Gateway，后配事件订阅；配完权限别忘了发布应用。遇到问题优先看日志 openclaw logs --follow。