飞书接入腾讯QClaw完整教程:从创建应用到实现机器人交互

本指南旨在指导您完成在飞书中配置QClaw的全过程,实现飞书与QClaw平台之间的无缝连接与通信,让您能够便捷地通过飞书机器人操控QClaw的功能。
配置前准备工作
在开始具体的配置步骤之前,请务必确认您已满足以下两项基本条件:
- 确保电脑上已安装并运行QClaw客户端。
- 准备一个具备应用创建权限的飞书企业账号。
详细配置步骤
整体操作流程概览
整个配置流程的核心可以概括为:在飞书开放平台创建并配置一个企业自建应用(机器人),获取该应用的凭证(App ID 和 App Secret),最后将这些凭证填入到QClaw的相应设置中,从而建立两者之间的关联。
分步操作详解
您可以通过以下两种方式之一来完成配置。
方式一:快速创建(推荐)
访问飞书开放平台,使用“创建 OpenClaw 飞书机器人”功能,该功能可协助您一键完成机器人的创建。创建成功后,直接复制生成的 App ID 和 App Secret,并将其填入QClaw的配置界面即可快速完成对接。

方式二:手动创建与配置
如果您需要更精细的控制,或快速创建功能不可用,请按照以下详细步骤手动操作。
第一步:在飞书开放平台创建应用并获取凭证
-
登录与创建应用 使用您的飞书账号登录飞书开放平台(建议使用个人账号登录,若使用企业账号,后续步骤可能需要管理员审核)。登录成功后,点击页面上的 【创建企业自建应用】 按钮。
重要提示: 请确保使用飞书(Feishu)登录,而非国际版 Lark。

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

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

-
批量导入权限 在应用详情页左侧的导航菜单中,点击进入 「权限管理」 页面。在该页面找到并点击 「批量导入 / 导出权限」 按钮。

-
粘贴权限列表 在弹出的权限导入窗口中,请先清空输入框内的默认内容。然后将下方提供的完整权限列表(JSON格式)复制并粘贴到输入框中。粘贴完成后,依次点击 「下一步,确定新增权限」 和 「申请开通」。
{ "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与飞书应用成功连接后,再返回飞书开放平台创建并发布版本,否则机器人将无法正常接收和响应消息。
-
配置事件订阅方式 返回飞书开放平台的应用详情页。在左侧菜单中,点击进入 「事件与回调」 页面。找到“订阅方式”旁边的 「编辑」 按钮并点击。
在弹出的编辑窗口中,将订阅方式选择为 「使用 长连接 接收事件」,然后点击 「保存」。

-
添加“接收消息”事件 仍在 「事件与回调」 页面的 「事件配置」 区域,点击 「添加事件」 按钮。在事件搜索框中输入“接收消息”,找到对应的事件后点击添加。

-
配置回调 切换到同一页面下的 「回调配置」 页签。首先确认顶部的订阅方式已设置为 「使用 长连接 接收事件」。 在 「回调配置」 区域,点击 「添加回调」 按钮。搜索 「卡片回传交互」,找到后点击 「添加」 按钮将其加入回调列表。

-
创建并发布应用版本 点击页面上方的 「创建版本」 按钮。在弹出的窗口中,填写版本号(例如:1.0.0)、版本描述(例如:首次发布用于QClaw对接),然后点击 「确定」 以创建版本。
重要提示: 应用必须成功发布后,才能在飞书客户端中被搜索和使用。

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

-
进行连通测试 在对话窗口中,向机器人发送一条简单的测试消息,例如“你好”。如果所有配置均正确无误,QClaw 将会处理这条消息,并通过机器人给您回复。
结果说明: 如果您能收到机器人正常的回复,那么恭喜您,这表明 QClaw 与飞书的对接已完全成功!🎊
故障排查与常见问题
1. 机器人没有响应怎么办? 如果发送消息后机器人毫无反应,请按顺序检查以下几点:
- 检查应用状态: 确认飞书开放平台中的应用版本已成功发布,且处于“已启用”状态。
- 检查 QClaw 运行状态: 确保电脑上的 QClaw 客户端正在后台正常运行,没有意外关闭。
- 检查网络连接: 确保您的电脑网络通畅,能够正常访问互联网。
2. 收不到消息或回调不工作怎么办? 如果机器人能收到消息但QClaw无反应,或交互卡片无效,请检查:
- 确认事件订阅: 在飞书开放平台“事件与回调”中,确认已正确添加 「接收消息」 事件。
- 确认回调配置: 同样在“事件与回调”的“回调配置”页签下,确认已添加 「卡片回传交互」 回调。