Codex api.notificationsの意味と通知設定・失敗時の確認

codex api.notificationsとは何を探しているのか

この検索語は、三つの別の話が短く結合したものと考えると理解しやすくなります。第一はCodex CLIの通知設定、第二はOpenAI APIを呼び出すアプリの状態通知、第三はCodexアプリやエディタで表示される更新案内です。名前にapiが含まれているからといって、Codexのconfig.tomlにapi.notificationsを書く場所があるとは限りません。公式の設定表に載るキーを起点にし、検索結果の言い回しは補助情報として扱うのが安全です。

Codexを使う人が知りたいのは、多くの場合「長い処理が終わったか」「確認を求められて止まっていないか」「別の画面に移っても結果を見逃さないか」という三点です。これらは通知の目的としては近くても、発生する場所と受け取り方が異なります。目的を先に書き出せば、CLIの設定を探すべきか、APIクライアントの状態処理を調べるべきか、アプリの版番号を確認すべきかが決まります。

検索語を三つに分ける

codexは製品やCLIを示し、apiは接続方式または検索者の入力を示し、notificationsは完了や注意を知らせる仕組みを示します。しかし、この三語が一つの正式名称として提供されているとは限りません。まずCodex CLIの通知なのかOpenAI APIの応答イベントなのかを決め、その後に公式ページの用語へ置き換えます。これだけで、似た名前の設定を重ねて試す失敗を防げます。

たとえばターミナルを離れている間にターンの終了を知りたいなら、tui.notificationsまたはnotifyが候補です。自分のサービスがAPIリクエストの完了を受け取りたいなら、Responses APIの応答やWebhookイベントを調べます。ここで重要なのは、同じ「通知」という言葉でも、前者はCodex CLIのローカル設定、後者はAPIを利用する側の設計だという境界です。

公式リファレンスにある名前

OpenAIのCodex Configuration Referenceでは、tui.notificationsはTUI通知を有効にする値、tui.notification_methodは通知方式、tui.notification_conditionはフォーカス状態による条件として説明されています。また、トップレベルのnotifyは通知時に呼び出すコマンドとして掲載されています。ここにapi.notificationsがないなら、まず未対応のキーではなく、検索語を公式のキーへ読み替える必要があります。

公式ページの表記をそのまま使うことには実務上の意味があります。notificationsとnotification_methodは似ていますが役割が違い、notifyは単数形で別の階層です。設定名を一文字でも変えると、Codexが無視しているのか、別の設定が優先されているのかを判定しにくくなります。設定ファイルを編集する前に、キー、型、置く階層の三つをメモしてください。

Codex CLIの通知を選ぶ基準

Codex CLIでは、ターミナル内蔵の通知と、外部プログラムへ情報を渡す通知を選べます。どちらが優れているかではなく、通知をどこで見たいかで決めるのが自然です。作業中のターミナルが一つで、完了を見逃さなければよいなら内蔵通知が扱いやすく、複数の作業場所を区別したいならnotifyで受け取ったJSONを自分の表示へ変換する方法が向いています。

tui.notificationsを使う場面

[tui]のnotificationsは、Codex CLIの対話画面が発生させる通知を有効にする設定です。最初はtrueで全対象を受け取り、通知が多いと感じたらイベント名の配列で絞ります。設定の目的は画面を見続けることではなく、別の作業へ移ったときにターン終了や確認待ちに気づくことです。通知が出ても、結果の内容や変更の正しさを確認したことにはならないため、合図と検証は分けて扱います。

公式リファレンスにある最小構成は次の形です。

[tui]
notifications = true

プロジェクト側の設定へ何でも書けばよいわけではありません。公式ページは、通知に関するキーはユーザー側の設定へ置き、プロジェクト固有の設定から上書きできないものがあると説明しています。複数のプロジェクトで同じ通知を使いたい場合も、まずユーザー側のconfig.tomlを確認し、共有したい作業条件だけを別途記録するのが分かりやすい方法です。

notification_methodとnotification_condition

通知が有効なのに画面へ出ない場合、notificationsだけを何度も変えるのではなく、方式と条件を見ます。tui.notification_methodはauto、osc9、belから選べ、既定値はautoです。ターミナルがOSC 9を扱えるならデスクトップ通知として表示されることがあり、対応が分からないときはまず既定値で試し、反応がなければbelを候補にします。

