飞书连接教程 — GetaClaw 新手入门

1

创建飞书应用

在飞书开放平台新建一个企业自建应用

1

打开飞书开放平台

用浏览器打开以下网址，用你的飞书账号登录：

🐦 飞书开放平台 → 🌐 Lark 国际版 →

2

点击「创建企业自建应用」

进入开放平台后，点右上角的蓝色按钮

① 填写应用名称（比如「我的AI助手」）

② 填写应用描述（随便写，比如「OpenClaw AI助手」）

③ 点击确定创建

3

复制 App ID 和 App Secret

创建完成后，在「凭证与基础信息」页面找到这两个值，先复制保存好，然后把两个值发给 AI 助手，它会自动写入配置并重启服务，无需手动操作。

⚠️ App Secret 很重要！不要泄露给别人，也不要截图发到群里。

App ID 格式示例

cli_xxxxxxxxxxxxxxxx

App Secret 格式示例

xxxxxxxxxxxxxxxxxxxxxxxx

💡 如何把凭证交给 AI 助手？

✅ 通过 GetaClaw 安装的用户： AI 助手已经在和你对话了，直接把 App ID 和 App Secret 发给它，它会自动写入配置并重启服务。

🔧 自己安装 OpenClaw 的用户：打开终端，依次运行下面 3 条命令。把 YOUR_APP_ID 和 YOUR_APP_SECRET 替换成你刚才复制的真实值，然后回车执行：

✏️ 第 1、2 条末尾需填入你自己的值（橙色部分），第 3 条直接复制执行即可。

① 写入 App ID

openclaw config set channels.feishu.accounts.default.appId YOUR_APP_ID

把末尾 YOUR_APP_ID 替换成你的 App ID（格式：cli_xxxxxxxx），再回车执行

② 写入 App Secret

openclaw config set channels.feishu.accounts.default.appSecret YOUR_APP_SECRET

把末尾 YOUR_APP_SECRET 替换成你的 App Secret，再回车执行

③ 启动网关（无需修改，直接复制执行）

openclaw gateway start

✅ 3 条命令都执行完、没有报错，配置就完成了。

2

配置权限和机器人能力

给 App 开放消息权限，并启用机器人功能

📌 本步顺序很重要：先完成权限 + 机器人设置 → 把凭证发给 AI 助手建立长连接 → 再回来配置事件订阅（飞书后台需要检测到长连接才能保存）→ 最后发布。

1

批量导入权限

①左侧菜单点「权限管理」

②点顶部蓝色按钮「批量导入/申请权限」（见截图），弹出输入框

③点击下方「复制」按钮，把 JSON 复制好

