Step1：打开 VS Code

一、这篇教程适合谁？

这篇教程尤其适合下面这几类人：

• 已经装好了 OpenClaw，但不会接飞书
• 打开飞书开放平台后，不知道每一步该点哪里
• 看到“长连接”“事件订阅”“配对码”这些词就紧张
• 想找一篇从头到尾、按顺序讲清楚的实操教程

如果你是第一次配，不要慌。你不需要一开始就把所有概念都搞懂，只需要先把流程走通就行。

二、先用一句人话，理解 OpenClaw 和飞书是怎么连起来的

你可以先把这件事理解成下面这样：

• 飞书
  ：聊天窗口
• OpenClaw
  ：机器人后端
• 飞书开放平台应用
  ：中间的“身份证”和“通行证”

也就是说：

你并不是把 OpenClaw 直接塞进飞书里。而是要先在飞书开放平台创建一个应用，再让 OpenClaw 用这个应用去连接飞书。

把这个关系想明白之后，后面的流程其实就很清楚了：

1. 创建飞书应用
2. 开启机器人能力
3. 开启事件订阅，并选择长连接
4. 获取 App ID 和 App Secret
5. 把参数填进 OpenClaw
6. 启动 OpenClaw
7. 去飞书里测试
8. 完成首次配对授权

三、开始之前，你需要准备什么？

正式操作前，先确认你已经准备好下面这些东西。

1）一台已经装好 OpenClaw 的电脑

先打开终端，输入：

openclaw -v

如果能看到版本号，说明 OpenClaw 已经安装成功。

如果提示：

zsh: command not found: openclaw

那就说明你还没有装好 OpenClaw，需要先完成安装部署，再继续后面的步骤。

OpenClaw 部署教程：从下载安装到跑通，小白也能一步一步装起来

酷酷的帅，公众号：AI少踩坑OpenClaw 部署教程：从下载安装到跑通，小白也能一步一步装起来

2）一个可以正常登录的飞书账号

后面你会用这个飞书账号来测试机器人，所以最好就是你自己正在使用的账号。

3）可以进入飞书开放平台

后面的配置，大部分都要在飞书开放平台里完成。如果你是企业内部使用，可能需要管理员权限，或者至少需要有创建应用的权限。

四、先看整体流程，避免做到一半乱掉

为了避免中途卡住，先把完整流程看一遍。

整个接入过程，建议你按下面这 6 步走：

Step1：创建飞书应用

Step2：开启机器人能力

Step3：开启事件订阅，并选择长连接模式

Step4：获取 App ID 和 App Secret

Step5：把参数写进 OpenClaw 配置

Step6：启动 OpenClaw，并在飞书里完成测试和配对

你只要照着顺序做，不要跳步骤，基本就不会乱。

五、第一步：在飞书开放平台创建应用

先进入飞书开放平台，创建一个自建应用。

创建的时候，一般会让你填写这些内容：

• 应用名称
• 应用描述
• 应用图标

这里不用想太复杂，名称只要自己能认出来就行，比如：

• OpenClaw助手
• 我的AI机器人
• 飞书测试机器人

这些都可以。

应用名称本身不会影响连接，重点是你自己后面能分清它是干什么的。

六、第二步：开启机器人能力

创建完应用后，进入应用后台，找到和机器人相关的功能区域，把机器人能力开启。

这一步的目的很简单：

让这个飞书应用具备“收消息、发消息”的能力。

你可以这样理解：

• 应用刚创建出来时，还只是一个壳
• 开了机器人能力之后，它才真正变成一个可以聊天的机器人

如果这一步没开，后面就算 OpenClaw 配好了，飞书里也没法正常和它对话。

七、第三步：开启事件订阅，并选择“长连接”

这一部分非常关键，也是很多人最容易卡住的地方。

在飞书开放平台里，找到：

事件与回调 / 事件订阅

通常你会看到两种模式：

• 使用长连接接收事件
• 将事件发送至开发者服务器

这里建议新手直接选：

使用长连接接收事件

为什么选这个？

因为它最省事，尤其适合第一次配置的人。

选择长连接之后，你通常不需要自己额外准备这些东西：

• 不需要公网服务器
• 不需要域名
• 不需要 HTTPS 回调地址
• 不需要内网穿透
• 不需要自己折腾外网映射

