飞书集成指南

本文档介绍如何将 lsbot 接入飞书（Feishu / Lark）。飞书原生支持 WebSocket 长连接模式，无需公网服务器，直接运行 lsbot gateway 即可。

Copy飞书 App ──WebSocket长连接──> lsbot gateway（你的电脑）──> AI

第一步：创建飞书应用

1. 访问 飞书开放平台
2. 点击 「创建企业自建应用」
3. 填写应用名称和描述，点击 「创建」

第二步：添加机器人能力

1. 进入 「添加应用能力」 → 找到 「机器人」 → 点击添加
2. 填写机器人名称和描述

重要：没有开启机器人能力，用户无法给 bot 发消息。

第三步：配置权限（JSON 批量导入）

进入 「权限管理」 → 点击 「批量导入」，粘贴以下 JSON 一键导入所有需要的权限：

Copy{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

点击 「批量开通」。已有权限会自动跳过，不会重复添加。

第四步：配置事件订阅

⚠️ 必须先启动 lsbot gateway，再做这一步，否则长连接验证会失败。 可以先跳到第五步启动网关，再回来完成事件订阅。

1. 进入 「事件与回调」 → 「事件配置」
2. 页面顶部 「订阅方式」 选择 「使用长连接接收事件」（不是 Webhook！）
3. 点击 「添加事件」，搜索并添加 im.message.receive_v1（接收消息）
4. 点击 「保存」

第五步：启动 lsbot gateway

写入 ~/.lsbot.yaml（推荐）

Copyplatforms:
  feishu:
    app_id: cli_your_app_id
    app_secret: your_app_secret

agents:
  - id: default
    default: true
    provider: minimax
    api_key: YOUR_MINIMAX_API_KEY
    base_url: https://api.minimax.chat/v1
    model: MiniMax-M2.5

然后直接运行：

Copylsbot gateway

或使用命令行参数

Copylsbot gateway \
  --feishu-app-id cli_your_app_id \
  --feishu-app-secret your_app_secret \
  --provider minimax \
  --api-key YOUR_API_KEY

看到日志输出 [Feishu] Credentials verified successfully 和 connected to wss://msg-frontier.feishu.cn 说明连接成功。

现在回到第四步完成事件订阅（如果之前跳过了）。

第六步：发布应用

1. 进入 「版本管理与发布」 → 「创建版本」
2. 填写版本信息，点击 「申请发布」
3. 管理员审批后生效（企业内部应用通常几秒到几分钟自动通过）

每次修改权限或事件订阅后，都需要创建新版本并发布才能生效。

测试

1. 打开飞书，搜索你的机器人名称
2. 私聊：直接发送消息
3. 群聊：将机器人添加到群组，然后 @机器人

故障排除

机器人完全没反应（最常见）

按顺序检查：

1. lsbot gateway 是否在运行？日志中是否有 connected to wss://msg-frontier.feishu.cn
2. 事件订阅是否配置？订阅方式是否选了「使用长连接接收事件」（不是 Webhook）？是否添加了 im.message.receive_v1
3. 应用是否已发布？进入「版本管理与发布」确认有已发布版本
4. 机器人能力是否开启？进入「添加应用能力」确认「机器人」已启用

权限错误 / failed to verify credentials

• App ID 或 App Secret 有误，重新从「凭证与基础信息」复制
• 权限不足：按第三步重新导入 JSON，然后创建新版本并发布

事件订阅保存失败

• lsbot gateway 必须正在运行且已连接，飞书会验证长连接是否存在

群聊无响应

• 确认机器人已添加到群组
• 群聊中必须 @机器人

参考链接

• 飞书开放平台
• 机器人开发指南
• oapi-sdk-go