从零开始：OpenClaw安装+飞书机器人全流程配置指南（附踩坑实录）
从零开始：OpenClaw 安装 + 飞书机器人全流程配置指南（附踩坑实录）
本文面向完全零基础的小白，手把手带你从一台干净的 Linux 机器开始，安装 OpenClaw、配置 AI 模型、对接飞书机器人，最终实现在飞书里和 AI 直接对话。全程附带我自己踩过的坑和解决方案。
目录
一、OpenClaw 是什么？
OpenClaw 是一个开源的 AI Agent 框架，简单理解就是：它让你拥有一个私人 AI 助手，可以接入飞书、Telegram、WhatsApp、Discord 等各种聊天平台。
它的核心架构很简单：
你的消息 → 飞书/Telegram/... → OpenClaw Gateway → AI 模型 → 回复 为什么选 OpenClaw？
- 🔒 数据自托管，隐私可控
- 🔌 支持多种聊天平台（飞书、Telegram、WhatsApp、Discord……）
- 🧠 支持多种 AI 模型（Claude、GPT、Gemini……）
- 🛠 可扩展的 Skill 系统，像安装 App 一样给 AI 加技能
- 💻 完全开源免费
二、环境准备
2.1 系统要求
| 项目 | 要求 |
|---|---|
| 操作系统 | Linux / macOS / Windows (WSL2) |
| Node.js | v22 或更高 |
| 网络 | 能访问飞书开放平台 + AI API |
2.2 安装 Node.js（如果还没装）
# 检查是否已安装node--version# 如果没有或版本太低，用 nvm 安装curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh |bashsource ~/.bashrc nvm install22 nvm use 22💡 小白提示：输入node --version后如果显示v22.x.x，说明安装成功。
三、安装 OpenClaw
3.1 一键安装
macOS / Linux：
curl-fsSL https://openclaw.ai/install.sh |bashWindows (PowerShell)：
iwr-useb https://openclaw.ai/install.ps1 |iex安装完成后验证：
openclaw --version看到版本号（如 2026.3.2）就说明安装成功了。
3.2 手动安装（备选）
如果一键脚本有问题，也可以用 npm 安装：
npminstall-g openclaw ⚠️ 踩坑预警：如果遇到EACCES: permission denied错误，不要用sudo npm install -g！正确做法是：
四、初始配置（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 侧配置 → 联调测试。
5.1 安装飞书插件
OpenClaw 的飞书支持是通过插件提供的，先安装：
openclaw plugins install @openclaw/feishu 安装完后重启 Gateway：
openclaw gateway restart 5.2 飞书开放平台：创建应用
Step 1：登录飞书开放平台
打开 https://open.feishu.cn/app，用你的飞书账号登录。
⚠️ 如果你用的是 Lark（国际版），地址是 https://open.larksuite.com/app。Step 2：创建企业自建应用
- 点击 「创建企业自建应用」
- 填写应用名称（比如 “我的AI助手”）
- 填写应用描述
- 选一个图标
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：开启机器人能力
进入 「应用能力」→「机器人」：
- 开启机器人能力
- 设置机器人名称
Step 6：配置事件订阅（⚠️ 这步容易翻车！）
进入 「事件与回调」：
- 选择「使用长连接接收事件」（WebSocket 方式）
- 添加事件：搜索并勾选
im.message.receive_v1（接收消息 v1）
🚨 大坑警告：一定要选「长连接」而不是「Webhook」！长连接不需要公网 IP，不需要域名，不需要配置 HTTPS，对个人开发者友好得多。配置事件订阅之前，OpenClaw Gateway 必须在运行！ 否则飞书检测不到长连接端，可能导致保存失败。先跑 openclaw gateway status 确认 Gateway 在线，再来配这一步。Step 7：发布应用
- 进入 「版本管理与发布」
- 创建一个版本
- 提交审核并发布
- 等待管理员审批（企业自建应用一般秒批）
⚠️ 不发布 = 不生效！ 很多人配完权限和机器人就以为搞定了，结果发消息没反应——因为应用还没发布。
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 首次联调
- 在飞书里找到你的机器人，发一条消息（比如 “你好”）
- 机器人会回复一个 配对码（Pairing Code）
- 在终端执行配对确认：
openclaw pairing approve feishu <配对码>- 配对成功后，再次发消息，AI 就会正常回复了 🎉
六、踩坑实录 & 避坑指南
以下是我们实际配置过程中踩过的坑，排列按「痛苦指数」从高到低 😂
🕳️ 坑 1：事件订阅保存失败
现象：在飞书开放平台配置长连接事件订阅时，点保存没反应或报错。
原因：OpenClaw Gateway 没有在运行，飞书检测不到 WebSocket 连接。
解决：
# 先确保 Gateway 在跑 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：配对码（Pairing）一直等不到
现象：发消息后机器人没有回复配对码。
原因：Gateway 没有成功连接飞书 WebSocket。
解决：
# 查看详细日志 openclaw logs --follow# 看看有没有 feishu 连接成功的日志# 如果有 error，根据错误信息排查（通常是 App ID/Secret 填错了）🕳️ 坑 6：Node.js 版本太低
现象：安装 OpenClaw 报错，或启动后各种奇怪问题。
原因：OpenClaw 要求 Node.js 22+，很多系统默认装的是 18 或 20。
解决：
node--version# 检查版本 nvm install22# 升级到 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 + 飞书机器人的配置确实有不少坑，但只要按照本文的流程走，应该能少走很多弯路。核心要记住的就是：
- 先装插件，后配飞书
- 先跑 Gateway，后配事件订阅
- 配完权限，别忘了发布应用
- 有问题先看日志：
openclaw logs --follow
如果本文对你有帮助，欢迎点赞收藏 👍
有问题可以在评论区交流，也欢迎加入 OpenClaw Discord 社区 一起讨论。
本文基于 OpenClaw 2026.3.2 版本，飞书开放平台截至 2026 年 3 月。如有版本差异请以官方文档为准：https://docs.openclaw.ai
