openClaw 配置飞书教程（小白版）

一、这篇教程是干什么的

这篇教程的目标只有一个：

把 OpenClaw 接入飞书，让你可以在飞书里直接和机器人聊天。

适合这几类人：

已经装好了 OpenClaw，但不会接飞书

打开飞书开放平台后，不知道每一步该怎么点

看到“长连接”“事件订阅”“配对码”这些词就头大

希望有一篇从头到尾、按顺序操作的教程

这篇教程会尽量用最简单的话解释，不讲太多原理，先以“能跑通”为主。

二、先理解一件事：OpenClaw 和飞书是怎么连起来的

你可以把整个过程理解成这样：

飞书：相当于聊天窗口

OpenClaw：相当于机器人后端

飞书开放平台应用：相当于中间的“身份证”和“通行证”

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

只要这个关系理顺了，后面的步骤其实就是：

1.创建飞书应用

2.开启机器人和事件订阅

3.把 App ID 和 App Secret 填进 OpenClaw

4.启动 OpenClaw

5.在飞书里测试

6.完成首次配对授权

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

在正式操作前，请先确认你已经有下面这些东西。

一台已经装好 OpenClaw 的电脑

先打开终端，输入：

openclaw -v

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

如果提示：

zsh: command not found: openclaw

那说明你还没装好 OpenClaw，要先把 OpenClaw 安装好，再继续下面的步骤。
文档点击openclaw的部署教程（部署安装教程）

一个可以登录的飞书账号

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

能进入飞书开放平台

后面的配置大部分都在飞书开放平台里完成。

如果你是企业内部使用，可能需要管理员权限，或者至少需要有创建应用的权限。

四、整体流程先看一遍

为了避免你做到一半乱掉，先把完整流程给你看一下。

整个配置流程一共分为 6 步：

第一步：创建飞书应用
第二步：给应用开启机器人能力
第三步：开启事件订阅，并选择长连接模式
第四步：获取 App ID 和 App Secret
第五步：把这两个参数写进 OpenClaw 配置文件
第六步：启动 OpenClaw，并在飞书里完成测试和配对

你只需要按顺序做，不要跳步骤。

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

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

创建时你会看到填写应用名称、应用描述、图标之类的内容。

这里你可以随便起一个自己容易记住的名字，比如：

OpenClaw助手

我的AI机器人

飞书AI测试号

名称不影响连接，只要你自己能认出来就行。

创建完成后，你就进入了这个应用的管理后台

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

进入应用后台后，先找到和“机器人”相关的功能区域。

这一步的目的很简单：

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

如果没有开启机器人能力，就算 OpenClaw 连上了，飞书里也没法正常和它聊天。

你可以把它理解成：

应用只是一个壳

开了机器人能力后，它才变成“会说话的机器人”

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

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

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

事件订阅

然后你会看到两种方式：

使用长连接接收事件

将事件发送至开发者服务器

这里我们选：

使用长连接接收事件

为什么选这个？

因为对于大多数普通用户来说，长连接模式更简单：

不需要公网服务器

不需要域名

不需要配置 HTTPS 回调地址

不需要做额外的外网映射

说得直白一点：

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

这对新手最友好。

看到“未检测到应用连接信息”怎么办

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

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

这个提示的意思不是飞书坏了，也不是你点错了。

它真正的意思是：

飞书平台现在还没有发现你的 OpenClaw 已经连上来。

所以这时候你先不用慌，也不要在这里反复点保存。

正确做法是：

先继续后面的步骤

把 OpenClaw 配好并启动起来

等 OpenClaw 成功建立飞书长连接后

再回来保存

也就是说，这个页面不是先配完就成功，而是要等你的本地程序真的跑起来。

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

这一部分的目的，是让飞书应用知道：

它应该接收哪些消息

它有没有权限回复消息

你不用一下子背很多内容，只要记住一个最核心的思路：

至少要保证机器人能“收到消息”和“发送消息”

如果缺这两类权限，常见现象就是：

你给机器人发消息，它没反应

或者它能收到，但不能回复

所以在权限和事件订阅那里，你要重点检查这两类能力是否已经开通。

如果你后面配置好了，但机器人没反应，优先回来检查这里。

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

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

App ID

App Secret

你可以把它们理解成：

App ID：应用编号

App Secret：应用密码

后面 OpenClaw 就靠这两个参数去登录飞书。

这两个值一定要复制准确，尤其注意：

不要多复制空格

不要漏掉字符

不要把别的字段当成 App ID 或 Secret

建议你先把这两个值临时保存到记事本里，后面要填到 OpenClaw 配置文件中。

十、第六步：配置 OpenClaw

