从零开始：OpenClaw 安装 + 飞书机器人全流程配置指南（附踩坑实录） > 面向完全零基础的小白，手把手带你从一台干净的 Linux 机器开始，安装 OpenClaw、配置 AI 模型、对接飞书机器人，最终实现在飞书里和 AI 直接对话。全程附带我自己踩过的坑和解决方案。 目录 一、OpenClaw 是什么？ 二、环境准备 三、安装 OpenClaw 四、初始配置（onboard 向导）…
本文面向完全零基础的小白，手把手带你从一台干净的 Linux 机器开始，安装 OpenClaw、配置 AI 模型、对接飞书机器人，最终实现在飞书里和 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 |bashsource ~/.bashrc nvm install22 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 安装：
npminstall-g openclaw
⚠️ 踩坑预警：如果遇到
EACCES: permission denied错误，不要用sudo npm install -g！正确做法是：
安装完后，运行引导向导：
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 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 + 飞书机器人的配置确实有不少坑，但只要按照本文的流程走，应该能少走很多弯路。核心要记住的就是：
openclaw logs --follow如果本文对你有帮助，欢迎点赞收藏 👍
有问题可以在评论区交流，也欢迎加入 OpenClaw Discord 社区 一起讨论。
本文基于 OpenClaw 2026.3.2 版本，飞书开放平台截至 2026 年 3 月。如有版本差异请以官方文档为准：https://docs.openclaw.ai
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online