OpenClaw 是什么?
OpenClaw 是一个开源的 AI Agent 框架,简单理解就是:它让你拥有一个私人 AI 助手,可以接入飞书、Telegram、WhatsApp、Discord 等各种聊天平台。
它的核心架构很简单:
你的消息 → 飞书/Telegram/... → OpenClaw Gateway → AI 模型 → 回复
为什么选 OpenClaw?
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