④在弹出的输入框里点一下，全选（Ctrl+A / Cmd+A）删除原有内容，再粘贴（如下图）

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message.p2p_msg:readonly",
      "im:message.group_at_msg:readonly",
      "im:message:send_as_bot",
      "im:message:readonly",
      "im:resource",
      "im:chat.members:bot_access",
      "im:chat.access_event.bot_p2p_chat:read",
      "contact:user.employee_id:readonly",
      "application:application:self_manage"
    ],
    "user": [
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

⑤点右下角蓝色按钮「下一步，确认新增权限」完成导入

✅ 导入是「新增」权限，不影响已有权限，放心确认。看到「已添加 X 个权限」就成功了。

2

开启机器人能力

左侧菜单找到「应用能力」→「机器人」，点击开启

① 点击「机器人」选项卡

② 点击「开启机器人能力」按钮（蓝色的那个）

③ 可以设置机器人名称，比如「AI 助手」

3

把凭证发给 AI 助手，建立长连接

先让 AI 启动网关、建立长连接，飞书后台才能在下一步检测到并保存事件配置

① 打开 GetaClaw / OpenClaw 助手对话窗口（如果是刚安装，打开终端运行 openclaw chat）

② 把 App ID 和 App Secret 发给 AI，格式如下：

发送示例：

App ID: cli_xxxxxxxxxxxxxxxx
App Secret: xxxxxxxxxxxxxxxxxxxxxxxx

③ 等待 AI 回复「✅ 凭证已写入，网关已启动！」（约 20-30 秒），确认长连接建立成功后，继续下一步

⚠️ 如果 AI 提示「凭证已成功配置，需要重启 Gateway」或「Gateway 服务未运行」：

① 找到系统托盘里的小龙虾图标（Windows 在右下角任务栏，Mac 在右上角菜单栏）

② 点击图标 → 选择「重启 Gateway」

③ 等待网页能正常打开（通常几秒内完成），然后继续下一步

⚠️ 必须先完成这一步，飞书后台才能检测到长连接，下一步「保存事件配置」才能成功。

💡 这是你和 AI 的私信，App ID 和 App Secret 不会被其他人看到，放心发送。

4

配置事件与回调（长连接模式）

回到飞书开放平台，左侧菜单找到「事件与回调」→「事件配置与订阅方式」

✅ 上一步已建立长连接，飞书后台现在可以检测到，保存配置不会报错。

① 接收事件方式选择「使用长连接接收事件」

② 点击「添加事件」，搜索并添加 im.message.receive_v1

③ 点击「保存」

⚠️ 长连接模式不需要服务器公网地址，个人电脑也可以用。

5

发布应用

左侧菜单找到「版本管理与发布」，创建版本并发布

① 应用版本号 → 填写版本号（比如 1.0.0）

② 更新说明 → 随便写几字（如「初次发布」），不能留空

③ 可用范围 → 滚到底部，点「编辑」改成全员可用

④ 点蓝色「保存」按钮

⑤

点击左侧「版本管理与发布」，找到刚才保存的待发布版本 → 点击「查看版本详情」→ 点击「申请线上发布」，等待管理员审批

审批完成后，飞书里就能搜到你的机器人，机器人就有聊天框了 🎉

✅ 审批通过后，飞书里就能搜到你的机器人了！

3

在飞书里找到你的机器人

应用发布后，在飞书搜索机器人名称，发第一条消息

1

在飞书里搜索你的机器人

打开飞书客户端，搜索你创建的应用名称（如「AI 助手」）

① 飞书 → 搜索栏 → 输入你的机器人名字

② 点击机器人头像，进入对话窗口

③ 发送任意一条消息，比如「你好」

✅ 机器人有回复 = 大功告成！

📋 如果机器人回复「OpenClaw: access not configured」

这是正常现象，说明你的账号还未完成配对。按以下步骤操作：

① 打开飞书网页端（feishu.cn 或 larksuite.com），找到与机器人的聊天窗口

② 把机器人回复的那条「access not configured」消息完整复制，粘贴到 OpenClaw 龙虾（命令行 AI 助手）中发送

③ 等待龙虾自动完成配对（通常几秒内完成）

④ 配对完成后，回到飞书重新给机器人发一条消息，确认机器人可以正常回复即配置完成 ✅

2

找不到机器人？检查这几个点

机器人发布后，通常需要 1-2 分钟才能在飞书搜索中出现

① 应用是否已在步骤 2.5 发布？刷新飞书再试

② 事件订阅是否已保存 im.message.receive_v1？

③ 网关是否在运行？打开终端运行 openclaw gateway status 确认

3

🎉 开始使用！

你的 AI 助手已经在飞书里等着你了

🔍

搜索信息

「帮我搜一下今天港股行情」

✍️

写作助理

「帮我写一封邮件给客户…」

📋

任务管理

「帮我明天早上9点提醒开会」

💡 以后每次重启电脑，网关需要重新启动。告诉 AI「启动网关」即可，或者用 openclaw gateway install 设置开机自启。

4

遇到问题？常见排查

机器人不响应、找不到聊天框……看这里

1

事件配置保存时提示「未检测到长连接」

这是最常见的卡点，原因是凭证还没发给 AI、网关未启动

→ 回到步骤 2.3，先把 App ID + App Secret 发给 AI 助手，等它回复「✅ 网关已启动」后再保存

2

机器人发布了但搜不到

→等 1-2 分钟后刷新飞书再搜

→确认「可用范围」已设置为全员可用（步骤 2.5）

3

找到机器人但发消息没回复

→打开终端运行 openclaw gateway status，确认网关 running

→如果网关未运行，运行 openclaw gateway start 重启

→查看日志：openclaw logs --follow

💡 重启电脑后网关需要手动重启。建议运行 openclaw gateway install 设置开机自启。

4

配对码是什么？

💡 配对码是权限控制机制：当「其他人」第一次给你的机器人发消息时，机器人会发一个配对码，你（管理员）审批后对方才能使用。自己用不需要配对码，机器人直接回复即成功。

🙋 常见问题

机器人没有回复，怎么办？ ▼

逐一检查：

终端里运行 openclaw gateway status，确认网关是 running 状态
飞书应用是否已发布？（步骤 2.4）
事件与回调是否已添加 im.message.receive_v1？（步骤 2.3）
查看实时日志：openclaw logs --follow

重启电脑后机器人不响应了？ ▼

网关需要重新启动：

openclaw gateway start

如果想让它开机自启：

openclaw gateway install

我用的是 Lark 国际版，步骤一样吗？ ▼

基本一样，但有两点不同：

开放平台网址改为 open.larksuite.com/app
配置文件里需要加 "domain": "lark"

怎么把机器人加到群里用？ ▼

直接在群里邀请机器人就行。默认设置下，群里需要 @机器人 才会触发回复（避免骚扰）。

如果想在群里随时触发，不需要 @，联系管理员修改配置。

把 AI 助手接入飞书
10 分钟，零基础

创建飞书应用

配置权限和机器人能力

在飞书里找到你的机器人

遇到问题？常见排查

🙋 常见问题

搞定了！

把 AI 助手接入飞书 10 分钟，零基础

创建飞书应用

配置权限和机器人能力

在飞书里找到你的机器人

遇到问题？常见排查

🙋 常见问题

搞定了！

把 AI 助手接入飞书
10 分钟，零基础