tui.notification_conditionはunfocusedまたはalwaysで、既定値はunfocusedです。ターミナルにカーソルを置いたまま完了を待つと通知が出ないように見えるのは、故障ではなく条件どおりの可能性があります。動作確認だけはalwaysにして、別の画面へ移ったときだけ必要ならunfocusedへ戻す、という順番が切り分けやすいです。

notifyを使う場面

トップレベルのnotifyは、対応するイベントが起きたときに外部プログラムを呼び出し、CodexからJSONを一つの引数として渡す設定です。公式のAdvanced Configurationでは、現在の代表的なイベントをagent-turn-completeとして説明し、thread-id、turn-id、cwd、input-messages、last-assistant-messageなどのフィールドを挙げています。

ここで注意したいのは、notifyが万能な状態監視機能ではないことです。通知を受け取った後に何を表示するか、同じ通知をどう識別するか、文字数の長い本文をどう扱うかは受け取り側の責任になります。最初はイベント種別、作業場所、最後のメッセージだけを表示する小さな受け口で確認し、必要な情報が揃ってから表示項目を増やします。

Codex CLIに通知を設定する手順

設定は一度に多くの項目を変えず、現在の版、ファイルの場所、最小の通知、表示条件、必要なら外部受け口という順で進めます。codex api.notificationsという検索結果を見て、存在を確かめないキーを先に追加するのは避けます。変更後に通知が出たとしても、それがどの設定によるものか分からなくなるため、各段階で結果を一つだけ確認することが大切です。

Step 1: 現在の版と設定場所を確認する

まずCodex CLIの版番号と、読み込んでいるユーザー設定の場所を確認します。2026年8月9日時点で基準にする安定版は、8月7日に公開されたCodex 0.147.0です。試験版を使っている場合は、その版番号と目的を記録し、安定版で同じ設定を試した結果と混ぜないようにします。

次に、ユーザー側のconfig.tomlとプロジェクト側の.codex/config.tomlを区別します。通知関連の設定はホストや利用者に結び付くため、プロジェクト側へ置いた記述が反映されない場合があります。設定ファイルを一つ開いただけで完了とせず、どの階層に置いたかを記録してから、既存の同名キーがないかを確認してください。

Step 2: TUI通知を最小構成で試す

最初は次のように[tui]とnotificationsだけを追加し、CLIを再起動して長めの読み取りやテスト確認を依頼します。

[tui]
notifications = true

この試験では、通知内容の見た目よりも「ターンの終了時に何か反応があるか」を見ます。ターミナルからフォーカスを外した状態と、フォーカスを置いた状態を分けて確認し、結果を短く記録します。通知が出ないときに、いきなりnotifyへ切り替えると原因が二つに増えるので、まず方式と条件を確かめます。

Step 3: 通知の条件を絞る

すべての通知が多い場合は、notificationsへイベント名の配列を設定します。たとえば完了と確認要求だけを対象にしたい場合は、公式リファレンスで現在のイベント名を確認したうえで、次のような形を試します。

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

イベント名は将来の版で増減する可能性があるため、古い記事の例を固定的な仕様とみなさないことが大切です。実際に利用中の版の公式説明にない名前を追加しても、期待した通知にはなりません。必要な対象を一つずつ増やし、どのイベントで何が表示されたかを残すと、通知の多さと見逃しのバランスを調整できます。

Step 4: 外部受け口を確認する

内蔵通知で目的を満たせない場合だけ、トップレベルのnotifyを検討します。公式例のnotify = ["python3", "/path/to/notify.py"]のように、起動するプログラムとファイルの場所を設定し、受け口が第一引数のJSONを読めることを小さなテストで確かめます。まずは通知文を画面に表示するだけにし、外部サービスへの転送や複数端末への配信は後から考えます。

受け口では、typeが想定した値か、last-assistant-messageが空でも処理できるか、cwdが長いパスでも表示できるかを確認します。入力値をそのまま画面へ出すと、コードやパスが長くなって見にくいため、タイトルと本文を分け、長文は短く切り出します。失敗時にCodex本体の画面へ戻れるよう、受け口の問題とCLIの通知機能を別々に記録してください。

