# 飞书开发者后台配置指南

要让机器人收发消息，需要在[飞书开放平台](https://open.feishu.cn/app)完成以下配置。
下面按“最小权限”原则给出默认配置对应的步骤。

## 1. 创建企业自建应用

1. 打开飞书开发者后台，创建一个**企业自建应用**。
2. 进入「凭证与基础信息」，记下 **App ID**（`cli_` 开头）和 **App Secret**。

## 2. 启用机器人能力

1. 进入「添加应用能力」。
2. 添加「机器人」能力，设置机器人名称与头像。

## 3. 添加权限

默认配置（单聊 + 群聊 @机器人 + 回复）需要以下三个权限：

| 权限标识 | 用途 | 是否必需 |
| --- | --- | --- |
| `im:message.p2p_msg:readonly` | 获取用户发给机器人的单聊消息 | 是 |
| `im:message.group_at_msg:readonly` | 获取群组中 @机器人的消息 | 是 |
| `im:message:send_as_bot` | 以应用身份发消息（回复） | 是 |
| `im:chat:readonly` | 读取群信息（判断群主/管理员） | 仅群聊 `/reset` 需管理员权限时 |

> 只申请 `group_at_msg:readonly` 时，机器人在群聊里**只会收到 @它的消息**，
> 因此插件默认 `requireMention: true` 无需额外过滤。

> **关于群聊 `/reset`**：默认开启「只有群主/管理员才能重置」（防止群成员随手清掉共享任务）。
> 这个判定要调用 `im.chat.get`，所以**必须额外开通 `im:chat:readonly` 权限**，否则群主发
> `/reset` 也会被当成“非管理员”而拒绝。如果你不需要这个限制，可以在配置里设置
> `requireAdminForGroupReset: false`（群成员也能重置），此时无需 `im:chat:readonly`。

如果希望处理群聊里**没有 @机器人**的普通消息，需要额外申请范围更大的
`im:message.group_msg`（通常要管理员审批），并把配置改为 `requireMention: false`。

权限变更可能需要企业管理员审批；测试时若机器人能加入群但收不到/发不出消息，
先确认权限是否仍在待审批状态。

## 4. 配置长连接事件订阅

1. 进入「事件与回调」/「事件订阅」。
2. 事件接收方式选择 **「使用长连接接收事件」**（不要填 Webhook 地址）。
3. 添加事件 **`im.message.receive_v1`**（接收消息）。
4. 保存。

长连接由插件主动连接飞书，所以本地电脑 / 内网环境也能跑。

## 5. 发布并安装应用

1. 创建应用版本，提交审核或发布到测试范围。
2. 把应用安装到当前企业。
3. 在飞书里找到机器人发起单聊，或把机器人拉进测试群。

> 只改后台配置而不发布新版本，事件和权限通常不会对已安装的应用生效。

## 6. 快速自检清单

- [ ] 已创建自建应用，拿到 App ID / App Secret
- [ ] 已启用机器人能力
- [ ] 已开通上表三个权限，且已通过审批
- [ ] 事件订阅方式为长连接，且订阅了 `im.message.receive_v1`
- [ ] 已发布版本并安装到企业
- [ ] 机器人能收到单聊，或群里 @机器人 能触发
- [ ] 确认没有其它进程（如 OpenClaw 的飞书通道）同时连着同一个应用的长连接

> **关于“一个应用多个长连接消费者”**：飞书平台会把每条事件**随机分发**给其中一个已连接
> 的消费者。如果同一个 App ID/Secret 同时被两个程序（例如本插件 + OpenClaw 的飞书通道）
> 连接，消息会被“抢走”——表现为时好时坏、第二条消息没反应、或收到别家程序的回复。
> 排查“偶发没反应/回复内容不对”时，先确认是否只有本插件这一个长连接在跑。