说明：本文由 OpenClaw 助手根据一次真实配置与排障过程辅助整理，内容经过人工确认。
文中涉及的应用 ID、用户 ID、群 ID、内部路径、具体租户信息和业务邮件内容均已脱敏或泛化。重点不是某个账号的私有配置，而是一次身份与权限排障中暴露出来的分层方法。
在接入飞书能力时，最容易让人误判的一句话是：
“我已经授权了，为什么还是不行？”
这句话听起来很具体，实际非常宽。因为“授权”可能指很多层：用户点了 OAuth 卡片、CLI 已经登录 user、bot 申请了 scope、bot 拿到了某类资源 privilege、当前 workspace profile 指向了正确应用，或者只是另一个工具链里的权限状态变了。
如果这些层混在一起解释，排障会越走越乱。我们这次就是从“应该能直接搜飞书邮箱”开始，一路拆到最后确认：问题不是一个授权按钮没点，而是几层身份和权限没有对齐。
1. 症状：想读个人邮箱，但工具一直读不到
最初的需求很简单：需要读取飞书邮箱里的完整邮件 thread，用于还原一段外部技术沟通的上下文。
第一反应会很自然：既然飞书插件已经能读消息、文档、任务，那邮箱也应该能搜到。
但实际尝试后发现：
- 转发到群里的邮件卡片只能看到摘要，不是完整 thread。
- 个人邮箱读取需要 user 身份，因为这是用户个人资源。
- 当前 lark-cli 运行环境被限制在 bot 身份。
- 改用 bot 身份读取时，又遇到邮箱 privilege 或 mailbox scope 不足。
所以表面症状是“邮箱读不到”，但真正的问题不是“邮箱 API 坏了”，而是身份链路没有拆清楚。
2. 第一次误归因：把 OpenClaw 插件授权当成 lark-cli 登录
过程中用户完成过一次飞书授权。授权完成后，直觉上会以为“现在应该好了”。
但这里有一个关键差异：OpenClaw 内置飞书插件的 OAuth 授权，和 lark-cli 的 user 登录授权，不是同一件事。
可以这样理解：
- OpenClaw 插件授权：让当前 OpenClaw 的 feishu_* 工具获得某些用户授权能力。
- lark-cli user 登录：让 lark-cli 这套命令行工具能够以某个用户身份访问资源。
- bot scope：让应用机器人具备调用某类 API 的基础权限。
- bot privilege：让机器人真的能访问某些用户或组织资源。
- workspace profile / app profile：决定当前命令到底在用哪一套应用配置。
用户点了某张 OAuth 卡片，并不自动代表 lark-cli 已经有 user session；也不代表 bot 已经有邮箱 privilege；更不代表当前 workspace profile 正在用正确应用。
这就是这次排障里第一个重要收窄：不要说“授权失败”，要问“哪一层授权失败”。
3. 第二次收窄：确认当前 CLI 被锁成 bot-only
接下来排查的关键不是继续猜，而是看当前 lark-cli 到底处于什么身份模式。
通过 CLI 配置状态可以确认几件事：
strict-mode: bot
default-as: bot
users: no logged-in users
这三行信息非常关键。
它们说明当前环境不是“默认用 bot，但也可以切 user”，而是被 strict mode 明确限制成只允许 bot 身份。也就是说，即使用户愿意授权，也不能直接让 agent 代替用户去关掉这个限制。
这是安全策略，不是普通偏好配置。
所以 user 身份路径被挡住了：
想用 user 身份读个人邮箱
→ strict mode = bot
→ user identity 不允许使用
这时再继续说“重新授权一下”就没有意义了，因为真正的阻塞点不是用户 OAuth 没点，而是当前 CLI 身份策略不允许 user。
4. 第三次收窄：bot 有 scope 也不等于能读个人邮箱
既然 user 身份被挡住，那能不能退一步，用 bot 身份读邮箱？
这又暴露了第二层差异：bot scope 和 bot privilege 也不是一回事。
scope 更像“这个应用理论上可以调用某类 API”。但个人邮箱这类敏感资源，通常还需要额外 privilege，明确允许 bot 访问对应用户邮箱或对应资源范围。
因此 bot 路线会变成：
用 bot 身份读邮箱
→ 需要邮箱相关 scope
→ 还可能需要用户邮箱 privilege
→ 没有 privilege 时仍然 permission denied
这解释了一个常见困惑：为什么补了 scope，错误消息变了，但功能仍然不通？
因为补 scope 只修了一层。后面还有 privilege、资源范围和 profile 指向问题。
5. 正确模型：权限排障要画成层，而不是揉成球
这次之后，我会把飞书 / Lark 相关权限问题按下面顺序拆：
调用入口
→ 当前工具链：OpenClaw 插件？lark-cli？原生 API？
→ 当前 profile：workspace profile 指向哪个 app？
→ 当前身份：bot / user / auto？
→ 身份限制：strict-mode 是否允许目标身份？
→ 登录状态：user 是否已 login？
→ API scope：应用是否有目标 API 权限？
→ resource privilege：是否有目标资源访问特权？
→ 目标资源：是个人邮箱、个人日历、云文档、群消息，还是 bot 自有资源？
只有这样拆，错误才会从“授权不行”变成可执行的修复项。
例如这次的问题，最终可以压缩成两条可选路径：
路径 A：走 user 身份
允许 lark-cli 使用 user identity
→ 用户完成 mail domain login
→ 读取个人邮箱
路径 B：走 bot 身份
保留 bot identity
→ 给 bot 补邮箱 API scope
→ 给 bot 开通访问目标邮箱的 privilege
→ 用 bot 读取被授权资源
这两个路径都合理，但它们的安全含义完全不同。不能混着修。
6. 为什么 AI agent 不能替用户关 strict-mode
这次还有一个很重要的安全边界：即使用户在聊天里说“授权你改”，agent 也不应该自己去关闭 strict-mode。
原因很简单：strict-mode 是管理员设置的身份限制策略，作用就是防止 agent 自己扩大身份边界。
如果 agent 可以在遇到权限问题时自己把 bot-only 改成 off，那这个策略就没有意义了。
更安全的做法是：
- agent 可以诊断并解释当前卡在哪一层；
- agent 可以给出用户手动执行的命令或后台配置路径；
- agent 不应该自己绕过身份限制；
- 对外发送、删除、移动、改权限、发邮件这类 user 身份动作，即使 user 身份可用，也必须二次确认。
权限系统的目标不是让 agent 永远顺利执行，而是让它知道哪些地方必须停下来。
7. 这次真正有价值的不是修邮箱，而是把问题变窄
这次排障最有价值的地方，不是多试了几个命令，而是把一个宽问题不断变窄：
读不到邮箱
→ 是不是邮件卡片不是完整 thread？
→ 是不是需要 user 身份？
→ 当前 lark-cli 是否允许 user？
→ strict-mode 是什么？
→ bot 路线是否缺 scope？
→ scope 之后是否还缺 privilege？
→ 当前 profile 指向的是哪套 app？
问题越窄，系统越能被修。
一个宽问题通常只能得到宽答案：重新授权、检查权限、重试一下。
一个窄问题可以直接变成工程动作：切换 profile、补 scope、开 privilege、执行 user login、或者明确停在安全策略边界。
8. 后续规则：默认 bot，个人资源显式 user，高风险动作再确认
这次之后，我认为更合理的飞书双身份规则是：
- 默认使用 bot 身份，适合群聊回复、机器人通知、团队助手、bot 自有资源。
- 读取个人邮箱、个人日历、用户可见消息、用户云空间等个人资源时，显式使用 user 身份。
- 不依赖默认身份猜测，命令里尽量显式写明 bot 或 user。
- 任何以 user 身份对外发送、删除、移动、改权限、发邮件、回复邮件、邀请外部人，都必须先确认对象、内容和后果。
也就是说，strict-mode off 并不等于“随便用用户身份”。它只是允许双身份存在。真正的安全边界应该由默认身份、显式身份选择和二次确认共同组成。
9. 小结
这次排障留下的核心教训很简单：
不要把“权限问题”当成一个整体。
遇到身份权限类问题，先拆层：
OpenClaw 插件 OAuth
lark-cli user 登录
bot scope
bot privilege
workspace profile / app profile
目标资源类型
每一层都有不同的证据、不同的错误信息、不同的修复动作。
如果把它们混在一起，就会出现最糟糕的体验：用户觉得自己已经授权了，agent 觉得还是没有权限，双方都没错，但问题就是修不好。
真正可靠的排障，不是更快给出答案，而是更快把问题变窄。
这也是我越来越喜欢的一条工程原则：
抽象问题无法修复。只有窄到能被具体技术手段验证的问题，才会开始变得可修。