通知が来ないときの切り分け

通知の不具合は、設定キーの誤りだけでなく、表示方式、フォーカス条件、設定ファイルの場所、受け取り側の処理に分かれます。症状を「まったく表示されない」「フォーカスを外したときだけ表示される」「内蔵通知は出るが外部受け口だけ動かない」のように分けると、確認範囲を絞れます。api.notificationsを追加して様子を見るより、公式に記載されたキーを一つずつ戻しながら調べるほうが再現性があります。

画面を開いているときだけ来ない

フォーカス中に表示されないなら、notification_conditionの既定値であるunfocusedが働いている可能性があります。alwaysへ一時的に変更し、同じ作業をもう一度行って結果が変わるか確認します。変化があれば、通知機能そのものではなく条件の選択が原因です。変更を戻した後も、どの状態で通知が出る設定なのかを作業メモに残しておくと、別の端末で同じ混乱を避けられます。

表示方式が端末に合っていない

autoで反応しないときは、ターミナルがOSC 9を扱えるか、ベルによる反応を表示できるかを確認します。osc9とbelを同じ試験で同時に変えず、一つずつ指定して結果を比べます。OS側でターミナルの通知が無効になっている場合は、Codexの設定を直しても画面には出ません。通知を許可する場所は端末やターミナルアプリで異なるため、別の通知が表示されるかも確認材料にします。

設定を書いた場所が違う

記述が正しく見えるのに変化がないときは、編集したファイルが実際に読み込まれる階層かを調べます。ユーザー側のconfig.tomlに書くべきキーをプロジェクト側へ置いていないか、同じキーを別の設定ファイルで上書きしていないかを確認します。api.notificationsのように公式表にない名前は、読み込まれていないのか、名前が違うのかを判断できないため、最初から使わないことが安全です。

外部受け口だけが失敗する

TUI通知が動き、notifyだけが動かないなら、JSONを渡すコマンドの場所、実行権限、引数の扱いを見ます。受け口を単独で起動して、typeとlast-assistant-messageを含むサンプルJSONが読めるか確認し、その後に実際のCodexから一回だけ呼びます。受け口の中で例外が起きてもCLIの画面に詳しい内容が出るとは限らないため、失敗理由を短いログへ残し、入力本文やパスを必要以上に保存しない設計にします。

1. 実際の設定キーがnotifyまたは[tui]内の項目か確認する。
2. ユーザー側とプロジェクト側のどちらを編集したか確認する。
3. notification_conditionとnotification_methodを一つずつ試す。
4. TUI通知と外部受け口を分けて、同じ作業で結果を比べる。
5. 版番号を記録し、公式のCodexリリース一覧で変更点を確認する。

0.147.0公開後に見直すポイント

Codex 0.147.0は2026年8月7日に公開され、Windowsのプロセス中断やパスの扱い、プラグインの隔離、MCP関連など複数の変更を含みます。通知だけを目的に更新する必要はありませんが、更新後に以前の設定が効かないと感じた場合は、版番号と設定を一緒に確認してください。公式リリースにはログイン完了時の通知に関する変更も記載されているため、製品内の表示とCLIのターン通知を同じ機能だと決めつけないことが大切です。

安定版と試験版を分ける

新しい番号のほうが必ず自分の環境に適しているとは限りません。まず0.147.0の安定版で設定を確認し、試験版を使う場合は別の小さなプロジェクトで同じ条件を比べます。通知だけでなく、セッションの再開、Windowsのパス、確認要求の表示など周辺の挙動も変わる可能性があるため、版を変える前後で同じ依頼を一度ずつ実行します。結果が違ったときは、通知設定と版の変更を別の要因として記録してください。

Windowsで確認する

Windowsでは、ターミナルの通知方式、フォーカス状態、外部プログラムの起動方法、パス表記が結果に影響します。まずPowerShellなど日常利用するターミナルでTUI通知だけを試し、次に外部受け口を単独で確認します。/と\\が混ざるパスを通知文に含める場合は、表示が崩れていないかも見ます。0.147.0の公式リリースがWindowsのプロセスとパスの修正を含むことを踏まえ、更新前の結果を残してから更新後を比べると原因を追いやすくなります。

