千帆 OpenClaw 接入飞书机器人教程
本教程将引导您完成 OpenClaw 部署、飞书应用创建与配置、OpenClaw 侧飞书对接，以及事件订阅设置，最终实现在飞书群聊中 @机器人 即可获得回复。
一、部署 OpenClaw
在千帆控制台完成 OpenClaw 的快速部署，包括选择模型、配置 API Key 和安装 Skills。
- 访问 千帆 OpenClaw 控制台，点击快速部署。
- 进入快速部署页面，选择模型和 API Key，以及需要安装的 Skills。若尚未创建 API Key，可在本页面直接创建。
选择 API Key：
创建 API Key：
根据需要选择权限，点击创建：
选择并填入 API Key 即可生效：
- 选择 Agent Skills。目前千帆提供了 7 种 Skills，可根据需要自行选装：
- 点击立即部署，稍作等待。
请记住此处配置的 API Key，后续在服务器端配置飞书时需要使用。
二、创建飞书应用并完成首次发布
本节将依次完成应用创建、权限配置、机器人能力开启，并进行首次发布。
- 进入 飞书开发者后台，点击创建企业自建应用。
- 填写应用名称和描述，点击创建。
- 进入权限管理页面，开通所需权限：
- 勾选以下权限并点击确认开通（以消息权限为例）：
基础权限（必需）
| 权限标识 | 类型 | 说明 |
|---|---|---|
contact:user.base:readonly |
用户信息 | 获取基础用户信息 |
im:message |
消息 | 收发消息 |
im:message.p2p_msg:readonly |
私聊 | 读取机器人私聊消息 |
im:message.group_at_msg:readonly |
群聊 | 接收群内 @机器人 的消息 |
im:message:send_as_bot |
发送 | 以机器人身份发送消息 |
im:resource |
媒体 | 上传/下载图片和文件 |
可选权限（按需开通）
| 权限标识 | 类型 | 说明 |
|---|---|---|
im:message.group_msg |
群聊 | 读取群内所有消息（敏感权限） |
im:message:readonly |
消息 | 获取消息历史记录 |
im:message:update |
消息 | 编辑/更新已发送的消息 |
im:message:recall |
消息 | 撤回已发送的消息 |
im:message.reactions:read |
互动 | 查看消息的表情回复 |
- 进入添加应用能力页面，开启机器人能力。点击添加。
- 进入凭证与基础信息页面，复制 App ID 和 App Secret 并妥善保存，后续配置 OpenClaw 时需要使用。
- 进入版本管理与发布页面，点击创建版本：
- 填写版本信息，点击发布。
注意：此处先完成首次发布即可，事件订阅将在后续步骤中配置。
- 点击【创建版本】，申请线上发布：
- 管理员进入管理后台 ：进行应用审核（如果发版后的状态为“待审核”），进入企业管理，点击审核
- 管理员审核通过：
三、在 OpenClaw Dashboard 中配置飞书
在 OpenClaw 的 Raw Config 中启用飞书插件并填入飞书应用凭证，使 Gateway 能够与飞书建立连接。
部署完成后，回到 OpenClaw Dashboard 页面。
1. 进入配置编辑器
点击左侧菜单栏的 Config，进入配置页面。切换到 Raw Config（原始配置）编辑模式，可以看到一段 JSON 格式的配置内容。
什么是 JSON？ 简单理解，它是一种用大括号
{}和引号""组织数据的格式。接下来只需要按照说明，在指定位置添加几行文字即可。
2. 启用飞书插件
在配置中找到 "plugins" → "entries" 部分，您会看到类似这样的内容：
1"entries": {
2 "wecom": {
3 "enabled": true
4 },
5 "wecom-app": {
6 "enabled": true
7 },
8 ...
9 "dingtalk-connector": {
10 "enabled": true
11 }
12}在最后一个插件（如 "dingtalk-connector"）的 } 后面，加一个英文逗号，然后添加以下两行：
1"feishu": {
2 "enabled": true
3}添加后效果如下（注意 dingtalk-connector 末尾新增的逗号）：
1 "dingtalk-connector": {
2 "enabled": true
3 },
4 "feishu": {
5 "enabled": true
6 }3. 添加飞书频道配置
在配置中找到 "commands" 部分，您会看到类似这样的内容：
1"commands": {
2 "native": "auto",
3 "nativeSkills": "auto"
4},在 "commands" 整个段落的 }, 后面（注意这里已经有逗号了），粘贴以下内容：
1"channels": {
2 "feishu": {
3 "enabled": true,
4 "dmPolicy": "pairing",
5 "accounts": {
6 "main": {
7 "appId": "替换为你的AppID",
8 "appSecret": "替换为你的AppSecret"
9 }
10 }
11 }
12},重要：将
替换为你的AppID和替换为你的AppSecret替换为第二步中从飞书开发者后台复制的实际值。注意保留两边的英文引号""。
4. 保存配置
检查无误后，点击页面上的 Save 或 Apply 按钮保存配置。系统将自动验证配置格式并重启 Gateway 使其生效。
如果保存时提示格式错误，请检查是否遗漏了逗号 , 或引号 ""，或者多了多余的逗号。
四、回到飞书配置事件订阅
OpenClaw 侧配置完成后，回到飞书开发者后台设置长连接事件订阅，并再次发布新版本使配置生效。
为什么要回来？ 飞书的事件订阅（长连接方式）需要在 OpenClaw Gateway 已经运行并配置好飞书凭证之后才能生效。因此必须先完成上一步，再来配置事件订阅。
- 回到 飞书开发者后台，进入你的应用，进入事件与回调。
- 进入事件与回调页面，将订阅方式设置为使用长连接接收事件，并添加事件
im.message.receive_v1。
回调配置设置订阅方式为长连接，但是不用添加回调：
- 进入版本管理与发布页面，再次创建新版本并发布，使事件订阅配置生效。
五、测试
创建飞书群聊，将机器人拉入群中，@机器人 发送消息验证是否正常回复。
- 在飞书中创建一个群聊：
- 添加机器人到群中：
- 确认机器人信息：
- 在群内 @机器人 并发送一条消息进行测试：
提示：机器人需要被拉入群聊后才能接收消息。所有的消息都需要@机器人才可以得到回复。
六、常见问题
Q1：在群里 @机器人发消息，机器人完全没有反应
依次检查以下几项：
| 检查项 | 如何确认 | 解决方法 |
|---|---|---|
| 飞书应用是否已发布上线 | 飞书开发者后台 → 版本管理与发布，确认状态为「已上线」 | 如果是「审核中」或「未发布」，需等待审核通过或创建版本发布 |
| 机器人能力是否已开启 | 飞书开发者后台 → 添加应用能力，查看是否有「机器人」 | 如未开启，开启后需重新创建版本并发布 |
| 事件订阅是否已配置 | 飞书开发者后台 → 事件与回调，查看是否有 im.message.receive_v1 事件 |
添加事件后需重新创建版本并发布 |
| 事件订阅方式是否正确 | 飞书开发者后台 → 事件与回调，确认为「使用长连接接收事件」 | 如果选了「将事件发送至请求网址」（Webhook 方式），需改为长连接方式 |
| 配置事件订阅后是否重新发布了版本 | 飞书开发者后台 → 版本管理与发布 | 事件订阅修改后必须重新创建版本并发布才能生效 |
| OpenClaw 中飞书插件是否启用 | Dashboard → Config，检查 plugins.entries 中是否有 "feishu": { "enabled": true } |
按第三节步骤添加 |
| OpenClaw 中飞书凭证是否填写正确 | Dashboard → Config，检查 channels.feishu.accounts.main 中的 appId 和 appSecret |
核对是否与飞书开发者后台「凭证与基础信息」页面一致，注意不要有多余空格 |
Q2：机器人回复了错误信息，提示「No API key found for provider」
这说明 OpenClaw 的模型 API Key 未配置。打开 Dashboard → Config，检查 models.providers.qianfan.apiKey 字段是否有值。如果为空 ""，填入部署时使用的千帆 API Key 并保存。
Q3：飞书开发者后台配置事件订阅时，保存长连接失败
这通常是因为 OpenClaw Gateway 尚未启动或飞书凭证未正确配置。请确认：
- OpenClaw 已成功部署且 Dashboard 能正常访问
- 已在 Dashboard Config 中正确填入了飞书的 App ID 和 App Secret 并保存生效
- 之后再回到飞书开发者后台配置事件订阅
Q4：Dashboard Config 保存时提示格式错误
JSON 格式要求严格，常见错误包括：
- 缺少逗号：每个
}或]之后，如果后面还有其他内容，需要加英文逗号, - 多余逗号：最后一项的末尾不能有逗号（例如
"enabled": true,}是错误的） - 引号不匹配：所有的键和值都需要用英文双引号
""包裹，不能用中文引号"" - 大括号不匹配：每个
{都需要有对应的}
小技巧：可以将配置内容复制到 JSON 在线校验工具 中检查格式是否正确。
Q5：机器人只在群聊中响应，私聊不回复
这是正常现象。默认配置中 dmPolicy 设置为 "pairing"，私聊需要额外的配对审批流程。建议通过建群并拉入机器人的方式使用，操作更简单。