结论先说
- Codex CLI 分两套通知机制:
[tui]内置终端提醒,以及顶层notify外部程序调用。 - 只想要窗口失焦响铃或终端桌面通知,配
[tui]即可,支持按agent-turn-complete(回合完成)和approval-requested(请求审批)过滤。 - 想调自定义脚本或发群机器人消息,在
~/.codex/config.toml顶层配notify = ["程序", "脚本路径"]。 notify只能写在用户级~/.codex/config.toml(且在所有[表]之前);写在项目.codex/config.toml里会被 Codex 出于安全原因直接忽略并警告。- ChatGPT 桌面端自带独立通知开关与活动视图(快捷键
Ctrl+Alt+U/Cmd+Option+U);IDE 扩展没有独立开关,需在所连接的 Codex 主机上配notify。

图:本站根据 Codex 官方文档:Notifications 整理的示意图
本文根据 Codex 官方文档《Notifications》《Advanced Configuration》与《Sample Configuration》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。Claude Code 的同类完成提醒配法见 Claude Code 任务完成提醒、提示音、Windows 通知怎么设。
适用于谁
- 让 Codex CLI 跑多文件修改或跑测试,切去别的窗口干活时总错过它停下来等指令的人;
- 想在回合结束时自动触发桌面弹窗、声音提醒,或把结果发到飞书、企业微信、Slack Webhook 的开发者;
- 在仓库
.codex/config.toml里配了notify却发现完全不生效的人。
一、轻量方案:开启 CLI 内置终端提醒([tui])
如果不需要写外部脚本,只想在切到浏览器或编辑器时收到终端响铃或系统气泡,直接在 ~/.codex/config.toml 的 [tui] 表下配置(也可在会话内输入 /config 搜索通知项修改):
toml
[tui]
# 布尔值或事件过滤数组:设为 true 全开,也可只订指定事件
notifications = ["agent-turn-complete", "approval-requested"]
# 终端提醒方式:auto(默认,优先 OSC 9 转义序列,不支持则回退响铃)| osc9 | bel
notification_method = "auto"
# 触发时机:unfocused(默认,仅终端窗口失焦时提醒)| always(始终提醒)
notification_condition = "unfocused"
官方说明:在 auto 模式下,Codex 优先发送 OSC 9 终端序列(iTerm2、Windows Terminal 等现代终端可将其识别为桌面通知),终端不支持时回退为标准响铃符 BEL(\x07)。
二、进阶方案:用顶层 notify 调用外部脚本或 Webhook
当内置终端提醒不够用(比如你在远程服务器上跑 CLI,希望回合一结束就往手机或办公群推一条消息),就用顶层 notify。

图:本站根据 Codex 官方文档:Advanced Configuration 整理的示意图
1. config.toml 写法位置
打开 ~/.codex/config.toml,务必写在文件最上方、任何 [xxx] 表头之前(TOML 语法规则详见 Codex config.toml 完整详解):
toml
notify = ["python3", "/Users/yourname/.codex/notify.py"]
Windows 原生环境下如果系统命令是 python,就把第一项写成 "python",第二项写脚本绝对路径(如 "C:/Users/yourname/.codex/notify.py")。
2. Codex 传给脚本的 JSON 参数结构
每次触发支持事件(官方写明当前仅支持 agent-turn-complete)时,Codex 会把一段 JSON 字符串作为单个命令行参数(sys.argv[1])传给你的程序,包含以下常用字段:
type:事件名,当前为"agent-turn-complete";thread-id:会话 ID;turn-id:当前回合 ID;cwd:会话所在工作目录;input-messages:触发本回合的用户输入消息列表;last-assistant-message:Codex 最后一条回复正文。
3. 最小可用 Python 脚本示例(本站跨平台补充)
官方原文示例调用了 macOS 的 terminal-notifier。下面这段脚本按官方相同的 JSON 解析方式编写,macOS 用系统自带 osascript、Windows 用终端响铃与提示,你也可以把末尾替换成 urllib.request 发往自己的群机器人地址:
python
#!/usr/bin/env python3
import json
import platform
import subprocess
import sys
def main() -> int:
data = json.loads(sys.argv[1])
if data.get("type") != "agent-turn-complete":
return 0
msg = (data.get("last-assistant-message") or "Turn Complete")[:80]
cwd = data.get("cwd", "")
if platform.system() == "Darwin":
subprocess.run(["osascript", "-e", f'display notification "{msg}" with title "Codex 完成" subtitle "{cwd}"'])
else:
print("\a", end="", flush=True)
return 0
if __name__ == "__main__":
sys.exit(main())
三、桌面端、网页版与 IDE 扩展怎么看进度提醒
不同客户端入口的通知分工不同(桌面端与 CLI 的整体差异见 Codex App 和 CLI 哪个好用):
- ChatGPT 桌面端:打开 设置(Settings),可设置回合完成提醒是「从不」「仅当应用在后台时」还是「始终」弹出,并能单独开关权限审批提醒与提问提醒(首次开启需允许操作系统通知权限)。侧边栏点击铃铛图标(或按 Windows
Ctrl+Alt+U、macOSCmd+Option+U)可打开 活动(Activity) 视图集中查看未读、运行中或等待回复的会话;还可开启桌面悬浮宠物(Pets)直观显示Running、Needs input、Ready、Blocked状态。 - ChatGPT 网页版:进入 设置(Settings)> 通知(Notifications) 管理推送、邮件等通知渠道。
- IDE 扩展:官方说明扩展本身没有独立的通知设置面板;若需要回合完成外部通知,请在扩展所连接的本机或远程 Codex 主机配置
notify。
跑长耗时重构或多会话并行任务时,套餐额度消耗也会加快;需要补充个人或高强度额度可查看本站 ChatGPT Plus 充值说明 或 ChatGPT Pro 充值说明。
常见问题
问:为什么把 notify 写进项目仓库的 .codex/config.toml 完全不触发?
答:这是官方刻意设计的安全限制。如果允许仓库配置定义 notify,克隆别人的代码就可能自动执行任意外部程序,所以项目级 .codex/config.toml 里的 notify 一律被忽略。
问:需要审批命令时,notify 外部脚本会被调用吗?
答:官方《Advanced Configuration》写明 notify 目前只支持 agent-turn-complete 事件;如果你想在等待审批时收到提醒,请同时把 [tui] 下的 notifications 配上 "approval-requested"。
问:在全屏 TUI 里开了提醒还是没声音怎么办?
答:先把 notification_method 显式改成 "bel"、notification_condition 改成 "always" 测试,同时确认你的终端模拟器本身没有关闭提示音(Bell)。其他斜杠命令可查 Codex 命令行常用命令一页看。
相关教程
参考资料
- Codex 官方文档:Notifications — https://learn.chatgpt.com/docs/notifications
- Codex 官方文档:Advanced Configuration — https://learn.chatgpt.com/docs/config-file/config-advanced
- Codex 官方文档:Sample Configuration — https://learn.chatgpt.com/docs/config-file/config-sample
0 条评论
还没有评论,来抢沙发~