VS Code / Cursor 中 Codex 任务完成通知配置指南

整理时间2026-07-01环境Windows 10/11 · VS Code / Cursor · Codex 插件openai.chatgpt1. 背景与目标在使用 Cursor 时Agent 完成长任务后会弹出系统级通知切到其他窗口也能看到。而在 VS Code / Cursor 中安装Codex 插件后默认没有同等体验。本文记录为何没有内置通知、尝试过哪些方案、最终如何在 Windows 上实现可用配置以及踩过的坑。2. 为什么 VS Code 插件里没有「通知」设置2.1 界面上的现象打开 Codex 侧边栏 →Settings → 常规通常只能看到语言、速度、代码审查编辑器发送快捷键、跟进行为没有「通知」相关选项。2.2 技术原因Codex 扩展与 Codex 桌面应用共用部分 UI 代码但通知设置被限制在 Electron 桌面应用中显示代码里用electron{true}包裹。因此在 VS Code / Cursor 的 Webview 里该区块会被隐藏。运行环境设置 → 常规 → 通知系统级完成通知Codex 桌面应用有有较完善VS Code / Cursor 插件无无内置2.3 VS Code 扩展 API 的限制OpenAI 官方在 GitHub #3962、#7083 等 issue 中说明VS Code 扩展难以像 Cursor 一样直接发 OS 级通知扩展内 Toast 在窗口失焦时几乎看不到该能力仍在社区请求中尚未作为插件一等公民功能提供结论不是配置漏了而是插件本身就不提供与 Cursor 对等的通知 UI。3. 可选方案概览方案是否适用于 VS Code 插件说明插件内 Settings → 通知否仅桌面应用可见[tui].notifications否仅 CodexCLI 终端有效notify钩子 外部脚本是设计上官方称扩展也会调用VibeNotificationpip install理论是Windows 实测失败Python 3.14 缺termiosCodex 桌面应用是通知最完整可与插件同步会话自建notify.py是本次采用Windows 兼容、可维护4. 推荐路径notify钩子4.1 原理Codex 在~/.codex/config.tomlWindows%USERPROFILE%\.codex\config.toml中支持notify [命令, 参数1, ...]当 Codex 发出agent-turn-complete事件一轮 Agent 任务结束时会调用该命令并传入JSON 字符串作为最后一个参数。常见字段type通常为agent-turn-completethread-id、turn-idcwd工作目录last-assistant-message最后一条助手消息外部脚本据此播放声音、弹出 Windows 通知即可。4.2 与tui.notifications的区别[tui] notifications [agent-turn-complete] # 仅 CLI/TUI扩展无效切勿在插件场景下只配[tui]不会有任何效果。4.3 可靠性说明OpenAI 在 GitHub #13020 称notify对 VS Code 扩展有效部分用户反馈扩展模式下偶发不触发可通过日志验证见下文notify目前主要覆盖「一轮完成」不包含审批/需要你输入时的提醒5. 实际操作过程5.1 尝试 VibeNotification未采用pip install vibe-notification python-m vibe_notification--test结果在 Windows Python 3.14 上报错ModuleNotFoundError: No module named termiostermios为 Unix 专用模块VibeNotification 在 import 阶段即失败无法在 Windows 上作为python -m vibe_notification使用。5.2 采用自建 Windows 通知脚本创建文件C:\Users\24385\.codex\notify.py功能读取 Codex 传入的 JSON 参数仅当type agent-turn-complete时处理通过 PowerShell 播放系统提示音SystemSounds.Asterisk通过NotifyIcon显示气泡通知写入日志C:\Users\24385\.codex\notify.log5.3 修改 config.toml在%USERPROFILE%\.codex\config.toml中设置notify [python, C:\\Users\\24385\\.codex\\notify.py]注意路径使用双反斜杠\\符合 TOML 字符串转义规则。5.4 本地模拟测试不依赖 Codexpython-cimport subprocess, json; payloadjson.dumps({type:agent-turn-complete,thread-id:test,turn-id:test,cwd:rC:\\Users\\24385\\Desktop,last-assistant-message:Test: Codex task completed}); subprocess.run([python, rC:\\Users\\24385\\.codex\\notify.py, payload])预期听到提示音右下角出现气泡通知notify.log中出现event typeagent-turn-complete sent notification### 5.5 在 VS Code 中生效 1. **完全重启** VS Code / Cursor使 Codex 重新加载 config.toml 2. 在 Codex 插件中发起一个稍长的任务 3. 切换到其他窗口等待完成 4. 查看 C:\Users\24385\.codex\notify.log 是否有新记录 | 日志内容 | 含义 | |----------|------| | 无新行 | 扩展可能未调用 notify需考虑桌面应用或其它方案 | | event typeagent-turn-complete sent notification | 钩子已触发通知已发送 | | skip: invalid json | 参数格式异常检查 Codex 版本或脚本 | --- ## 6. 踩坑config.toml UTF-8 编码错误 ### 6.1 现象 Codex 报错无法加载配置Failed to read config file C:\Users\24385.codex\config.tomlinvalid utf-8 sequence of 1 bytes from index 146### 6.2 原因 在 config.toml 中加入**中文注释**时若编辑器或工具以错误编码保存如 GBK 字节被当作 UTF-8会产生非法 UTF-8 序列。Codex 使用 Rust 严格解析 UTF-8会直接拒绝加载。 问题字节示例index 146 附近\xd4\xad\xc4\xda\xd6\xc3 notify…### 6.3 修复 1. **删除**含乱码的中文注释行 2. 仅保留 ASCII 配置例如 toml notify [python, C:\\Users\\24385\\.codex\\notify.py]验证文件合法性python-copen(rC:\Users\24385\.codex\config.toml,rb).read().decode(utf-8); print(UTF-8 OK)python-cimport tomllib; tomllib.load(open(rC:\Users\24385\.codex\config.toml,rb)); print(TOML OK)重新打开 Codex 对话串6.4 建议config.toml中优先使用英文注释或确保以UTF-8无 BOM保存修改后先用上述命令验证再交给 Codex 加载7. Windows 系统权限配合使用即使脚本正常也需在系统中允许通知设置 → 系统 → 通知找到Visual Studio Code或Cursor开启通知允许横幅/通知中心确认专注助手未屏蔽 IDE8. 若仍不满意Codex 桌面应用若 VS Code 插件环境下notify不稳定可改用Codex Desktop AppSettings → Notifications可配置从不 / 仅后台 / 始终任务完成或需要审批时通知更可靠与 VS Code 插件会话可同步同一项目参考Codex app features - Notifications9. 当前最终配置摘要项目值配置文件C:\Users\24385\.codex\config.tomlnotify 命令python C:\Users\24385\.codex\notify.py通知脚本C:\Users\24385\.codex\notify.py调试日志C:\Users\24385\.codex\notify.log触发事件agent-turn-complete一轮任务结束config.toml 关键片段notify [python, C:\\Users\\24385\\.codex\\notify.py]10. 流程图决策是是否/备选是否需要 Codex 完成通知使用 VS Code 插件?插件内无通知设置配置 notify 钩子Windows?VibeNotification 可能不可用使用自建 notify.py确保 config.toml 为 UTF-8重启 IDE 并测试 notify.logCodex 桌面应用 Notifications日志有 agent-turn-complete?通知链路正常11. 参考链接Codex Advanced Config - NotificationsCodex app - Notifications 设置GitHub: VS Code extension notifications #7083GitHub: notify hook vs extension #13020VibeNotificationmacOS/Linux 更成熟12. 一句话总结VS Code Codex 插件没有 Cursor 式内置通知在 Windows 上可通过config.toml的notify钩子 自建notify.py实现任务完成时的声音与气泡提醒并务必保证config.toml为合法 UTF-8通过notify.log验证扩展是否真正调用了钩子。