| # | 条件 | 说明 | 本手册覆盖 |
|---|---|---|---|
| 1 | 事件订阅已开通 | 飞书开放平台已为 bot 订阅drive.notice.comment_add_v1 事件 |
✅ 第二节 |
| 2 | 权限已开通 | bot 已申请评论读写等相关权限并通过审核 | ✅ 第二节 |
| 3 | 应用已发布 | 权限变更后应用已重新发布上线 | ✅ 第二节 |
| 4 | Agent 已运行 | bot 背后的 Agent 部署完成，可接收并处理该事件 | ✅ 第三节 |
| 5 | 文档已授权 | 具体文档已将访问权限授予该 bot | ✅ 第四节 |
scopes.tenant 中：
```
{
"scopes": {
"tenant": [
"drive:drive.metadata:readonly",
"docs:document.comment:create",
"docs:document.comment:delete",
"docs:document.comment:read",
"docs:document.comment:update",
"docs:document.comment:write_only",
"docx:document:create",
"docx:document:readonly",
"docx:document:write_only",
"docx:document.block:convert"
],
"user": []
}
}
```
### Step 4：重新发布应用
权限变更后必须重新发布，新权限才会生效。 进入「版本管理与发布」 → 创建并提交新版本，等待审核通过后上线。
### 附录：（Agent 专用）一键配置链接
> 本小节仅面向 Agent 执行场景：人类用户按 Step 1–4 操作即可，跳过本小节。
如果你是 Agent 在帮用户配置本节，可以用一条一键配置 URL 让用户点击代替手动 Step 1–4 全套（事件订阅 \+ 长连接 \+ 评论权限 \+ 发布）。
cli_xxxxxxxxxxxxxxxx）。<APP_ID> 替换为实际值：clientID：上一步拿到的 App ID。tp=ccm：配置模板类型，这里传入 tp=ccm（云文档场景）。
1. 把 URL 用代码块原样发给用户（不要做 Markdown 链接化、不要 URL 编码）。用户在飞书里点开链接 → 点击页面里的「开通并授权」按钮即可。回退条件： 用户反馈点开 404、模板选项明显不对，或者部署环境只能用公网
open.feishu.cn时，跳过本附录、按 Step 1–4 手动操作。
openclaw --version \| 命令存在且有版本输出 \| 选项 A：本地 OpenClaw \| \| 2 \| ls ~/.hermes/.env \| 文件存在 \| 选项 B：Hermes Agent \| \| 3 \| 询问用户是否使用云端部署（妙搭龙虾 / Arkclaw 等） \| 用户确认是 \| 选项 C：云端 OpenClaw \| \| 4 \| 以上均不匹配，或用户确认使用自建框架 \| — \| 选项 D：自建 Bot \|
识别完成后，向用户说明：
> "我判断你的环境是 [选项 X：名称] ，接下来准备执行：\[步骤列表\]。请确认是否继续。"
>
>
>
> 确认后再进入对应选项的配置步骤。
### 选项 A：本地 OpenClaw
#### 版本要求
推荐版本：OpenClaw 2026.4.12
```
// 安装到 4.12 版本
npm install -g openclaw@2026.4.12
// 检查版本是否准确
openclaw --version
```
预期输出：版本号包含 2026.4.12。
#### 重启 OpenClaw
```
openclaw gateway restart
```
> 重启后 OpenClaw 需要初始化飞书文档相关配置，建议等待 2–3 分钟后再发送测试评论。
#### 验证连接状态
```
openclaw gateway status
```
预期输出：包含连接成功信息（如 Connected to Feishu 或类似字样）。
#### （可选）开启 Full 工具模式
如果遇到 bot 无法读取文档内容或写入评论，执行：
```
openclaw config set tools.profile "full"
openclaw gateway restart
```
### 选项 B：Hermes Agent
#### 前置条件
已完成 Hermes 飞书 Channel 接入配置。
> 💡 Channel 是什么： 相当于 Hermes 里的"飞书机器人前台"，负责处理消息收发、去重、多媒体文件、卡片交互等底层逻辑，开发者只需关注用户输入、机器人回复和后续业务处理。
如未完成 Channel 接入，先参考官方文档。
#### 确认 .env 配置
打开 ~/.hermes/.env，确认以下字段存在且正确：
```
FEISHU_APP_ID=cli_xxx # 飞书开放平台的 App ID
FEISHU_APP_SECRET=your_secret # 对应的 App Secret
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket # 必须是 websocket（长连接）
```
#### 配置允许 @bot 的用户白名单
Hermes 默认只回复白名单内的用户，其他人 @bot 会被忽略。编辑 ~/.hermes/feishu_comment_rules.json，在 allow_from 中填入允许的 open\_id：
```
{
"enabled": true,
"policy": "allowlist",
"allow_from": ["ou_xxxxxxxx", "ou_yyyyyyyy"],
"documents": {}
}
```
#### 重启 Hermes
```
hermes gateway restart
```
> ⏱️ 重启后 Hermes 需要初始化飞书文档相关配置，建议等待 2–3 分钟后再发送测试评论。
#### 验证某用户是否已放行
```
python -m gateway.platforms.feishu_comment_rules check feishu.state 为 connected：
```
{
"gateway_state": "running",
"platforms": {
"feishu": {
"state": "connected"
}
}
}
```
若 feishu.state 不是 connected，重新执行 hermes gateway restart。
### 选项 C：其他 OpenClaw（妙搭龙虾 / Arkclaw/ Coze Claw/ TRAE 等）
#### 社区版 OpenClaw 版本要求
Agent 需判断底层使用的是否为社区版 OpenClaw，社区版 OpenClaw 的版本要求为 OpenClaw 2026.4.12。
以妙搭龙虾为例，可登录 控制台，在实例详情中查看当前版本。若版本不足，在控制台执行版本升级。
若仍有疑问，请咨询当前 Agent 平台官方客服。
#### 飞书官方 OpenClaw 插件版本要求
若 Agent 还依赖飞书官方 OpenClaw 插件（@larksuite/openclaw-lark），最低版本要求 2026.4.7（含 tools-version ≥ 1.0.37）。
升级方式因平台而异（Arkclaw、Coze Claw 等各家入口不同）。以妙搭龙虾为例：登录控制台 → 打开实例终端 → 执行以下命令：
```
npx -y @larksuite/openclaw-lark@2026.4.7 install --version 2026.4.7 --tools-version 1.0.37
```
升级后必须重启实例（见下一节）。
#### 重启实例
在 Agent 控制台找到对应实例，执行重启操作。
> 重启后同样建议等待 2–3 分钟再测试。
### 选项 D：自建 Bot（其他框架）
开放平台侧配置和其他选项完全一样（按第二节做）。自建 vs A/B/C 的核心差异：选项 A/B 的 OpenClaw / Hermes 本身、以及选项 C 的官方 OpenClaw 插件，都内置了一层「长连接接收飞书事件 \+ dispatch」的 gateway——自建 bot 没有，必须自己实现。
#### 核心能力清单
drive.notice.comment_add_v1 事件 payload 取 file_token / comment_id / mention_list，确认 bot 自己在 mention 列表里，再触发业务逻辑。tenant_access_token 管理和请求格式）；裸 HTTP 也能跑但更费力。@[你的 bot 名称] 并发送 1. 预期结果：bot 在 2 分钟内在该评论下回复
## 六、排查清单
Bot 未回复时，按顺序逐项检查： \| \# \| 检查项 \| 验证方式 \| 预期结果 \| \| \-\- \| \-\-\-\-\-\-\-\-\-\- \| \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \| \-\-\-\-\-\-\-\-\-\-\-\-\- \| \| 1 \| 事件已订阅 \| 飞书开放平台 → 事件与回调 \| 列表中有 drive.notice.comment_add_v1 \| \| 2 \| 使用长连接 \| 飞书开放平台 → 事件配置 / 回调配置 \| 均显示「长连接」 \| \| 3 \| 权限齐全 \| 飞书开放平台 → 权限管理 \| 表格中的 10 个 scope 均已申请并通过 \| \| 4 \| 应用已发布 \| 飞书开放平台 → 版本管理 \| 最新版本状态为「已上线」 \| \| 5 \| Agent 正在运行 \| 见第三节各选项验证步骤 \| 网关状态：connected \| \| 6 \| 文档已授权 \| 云文档中 hover bot mention \| popover 显示已授权
\| 逐项检查完仍未解决： \- 本地 OpenClaw：执行 openclaw gateway restart，等 3 分钟后重新测试 \- Hermes：检查 ~/.hermes/gateway_state.json 确认 feishu.state = connected \- 云端 OpenClaw：在控制台重启实例后重新测试
## 七、已知限制