飞书桥接

通过飞书（或 Lark）应用与 Claude 对话。支持国内版和国际版切换、群组策略控制。

创建飞书应用

国内版（飞书）

1. 前往 飞书开放平台，登录开发者账号
2. 点击 创建企业自建应用
3. 填写应用名称和描述
4. 进入应用详情页，在 凭证与基础信息 中获取：
   • App ID（格式：cli_xxxxxxxxxx）
   • App Secret
5. 在左侧选择 添加应用能力 > 机器人，启用机器人功能
6. 在 事件订阅 中，先选择 使用长连接模式（WebSocket，无需公网地址）：
   • 长连接模式需要先启动才能保存配置 — 点击启用后等待连接建立
   • 连接建立成功后，再添加事件：im.message.receive_v1（接收消息）
   • 保存事件订阅配置
7. 在 权限管理 中申请以下权限：
   • im:message（发送消息）
   • im:message.group_at_msg（接收群聊 @消息）
   • im:message.p2p_msg（接收私聊消息）
8. 发布应用 — 提交审核或自审通过

国际版（Lark）

流程与国内版相同，但在 Lark Developer 上操作。在 CodePilot 配置时选择域名为 Lark。

在 CodePilot 中配置

1. 点击侧边栏 桥接，切换到 飞书 页面
2. 选择域名：飞书（国内版）或 Lark（国际版）
3. 填写 App ID 和 App Secret
4. 点击 测试连接 验证凭据
5. 配置群组策略：
   • 开放 — Bot 响应所有群聊中的 @消息
   • 白名单 — 只响应指定群聊（填写群聊 chat_id）
   • 禁用 — 只响应私聊
6. （可选）需要 @提及 — 开启后群聊中只响应 @Bot 的消息
7. （可选）允许的用户 — 填写飞书 open_id 或 chat_id，限制谁可以使用 Bot
8. 点击 保存

启用桥接

1. 回到桥接总览页面
2. 确保 飞书 渠道开关已打开
3. 确保桥接主开关已开启
4. 点击 启动

消息格式

飞书桥接会将 Claude 的回复转换为飞书消息格式：

• 复杂回复（含代码块、表格等）→ 消息卡片（Interactive Card）
• 简单回复 → 富文本消息（Post）
• 单条消息最大 30000 字符（通常无需分片）

故障排除

测试连接失败

1. 确认 App ID 和 App Secret 正确
2. 确认应用已发布（审核通过）
3. 确认选择了正确的域名（国内版 vs 国际版）

Bot 不响应群聊

1. 确认已添加机器人能力
2. 确认已申请 im:message.group_at_msg 权限
3. 确认群组策略不是"禁用"
4. 如果策略为"白名单"，确认群聊 ID 在允许列表中
5. 如果开启了"需要 @提及"，确保消息中 @了 Bot

Bot 不响应私聊

1. 确认已申请 im:message.p2p_msg 权限
2. 确认应用已发布
3. 在飞书中搜索 Bot 名称，发起私聊