Codexの通知設定｜CLIの完了通知と承認待ちを見落とさず、出ない原因を切り分ける

Codex CLIの通知には、Codexの画面（TUI）が端末へ信号を出すtui.notificationsと、外部プログラムを動かすnotifyの2つがあります。承認待ちを知らせられるのは前者で、後者は公式資料の現時点の説明では作業の完了（agent-turn-complete）だけに対応します。見落としを減らすには、まず知らせたい場面に合う方を選びます。この記事では、2つの違い、設定例、編集部の手元で確かめた動き、通知が出ない時の確認順を説明します。

この記事は、OpenAIの公式資料（Advanced Configuration、Configuration Reference、Hooks、Settings。いずれも2026年11月1日に確認）に基づく解説です。あわせて、編集部がCodex CLI 0.166.0を教材のリポジトリで動かし、端末へ出た信号とnotifyが受け取った内容を記録しました。実測したのは仮想端末の出力までで、macOSの通知センターへの表示や音は確かめていません。WindowsとWSLでは試していません。

Codexの通知は2つ：tui.notificationsとnotifyの違い

公式のAdvanced Configurationによると、2つの違いは次のとおりです。

迷ったら、最初はtui.notificationsだけで始めます。追加のプログラムが要らず、承認待ちも扱えるからです。通知の文面を変えたい、完了を別の場所に残したいという目的が出てきたらnotifyを足します。

デスクトップアプリの通知は別の設定です。公式のSettingsは、完了の通知を出す場面と通知の許可の確認をアプリの設定で選ぶと説明しています。この記事はCLIを扱います。

Codexの完了通知と承認待ち通知を設定する

どちらも~/.codex/config.tomlに書きます。設定ファイル全体の置き場所と優先順位は、config.tomlの解説にまとめています。

Codexの画面の通知を設定する：完了と承認待ち

完了と承認待ちの両方を、端末にフォーカスがない時（別のアプリやウィンドウへ移った時）に知らせる設定です。

[tui]
notifications = ["agent-turn-complete", "approval-requested"]
notification_method = "auto"
notification_condition = "unfocused"

条件は視線や離席ではなく、フォーカスです。端末を前面に置いたまま席を離れても、既定のunfocusedでは出ません。編集部はこの設定を仮想端末で動かし、フォーカスが外れた信号を送った状態で、完了と承認待ちのそれぞれでOSC 9が1回出ることを確かめました（TERM_PROGRAM=iTerm.appを指定）。

キーの一覧は公式のConfiguration Referenceで確かめられます。この資料にnotificationsの既定値は書かれていません。編集部の環境では、このキーを書かずにosc9とalwaysを指定して起動すると、完了でOSC 9が出ました。承認待ちと既定の出し方では確かめていないので、確実に制御したいなら明記します。

notifyで外部プログラムを動かす：完了をログに残す例

次の例は、完了のたびに内容を手元のファイルへ1行残すだけのプログラムです。~/.codex/notify_log.pyとして保存します。Codexは、1つのJSONを第1引数としてプログラムに渡します。まずこの形で何が届くかを確かめ、それから通知を出す処理に差し替えると、切り分けが楽です。編集部はこのスクリプトを手動とcodex execの両方から動かし、ログに1行残ることを確かめました。

#!/usr/bin/env python3
import json, os, sys

payload = json.loads(sys.argv[1])
row = {key: payload.get(key) for key in (
    "type", "client", "cwd", "input-messages", "last-assistant-message"
)}
with open(os.path.expanduser("~/codex-notify-log.jsonl"), "a", encoding="utf-8") as f:
    f.write(json.dumps(row, ensure_ascii=False) + "\n")

保存した場所をnotifyに書きます。パスは自分の環境に合わせて直します。notifyは1つのキーなので、すでに値がある環境では上書きになります。書く前に今の値を確かめます。

notify = ["python3", "/Users/you/.codex/notify_log.py"]

[tui]
notifications = ["agent-turn-complete", "approval-requested"]

notifyは[tui]より上に書きます。TOMLでは表の見出しの下に書いたキーがその表に入るので、[tui]の下に置くと、最上位のnotifyとして読まれません。

もう1つの制限があります。リポジトリの.codex/config.tomlに書いたnotifyは無視されます。公式資料の説明どおりで、編集部の確認でも起動時に警告が出て、スクリプトは動きませんでした。自分の~/.codex/config.tomlに書きます。

Codexの通知を編集部で試した結果

