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

踩坑预警：遇到 EACCES: permission denied 错误时，不要直接使用 sudo npm install -g。建议配置 npm 目录权限后再安装。

四、初始配置（Onboard 向导）

安装完成后运行引导命令：

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 的飞书支持依赖独立插件，先安装并重启 Gateway：

openclaw plugins install @openclaw/feishu
openclaw gateway restart

5.2 飞书开放平台：创建应用

Step 1：登录平台

打开 https://open.feishu.cn/app，使用企业账号登录。

国际版用户请访问 https://open.larksuite.com/app。

Step 2：创建企业自建应用

1. 点击 「创建企业自建应用」
2. 填写应用名称（例如 "我的 AI 助手"）及描述
3. 上传应用图标

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 和域名，对个人开发者更友好。配置前请确保 OpenClaw Gateway 已在运行，否则飞书检测不到 WebSocket 端点会导致保存失败。

Step 7：发布应用

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

注意：不发布 = 不生效。很多人配完权限就以为搞定，结果发消息没反应，就是因为未发布应用。

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：配对码一直等不到

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

原因：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

本文基于 OpenClaw 当前稳定版编写，飞书开放平台界面如有更新请以官方文档为准：https://docs.openclaw.ai