Codex 通知設定の方法｜notify と tui.notifications の違い

Codex の通知は 2 系統ある

Codex CLI が提供する通知の仕組みは、役割の異なる 2 つに分かれている。公式の設定リファレンスに挙げられているキーで言えば、tui.notifications（およびそれを補助する tui.notification_method と tui.notification_condition）と、トップレベルの notify だ（出典: https://developers.openai.com/codex/config-reference ）。どちらも設定ファイル ~/.codex/config.toml に記述するが、通知を「誰が出すか」がまったく違う。tui.notifications は Codex のターミナル UI 自身が、ターミナルエミュレータの通知機能を通じて OS に通知を出す。一方の notify は、Codex がイベント発生時に外部プログラムを起動し、通知の出し方そのものを利用者側のスクリプトに委ねる。前者は設定 1 行で済む手軽さが持ち味で、後者は通知先やメッセージ整形を完全に制御できる拡張性が持ち味だ。まずはこの構図を頭に入れておくと、後述の設定項目がどちらの系統に属するのか迷わなくなる。

tui.notifications — ターミナル内蔵の通知

tui.notifications は、対話モード（TUI）で作業しているときに、Codex の応答完了などをターミナル経由で知らせてくれる組み込み機能だ。型は boolean または文字列配列で、true を指定すればすべての対象イベントで通知され、配列でイベント種別を列挙すれば通知対象を絞り込める（出典: https://developers.openai.com/codex/config-reference ）。別ウィンドウで調べ物をしている間に Codex のターンが終わった、といった場面で真価を発揮する。

notify — 外部プログラムを呼び出す通知

トップレベルの notify キーには、通知時に起動するコマンドを文字列配列で指定する。Codex はイベントの内容を JSON にまとめ、単一の引数としてそのプログラムへ渡す（出典: https://developers.openai.com/codex/config-advanced ）。受け取った JSON をどう料理するかは完全に自由で、デスクトップ通知に変換するもよし、チーム共有のチャットへ転送するもよし。対話モードに限らず通知の受け口を統一したい場合や、通知内容をログとして残したい場合にはこちらが向いている。

tui.notifications の設定手順

まずは手軽な内蔵通知から設定してみよう。必要な作業は config.toml への数行の追記だけだ。

1. ~/.codex/config.toml を開く（存在しなければ新規作成する）。
2. [tui] セクションを作り、notifications = true を追記する。
3. Codex CLI を起動し直し、時間のかかる指示を出してターミナルからフォーカスを外し、応答完了時に通知が届くか確認する。

最小構成は次のとおりだ。

[tui]
notifications = true

すべてのイベントで通知されるのが騒がしいと感じたら、配列でイベント種別を指定して絞り込める。たとえば応答の完了と承認の要求だけ受け取りたい場合は次のように書く。

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

承認要求の通知は実務上とくに重要だ。Codex がコマンド実行の許可を求めて止まっているのに気づかず、数分間まったく作業が進んでいなかった——という空白時間を、この 1 行がほぼゼロにしてくれる。

notification_method — 通知方式の選択

ターミナルへの通知の伝え方は tui.notification_method で調整できる。取りうる値は osc9・bel・auto の 3 つで、既定値は auto だ（出典: https://developers.openai.com/codex/config-reference ）。OSC 9 はターミナルエミュレータに通知文字列を渡すエスケープシーケンスで、対応ターミナルなら OS のデスクトップ通知として表示される。bel はいわゆるベル文字による古典的な合図で、ほとんどのターミナルが何らかの反応（音や画面のフラッシュ、タブのハイライトなど）を返す。まずは auto のまま使い、届かない場合にだけ明示指定を検討すればよい。

notification_condition — 通知するタイミングの制御

tui.notification_condition は、通知を出す条件を unfocused（ターミナルが非フォーカスのときだけ）と always（常に）から選ぶ設定で、既定値は unfocused だ（出典: https://developers.openai.com/codex/config-reference ）。画面を見ながら作業しているときにまで通知が重なるのは煩わしいため、既定の unfocused が多くの人にとって最適解になる。逆に、複数ペインを並べて Codex を走らせており、フォーカス状態にかかわらず完了の合図がほしい場合は always に切り替えるとよい。

notify で通知の受け取り方を自作する

notify の設定は、コマンドとして起動できるプログラムを用意し、それを config.toml に登録するという 2 段階になる。たとえば Python スクリプトを使うなら次のように書く。

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

