飞书渠道接入

本文指导管理员完成飞书机器人的接入：在飞书开放平台创建应用、在管理后台配置渠道，并验证用户绑定与对话。渠道凭据通过管理后台「渠道」页配置并持久化到 identity-service，不要使用 FEISHU_BIND_* 环境变量（见 业务配置 - 渠道连接器）。

前置准备

1. 飞书开放平台管理员账号（https://open.feishu.cn/app）。
2. FinClaw 已完成部署，且管理员账号已注册并加入 .env 的 ADMIN_EMAILS（见 管理员注册）。
3. feishu-connector 服务正常运行（默认端口 26460，健康检查 GET /health，见服务健康检查）。

飞书开放平台创建应用

创建应用并获取凭证

浏览器打开 https://open.feishu.cn/app，使用飞书管理员账号登录，点击「创建企业自建应用」，填写应用名称、描述、上传应用图标，提交创建。

在应用详情页「凭证与基础信息」中，记录 App ID 和 App Secret（下一步填入管理后台）。

配置事件订阅

在「事件与回调」->「事件配置」中，选择「使用长连接接收事件」，保存。feishu-connector 通过 WebSocket 长连接接收事件，无需公网回调地址。

在「事件与回调」->「事件订阅」中，添加以下事件：

事件	Event	用途
接收消息	im.message.receive_v1	接收用户发给机器人的消息
卡片回传交互	card.action.trigger	处理消息卡片上的按钮回调（绑定卡片等）

添加完成后的事件订阅列表：

启用机器人能力

在「添加应用能力」->「机器人」中，启用机器人能力。

开通权限

在「权限管理」中，搜索并开通以下权限：

权限	用途
im:message	获取与发送单聊、群聊消息
im:message:send_as_bot	以机器人身份发送消息
im:resource	获取消息中的资源文件（图片、文件等附件）

发布应用

在「版本管理与发布」中，创建版本并提交审核；审核通过后应用生效。

验证：应用详情页显示「已发布」状态，事件订阅列表已包含上述两个事件。

管理后台配置渠道

浏览器打开 FinClaw 管理后台，使用管理员账号登录。渠道配置按租户生效，需先在租户下拉框中选择目标租户，再进入「渠道」页面。

找到「飞书」渠道卡片，点击「配置」，填入上一节记录的 App ID 和 App Secret，保存。

在「账号绑定」中填入绑定地址（bind_base_url，FinClaw 对外可达的 Web 地址，如 https://chat.example.com）。该地址为飞书、钉钉、企业微信三个渠道共用；用户在 IM 中点击绑定按钮时，打开 {bind_base_url}/feishu-bind?token=... 页面完成登录与绑定。

绑定 token 的签名密钥 bind_state_secret 由 identity-service 在设置绑定地址时自动生成并保存在服务端，无需人工配置。

将飞书渠道的「启用」开关置为开启，点击「保存」。

保存后 identity-service 会调用 feishu-connector 的 POST /internal/reload 通知其重新加载配置；connector 在进程内应用新配置（按需断开并重建飞书 WebSocket 连接），不重启容器。

验证：

1. 渠道卡片状态由「可用」变为「已连接」（状态来自 connector 的 ws_connected 上报，保存后需等待数秒刷新页面）。
2. feishu-connector 日志出现 feishu.connector.reload、feishu.lark_client.started 事件（见服务日志查看）。
3. 可运行 doctor.sh，其 "IM Channel Bind Config" 段会检查绑定地址配置是否完整（见渠道连通性巡检）。

用户绑定与使用

在飞书客户端中搜索并打开机器人会话，发送「你好」（单聊直接发送；群聊需 @机器人）。

首次使用时，机器人检测到该用户未绑定 FinClaw 账号，会回复一张绑定卡片。点击卡片中的「去登录/注册」按钮，打开 {bind_base_url}/feishu-bind?token=... 页面，按提示登录（或注册）FinClaw 账号后即完成绑定。

绑定完成后，即可在飞书中与机器人正常对话。

常见问题

现象	排查方向
渠道状态一直为「可用」，未变「已连接」	确认 App ID / App Secret 正确、应用已发布；查看 feishu-connector 日志中的 WebSocket 连接错误
机器人不回复消息	确认已订阅 im.message.receive_v1 且事件配置为「长连接」模式；确认渠道已启用
收到「请在管理后台配置绑定地址」类提示	「账号绑定」未设置绑定地址，或保存未生效；用 doctor.sh 的 "IM Channel Bind Config" 段检查
群聊中发消息无响应	群聊场景需 @机器人触发