说得更直白一点：

只要你的 OpenClaw 能在本机正常运行，飞书就可以通过长连接把消息送过来。

这也是为什么对新手来说，长连接模式最友好。

八、看到“未检测到应用连接信息”，先别慌

很多人做到这一步时，会看到类似提示：

未检测到应用连接信息，请确保长连接建立成功后再保存配置

这个提示不代表飞书坏了，也不代表你一定点错了。

它真正的意思是：

飞书平台现在还没有检测到你的 OpenClaw 已经连接上来。

所以这时候正确做法不是反复点保存，而是：

1. 继续后面的配置
2. 先把 OpenClaw 里的飞书参数填好
3. 启动 OpenClaw
4. 等 OpenClaw 成功建立长连接
5. 再回到飞书后台保存或继续配置

换句话说：

这个页面能不能最终保存成功，取决于你的本地 OpenClaw 是否真的跑起来了。

九、第四步：添加必要的权限和事件

这一部分的核心目的，是让飞书应用具备两种最基本的能力：

• 收到消息
• 发送消息

你不需要一开始就记住一大堆权限名，先记住这个原则就行：

至少要保证机器人能收消息、能发消息。

如果权限没开对，常见现象一般是：

• 你给机器人发消息，它没反应
• 它似乎收到了消息，但无法回复
• 群里 @它也不理你

所以你在配置权限和事件的时候，优先把“消息相关”的能力开通。

建议重点检查的方向

• 消息接收相关权限
• 消息发送相关权限
• 群聊消息 / 私聊消息相关能力
• 事件订阅中的消息事件

如果你后面配置好了，但机器人还是没反应，第一时间优先回来看这里。

配图建议：

十、第五步：获取 App ID 和 App Secret

在飞书开放平台应用后台里，你会看到两组非常重要的信息：

• App ID
• App Secret

你可以简单把它们理解成：

• App ID
  ：应用编号
• App Secret
  ：应用密码

后面 OpenClaw 就是通过这两个参数去连接飞书的。

复制时要特别注意下面几点：

• 不要多复制空格
• 不要漏字符
• 不要把别的字段当成 App ID 或 Secret
• 建议先临时保存到记事本里，避免来回切换时粘贴出错

十一、第六步：在 OpenClaw 里配置飞书

接下来开始进入 OpenClaw 这边的配置。

1）打开 OpenClaw 配置文件

在终端输入：

vim ~/.openclaw/openclaw.json

如果你不会用 vim，也可以换成你自己熟悉的编辑器打开这个文件。

这个文件就是 OpenClaw 的主配置文件。

2）写入飞书配置

把下面这段内容写进去：

{  "channels": {    "feishu": {      "accounts": {        "main": {          "appId": "这里填写你的App ID",          "appSecret": "这里填写你的App Secret"        }      }    }  }}

然后把这两个占位内容替换成你自己的：

• 这里填写你的App ID
• 这里填写你的App Secret

3）完整示例

比如你的参数是：

• App ID：cli_xxxxx
• App Secret：abcdefg123456

那么配置就会长这样：

{  "channels": {    "feishu": {      "accounts": {        "main": {          "appId": "cli_xxxxx",          "appSecret": "abcdefg123456"        }      }    }  }}

写完后保存退出即可。

十二、如果你之前装过第三方 Feishu 插件，先处理一下冲突

这一点很重要，尤其是你前面已经手动装过第三方 Feishu 插件时。

很多人会遇到这种情况：

• OpenClaw 自带一个 Feishu 通道
• 自己又安装了另一个第三方 Feishu 插件
• 结果出现重复加载、插件冲突、识别异常

常见提示可能类似：

• duplicate plugin id detected
• plugins.allow is empty
• feishu 插件重复
• plugin path not found

如果你已经遇到过这种情况，建议先把第三方 Feishu 插件移走，只保留一套飞书通道。

例如可以执行：

mv ~/.openclaw/extensions/feishu ~/.openclaw/extensions/feishu.bak

这样做的意思是：

• 不直接删除
• 先做备份
• 避免它继续和内置 Feishu 通道冲突

如果你没有装过第三方插件，这一步可以直接跳过。

十三、第七步：启动 OpenClaw

配置文件写好之后，回到终端，执行：

openclaw gateway