Codex はイベント発生時にこのコマンドを起動し、最後の引数として JSON 文字列を 1 つ渡す。公式ドキュメントによれば、ペイロードに含まれる代表的なフィールドは type（現時点では agent-turn-complete）、thread-id（セッション識別子）、turn-id（ターン識別子）、cwd（作業ディレクトリ）、input-messages（そのターンにつながった利用者のメッセージ）、last-assistant-message（最後のアシスタントメッセージ）だ（出典: https://developers.openai.com/codex/config-advanced ）。

macOS でデスクトップ通知に変換する最小例を挙げる。

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

payload = json.loads(sys.argv[1])
if payload.get("type") == "agent-turn-complete":
    message = payload.get("last-assistant-message") or "ターンが完了しました"
    script = f'display notification {json.dumps(message[:120])} with title "Codex"'
    subprocess.run(["osascript", "-e", script])

Linux であれば osascript の代わりに notify-send を呼び出せば同じことができる。ポイントは、type フィールドで処理を分岐させておくことだ。将来イベント種別が増えても、未知の種別を黙って無視する作りにしておけばスクリプトが壊れない。また cwd を通知タイトルに含めると、複数リポジトリで Codex を並行稼働させているときに「どのプロジェクトの完了通知か」を一目で判別できるようになる。

tui.notifications との使い分け

両者は排他ではなく併用もできるが、役割を整理しておくと迷わない。tui.notifications は対話モード専用の手軽な合図で、設定コストが最小の代わりに通知先はターミナル経由に限られる。notify は起動するプログラム次第でどこへでも届けられる代わりに、スクリプトの用意と保守が必要になる。日々の対話利用が中心なら tui.notifications だけで十分で、codex exec を使った非対話の運用や、通知をチャットツールに集約したいチーム利用では notify が本命になる。非対話モードの活用方法はCodexのheadless実行入門も参考にしてほしい。

通知が届かないときの確認ポイント

設定したのに通知が来ない場合、確認すべき箇所は系統ごとに決まっている。順に潰していこう。

1. ターミナルエミュレータの対応方式を確認する。 OSC 9 に対応していないターミナルでは、auto や osc9 指定の通知が表示されないことがある。tui.notification_method = "bel" に切り替えて反応があるか試すと、方式の問題かどうかを切り分けられる。
2. notification_condition の値を見直す。 既定は unfocused のため、ターミナルにフォーカスを当てたまま待っていると通知は出ない。テスト時は always に変えて動作を確かめるのが早い。
3. OS 側の通知許可を確認する。 ターミナルアプリからの通知が OS の設定でオフになっていれば、Codex 側をいくら調整しても届かない。macOS なら通知設定でターミナルアプリの許可状態を確かめる。
4. notify のコマンドを単体で試す。 config.toml に書いたパスの誤り、実行権限の不足、スクリプト内の例外は Codex の画面からは見えにくい。ダミーの JSON を引数に渡して手動起動し、意図どおり通知が出るかを先に確認しておく。
5. 設定ファイルの置き場所とセクションを確かめる。 notifications を [tui] セクションの外に書いてしまう、プロジェクト側とユーザー側の config.toml を取り違える、といった配置ミスは意外に多い。

この 5 点で解決しない場合は、Codex CLI 自体の更新も試す価値がある。CLI は現在も高い頻度で改善が続いており、リリースノートには不具合修正が細かく記載されている（出典: https://github.com/openai/codex/releases ）。

長時間タスク時代の「気づける仕組み」として

通知設定は地味な項目に見えるが、Codex の使い方が変わるにつれて重要度が上がっている。モデルの推論が深くなり、1 ターンで数分〜数十分かかるタスクを任せる場面が増えた結果、「完了を待つ時間」ではなく「完了に気づくまでの時間」が実質的なボトルネックになりつつあるからだ。2026 年 7 月時点で Codex CLI は安定版 v0.142 系が提供され、次期 0.143 系のプレリリースも進行中と、改善のテンポは落ちていない（出典: https://github.com/openai/codex/releases ）。承認要求に即応できれば Codex の手が止まる時間は減り、完了に即応できれば次の指示までの空白が減る。設定にかかる時間は数分なので、まずは [tui] セクションの 1 行から試し、運用が固まってきたら notify で自分好みの受け取り方に育てていく——という順番をおすすめしたい。

出典

• OpenAI Developers — Codex Config Reference: https://developers.openai.com/codex/config-reference
• OpenAI Developers — Codex Advanced Configuration: https://developers.openai.com/codex/config-advanced
• OpenAI — Codex CLI Releases: https://github.com/openai/codex/releases