OpenClaw 是开源 AI Agent 框架，支持多平台接入。本文详述在 Linux/macOS 环境下通过 Node.js 安装 OpenClaw，配置 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
如果你用的是 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 模型 |
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online