Codex CLI フック連携
コマンドを自分で実行しなくても、Codex CLIが今何をしているかをライトがどうやって把握しているのか。
andon-light install-hooks --agent codex を一度実行すれば、あとはライトが自動的に更新されます。日常的に自分でコマンドを打つ必要はありません。このページでは、その設定が実際に何をしているのか、なぜこの作り方になっているのかを説明します。何か気になる動きがあった時の参考にしてください。
Codex CLIにも、Claude Codeと同じ種類の「フック」があります。これは、Codexの動作の節目節目で、自動的にコマンドを実行させられる仕組みです。連携をインストールすると、それぞれの節目に対して、適切な色で andon-light を呼び出すよう設定されます。使っているのは同じ andon-light プログラム、同じUSB接続、同じファームウェアです（Claude Code フック連携参照）。変わるのはパソコン側で動くソフトだけで、デバイス側は何も変わりません。
それぞれの色が呼び出されるタイミング
| タイミング | 色 | 理由 |
|---|---|---|
| 新しいセッションが始まった時 | アイドル（赤） | セッションはまだ何も指示されていない状態だからです。 |
| プロンプトを送信した時 | 作業中（緑） | 何か作業を指示した直後だからです。 |
| ツールを使う直前 | 作業中（緑） | すべてのツール呼び出しの直前で発動するため、ツール呼び出しが連続する長い作業の間もずっと緑色が保たれます。 |
| Codexがあなたの許可を求めようとしている時 | 対応待ち（黄） | 例えば、実行したいコマンドの承認を求めている場合などです。 |
| 内部整理（「コンパクト中」） | 順次点灯パターン | 内部的なメンテナンス中：作業は続いていますが、種類の違う「忙しさ」です。 |
| ひとつのやり取りが正常に終了した時 | アイドル（赤） | アイドルに戻ります。 |
| セッションが何らかの理由で終了した時 | アイドル（赤） | 通常の「終了」のタイミングでは拾いきれないケースをカバーします。 |
Claude Codeにあって、Codexにはないものが一つあります：汎用の「あなたの注意が必要です」通知です。Codexの「対応待ち」に該当する瞬間は上記の許可確認だけなので、黄色を担当するフックもこれ一つです。詳しくは下記のなぜ汎用の通知フックがないのかを参照してください。
これらのコマンドは、バックグラウンドではなく、ひとつずつ順番に実行されます。Claude Codeと同じ理由です（バックグラウンドで実行しない理由参照）。Claude Codeの設定は広範な設定ファイルに組み込まれますが、Codexのフックは専用のファイルにまとめられているため、この連携もそのファイルに直接書き込み（または統合し）ます。インストール時に選んだ範囲に応じて、グローバルな ~/.codex/hooks.json か、単一プロジェクトのものかのどちらかです。このファイルを編集した場合は、変更を反映させるためにCodex CLIを再起動（または新しいセッションを開始）してください。
実行前に信頼を与える
Codexは、新規または変更されたフックファイルを、あなた自身がCLI内で確認して承認するまで実行しません。外部から信頼を与える方法はありません。andon-light install-hooks --agent codex を実行した後、Codex CLIを起動し、/hooks を実行して、新しい設定内容を確認してください。
この手順を飛ばしてライトが反応しない場合、まずこれを疑ってください：信頼されていないフックはエラーを出さず、ただ静かに実行されないだけです。
ターミナルの代わりにChatGPTデスクトップアプリを使っている場合
Windowsでは、「Codexアプリ」というと、たいていChatGPTデスクトップアプリ（Microsoft Storeで配布されているもの）の中のCodexタブを指します。これはチャット画面であって、ターミナルで打つ codex コマンドとは別物です。これが重要なのは、上記の信頼の手順が対話的なターミナルセッションの中でしか使えないためです。ChatGPTアプリ自体には /hooks 画面がありません。
ただし、信頼の設定自体はどちらのアプリから許可したかに関係なく共有されます。ターミナルもChatGPTアプリも、同じ ~/.codex 設定を読み込んでいるからです。そのため、普段ChatGPTアプリしか使わない場合でも、一度だけターミナルでCodex CLIセッションを開き、そこで /hooks を実行して承認する必要があります。それが済めば、ChatGPTアプリも同じ信頼済みのフックを自動的に使うようになります。
この手順を済ませるまでは、ChatGPTアプリ側ではエラーも出ないまま、ライトが黙って反応しないだけの状態になります。上で説明した「信頼されていないフックの挙動」と同じです。
ターミナルで codex と打っても認識されない場合、それはChatGPTアプリが独自のCLIのコピーを内蔵していて、システムのPATHには追加していないためです。PowerShellでの見つけ方・実行方法は次の通りです。
-
まず設定を直接確認し、スクリプトを盲目的に信頼するのではなく、実際の値を自分の目で見ます。
Get-Content "$env:USERPROFILE\.codex\config.toml" | Select-String CODEX_CLI_PATHこれで
CODEX_CLI_PATH = "C:\Users\you\AppData\...\codex.exe"のような行が表示されます。 -
その正確なパスを引用符で囲み、先頭に
&（PowerShellの「このプログラムを実行する」演算子）を付けて実行します。以下は例なので、先ほど見つけた実際のパスに置き換えてください。& "C:\Users\you\AppData\...\codex.exe" -
これで本物のターミナルのCodex CLIセッションが開きます。そこで
/hooksを実行し、内容を確認して承認してください。 -
そのウィンドウを閉じて構いません。ChatGPTアプリのCodexタブは、それ以降この信頼済みのフックを自動的に使うようになります。信頼はディスク上に保存されるもので、承認したウィンドウに紐づいているわけではありません。
いくつかの設計判断について
「ツールを使う直前」が重要な理由
Claude Codeと同じ理由です：上の表にあるタイミングのほとんどは1ターンに一度きりですが、Codexからの1つの応答の中で、ツール呼び出しが何十回と連続することがあります。「すべてのツール呼び出しの直前」にフックを仕込むことで、その間ずっとライトが継続的に更新され続け、作業の途中で接続が途切れたようなパルス表示になってしまうのを防いでいます。ツール呼び出しが一切ない、思考だけのターンはこれでカバーしきれませんが、この隙間はファームウェアの30分のウォッチドッグタイムアウトに比べればずっと短いので、実用上の問題にはなりません。ファームウェアの概要も参照してください。
なぜ汎用の通知フックがないのか
Claude Codeには、個別の許可確認フックとは別に「あなたの注意が必要です」という広い意味の通知フックがあります。Codexのライフサイクルフックには、これに相当するものがありません。近いものとして notify という別の設定項目がありますが、これはターンが終わった時にしか発動せず、それは上記の「ターン終了」フックで既にカバーされています。そのため、Codexが「対応待ち」の信号としてフックで公開しているのは許可確認の瞬間だけで、黄色を担当するのもこの一つだけになっています。
内部整理だけ専用の見た目がある理由
Claude Codeと同じ理由です：専用のパターンがなければ、内部整理中はそれまでの色をそのまま表示し続けるか（それが赤・アイドルだった場合、誤解を招きます）、終わった後に元の色へ戻すためだけの追加フックが必要になってしまいます。順次点灯パターンなら、ひと目で「まだ生きていて、片付け作業をしている」と伝わりますし、次のフックが発動すれば自然に次の状態へ移り変わります。
セッションの開始と終了で、あえてアイドルにする理由
セッション開始時に明示的にアイドルへ設定しておくことで、新しいセッションが、途中でクラッシュしたかもしれない前のセッションの色をそのまま引き継ぐことがなくなります。セッション終了時（Codexが報告するどんな理由であっても）にも同様にアイドルへ設定することで、通常の「ターン終了」フックでは拾いきれないケース、たとえば中断されたセッションや、突然閉じられたセッションなども、あわせてカバーできます。
バックグラウンドで実行しない理由
Claude Codeと同じトレードオフです：それぞれの andon-light の呼び出しをバックグラウンドで実行しても、保証されるのは正しい順番で「開始される」ことだけで、正しい順番で「完了する」ことではありません。それぞれの呼び出しは独立した短命なプログラムで、速いとはいえ（だいたい40〜50ミリ秒）瞬時ではありません。そのため、ツール呼び出しが連続する場面では、後から始まった呼び出しが先に終わってしまい、正しい色を古い色で静かに上書きしてしまうことがあります。ひとつずつ順番に実行するようにすると、1回あたりのわずかな待ち時間と引き換えに、ライトが常に本当の出来事の順序を反映することが保証されます。この考え方の詳細はClaude Code フック連携を参照してください。
すべてのコマンドが静かに失敗するように作られている理由
Claude Codeと同じ理由です：ボードが抜けている時や、ボードが接続されていないパソコンでCodexを実行した時、対策をしていなければ、すべてのフックが毎回大きなエラーを表示してしまいます。これでは、本来静かに背後で動いているはずのステータスライトとしての意味がなくなってしまいます。この挙動は、ツールが自動的に再接続できるようになった時点で見直す価値があります。詳しくはClaude Code フック連携を参照してください。