你可以把这一步理解成：

现在 OpenClaw 开始拿着你的 App ID 和 App Secret 去连接飞书。

如果前面的参数都没问题，飞书平台就会逐步检测到连接信息。

十四、如何确认是否连接成功？

如果你想看当前网关状态，可以执行：

openclaw gateway status

如果你想实时查看日志，可以执行：

openclaw logs --follow

这一条命令非常重要。

以后凡是出现下面这些问题，第一时间都建议看日志：

• 收不到消息
• 回不了消息
• 配对失败
• 飞书后台显示未连接
• 群聊不回复

你不需要一开始就看懂全部日志，只要重点观察有没有这类关键词：

• connected
• authenticated
• feishu connected
• websocket connected
• access not configured
• pairing code

这些信息能帮助你判断，现在到底卡在了哪一步。

十五、第八步：去飞书里测试机器人

现在打开飞书，找到你创建的应用机器人，给它发一条最简单的消息，比如：

你好

如果前面的连接已经建立成功，机器人通常会有反应。

不过很多新手到这里会发现，机器人并没有直接开始聊天，而是返回了一段类似这样的提示：

OpenClaw: access not configured.Your Feishu user id: ou_xxxPairing code: ABCD1234Ask the bot owner to approve with:openclaw pairing approve feishu ABCD1234

这并不是失败。

恰恰相反，这通常说明你已经走到比较后面的步骤了。

十六、为什么会出现配对码？

你可以把这一步理解成：

机器人第一次见到你，它不知道你是不是被允许使用它的人。

所以在第一次接触时，它不会立刻开放权限，而是先给你一个配对码，要求管理员手动批准。

这样做的好处是：

• 不是谁都能直接私聊机器人
• 可以控制哪些飞书用户能使用它
• 更安全

所以你看到配对码，不要慌。这说明 OpenClaw 的飞书通道已经基本跑起来了。

十七、第九步：批准配对

拿到配对码之后，回到 OpenClaw 所在电脑的终端，执行：

openclaw pairing approve feishu 配对码

例如你的配对码是：

VC7Z93JT

那么就执行：

openclaw pairing approve feishu VC7Z93JT

如果执行成功，就代表：

这个飞书账号已经被允许访问你的 OpenClaw 机器人。

然后你再回到飞书里重新发消息，一般就可以正常聊天了。

十八、如果批准配对后还是不行，按这个顺序排查

这时候先别急着重装，按下面顺序排查会更高效。

1）先看配对有没有成功

执行：

openclaw pairing list

确认当前飞书账号是否已经在允许列表中。

2）再看网关是不是还在运行

执行：

openclaw gateway status

如果网关没跑，机器人当然不会回复。

3）再看日志有没有报错

执行：

openclaw logs --follow

重点关注下面这些问题：

• App ID 填错
• App Secret 填错
• 飞书连接失败
• 插件冲突
• 权限不足
• 事件没有订阅成功

一般来说，大多数问题都能在日志里看到线索。

十九、群聊里怎么用？

很多人把私聊调通之后，下一句就会问：

能不能在飞书群里用？

答案是：通常可以，但一般要满足一定条件。

最常见的做法是：

在群里 @机器人 再发送消息

比如不要只发：

你好

而要发：

@机器人 你好

为什么？

因为很多机器人默认不会“看到群里任何一句话都回复”，而是只有在被明确提及时，才会回应。

这样做的目的，是为了避免它在群里到处刷屏。

所以如果你在群里测试，请优先用 @机器人的方式。

二十、最常见的几个坑

坑 1：飞书后台一直提示“未检测到应用连接信息”

这通常说明：

OpenClaw 还没有真正成功连接飞书。

正确做法是：

1. 先确认 App ID 和 App Secret 是否填写正确
2. 启动 openclaw gateway
3. 用 openclaw logs --follow 查看日志
4. 确认长连接已经建立成功
5. 再回飞书后台继续保存或测试

坑 2：机器人能收到消息，但就是不回复

一般优先检查：

• 消息发送权限是否开通
• 事件是否订阅正确
• 群聊里是否用了 @机器人
• 配对是否批准成功

坑 3：明明已经配过一次，还是提示配对

这通常要检查：

