配置飞书应用
第一次配置通常需要 5～10 分钟。跟着本页逐步操作即可，不需要提前了解飞书开放平台。
不要选择 Webhook 自定义机器人
codex-notify 使用的是企业自建应用机器人：它通过 App ID 和 App Secret 发送消息，只在你的飞书组织内使用。它不是群聊中通过 Webhook 地址配置的“自定义机器人”。
飞书开放平台的界面名称可能会略有调整，找到含有下列关键词的入口即可。
先了解几个常见词
| 名称 | 简单解释 |
|---|---|
| 企业自建应用 | 由你的飞书组织创建和管理的应用，不会公开上架到应用商店 |
| 机器人能力 | 让应用可以用“机器人”的身份向个人或群聊发送消息 |
| 权限 | 明确允许应用调用哪些飞书接口；本项目只需要发送消息相关权限 |
| App ID | 应用的公开编号，用来识别是哪一个应用，通常以 cli_ 开头 |
| App Secret | 应用密钥，相当于这个应用的密码，不能公开或提交到 Git 仓库 |
| 接收者 ID | 告诉飞书把通知发给谁，可以使用邮箱、用户 ID 或群聊 ID |
| 可用范围 | 允许哪些组织成员使用这个应用、接收它发送的消息 |
1. 创建企业自建应用
- 打开飞书开放平台，使用接收通知的飞书组织账号登录。
- 进入“开发者后台”，点击“创建企业自建应用”。
- 填写应用名称，例如
Codex Notify；图标和描述可以按需填写。 - 创建完成后进入应用详情页。后续的机器人、权限、凭证和发布设置都在这里完成。
如果看不到创建按钮，通常是当前账号没有创建应用的权限，请联系飞书组织管理员开通。应用和通知接收者需要属于同一个飞书组织。
2. 添加机器人能力
- 在应用详情页找到“添加应用能力”或“应用能力”。
- 选择“机器人”，然后点击“添加”或“启用”。
- 机器人名称可以直接使用应用名称，其他展示信息按需填写。
这里的“机器人”是应用发送消息时使用的飞书身份。codex-notify 只负责调用它发送通知，不会读取你的飞书聊天记录。
3. 开通发送消息权限
- 打开“权限管理”或“API 权限”。
- 搜索“以应用的身份发消息”，添加对应权限；权限标识通常是
im:message:send_as_bot。 - 如果后台显示“获取与发送单聊、群组消息”，也可以开通这项消息权限。
- 确认权限状态已经生效。部分飞书组织需要管理员审批，处于“待审核”状态时还不能发送通知。
只发送通知不需要开通读取聊天内容的权限。建议遵循最小权限原则，不要添加与发送消息无关的权限。
4. 发布应用并设置可用范围
- 进入“版本管理与发布”，点击“创建版本”。
- 填写版本号和更新说明，例如版本号
1.0.0、更新说明“用于接收 Codex 通知”。 - 在发布页面或飞书管理后台设置“可用范围”，确保通知接收者包含在范围内。
- 提交审核并发布。管理员审核通过后，状态应显示为已发布或已启用。
“发布”是让刚才配置的机器人和权限正式生效。仅保存开发配置还不够，未发布的应用通常无法向用户发送消息。
5. 获取 App ID 和 App Secret
- 打开“凭证与基础信息”。
- 复制 App ID，它通常以
cli_开头。 - 点击查看并复制 App Secret。请像保管密码一样保管它，不要发到聊天、截图或写入公开文件。
初始化时 App Secret 的输入内容会隐藏。codex-notify 会将它明文保存到 ~/.codex-notify/config.toml；在 Unix 系统上，该目录和文件分别限制为仅当前用户可访问的 700 和 600 权限。不要提交或分享这个文件。
6. 选择通知接收者
第一次使用建议选择邮箱：填写接收人的飞书账号邮箱即可，不需要了解飞书内部 ID。
| 接收方式 | 需要填写的内容 | 适用场景 |
|---|---|---|
邮箱 email | 接收人飞书账号绑定的邮箱，例如 name@example.com | 最容易上手，推荐首次使用 |
Open ID open_id | 当前应用下形如 ou_xxx 的用户 ID | 私聊通知；不同应用中的 Open ID 可能不同 |
User ID user_id | 飞书组织为成员设置的内部用户 ID | 已从通讯录管理员或接口获得 User ID |
群聊 ID chat_id | 形如 oc_xxx 的会话 ID | 将通知发到群聊，机器人必须已经加入该群 |
邮箱必须是飞书能够识别的账号邮箱，并且该用户位于应用的可用范围内。如果不确定 Open ID、User ID 或 Chat ID 在哪里获取，直接使用邮箱即可。
发送到群聊
使用 chat_id 前，先把企业自建应用机器人添加到目标群聊。群名不是 Chat ID；Chat ID 是以 oc_ 开头的会话编号，通常需要通过飞书接口或已有管理工具查询。
初始化前检查清单
运行 codex-notify init 前，请确认：
- 企业自建应用已经发布；
- 机器人能力已经启用；
- 发送消息权限已经生效；
- 接收者位于应用可用范围内；
- App ID 和 App Secret 来自同一个应用；
- 如果发送到群聊，机器人已经加入该群。
准备完成后，继续运行初始化。
飞书配置常见问题
测试通知提示没有权限
回到“权限管理”，确认发送消息权限已经通过审批；再到“版本管理与发布”确认包含该权限的版本已经发布。
测试成功，但目标用户没有收到
检查接收者是否属于创建应用的同一个飞书组织，并确认该用户包含在应用的可用范围内。使用邮箱时，还要确认填写的是飞书账号能够识别的邮箱。
App ID 格式不正确
App ID 通常以 cli_ 开头。请回到“凭证与基础信息”复制，不要误填 App Secret、应用名称或机器人名称。
App Secret 粘贴后没有任何字符
这是终端的安全输入方式。直接粘贴并按回车即可，向导随后会明确提示已经收到 App Secret。