結論先說
- 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 條評論
還沒有評論,來搶沙發~