现在开始进入 OpenClaw 这边的配置。

打开 OpenClaw 配置文件

在终端输入：

vim ~/.openclaw/openclaw.json

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

这就是 OpenClaw 的主配置文件。

写入飞书配置

把下面这段内容写进去：

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

然后把里面这两处替换成你自己的值：

这里填写你的App ID

这里填写你的App Secret

一个完整示例

比如你的参数是：

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 插件重复

如果你已经遇到过这种情况，建议先把第三方 Feishu 插件移走，尽量只保留一套飞书通道，不然很容易把自己绕晕。

比如可以先执行：

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

这样做的意思是：

不直接删除

先备份

避免它继续和内置 Feishu 冲突

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

十二、第七步：启动 OpenClaw

配置文件写好后，回到终端，输入：

openclaw gateway

这一步就是启动 OpenClaw 网关。

你可以理解成：

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

如果一切正常，飞书平台就会逐渐检测到连接信息。

十三、如何查看是否连接成功

如果你想确认当前 OpenClaw 状态，可以输入：

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_xxx
Pairing code: ABCD1234
Ask the bot owner to approve with:
openclaw pairing approve feishu ABCD1234

这并不是失败。

这其实是 OpenClaw 的一层安全机制。

十五、为什么会出现配对码

你可以把这一步理解成：

机器人第一次见到你，它不知道你是不是允许使用它的人，所以先不让你直接用。

于是它会给你一个配对码，要求 OpenClaw 管理员手动批准。

这样做的好处是：

不会谁都能私聊机器人

可以控制哪些飞书用户能使用这个机器人

更安全

十六、第九步：批准配对

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

openclaw pairing approve feishu 配对码

比如你的配对码是：

VC7Z93JT

那就执行：

openclaw pairing approve feishu VC7Z93JT

执行成功后，就代表：

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

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

十七、如果配对命令执行了还是不行

这时候不要急着重装，先按下面顺序排查。

看配对是不是批准成功了

可以执行：

openclaw pairing list

看网关是否还在运行

执行：

openclaw gateway status

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

看日志有没有报错

执行：

openclaw logs --follow

重点看有没有下面这些问题：

App ID 错误

App Secret 错误

飞书连接失败

插件冲突

权限不足

事件没有订阅成功

十八、群聊里怎么用

很多人配置好私聊后，还会问一句：

能不能在飞书群里用？

答案是：能，但通常有条件。

一般情况下，群里要想让机器人回复，最好：

@机器人再发消息

因为很多机器人默认不是“看见群里一句话就回复”，而是被提到时才回应。

这样做是为了避免它在群里乱刷屏。

所以你在群里测试时，不要只发：

你好

而是发：

@机器人 你好

这样更容易成功。

十九、最常见的几个坑

坑 1

坑 2

坑 3

坑 4

坑 5

飞书页面提示“未检测到应用连接信息”
这通常说明 OpenClaw 还没成功连接飞书。

做法是：

先把 OpenClaw 配好

启动 gateway

看日志确认连接成功

再回飞书后台操作

二十、写给第一次接触的人：你可以这样理解整件事

如果你已经看完上面所有解释，最后可以直接按这份清单做。

1.创建飞书自建应用

2.开启机器人能力

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

4.拿到 App ID 和 App Secret

5.编辑 ~/.openclaw/openclaw.json

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

6.启动 OpenClaw

openclaw gateway

7.去飞书私聊机器人

8.拿到配对码后执行

openclaw pairing approve feishu 配对码

9.再次测试聊天
按照图片配置：

📌

参考图片配置：

 openclaw config

选择Local

选择channels

选择Configure/link

选择Feishu/Lark

选择No

这里要输入飞书app ID

打开网址 https://open.feishu.cn

创建应用

添加应用

凭证与基础信息里面获取App ID和 App Secret

点击权限这里，开通权限

选择消息里面，开通所有的内容

或者点击批量导入

将一下内容复制粘贴进去

