连接飞书

此连接面向中国区飞书的企业自建应用，不包含国际版 Lark。准备好能创建和发布应用的权限、一个工作区，以及保持在线的 ClawPi 客户端。

创建应用并启用机器人

进入飞书开发者后台，创建企业自建应用，填写名称和说明，添加机器人能力。在“凭证与基础信息”中找到 App ID 与 App Secret。

每个独立 ClawPi 连接账号使用独立应用。不要把同一应用同时连接到多台运行中的客户端，否则事件可能被分发给其他连接。

配置事件与权限

按飞书控制台的事件订阅说明选择“使用长连接接收事件”，添加接收消息事件 im.message.receive_v1。该事件名不是权限名称，不要把它填入权限搜索后以为已完成订阅。

要完成的操作	在平台中核对的能力
接收机器人私聊	接收用户发给机器人的单聊消息
接收群内指令	接收群聊中 @ 机器人的消息
回复消息	以应用身份发送消息
收发图片与文件	消息资源的读取、上传等相关权限

只申请当前用途需要的权限，按平台提示完成管理员审核。回复权限可对照飞书发送消息文档。ClawPi 使用出站长连接，不需要公网回调地址。

在 ClawPi 中连接

1. 打开“消息渠道 → 飞书 → 添加账号”。
2. 将同一应用的 App ID 填入 appId，App Secret 填入 appSecret 并提交。密钥不会回显。
3. 如果飞书保存长连接配置时提示未检测到连接，保持此客户端运行，再返回平台完成保存。
4. 在飞书创建并发布应用版本，确认机器人能力、事件和权限已生效，并把测试成员加入可用范围。
5. 回到 ClawPi 检查“已连接”，从飞书私聊机器人发送文字，在电脑端批准配对。

成功标志：任务出现在对应工作区，结果回到飞书来源会话。连接状态正常只说明传输连接成立，不能替代应用发布、权限和配对检查。

排查不回消息

现象	检查顺序
找不到机器人	机器人能力、应用发布状态、成员可用范围
已连接但无配对请求	消息接收事件、私聊或群聊权限、是否 @ 机器人
电脑执行了但飞书没回复	发送消息权限、消息资源权限、客户端错误提示
回复时有时无	是否多台电脑共用同一个 App ID

群聊需要每位发送者分别配对。后续操作见连接与配对，附件交付见文件与附件。