OpenClaw AI Agent 框架的安装与飞书机器人配置流程。涵盖环境准备（Node.js 22+）、一键安装命令、Gateway 启动验证、飞书开放平台应用创建及权限配置、长连接事件订阅设置、以及联调配对步骤。包含常见故障排查指南，如事件订阅保存失败、机器人无响应、群聊权限不足等问题解决方案，帮助开发者快速实现本地 AI 助手对接飞书。
OpenClaw 是一个开源的 AI Agent 框架，简单理解就是：它让你拥有一个私人 AI 助手，可以接入飞书、Telegram、WhatsApp、Discord 等各种聊天平台。
它的核心架构很简单：
你的消息 → 飞书/Telegram/... → OpenClaw Gateway → AI 模型 → 回复
为什么选 OpenClaw？
| 项目 | 要求 |
|---|---|
| 操作系统 | Linux / macOS / Windows (WSL2) |
| Node.js | v22 或更高 |
| 网络 | 能访问飞书开放平台 + AI API |
# 检查是否已安装
node --version
# 如果没有或版本太低，用 nvm 安装
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
提示：输入 node --version 后如果显示 v22.x.x，说明安装成功。
macOS / Linux：
curl -fsSL https://openclaw.ai/install.sh | bash
Windows (PowerShell)：
iwr -useb https://openclaw.ai/install.ps1 | iex
安装完成后验证：
openclaw --version
看到版本号（如 2026.3.2）就说明安装成功了。
如果一键脚本有问题，也可以用 npm 安装：
npm install -g openclaw
注意：如果遇到 EACCES: permission denied 错误，不要用 sudo npm install -g！正确做法是调整 npm 目录权限。
安装完后，运行引导向导：
openclaw onboard --install-daemon
向导会引导你配置：
提示：--install-daemon 参数会把 Gateway 安装为系统服务，开机自动启动。
配置完后检查 Gateway 状态：
openclaw gateway status
如果显示 running，基础安装就完成了。
此时你已经可以通过 Web UI 聊天了：
openclaw dashboard
浏览器会自动打开 http://127.0.0.1:18789，这就是 OpenClaw 的控制面板。
这是本文的重头戏。飞书机器人配置分 三大步：飞书侧建应用 → OpenClaw 侧配置 → 联调测试。
OpenClaw 的飞书支持是通过插件提供的，先安装：
openclaw plugins install @openclaw/feishu
安装完后重启 Gateway：
openclaw gateway restart
打开 https://open.feishu.cn/app，用你的飞书账号登录。
注意：如果你用的是 Lark（国际版），地址是 https://open.larksuite.com/app。
进入应用后，在 「凭证与基础信息」 页面，复制两个东西：
cli_xxxxxxxxx）安全提示：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 等）。
进入 「应用能力」→「机器人」：
进入 「事件与回调」：
im.message.receive_v1（接收消息 v1）警告：一定要选「长连接」而不是「Webhook」！长连接不需要公网 IP，不需要域名，不需要配置 HTTPS，对个人开发者友好得多。配置事件订阅之前，OpenClaw Gateway 必须在运行！ 否则飞书检测不到长连接端，可能导致保存失败。先跑 openclaw gateway status 确认 Gateway 在线，再来配这一步。
注意：不发布 = 不生效！很多人配完权限和机器人就以为搞定了，结果发消息没反应——因为应用还没发布。
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
openclaw pairing approve feishu <配对码>
以下是实际配置过程中遇到的常见问题及解决方案。
现象：在飞书开放平台配置长连接事件订阅时，点保存没反应或报错。
原因：OpenClaw Gateway 没有在运行，飞书检测不到 WebSocket 连接。
解决：
# 先确保 Gateway 在跑
openclaw gateway start
openclaw gateway status # 确认是 running
# 然后再去飞书平台配置事件订阅
现象：飞书里发消息，机器人完全没反应。
排查清单（按顺序检查）：
im.message.receive_v1？# 实时查看日志，发消息后观察输出
openclaw logs --follow
现象：私聊正常，群聊里 @机器人 没反应。
原因：默认配置下，群聊需要 @mention 机器人才会响应。而且机器人必须被 添加到群里。
解决：
{"channels":{"feishu":{"groups":{"oc_你的群 ID":{"requireMention":false}}}}}
提示：群 ID 怎么获取？启动 Gateway 后在群里 @机器人，然后 openclaw logs --follow 里找 chat_id。
现象：消息发送失败、无法读取文件、操作飞书文档报错。
原因：飞书权限是细粒度的，缺什么权限就报什么错。
解决：回到飞书开放平台 → 权限管理，按需补充权限。常用的：
| 场景 | 需要的权限 |
|---|---|
| 收发消息 | im:message, im:message:send_as_bot |
| 读取群消息 | im:message.group_at_msg:readonly |
| 操作文档 | docx:document, docx:document:readonly |
| 操作多维表格 | bitable:app |
| 云盘操作 | drive:drive, drive:file |
注意：添加新权限后，需要 重新发布应用版本 才能生效！
现象：发消息后机器人没有回复配对码。
原因：Gateway 没有成功连接飞书 WebSocket。
解决：
# 查看详细日志
openclaw logs --follow
# 看看有没有 feishu 连接成功的日志
# 如果有 error，根据错误信息排查（通常是 App ID/Secret 填错了）
现象：安装 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 gateway status | 查看 Gateway 状态 |
openclaw gateway restart | 重启 Gateway |
openclaw logs --follow | 实时查看日志 |
openclaw channels add | 添加聊天渠道 |
openclaw pairing list feishu | 查看飞书配对请求 |
openclaw pairing approve feishu <CODE> | 确认配对 |
openclaw dashboard | 打开 Web 控制面板 |
openclaw skills list | 查看已安装技能 |
openclaw doctor | 健康检查 + 快速修复 |
| 命令 | 用途 |
|---|---|
/status | 查看机器人状态 |
/reset | 重置对话 |
/model | 查看/切换 AI 模型 |
本文基于 OpenClaw 2026.3.2 版本，飞书开放平台截至 2026 年 3 月。如有版本差异请以官方文档为准：https://docs.openclaw.ai
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online