{
  "scopes": {
    "tenant": [
      "base:app:copy",
      "base:app:create",
      "base:app:read",
      "base:app:update",
      "base:collaborator:create",
      "base:collaborator:delete",
      "base:collaborator:read",
      "base:dashboard:copy",
      "base:dashboard:read",
      "base:field:create",
      "base:field:delete",
      "base:field:read",
      "base:field:update",
      "base:form:read",
      "base:form:update",
      "base:record:create",
      "base:record:delete",
      "base:record:read",
      "base:record:retrieve",
      "base:record:update",
      "base:role:create",
      "base:role:delete",
      "base:role:read",
      "base:role:update",
      "base:table:create",
      "base:table:delete",
      "base:table:read",
      "base:table:update",
      "base:view:read",
      "base:view:write_only",
      "bitable:app",
      "bitable:app:readonly",
      "board:whiteboard:node:create",
      "board:whiteboard:node:delete",
      "board:whiteboard:node:read",
      "board:whiteboard:node:update",
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "contact:user.employee_id:readonly",
      "contact:user.employee_number:read",
      "contact:user.id:readonly",
      "docs:doc",
      "docs:doc:readonly",
      "docs:document.comment:create",
      "docs:document.comment:read",
      "docs:document.comment:update",
      "docs:document.comment:write_only",
      "docs:document.content:read",
      "docs:document.media:download",
      "docs:document.media:upload",
      "docs:document.subscription",
      "docs:document.subscription:read",
      "docs:document:copy",
      "docs:document:export",
      "docs:document:import",
      "docs:event.document_deleted:read",
      "docs:event.document_edited:read",
      "docs:event.document_opened:read",
      "docs:event:subscribe",
      "docs:permission.member",
      "docs:permission.member:auth",
      "docs:permission.member:create",
      "docs:permission.member:delete",
      "docs:permission.member:readonly",
      "docs:permission.member:retrieve",
      "docs:permission.member:transfer",
      "docs:permission.member:update",
      "docs:permission.setting",
      "docs:permission.setting:read",
      "docs:permission.setting:readonly",
      "docs:permission.setting:write_only",
      "docx:document",
      "docx:document.block:convert",
      "docx:document:create",
      "docx:document:readonly",
      "drive:drive",
      "drive:drive.metadata:readonly",
      "drive:drive.search:readonly",
      "drive:drive:readonly",
      "drive:drive:version",
      "drive:drive:version:readonly",
      "drive:export:readonly",
      "drive:file",
      "drive:file.like:readonly",
      "drive:file.meta.sec_label.read_only",
      "drive:file:download",
      "drive:file:readonly",
      "drive:file:upload",
      "drive:file:view_record:readonly",
      "event:ip_list",
      "im:app_feed_card:write",
      "im:biz_entity_tag_relation:read",
      "im:biz_entity_tag_relation:write",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.announcement:read",
      "im:chat.announcement:write_only",
      "im:chat.chat_pins:read",
      "im:chat.chat_pins:write_only",
      "im:chat.collab_plugins:read",
      "im:chat.collab_plugins:write_only",
      "im:chat.managers:write_only",
      "im:chat.members:bot_access",
      "im:chat.members:read",
      "im:chat.members:write_only",
      "im:chat.menu_tree:read",
      "im:chat.menu_tree:write_only",
      "im:chat.moderation:read",
      "im:chat.tabs:read",
      "im:chat.tabs:write_only",
      "im:chat.top_notice:write_only",
      "im:chat.widgets:read",
      "im:chat.widgets:write_only",
      "im:chat:create",
      "im:chat:delete",
      "im:chat:moderation:write_only",
      "im:chat:operate_as_owner",
      "im:chat:read",
      "im:chat:readonly",
      "im:chat:update",
      "im:datasync.feed_card.time_sensitive:write",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message.pins:read",
      "im:message.pins:write_only",
      "im:message.reactions:read",
      "im:message.reactions:write_only",
      "im:message.urgent",
      "im:message.urgent.status:write",
      "im:message.urgent:phone",
      "im:message.urgent:sms",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "im:message:send_multi_depts",
      "im:message:send_multi_users",
      "im:message:send_sys_msg",
      "im:message:update",
      "im:resource",
      "im:tag:read",
      "im:tag:write",
      "im:url_preview.update",
      "im:user_agent:read",
      "sheets:spreadsheet",
      "sheets:spreadsheet.meta:read",
      "sheets:spreadsheet.meta:write_only",
      "sheets:spreadsheet:create",
      "sheets:spreadsheet:read",
      "sheets:spreadsheet:readonly",
      "sheets:spreadsheet:write_only",
      "space:document.event:read",
      "space:document:delete",
      "space:document:move",
      "space:document:retrieve",
      "space:document:shortcut",
      "space:folder:create",
      "wiki:member:create",
      "wiki:member:retrieve",
      "wiki:member:update",
      "wiki:node:copy",
      "wiki:node:create",
      "wiki:node:move",
      "wiki:node:read",
      "wiki:node:retrieve",
      "wiki:node:update",
      "wiki:setting:read",
      "wiki:setting:write_only",
      "wiki:space:read",
      "wiki:space:retrieve",
      "wiki:space:write_only",
      "wiki:wiki",
      "wiki:wiki:readonly"
    ]
  }
}