• 当前发消息的飞书账号，是不是和之前批准的账号是同一个
• 网关重启后配置是否仍然生效
• 是否存在插件冲突或配置文件被覆盖

坑 4：日志里一堆信息，看不懂

没关系。

对于第一次配置的人来说，不需要一开始就把日志全部看懂。你只要先看三件事：

• 有没有报错
• 有没有连接成功相关关键词
• 有没有配对码相关提示

先抓大方向，再一点点定位问题。

二十一、按图配置版：如果你更习惯“照着截图做”

如果你不想一次看太多字，也可以按下面这个顺序，对着截图一步一步来。

1）打开 OpenClaw 配置向导

进入 OpenClaw 配置流程。

2）选择 Local

选择本地模式。

3）选择 channels

进入通道配置。

4）选择 Configure / link

开始配置连接。

5）选择 Feishu / Lark

选择飞书通道。

6）根据提示输入 App ID

这里需要填写你在飞书开放平台获取到的 App ID。

7）打开飞书开放平台，创建应用

进入开放平台后，创建自建应用。

8）在“凭证与基础信息”里获取 App ID 和 App Secret

把这两个值复制出来，后面填回 OpenClaw。

9）在权限页面开通相关权限

优先开通消息、群组、机器人对话相关权限。

10）在事件与回调里开启长连接

进入事件与回调页面，选择长连接模式并保存。

11）添加消息与群组相关事件

确保机器人能接收消息类事件。

12）创建并发布版本

很多配置改完之后，需要创建版本并发布，才会正式生效。

13）回到飞书客户端，找到应用机器人

然后在飞书里打开这个应用，开始测试对话。

二十二、权限怎么配更合适？

很多人第一次看到权限页，会忍不住想：

是不是要把所有权限全开？

从“小白先跑通”的角度来说，不建议一上来就为了图省事，把一大串权限全部塞进去。

更稳妥的做法是：

先开最基础、最必要的权限

优先保证：

• 能收到私聊消息
• 能收到群聊消息
• 能发送消息
• 能让机器人在对应场景里工作

先把机器人跑通，后面你再根据自己的需求逐步补权限，会更清晰，也更不容易乱。

如果你已经在用“批量导入权限”的方式，也建议优先导入与消息、聊天、群组相关的权限，而不是一开始就导入非常庞大的全量权限集。

二十三、最后给第一次接触的人一句话

如果你是第一次配置 OpenClaw 和飞书，不要要求自己一上来就把所有术语都搞明白。

你只要先记住这几件事：

• 看不懂术语没关系
• 先把流程跑通最重要
• 出问题先看日志
• 有配对码，通常说明已经走到比较后面的步骤了
• 真正难的往往不是技术本身，而是不知道每一步是在干什么

只要你知道每一步的作用，这套流程其实没有想象中那么复杂。

二十四、最后再帮你总结一遍最短流程

如果你已经看完全文，最后可以只记这份清单：

1）创建飞书自建应用

2）开启机器人能力

3）开启事件订阅，选择长连接

4）获取 App ID 和 App Secret

5）写入 OpenClaw 配置文件

{  "channels": {    "feishu": {      "accounts": {        "main": {          "appId": "你的App ID",          "appSecret": "你的App Secret"        }      }    }  }}

6）启动 OpenClaw

openclaw gateway

7）去飞书私聊机器人

8）拿到配对码后执行

openclaw pairing approve feishu 配对码

9）回到飞书继续测试聊天

如果你能看到这里，说明你已经把 OpenClaw 接飞书这件事，梳理得差不多了。

第一次配的时候，最容易让人放弃的，不是命令本身，而是看到一堆页面之后，不知道该先做什么、后做什么。

但只要顺序理清楚，你会发现它并没有想象中那么难。

先把它跑起来。等你真正用顺了，再慢慢研究更细的配置、权限、群聊用法和插件扩展，也完全来得及。

如果这篇文章对你有帮助，欢迎点个关注。后面我也会继续整理更多 OpenClaw / AI 工具 / 接口配置 / 小白实操教程，尽量都写成“第一次接触也能看懂”的版本。

我是 AI之王。如果你在实际操作里还有不懂的地方，或者还想继续看后续更新的教程内容，欢迎扫描下方二维码关注我，后面会继续整理更多适合新手照着走的实用内容。

AI之王

微信号：xj18578671284