更新後の確認項目を固定する

更新のたびに長い検証を行う必要はありません。版番号、設定ファイルの場所、notificationsの値、フォーカス状態、通知方式、表示されたイベント名だけを短く残せば、前回との差を説明できます。通知が表示されたことだけで成功とせず、完了した作業の内容と変更差分を別に確認します。通知は作業を知らせる入口であり、コードの品質や安全性を判定するものではないからです。

Codex APIとCLIの通知を混同しない

codex api.notificationsという検索語には、Codex CLIの通知設定をOpenAI APIの機能名として探しているケースも含まれます。CLIのnotifyは、Codexが動く端末上の設定ファイルから外部プログラムへイベントを渡す仕組みです。一方、OpenAI APIを使うアプリは、Responses APIの応答、ストリーミング、バックグラウンド処理、Webhookイベントなど、利用する方式に合わせて状態を扱います。名前が似ているだけで、CLIのconfig.tomlへAPI側の設定名を書くことはできません。

CLIのnotifyはローカル設定

CLIのnotifyで渡されるJSONには、ターンの種類やセッション識別子、作業場所、最後の応答などが含まれます。これはCodex CLIが処理を終えたことを、端末上の別の表示へ知らせるための情報です。APIエンドポイントへ送信すること自体が組み込まれた機能ではなく、必要なら利用者が受け口の動作を設計します。ここをAPIの標準フィールドと誤認すると、設定場所とエラーの確認先を間違えます。

API側の結果通知を考える

OpenAI APIを組み込んだサービスで結果を受け取りたい場合は、Responses APIの公式リファレンスと、Webhookイベントの公式リファレンスを確認します。ストリーミングならクライアントが受け取るイベント、サーバー側で後から結果を確認するなら対象の状態と再取得方法を整理します。そこにapi.notificationsというCodex CLIの設定キーを持ち込むのではなく、APIのリクエストとレスポンスの仕様に沿って受け取る方法を選ぶのが正しい分け方です。

CLIとAPIを一緒に使う場合は、同じ作業名を両方へ渡すと比較しやすくなります。CLI側ではthread-idやturn-id、API側では自分のリクエスト識別子を記録し、どの結果を見ているかを結び付けます。ただし、識別子の形式や保持期間が同じとは限らないため、片方の値をもう片方の公式IDとして扱わないでください。

codex api.notificationsを調べるときの結論

このKWで迷ったら、最初にapi.notificationsという一続きの設定名を探すのではなく、通知の発生場所を決めます。Codex CLIの画面内通知なら[tui] notifications、方式を選ぶならnotification_method、フォーカス条件ならnotification_condition、外部受け口へJSONを渡すならnotifyです。OpenAI APIを使うアプリの結果通知なら、Responses APIやWebhookの公式仕様を読みます。言葉の似ている設定を混ぜないことが、最短の解決策になります。

2026年8月7日公開の0.147.0を基準にする場合も、更新後に設定を全部書き換える必要はありません。版番号、設定の階層、通知方式、フォーカス条件、発生したイベントを一つずつ確認し、同じ作業で更新前後を比べます。api.notificationsが画面に表示されない、という検索上の疑問は、公式のキーが分かれば「何を設定すべきか」という具体的な確認へ変えられます。

長い開発作業では、通知が届くことより、通知を見たあとにどの差分とテスト結果を確認するかが重要です。完了の合図を受けたら、作業の目的、変更範囲、検証結果を順番に見直し、必要なら元の状態と比較します。通知は判断を代わりに行うものではなく、確認を始めるきっかけです。この役割を明確にしておけば、Codex CLI、GitHub Copilot、Cursorなど複数のAIコーディングエージェントを使う場合も、通知の仕組みと成果物の確認を混同せずに済みます。

公式情報は更新されるため、設定名や対応イベントを確認するときは、Codex Configuration Reference、Codex Advanced Configuration、openai/codexの0.147.0リリースを順に参照してください。検索結果の断片より、利用中の版に対応する公式ページの記述を優先すれば、codex api.notificationsをめぐる設定の行き違いを減らせます。