最近最近弄了一个 OpenClaw + 飞书 Bot，如果你也想用个人飞书账号搭一个能“帮你干活”的 AI Bot，这篇可以直接跟着做。
一、准备工作
开始之前，建议先确认下面几件事：
1. 你已经有一个飞书开发者账号
可以正常登录飞书开放平台。
2. 你已经安装了 OpenClaw
你可以先在终端里执行：
openclaw --help
如果能正常输出帮助信息，就说明 CLI 已经装好了。
如果没有安装那么先需要安装openclaw，需要先安装openclaw：
一、OpenClaw 安装指南（Mac / Node 环境）
1️⃣ 先确认你的环境
OpenClaw 是基于 Node.js 的 CLI 工具，所以你必须先有：
必备环境：
Node.js >= 18
npm 或 pnpm
👉 检查是否已安装
在终端执行：
node -v
npm -v
✅ 正常情况
v18.x.x 或 v20.x.x
❌ 如果没有
建议直接去官网装：
或者用 nvm（推荐开发者用）：
brew install nvm
2️⃣ 安装 OpenClaw（推荐方式）
✅ 方式一：npm 全局安装（最通用）
npm install -g openclaw
✅ 方式二：pnpm（更快）
pnpm add -g openclaw
⚠️ Mac 用户注意
如果报权限错误：
EACCES: permission denied
可以这样：
sudo npm install -g openclaw
或者配置 npm 全局目录（更推荐长期方案）
3️⃣ 验证是否安装成功
执行：
openclaw --help
✅ 正确输出（示例）
Usage: openclaw [options] [command]
Commands:
gateway
pairing
message
👉 看到这些命令就说明安装成功了
4️⃣ ⚠️ 很多人会踩的坑（重点）
❌ 坑1：以为 openclaw 就是启动服务
执行：
openclaw
👉 只会输出帮助，不会启动任何东西
✅ 正确做法是：
openclaw gateway
👉 这个才是启动服务
❌ 坑2：命令找不到
command not found: openclaw
👉 原因：
- npm 全局路径没加到 PATH
✅ 解决方法：
执行：
npm root -g
找到路径后加入：
export PATH=$PATH:你的npm全局bin路径
❌ 坑3：装了但版本太低
有些同学 Node 是 14 / 16：
👉 可能会运行异常或报错
✅ 建议：
Node 18 或 20（最稳）
5️⃣ （可选）用 brew 安装（Mac）
如果你习惯 brew：
brew install openclaw
⚠️ 注意
brew 版本可能不是最新
如果遇到奇怪问题，建议还是用 npm
6️⃣ 安装完成后你应该达到的状态
你现在应该能做到：
openclaw --help ✅
openclaw gateway ✅（可以启动）
👉 到这里为止：
OpenClaw 安装 ✔
CLI 可用 ✔
二、第一步：在飞书开放平台创建应用
进入飞书开放平台后，创建一个自建应用。
创建完后，先给应用加上机器人能力。
创建一个自建应用，并添加“机器人”能力。后续所有消息交互，都会通过这个 Bot 进行。
三、第二步：进入“事件与回调”，这里一定要选对
这一部分是最容易走错的地方。
路径是：
开发配置 → 事件与回调
进入后你会看到“订阅方式”，一般会有两种：
- 使用长连接接收事件
- 将回调发送至开发者服务器
正确选择：使用长连接接收事件
如果你是本地体验，直接选这个。
不要一开始就选“开发者服务器回调”，因为那种方式意味着你要额外准备：
- 一个公网可访问的 HTTP 地址
- 回调 JSON 校验
- 请求地址配置
- 可能还要做内网穿透
这套流程更适合你已经有正式后端服务的情况，不适合初次接入。
三、第三步：不要纠结 webhook，也不要填请求地址
这里专门说一下我踩过的坑。
我一开始以为只要给飞书配一个 URL，比如：
https://xxx.loca.lt/webhook/feishu
Bot 就能工作。
结果飞书直接报：
返回数据不是合法的 JSON 格式
后来才发现，这是因为我把流程搞复杂了：
- 本来可以走长连接
- 结果跑去配开发者服务器回调
- 本地又没有真正启动一个符合飞书要求的 webhook 服务
- 自然就会报错
所以如果你走的是本文这套流程：
这里完全不需要填写请求地址
也不需要 localtunnel / cloudflare
四、第四步：发布应用版本
飞书有一个很容易被忽略的机制：
很多配置改完以后，必须发布版本才会生效。
也就是说，你不是点了保存就算完成了，还需要：
创建版本 → 发布
这个动作特别容易漏掉。
漏掉之后最典型的现象就是：
- 你明明觉得自己都配好了
- 但 Bot 还是没有反应
配置完长连接模式后，记得创建版本并发布，否则 Bot 仍然不会按新配置工作。
五、第五步：不要直接执行 openclaw，真正该启动的是 gateway
这是第二个特别容易误判的点。
我一开始在终端里直接执行：
openclaw
结果出来的是帮助信息、Usage、Options。
当时我还以为 OpenClaw 已经跑起来了，实际上并没有。
后来查看帮助内容才发现，真正应该启动的是：
openclaw gateway
这条命令的含义是：
启动本地 WebSocket Gateway，也就是和飞书建立长连接的核心进程。
你可以把这部分写得很明确：
正确启动命令
openclaw gateway
错误理解
openclaw
只是显示帮助，不会启动服务。
openclaw本身只是 CLI 入口，真正要跑起来的是openclaw gateway。
六、第六步：如果提示 “Gateway already running”，其实是好事
当我执行：
openclaw gateway
之后，又重复执行了一次，终端里报了类似：
Gateway already running
Port xxxx is already in use
第一反应会觉得是不是又报错了。
但实际上这通常说明：
OpenClaw Gateway 已经在本地成功启动了。
也就是说，这不是坏消息，而是说明你已经跑起来了，只是又重复开了一次。
所以看到类似下面这些信息时，不要慌：
Gateway already runningGateway already running locallyPort xxxx is already in use
它们通常意味着：
已经有一个 OpenClaw gateway 进程在运行。
这类提示一般不是失败，而是说明 gateway 已经在跑了，不需要重复启动。
七、第七步：回到飞书里给 Bot 发消息，拿 pairing code
当长连接已经跑起来之后，就可以回到飞书里和 Bot 对话了。
这时候你可以先发一句最简单的：
hi
如果链路是通的，Bot 一般会回复类似这样的内容：
OpenClaw: access not configured.
Your Feishu user id: ...
Pairing code: XXXXXXXX
Ask the bot owner to approve with:
openclaw pairing approve feishu XXXXXXXX
看到这一步，说明已经非常接近成功了。
这不是报错，而是在提示你进行绑定授权。
看到 pairing code，说明飞书已经能和本地 OpenClaw 正常通信，当前只差最后一步授权绑定。
八、第八步：回到终端执行 pairing approve
把飞书返回的 code 复制出来，在终端里执行：
openclaw pairing approve feishu 你的PairingCode
例如：
openclaw pairing approve feishu 4KJQBPE4
这一步成功之后，飞书端就不会再提示 access not configured 了。
这里可以加一句特别实用的提醒：
注意事项
- pairing code 必须用最新生成的
- 旧 code 很容易报：
No pending pairing request found for code: XXXXX
这不是命令写错，而是 code 已经过期或已失效了
用飞书里刚拿到的最新 pairing code 执行 approve。旧 code 可能会提示 no pending pairing request。
九、第九步：第一次跑通后，先做最小能力测试
到这里，其实接入已经完成了。
但不要一上来就给它下特别复杂的任务，比如：
- 创建调研文档
- 生成内容
- 再同步到飞书
- 再发消息通知别人
因为 OpenClaw 这类 Agent 的链路比较长，很容易在第一轮就把自己搞糊涂。
我建议先做一个最小测试：
请创建一个飞书文档，标题为 test-openclaw，并返回文档链接。
如果这个都能成功，说明最基础的 doc 工具链是通的。
然后再逐渐加复杂度。
十、为什么我会遇到 “LLM request timed out”
我在测试“创建调研文档”时，Bot 一开始回复说：
已创建调研文档，文件保存在本地工作空间。
接着我回复“需要的”之后，它又卡住，最后报：
LLM request timed out.
这说明什么？
说明它不是“还在思考”，而是：
这轮请求已经失败 / 超时结束了。
这个现象在 Agent 系统里很常见，原因通常包括：
- 模型本身慢
- 指令太复杂
- Tool 调用过多
- 先生成本地结果，再尝试同步飞书时超时
所以我后来总结出一个更稳的使用方式：
错误方式
一步要求它完成太多事：
帮我写文档 + 创建飞书文档 + 同步 + 返回链接 + 发消息通知
正确方式
拆成两步：
第一步：
先帮我整理一份调研文档内容
第二步：
请把上面的内容创建为飞书文档，并返回链接
这样成功率会高很多。
十一、如何判断它是“还在思考”还是“已经失败”
这是使用过程中很实用的一个判断方法。
还在跑的表现
- 飞书里还在持续输出
- 本地 gateway 日志还在动
- 没有明确报错
已经失败的表现
- 飞书出现
LLM request timed out - 很久没有任何新消息
- 本地日志也停住了
一旦看到 timeout，基本不用继续等了，应该重新发更明确、更短的任务。
十二、适合谁用，适合什么场景
就我目前的体验来说，这套接入方式特别适合：
- 个人飞书账号做体验
- 本地验证 OpenClaw 能力
- 做文档生成、飞书工具调用类 demo
- 想先做一个自己的 AI 助手原型
但如果你是要上公司正式环境，那就另一个话题了，后面一般还要考虑：
- 应用审批
- 权限范围
- 安全合规
- 稳定部署
- 服务器化运行
也就是说：
个人验证阶段，长连接模式很好用
正式生产环境，再考虑服务端部署和团队权限
