QClaw接入飞书详细教程：技术联调与配置指南

摘要：QClaw是一款本地智能体控制台，可通过飞书对话框远程调度本地电脑执行任务。本文详细介绍了QClaw接入飞书的技术指南，包括在飞书开放平台创建应用、挂载机器人与事件订阅、注入通信参数及联调测试。

想象一下，在飞书的工作群里，你只需要输入一句自然语言指令，就能让办公室的电脑自动帮你整理报表、查找文件，甚至执行更复杂的桌面任务。这听起来像是科幻场景，但借助QClaw这款本地智能体控制台，它已经成为了现实。QClaw的核心价值，正是打破了聊天软件与本地操作系统之间的物理屏障，让你在熟悉的对话窗口中，就能直接调度本地电脑。

图源：AI生成示意图

一、飞书开放平台建用

要让QClaw听懂飞书里的指令，第一步是为它在飞书云端建立一个合法的“身份”。这个过程，就好比为新员工办理入职手续。

首先，登录飞书开放平台（https://open.feishu.cn/），进入“开发者后台”。点击“创建企业自建应用”，填入一个清晰的应用名称，例如“本地QClaw助手”，然后保存。

应用创建成功后，身份凭证的获取是关键。在左侧菜单栏进入“凭证与基础信息”页面，你会找到App ID和App Secret。这两个参数相当于应用在飞书生态内的“身份证”和“密钥”，务必妥善记录，后续每一步都离不开它们。

图源：AI生成示意图

二、应用能力与权限挂载

有了身份之后，下一步是赋予这个应用“行动能力”，让它能够接收和发送消息。这就像给新员工配置办公电脑和开通系统权限。

在开发者后台的左侧导航栏找到“添加应用能力”，选择并开启“机器人（Bot）”功能。这是应用能够以聊天机器人形式交互的基础。

接着，进入“事件订阅”页面。这里是配置的核心：你需要填入QClaw所在本地机器的公网可访问回调地址（即请求URL）。如果你的QClaw运行在办公室或家中的电脑上（通常处于内网），就需要借助内网穿透工具（例如cpolar）来生成一个稳定的HTTPS链接并填入此处。

同时，在事件订阅页面，系统会提供Verification Token与Encrypt Key。这两个加密参数用于后续消息的安全校验与加解密，同样需要记录下来。

最后，别忘了进入“权限管理”，为应用开通“接收消息”、“发送消息”等必要的基础权限。至此，应用在云端的能力配置就基本完成了。

简单来说，飞书服务器在云端，而QClaw在你的物理电脑上。事件订阅中配置的请求URL，就是连接这两端的通信桥梁，它确保了你在飞书群里的每一条指令，都能被精准投递到内网中的电脑网关。

图源：AI生成示意图

三、QClaw端参数注入

云端配置妥当后，工作重心就转移到了本地。现在，需要用刚才获取的“钥匙”来打开QClaw的通信通道。

启动本地QClaw控制台，找到飞书集成的配置界面。你需要将前两步收集到的关键参数一一对应填入：

• App ID & App Secret：填入从飞书开放平台获取的凭证。
• Verification Token & Encrypt Key：填入从事件订阅页面获取的加密参数。
• 请求URL：这里填入的地址，必须与你在飞书事件订阅中配置的请求URL完全一致。

这个过程本质上是建立一条双向的、加密的通信隧道。飞书端用这些参数来识别和加密消息，QClaw端则用同样的参数来解密和验证消息来源，确保指令既安全又准确。

图源：AI生成示意图

四、版本发布与执行联调

所有参数配置完成后，就到了最后的验证与上线环节。

首先，回到飞书开放平台，找到“版本管理与发布”。创建一个新版本，提交审核并发布。通常企业自建应用可以快速通过。发布后，你可以在飞书工作台中找到刚刚上线的应用，将其添加至群聊或作为独立应用使用。

真正的考验在于联调测试。在飞书群聊中@你的机器人，或者直接向它发送一条测试指令，比如“帮我列出桌面上的文件”。

观察几个关键点：飞书是否显示消息已送达机器人？本地QClaw控制台的日志里，是否收到了这条消息的解密记录？本地电脑是否成功执行了相应的任务，并将结果反馈回了飞书对话框？

如果一切顺利，恭喜你，你已经成功搭建了一条从云端对话到本地执行的自动化流水线。从此，远程调度电脑处理任务，就像在群里聊天一样简单。

这个过程看似步骤不少，但每一步都环环相扣。从云端创建身份、配置能力，到本地注入密钥、建立隧道，再到最后发布联调，本质上是在构建一个安全、可靠的远程RPC（远程过程调用）机制。一旦跑通，其带来的效率提升将是革命性的。

图源：AI生成示意图