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

Image

本指南旨在指导您完成在飞书中配置QClaw的全过程，实现飞书与QClaw平台之间的无缝连接与通信，让您能够便捷地通过飞书机器人操控QClaw的功能。

配置前准备工作

在开始具体的配置步骤之前，请务必确认您已满足以下两项基本条件：

  • 确保电脑上已安装并运行QClaw客户端。
  • 准备一个具备应用创建权限的飞书企业账号。

详细配置步骤

整体操作流程概览

整个配置流程的核心可以概括为：在飞书开放平台创建并配置一个企业自建应用（机器人），获取该应用的凭证（App ID 和 App Secret），最后将这些凭证填入到QClaw的相应设置中，从而建立两者之间的关联。

分步操作详解

您可以通过以下两种方式之一来完成配置。

方式一：快速创建（推荐）

访问飞书开放平台，使用“创建 OpenClaw 飞书机器人”功能，该功能可协助您一键完成机器人的创建。创建成功后，直接复制生成的 App ID 和 App Secret，并将其填入QClaw的配置界面即可快速完成对接。

Image Image

方式二：手动创建与配置

如果您需要更精细的控制，或快速创建功能不可用，请按照以下详细步骤手动操作。

第一步：在飞书开放平台创建应用并获取凭证

  1. 登录与创建应用 使用您的飞书账号登录飞书开放平台（建议使用个人账号登录，若使用企业账号，后续步骤可能需要管理员审核）。登录成功后，点击页面上的 【创建企业自建应用】 按钮。

    重要提示： 请确保使用飞书（Feishu）登录，而非国际版 Lark。 Image

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

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

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

  5. 粘贴权限列表 在弹出的权限导入窗口中，请先清空输入框内的默认内容。然后将下方提供的完整权限列表（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"  
    ]  
  }  
}

    Image 注意： 如果粘贴后提示格式错误，请检查您创建的应用类型是否为“企业自建应用”，而非“商店应用”。 等待几秒钟，页面会显示权限已成功添加，点击右下角的 「确认」 按钮。 Image

  6. 获取应用凭证 在应用详情页左侧菜单中，点击进入 「凭证与基础信息」 页面。在此页面中，您可以直接查看到该应用的 App ID 和 App Secret，请妥善复制并保存它们。 Image

第二步：在QClaw中关联飞书应用
  1. 在您的电脑上启动 QClaw 客户端。
  2. 点击界面左下角的设置按钮，进入设置菜单，选择 「远控通道」 选项。
  3. 在远控通道列表中找到并选择 「飞书」，然后点击其右侧的 「配置」 按钮。
  4. 在弹出的配置窗口中，准确填入从上一步复制的 App ID 和 App Secret。
  5. 点击 「连接」 按钮，等待系统提示绑定成功。 Image
第三步：发布飞书应用版本

关键提醒： 必须先完成上一步，确保QClaw与飞书应用成功连接后，再返回飞书开放平台创建并发布版本，否则机器人将无法正常接收和响应消息。

  1. 配置事件订阅方式 返回飞书开放平台的应用详情页。在左侧菜单中，点击进入 「事件与回调」 页面。找到“订阅方式”旁边的 「编辑」 按钮并点击。 Image 在弹出的编辑窗口中，将订阅方式选择为 「使用 长连接 接收事件」，然后点击 「保存」。 Image

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

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

  4. 创建并发布应用版本 点击页面上方的 「创建版本」 按钮。在弹出的窗口中，填写版本号（例如：1.0.0）、版本描述（例如：首次发布用于QClaw对接），然后点击 「确定」 以创建版本。

    重要提示： 应用必须成功发布后，才能在飞书客户端中被搜索和使用。 Image Image

测试与使用

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

  2. 进行连通测试 在对话窗口中，向机器人发送一条简单的测试消息，例如“你好”。如果所有配置均正确无误，QClaw 将会处理这条消息，并通过机器人给您回复。 Image 结果说明： 如果您能收到机器人正常的回复，那么恭喜您，这表明 QClaw 与飞书的对接已完全成功！🎊

故障排查与常见问题

1. 机器人没有响应怎么办？ 如果发送消息后机器人毫无反应，请按顺序检查以下几点：

  • 检查应用状态： 确认飞书开放平台中的应用版本已成功发布，且处于“已启用”状态。
  • 检查 QClaw 运行状态： 确保电脑上的 QClaw 客户端正在后台正常运行，没有意外关闭。
  • 检查网络连接： 确保您的电脑网络通畅，能够正常访问互联网。

2. 收不到消息或回调不工作怎么办？ 如果机器人能收到消息但QClaw无反应，或交互卡片无效，请检查：

  • 确认事件订阅： 在飞书开放平台“事件与回调”中，确认已正确添加 「接收消息」 事件。
  • 确认回调配置： 同样在“事件与回调”的“回调配置”页签下，确认已添加 「卡片回传交互」 回调。