OpenClaw 安装与飞书机器人配置全流程
OpenClaw 是一个开源的 AI Agent 框架，核心作用是让你拥有私人 AI 助手，可接入飞书、Telegram、WhatsApp 等多种聊天平台。
环境准备
系统要求
| 项目 | 要求 |
|---|---|
| 操作系统 | Linux / macOS / Windows (WSL2) |
| Node.js | v22 或更高 |
| 网络 | 能访问飞书开放平台 + AI API |
安装 Node.js
如果尚未安装，建议使用 nvm 管理版本：
# 检查是否已安装 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 即表示成功。
安装 OpenClaw
一键安装
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 目录权限。
初始配置（onboard 向导）
运行引导向导：
openclaw onboard --install-daemon
向导会引导配置：
- AI 模型密钥 — 输入 Anthropic / OpenAI / Google API Key
- Gateway 设置 — 默认端口 18789，一般不用改
- 聊天渠道 — 这里先跳过，后续单独配飞书
--install-daemon 参数会把 Gateway 安装为系统服务，开机自动启动。
配置完后检查 Gateway 状态：
openclaw gateway status
显示 running 即基础安装完成。此时可通过 Web UI 聊天：
openclaw dashboard
浏览器会自动打开 http://127.0.0.1:18789，这是 OpenClaw 的控制面板。
飞书机器人配置全流程
飞书配置分三步：飞书侧建应用 → OpenClaw 侧配置 → 联调测试。
1. 安装飞书插件
OpenClaw 的飞书支持通过插件提供，先安装：
openclaw plugins install @openclaw/feishu
安装完重启 Gateway：
openclaw gateway restart
2. 飞书开放平台：创建应用
登录平台
打开 https://open.feishu.cn/app，用飞书账号登录。
创建企业自建应用
- 点击「创建企业自建应用」
- 填写应用名称（如'我的 AI 助手'）、描述和图标
获取凭证
进入「凭证与基础信息」页面，复制：
- App ID（格式：
cli_xxxxxxxxx） - App Secret
*注意：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 等。
开启机器人能力
进入「应用能力」→「机器人」，开启能力并设置名称。
配置事件订阅（⚠️ 关键步骤）
进入「事件与回调」：
- 选择「使用长连接接收事件」（WebSocket 方式）
- 添加事件：搜索并勾选
im.message.receive_v1
*大坑警告：一定要选「长连接」而不是「Webhook」。长连接不需要公网 IP 和域名，对个人开发者更友好。配置前确保 OpenClaw Gateway 已在运行，否则飞书检测不到 WebSocket 端点，可能导致保存失败。
发布应用
- 进入「版本管理与发布」
- 创建版本并提交审核
- 等待管理员审批（企业自建应用通常秒批）
*不发布 = 不生效！很多人配完权限就以为搞定，结果发消息没反应。
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
4. 首次联调
- 在飞书里找到机器人，发一条消息（如'你好'）
- 机器人回复一个 配对码（Pairing Code）
- 终端执行配对确认：
openclaw pairing approve feishu <配对码>
- 配对成功后再次发消息，AI 即可正常回复。
踩坑实录 & 避坑指南
以下是实际配置中常见的问题及排查思路。
坑 1：事件订阅保存失败
现象：飞书平台配置长连接事件时，点保存无反应或报错。
原因：OpenClaw Gateway 未运行，飞书检测不到 WebSocket 连接。
解决：
openclaw gateway start
openclaw gateway status # 确认是 running
# 然后再去飞书平台配置事件订阅
坑 2：机器人不回复消息
现象：飞书发消息，机器人无响应。
排查清单：
- 应用有没有 发布？（最常见原因）
- 事件订阅里有没有添加
im.message.receive_v1？ - 是否选择了「长连接」方式？
- 权限是否全部开通？
- Gateway 是否在运行？
实时查看日志观察输出：
openclaw logs --follow
坑 3：群聊里机器人不回复
现象：私聊正常，群聊里@机器人没反应。
原因：默认配置下，群聊需要@mention 机器人才会响应。且机器人必须被添加到群里。
解决：
- 确认机器人已加入群聊
- 发消息时@机器人
- 如果想不@也能回复，修改配置：
{"channels":{"feishu":{"groups":{"oc_你的群 ID":{"requireMention":false}}}}}
群 ID 怎么获取？启动 Gateway 后在群里@机器人，然后 openclaw logs --follow 里找 chat_id。
坑 4：权限不足导致报错
现象：消息发送失败、无法读取文件、操作飞书文档报错。
原因：飞书权限细粒度，缺什么报什么错。
解决：回到飞书开放平台 → 权限管理，按需补充。常用权限如下：
| 场景 | 需要的权限 |
|---|---|
| 收发消息 | im:message, im:message:send_as_bot |
| 读取群消息 | im:message.group_at_msg:readonly |
| 操作文档 | docx:document, docx:document:readonly |
| 操作多维表格 | bitable:app |
| 云盘操作 | drive:drive, drive:file |
*添加新权限后，需要重新发布应用版本才能生效！
坑 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 # 升级到 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 模型 |
核心要点记住：
- 先装插件，后配飞书
- 先跑 Gateway，后配事件订阅
- 配完权限，别忘了发布应用
- 有问题先看日志：
openclaw logs --follow