Codex CLI 0.166.0を教材のリポジトリで動かし、仮想端末に出た信号を記録しました。編集部のユーザー設定の上で、該当するキーだけを上書きした結果です。

端末の種類でautoの出し方が変わることも確かめました。ただし、環境変数のTERM_PROGRAMなどを指定した観測で、実際の端末アプリで表示を見たものではありません。

BELが出ても、音が鳴るか、タブに印が付くかは端末の設定で決まります。デスクトップ通知を期待していたのに何も見えない時は、autoがBELを選んでいることがあります。

CLIの画面ではnotifyが2回動いた

公式資料にない動きが1つありました。編集部の環境では、CLIの画面で1回頼むとnotifyが2回動きました。2回のうち1回のinput-messagesは、依頼文ではなく、英語の「Generate a concise, single-line task title」で始まる文でした。作業のタイトルを作る内部の処理と見られます。もう1回が本来の依頼と回答です。順序は固定ではなく、記録した5回のうち1回は本来の依頼が先でした。順番では見分けられません。clientの値を記録した回は、どちらもcodex-tuiでした。codex execでは1回だけで、clientはcodex_execです。

完了のたびに音を鳴らすプログラムを書くと、1回の依頼で2回鳴る可能性があります。notifyとtui.notificationsの両方で音を鳴らす設定にすると、それとは別に音が重なる可能性もあります。文面に最後の回答を使うと、タイトルのJSONが表示されることもあります。編集部のユーザー設定の上で確かめた結果なので、他の環境で同じとは限りません。プログラムを書く前に上のログで回数と中身を見てください。なお、端末の信号（OSC 9）のほうは同じ条件で1回だけでした。

Codexの通知が出ない時の確認順

通知が出ない原因は、Codexが信号を出していない場合と、出した信号を端末やOSが見せていない場合に分かれます。上から順に確かめます。

python3 ~/.codex/notify_log.py '{"type":"agent-turn-complete","client":"manual-test"}'
tail -n 1 ~/codex-notify-log.jsonl

手動で動くのにCodexからは動かない時は、まずnotifyの絶対パスを見直します。CLIと別の入口（デスクトップアプリやIDE拡張）で試している場合は、この記事のtui.notificationsの対象ではありません。tuiの設定は、公式資料でCLIの画面（TUI）のものと説明されています。

承認待ちを外部プログラムでも扱いたい時は、notifyではなくhooksのPermissionRequestを調べます。Codexが承認を求める直前に動く仕組みです。ただし、許可や拒否を返せるので、知らせるだけの用途でも扱いは慎重にします。書き方はhooksの解説を参照してください。

Codexの完了通知が来た後に確かめること

完了の通知は、作業の区切りが来たという合図です。頼んだ内容が正しくできたことを保証するものではありません。編集部の確認でも、短い回答ではOSC 9の本文は最後の回答そのものでした。回答に「直しました」と書いてあっても、それはCodexの報告です。

通知を受けたら、次の順に確かめてから次の作業へ進めます。この順番は編集部のすすめです。

1. Codexの画面に戻り、作業が止まっていないか、質問が残っていないかを読みます。
2. /diffで変更の範囲を見ます。頼んでいないファイルが変わっていないかを確かめます。
3. テストを自分で動かすか、実行したテストの結果が回答にあるかを確かめます。
4. 承認の通知だった時は、本文のコマンドだけで判断せず、画面で内容を読んでから選びます。通知の本文は途中で切られていました。

通知の中身の扱いにも注意します。notifyのJSONには依頼文、最後の回答、作業フォルダのパスが入っています。このまま社外のサービスやチャットへ送ると、それらも一緒に出ていきます。送る場合は「完了しました」のような固定の文にするか、送ってよい項目だけを選びます。スマホやPCのロック画面に通知を出す場合も同じです。

まとめ：承認待ちはtui.notifications、記録や加工はnotifyで分ける

完了と承認待ちを手元で知るだけならtui.notificationsで足ります。notifyは完了だけに対応する外部プログラムの入口で、CLIの画面では1回の依頼で2回動くことがあったので、まずログで中身を確かめます。通知が出ない時は、設定の種類、端末のフォーカス、書いた場所、プログラム、端末の設定の順に見ていきます。通知が来たら、変更とテストを確かめてから次へ進みます。

Codexの全体像から確かめたい場合は、Codexとは？使い方と仕事でできることを読んでください。チームでCodexを動かす時の承認や確認の決まりを整理したい場合は、法人向けのご相談も受け付けています。