飞书接入腾讯QClaw完整指南:手把手教你实现机器人互联

本教程将详细指导您如何在飞书中配置腾讯 QClaw,实现飞书平台与 QClaw 服务之间的无缝连接与信息互通。
前置条件
开始配置之前,请务必确认已满足以下所有必要条件:
- 您已在本地计算机上成功安装并运行 QClaw 客户端。
- 您拥有一个飞书企业账号,并且该账号具备在企业内部创建和配置自建应用的权限。
流程指引
整体流程概览
实现飞书与 QClaw 互联的核心流程可以概括为:在飞书开放平台创建一个企业自建应用,获取该应用的 App ID 和 App Secret 凭证,最后将这些凭证信息填入 QClaw 的对应配置项中。
详细配置步骤
方法一:快速创建(推荐)
- 访问飞书开放平台的“OpenClaw 飞书机器人”创建页面。
- 按照提示一键完成机器人应用的创建。
- 创建成功后,系统会提供 App ID 和 App Secret,直接复制这两组信息。
- 打开 QClaw,将复制的 App ID 和 App Secret 填入相应配置项,即可快速完成绑定。

方法二:手动配置(详细版)
如果您需要更细致的控制,或想了解完整流程,可以按照以下步骤手动配置。
第一步:在飞书开放平台获取 App ID 和 App Secret
-
创建自建应用
- 使用飞书账号登录飞书开放平台(建议使用个人账号登录,若使用企业账号,后续步骤可能需要管理员审批)。
- 登录后,在控制台找到并点击 【创建企业自建应用】。
重要提示: 请确保使用飞书(Feishu)账号登录,而非 Lark 国际版账号。

-
填写应用信息
- 在弹出的窗口中,根据要求填写应用名称、描述等基本信息,然后点击 「创建」 按钮。
- 应用创建成功后,页面会自动跳转到该应用的详情页面。

-
添加机器人能力
- 在应用详情页的 「添加应用能力」 区域,找到 「机器人」 功能卡片,并点击其上的 「添加」 按钮。

- 在应用详情页的 「添加应用能力」 区域,找到 「机器人」 功能卡片,并点击其上的 「添加」 按钮。
-
导入权限
- 在应用详情页左侧的菜单栏中,点击进入 「权限管理」 页面。
- 在该页面找到并点击 「批量导入 / 导出权限」 选项。

- 在弹出的权限导入窗口中,清空输入框内的所有默认内容。
- 将下方提供的完整权限列表代码复制,并粘贴到清空后的输入框中。
- 点击 「下一步,确定新增权限」,接着点击 「申请开通」。
{ "scopes": { "tenant": [ "contact:contact.base:readonly", "docx:document:readonly", "im:chat:read", "im:chat:update", "im:message.group_at_msg:readonly", "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:readonly", "im:message:recall", "im:message:send_as_bot", "im:message:send_multi_users", "im:message:send_sys_msg", "im:message:update", "im:resource", "application:application:self_manage", "cardkit:card:write", "cardkit:card:read" ], "user": [ "contact:user.employee_id:readonly", "offline_access", "base:app:copy", "base:field:create", "base:field:delete", "base:field:read", "base:field:update", "base:record:create", "base:record:delete", "base:record:retrieve", "base:record:update", "base:table:create", "base:table:delete", "base:table:read", "base:table:update", "base:view:read", "base:view:write_only", "base:app:create", "base:app:update", "base:app:read", "board:whiteboard:node:create", "board:whiteboard:node:read", "calendar:calendar:read", "calendar:calendar.event:create", "calendar:calendar.event:delete", "calendar:calendar.event:read", "calendar:calendar.event:reply", "calendar:calendar.event:update", "calendar:calendar.free_busy:read", "contact:contact.base:readonly", "contact:user.base:readonly", "contact:user:search", "docs:document.comment:create", "docs:document.comment:read", "docs:document.comment:update", "docs:document.media:download", "docs:document:copy", "docx:document:create", "docx:document:readonly", "docx:document:write_only", "drive:drive.metadata:readonly", "drive:file:download", "drive:file:upload", "im:chat.members:read", "im:chat:read", "im:message", "im:message.group_msg:get_as_user", "im:message.p2p_msg:get_as_user", "im:message:readonly", "search:docs:read", "search:message", "space:document:delete", "space:document:move", "space:document:retrieve", "task:comment:read", "task:comment:write", "task:task:read", "task:task:write", "task:task:writeonly", "task:tasklist:read", "task:tasklist:write", "wiki:node:copy", "wiki:node:create", "wiki:node:move", "wiki:node:read", "wiki:node:retrieve", "wiki:space:read", "wiki:space:retrieve", "wiki:space:write_only" ] } }
注意: 如果粘贴代码后提示格式错误,请检查您创建的应用类型是否为 “企业自建应用”,而不是“商店应用”。
- 等待几秒钟,页面会提示权限已成功添加,点击右下角的 「确认」 按钮。

