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

安装完后，运行引导向导：

openclaw onboard --install-daemon

向导会引导你配置：

1. AI 模型密钥 — 输入你的 Anthropic / OpenAI / Google API Key
2. Gateway 设置 — 默认端口 18789，一般不用改
3. 聊天渠道 — 这里先跳过，我们后面单独配飞书

💡 --install-daemon 参数会把 Gateway 安装为系统服务，开机自动启动。

配置完后检查 Gateway 状态：

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，用你的飞书账号登录。

⚠️ 如果你用的是 Lark（国际版），地址是 https://open.larksuite.com/app。

Step 2：创建企业自建应用

1. 点击「创建企业自建应用」
2. 填写应用名称（比如'我的 AI 助手'）
3. 填写应用描述
4. 选一个图标

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：开启机器人能力

进入「应用能力」→「机器人」：

1. 开启机器人能力
2. 设置机器人名称

Step 6：配置事件订阅（⚠️ 这步容易翻车！）

进入「事件与回调」：

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

🚨 大坑警告：一定要选「长连接」而不是「Webhook」！长连接不需要公网 IP，不需要域名，不需要配置 HTTPS，对个人开发者友好得多。配置事件订阅之前，OpenClaw Gateway 必须在运行！ 否则飞书检测不到长连接端，可能导致保存失败。先跑 openclaw gateway status 确认 Gateway 在线，再来配这一步。

Step 7：发布应用

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

⚠️ 不发布 = 不生效！ 很多人配完权限和机器人就以为搞定了，结果发消息没反应——因为应用还没发布。

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 连接。

解决：

# 先确保 Gateway 在跑
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：配对码（Pairing）一直等不到

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

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

解决：

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

坑 6：Node.js 版本太低

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

原因：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 回复 = 全部搞定

进阶：常用命令速查

在飞书里可以发的命令

OpenClaw + 飞书机器人的配置确实有不少坑，但只要按照本文的流程走，应该能少走很多弯路。核心要记住的就是：

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

如有版本差异请以官方文档为准：https://docs.openclaw.ai