上一篇《把飞书变成 AI Agent 的日常操作台》拆的是「AI 在飞书里怎么干活」——运行时接入层的架构和踩坑。但那篇文章默认你已经有了一个能对话的机器人。这篇补上前半截：一个不懂代码的普通人，怎么从零开始，把 AI 真正装进飞书。全程网页后台点击 + 一份五层体检脚本，大概 20 分钟能跑通。
一、先说清楚：这件事其实只有两层
很多人卡在第一步，是因为把「开通」想象成了一个庞然大物。实际拆开看，把 AI 装进飞书只有两层事：
| 层 | 干什么 | 占的工作量 | 需要写代码吗 |
|---|---|---|---|
| 飞书侧开通 | 在飞书开放平台建应用、开权限、订阅事件、发布版本 | 约 80% | 不需要，全程网页后台点击 |
| agent 侧接入 | 把 app_id / app_secret 填进你用的 AI agent 配置 |
约 20% | 复制粘贴一段配置 |
关键点在于：飞书侧这 80% 和你在 agent 侧用什么框架完全无关。你在飞书后台做完所有配置，拿到的唯一产出就是两个值——app_id（形如 cli_xxxxxxxx）和 app_secret。之后不管你是接 Hermes Agent 还是别的任何支持飞书机器人的框架，填的都是这俩。所以本文讲的开通流程是通用的，agent 侧只是最后一步填空。
对普通人的好消息是：飞书侧全是点鼠标，agent 侧好的框架也就几行配置。真正的门槛不在技术，在于飞书后台有一套自己的规矩——这套规矩没人讲清楚，就会被卡在各种「明明配置了却不生效」的玄学里。这正是这篇向导要解决的。
前置条件只有一个：一个飞书账号（个人版即可），并且你是这个组织的管理员——个人免费版组织里你自己就是管理员，所以这条基本自动满足。
二、六步开通链路：建应用 → 能验证
下面是我整理并实战验证过的完整链路，全程在飞书开放平台后台完成，约 15 分钟。
Step 1：创建应用，拿到凭据
开发者后台 → 创建企业自建应用 → 填名称、描述、图标。建好后进应用详情页，左侧「凭证与基础信息」里记下两个值：App ID 和 App Secret（secret 要点「获取」并手机验证码确认）。
⚠️ 拿到 secret 的第一时间存进密码管理器。它等价于这个机器人的全部身份——泄露了，任何人都能以它的名义收发你组织里的消息。
Step 2：开权限（最小三个）
应用详情 → 权限管理 → 搜索开通。跑通「收发消息」的最小可用集就三个：
| 权限 | 干什么用 | 不开会怎样 |
|---|---|---|
im:message（获取与发送单聊、群组消息） |
收用户消息 + 发 AI 回复，基本盘 | 机器人完全无法收发消息 |
im:message.group_at_msg:readonly（获取群组中用户@机器人消息） |
群里 @ 它才响应，不刷屏 | 私聊正常，群里 @ 没反应 |
im:chat（获取群信息） |
知道消息来自哪个群 | 多群场景没法分流 |
注意一个时效性坑：旧教程里的 im:message.group_at_msg（不带 :readonly）已于 2024-09-30 被官方下线，现在开只读版。图片/语音等进阶权限先不开，跑通后再按需补。
Step 3：启用机器人能力（高频遗忘点）
应用详情 → 应用能力 → 机器人 → 启用。不开这个，权限开全了也没有「机器人」这个实体可对话——应用只是个空壳。建应用时它默认是关的，这是最容易漏的一步。
Step 4：配置事件订阅（AI 能收到消息的关键）
应用详情 → 事件与回调 → 事件配置：
- 订阅方式选长连接（WebSocket）。这是个人用户的首选——不需要公网服务器、不需要域名，你的电脑跑 agent 就能收到事件。选 HTTP 回调则需要公网可访问的 https 地址，内网用户直接卡死在这步。
- 添加事件：
接收消息 im.message.receive_v1。 - 提示「权限不足」就回 Step 2 补对应权限。
Step 5：发布版本（最高频遗忘点 ⚠️）
飞书后台有个硬规则：所有权限、能力、可用范围的改动只落在草稿上，必须创建版本并发布才生效。路径：版本管理与发布 → 创建版本 → 填版本号（如 1.0.0）→ 提交。个人/免费组织自己就是管理员，直接通过；企业组织走管理员审批。状态变「已启用」才算上线。
Step 6：验证飞书侧通了
打开飞书客户端（不是网页后台），搜索你的应用名，点进单聊发一句「hi」。此时机器人还不会回复（agent 还没接）——但只要消息没有红色感叹号、机器人能被搜到，说明飞书侧链路已经通了。至此你手上有了 app_id + app_secret，去 agent 侧完成最后接入即可。
三、权限三铁律：比清单本身更重要
权限管理是整个开通流程里最容易反复折腾的部分。比起逐项清单，先记住三条铁律：
- 最小够用。 先只开「收发消息」三个权限跑通，之后缺什么开什么。每开一个都问自己一句「不开会缺什么」，答不上来就别开——机器人权限越大，被 @ 一次它能做的事就越多，也越需要谨慎。
- 开了不发布 = 没开。 权限开通后必须走版本发布才生效。「权限明明开了还是报错」，十有八九是这个原因。
- 报错会告诉你缺哪个。 调用接口报
99991672时，返回体里的error.permission_violations字段会直接列出缺的权限名，照着补就行，不用猜。
这三条里，第 2 条值得展开：它本质上是说飞书后台是「改动」和「发布」两层结构，你所有的操作都在草稿层。把这个机制记牢，后面 70% 的「玄学问题」都有了统一的解释。
四、五层体检脚本：坏了先跑它，直接告诉你断在哪层
向导写到这就完了吗？没有。真正的不确定性在坏了怎么办。配置类问题最折磨人的地方是症状和根因经常对不上：「机器人不回复」可能是权限没开、可能是版本没发、可能是 agent 没启动，肉眼完全分不出来。
我的解法是把整条链路切成五层，写一个体检脚本从底层往上逐层探，停在第一处断掉的层，并直接给出修复指引：
| 层 | 检查什么 | 典型症状 |
|---|---|---|
| L1 凭据有效性 | 用 app_id/secret 换 tenant_access_token | 报 99991543（凭据不存在），多半是抄错或 secret 重置过 |
| L2 权限比对 | 拿 token 调只读接口探权限 | 报 99991672（缺权限），返回体直接告诉你缺哪个 |
| L3 应用状态 | 应用是否启用、机器人能力是否开了 | 飞书里搜不到机器人；报 99991662 |
| L4 事件订阅 | 静态自查清单：长连接进程活着吗 / HTTP 地址公网可达吗 | 搜得到、发消息不报错，但 AI 收不到 |
| L5 agent 侧 | 本机配置文件里 feishu 段是否配对、enabled | 飞书侧全绿但 AI 不理人 |
脚本设计上刻意做了几个决定：纯 Python 标准库、零依赖，任何一台装了 Python3 的电脑直接能跑；只做体检不改配置，凭据只存在进程内存里，退出即消失，不落盘；输出的是「断在第几层 + 怎么修」，而不是一堆原始日志。
这个「分层体检」的思路对普通人特别友好：你去社区提问，只要说一句「doctor 说我断在 L2」，比贴十行报错日志有用得多。
五、踩坑实录：四条最有共鸣的
开通流程走通不难，难的是走通之后反复遇到「改了不生效」。以下四条全部真实发生过（时间：2026-09）：
1. 权限改了不生效 = 忘了发布
后台明明开了权限，机器人行为纹丝不动。根因就是上面说的两层结构：改动只落在草稿，必须创建版本并发布才生效。更隐蔽的是两侧各有一个「改了没生效」的开关——飞书侧要发布版本，agent 侧改完配置要重启——叠在一起极易漏掉一边。预防方法：把「改后台 → 发版本 → 重启 agent → 重测」当成一个不可拆分的固定动作链。
2. 搜不到机器人 = 机器人能力没开
权限全开、版本也发了，飞书里就是搜不到这个应用。根因：应用能力和权限是两回事——没启用「机器人」能力，应用就没有可对话的实体，权限再全也是空转。因为建应用时默认不开，这个坑几乎人人踩一次。预防方法：开通顺序固定为「建应用 → 启用机器人能力 → 开权限 → 事件订阅 → 发布」。
3. restart 连坐自杀
改完配置，我在 agent 的会话里直接让它执行 gateway restart——结果网关把自己所在的会话一起 SIGTERM 杀掉了，restart 命令自己都没走完，会话凭空消失，一度以为 agent 罢工了。根因很直白：restart 会先杀掉旧网关进程，而你正坐在旧网关的会话里，命令执行者和被杀对象是同一个进程树。修复：开一个独立的 shell 会话执行 restart，或者直接对 bot 发 /restart。这条写进肌肉记忆能少很多灵异事件。
4. 一个 bot 绑两台机器，人格分裂
换机器部署时没停掉旧机器，同一个 app_id 被两台机器的 gateway 同时长连接接管。表现为：消息时灵时不灵，回复「人格分裂」——有的回复来自旧机器的旧配置，事件被两边互相抢。根因是架构级的：一个 bot 只绑一个 gateway。修复和预防是同一句话：迁移机器时，旧机器先 stop，新机器再启动。
六、沉淀原则
把向导和坑捋完，真正值得带走的是三条：
- 两层切开，各管各的。 飞书侧 80% 的配置对任何 agent 框架通用，别和具体框架的文档搅在一起读。
- 改动必发布，改配置必重启。 飞书侧的「发布版本」和 agent 侧的「restart」是两颗同名按钮，漏按任何一颗都等于没改。
- 坏了先分层，再动手。 不分层的排查是在黑暗中乱摸；有了 L1–L5 的切分，任何问题都能一句话定位。
七、写在最后
这套开通流程我已经把它整理成了一份完整的向导包：六步开通文档、权限逐项清单、症状速查表和五层体检脚本都在里面，agent 侧附了我自己在用的 Hermes Agent 接入篇（Hermes 是开源项目，见官方文档）。包目前还是 private 的，正在打磨中——等把语音权限等几个 TODO 核对完，大概率会整理共享出来，欢迎到时候来拿。
至此两篇就齐了：这篇讲「怎么把 AI 装进飞书」（开通），前一篇讲「AI 在飞书里怎么干活」（运行时）。装好和用好，中间隔的就是这两件事。
（文中涉及的 Hermes Agent 为开源项目；飞书为字节跳动旗下产品，流程截图与后台 UI 以飞书开放平台官方文档为准。本文不包含任何真实凭据。）