-
获取凭证
- 在应用详情页左侧菜单中,点击进入 「凭证与基础信息」 页面。
- 在该页面中,您可以找到并复制 App ID 和 App Secret 这两项关键信息。

第二步:在 QClaw 中关联飞书应用
- 打开电脑上的 QClaw 客户端,点击界面左下角的设置图标,进入设置菜单。
- 在设置菜单中,找到并进入 「远控通道」 配置页面。
- 在远控通道列表中选择 「飞书」,然后点击其旁边的 「配置」 按钮。
- 在弹出的配置窗口中,粘贴您从飞书开放平台复制的 App ID 和 App Secret。
- 点击 「连接」 或 「绑定」 按钮,完成 QClaw 与飞书应用的关联。

第三步:在飞书中创建并发布应用版本
关键提醒: 必须在 QClaw 中成功连接飞书应用后,再返回飞书开放平台创建应用版本,才能确保消息互通功能正常。
-
配置事件回调
- 返回飞书开放平台的应用详情页,在左侧菜单中点击进入 「事件与回调」 页面。
- 在“订阅方式”一栏旁边,点击 「编辑」 按钮。

- 在弹出的窗口中,将订阅方式选择为 「使用 长连接 接收事件」,然后点击 「保存」。

-
添加“接收消息”事件
- 在 「事件配置」 区域,点击 「添加事件」 按钮。
- 在事件搜索框中输入“接收消息”,找到后点击 「添加」。

-
配置“卡片回传交互”回调
- 切换到 「回调配置」 页签。
- 在 「回调配置」 区域,点击 「添加回调」 按钮。
- 搜索并找到 「卡片回传交互」,点击 「添加」。

-
创建并发布版本
- 点击页面上方的 「创建版本」 按钮。
- 在弹出的窗口中,填写版本号(例如:1.0.0)和版本描述(例如:首次发布),然后点击 「确定」。
- 版本创建后,您需要将其提交发布。只有发布后的应用才能在飞书中被正常使用。

开始使用与连通测试
-
找到机器人
- 应用发布成功后,您会在飞书的聊天列表里收到来自 「开发者小助手」 的“应用审批通过,已发布成功”通知,点击通知中的 「打开应用」 即可开始使用。
- 或者,您也可以在飞书顶部的搜索框中,直接搜索您创建的机器人应用名称,找到并点击进入与它的对话窗口。

-
发送测试消息
- 在对话窗口中,向机器人发送一条简单的测试消息,例如“你好”。
- 如果所有配置均正确无误,QClaw 将会接收到这条消息,并通过机器人在飞书中给您回复。

成功提示: 如果机器人能够正常接收消息并给出回复,恭喜您!这标志着 QClaw 与飞书的对接已圆满成功。
常见问题排查
1. 机器人没有响应怎么办?
- 检查应用状态: 确认您在飞书开放平台创建的应用已成功发布最新版本。
- 检查 QClaw 运行状态: 确保您电脑上的 QClaw 客户端正在后台正常运行,没有意外退出。
- 检查网络连接: 确保您的电脑网络连接稳定,能够正常访问互联网及飞书服务。
2. 收不到机器人的消息怎么办?
- 确认事件订阅: 返回飞书开放平台,在应用的 「事件与回调」 页面,确认已正确添加 「接收消息」 事件。
- 确认回调配置: 同样在 「事件与回调」 页面,检查是否已正确配置 「卡片回传交互」 回调。