Codex Exec: ターミナルからのデプロイメントチェック自動化

codex execを使用すると、対話型のターミナルインターフェースなしでCodexを実行できます。プロンプトを指定するかデータをパイプで渡し、後続のスクリプト処理のために回答を保存します。このガイドでは、JSONLイベント、スキーマで制約された結果、および実際のHTTPチェックに基づく終了コードを使用して、デプロイメントレポートを構築します。

小規模な見積もり計算APIの2つのバージョンをテストします。1つは正常に動作し、もう1つはヘルスエンドポイントからHTTP 200を返しますが、見積もり計算ルートは失敗します。完全な例には、コレクター、レポートスキーマ、および検証スクリプトが含まれています。

対話型インターフェースなしでCodexを実行する

信頼できるGitリポジトリから、以下を実行します。

codex exec --sandbox read-only \
  "Summarize this repository in three sentences. Do not change files."

Codexは進行状況を標準エラー出力(stderr)に、最終的な回答を標準出力(stdout)に書き込みます。その回答をファイルにリダイレクトできます。公式の非対話型ガイドでは、この動作とサポートされている自動化パターンについて説明しています。

デプロイメントレポートのために、標準入力(stdin)で観測結果を提供します。小さなPythonコレクターがネットワークリクエストを行います。Codexは検証データを説明し、別の関数がその観測結果とレポートを照合してチェックします。

3つの出力ファイルを理解する

これらのファイルには異なる役割があります。

--jsonは標準出力をイベントストリームに変更します。ストリーム全体を単一のレポートオブジェクトにするわけではありません。--output-schemaは最終的な回答を記述し、-oはその回答を個別に保存します。この区別により、イベントログ全体を1回のJSON読み取りでパースしようとする、よくある自動化のバグを防ぐことができます。

例の準備

Python 3.10以降と、認証済みのCodex CLIを使用します。Pythonファイルにはサードパーティのパッケージは必要ありません。以下のシェルコマンドは、macOSまたはLinux上のBashまたはZshを対象としています。

codex --version
codex login status
mkdir codex-deployment-check
cd codex-deployment-check
for file in demo.py collect.py gate.py run.py report.schema.json verify.py; do
  curl --fail --silent --show-error \
    "https://lizard.build/blog-examples/agent-deployment-checks/$file" \
    --output "$file"
done

ダウンロードしたファイルは、実行する前に読んでください。デモを開始し、実行したままにします。

python3 demo.py --port 8787

アプリケーションには2つのGETルートがあります。/healthzはstatus: okを返します。/api/quote?quantity=3は、1つ1,200セントのアイテム3つの見積もり計算を行います。期待される結果は$36.00（3,600セント）です。この例では、アサーションでの丸め誤差を避けるために整数のセントを使用しています。

残りのコマンドを実行するために、同じフォルダーで別のターミナルを開きます。

HTTP検証データの収集と検査

python3 collect.py http://127.0.0.1:8787 > evidence.json

コレクターは、URL、チェック時刻、HTTPステータス、および各レスポンスが期待されるフィールドと一致するかどうかを記録します。2つの制限付きリクエストを行い、リダイレクトを拒否し、各レスポンスの上限を64 KiBに制限します。任意のレスポンステキストをコピーすることなく、期待値とブール値をモデルに送信します。

自身のアプリケーションの場合は、collect.pyとgate.pyの両方で、デモのパスと期待値を置き換えてください。価格の計算、シードされたデータベースレコードの読み取り、既存のドキュメントの取得など、有用な動作を実行するルートを選択します。ステータスコードだけでなく、レスポンスの内容も照合します。

コレクターの終了コードは、検証データを収集したかどうかを示します。アプリケーションのチェックが失敗しても検証データファイルは生成されるため、Codexは失敗の理由を説明できます。最終的な検証スクリプトがジョブの結果を決定します。

構造化されたレポートをリクエストする

ファイルが含まれている信頼できるGitリポジトリから、以下を実行します。

codex exec --ignore-user-config --ephemeral \
  --sandbox read-only \
  --json \
  --output-schema report.schema.json \
  -o report.json \
  "Explain the evidence on stdin. Use no tools. Copy its verdict, list failed check names in failed_checks, and give a summary and next_step. Do not infer a root cause from HTTP status alone." \
  < evidence.json > events.jsonl 2> stderr.log

新しいダウンロードフォルダーのみを使用する場合は、--skip-git-repo-checkを追加します。完全なラッパーは、レポート用に作成された一時ディレクトリでこれを行います。リポジトリが不要な場合は、このフラグを意図的に使用してください。

--ignore-user-configは、通常の認証を保持したまま、ユーザーのメインのCodex設定ファイルをスキップします。--ephemeralは、セッションのロールアウトの保存を防ぎます。シェルは引き続き、上記の3つの明示的な出力ファイルを保存します。--sandbox read-onlyはモデルが生成するコマンドを制限します。シェルのリダイレクトがアーティファクトを書き込みます。

スキーマはverdict、failed_checks、summary、およびnext_stepを必須とし、余分なフィールドを許可しません。レポートは、提供されたチェックが何を立証しているかを説明する必要があります。レスポンスは503の後にアプリケーションログを検査することを提案できますが、ステータスコードだけではデータベースの障害を証明できません。

ストリームと最終的な回答を個別にパースする

ライブテストでは、Codexは以下のイベントタイプを順番に出力しました。

thread.started
turn.started
item.completed
turn.completed

完了したアイテムはエージェントメッセージでした。これらの特定の実行ではツール呼び出しは行われませんでした。他のタスクでは、コマンド実行、ツール呼び出し、エラーなど、より多くのイベントが生成される可能性があります。成功したすべての実行が正確に4行であることを必須としないでください。

ラッパーは各イベントを読み取り、turn.failedまたはerrorを拒否します。また、turn.completed、成功したプロセス終了、およびパース可能な最終レポートも必要とします。次に、レポートの判定および失敗したチェックの名前をHTTP検証データと比較します。

早期に終了するストリームは不完全なジョブです。以前の実行から残されたレポートファイルを再利用するのも安全ではありません。ラッパーは新しい出力ディレクトリを作成し、既存の実行の上書きを拒否します。

完全なワークフローを実行する

python3 run.py codex http://127.0.0.1:8787 runs/healthy

このコマンドは、新しい検証データを収集し、180秒のプロセスタイムアウトでCodexを起動し、その出力を保存してレポートを検証します。ラッパーは、両方のアプリケーションチェックに合格し、レポートが一致する場合にのみ0で終了します。

失敗を再現するには、別のターミナルで2つ目のデモを開始します。

python3 demo.py --port 8788 --broken

次に、そのインスタンスに対して同じワークフローを実行します。

python3 run.py codex http://127.0.0.1:8788 runs/broken

ヘルスルートは200を返し、見積もり計算ルートは503を返します。Codexはそれらの観測結果を受け取り、失敗レポートを返します。ラッパーは1で終了します。アプリケーションチェックが失敗しても、レポートプロセスは正常に完了する可能性があります。自動化では、アプリケーションの判定にラッパーの終了コードを使用する必要があります。

動作する例からの結果

2026年9月28日に、Codex CLI 0.156.1とPython 3.12.10を使用して両方のシナリオを実行しました。また、バージョン4.0.8に対してLizard CLIコマンドもチェックしました。

両方のモデル呼び出しが完了し、収集された検証データと一致するレポートが生成されました。失敗した実行のレポートは、記録された時刻のログを確認することを提案しました。ヘルスエンドポイントがアプリケーション全体の健全性を立証したとは主張しませんでした。

ローカルの検証テストでは、誤った成功レポートや不完全な検証データも拒否されます。モデル呼び出しなしでそれらを実行します。

python3 verify.py

これはローカルマシンでの合成HTTPテストです。本番トラフィック、パブリックDNS、TLS、データベースのマイグレーション、またはすべてのルートをカバーするものではありません。自身のデプロイメントの重要な部分に対するチェックを追加してください。

Lizardサービスのステータスとログを追加する

Lizard上のアプリケーションの場合、失敗を解釈する前にターゲットを確認します。

lizard skills get core --json
lizard status --json
lizard ps --project YOUR_PROJECT --json
lizard logs --project YOUR_PROJECT --service YOUR_SERVICE --tail 100 --json

Lizard CLIは、機械可読なサービス情報と制限付きのログスナップショットを提供します。コアガイドはインストールされているCLIバージョンと一致します。より多くのコマンドやフラグが必要な場合に使用し、自動化では明示的なプロジェクトおよびサービスセレクターを使用してください。

適合させたHTTPコレクターをサービスのパブリックURLに対して実行します。コンテナが実行中としてマークされていても、価格の検索やデータベースの読み取りが機能することを証明するものではありません。HTTPの失敗時刻とサービスログを比較して、次の調査を絞り込みます。モデルに送信する前に、ログの内容を確認して編集（リダクト）してください。

最初にデプロイする必要がある場合は、コーディングエージェントのデプロイメントガイドから始めてください。データ依存関係があるアプリの場合、Postgres MCPチュートリアルとRedis MCPチュートリアルで、テストデータを検査するためのスコープ付きアクセスについて説明しています。

自動化で結果を使用する

アプリケーション合格、アプリケーション失敗、レポートジョブ失敗の3つの結果を明示的に保持します。このラッパーはそれぞれ0、1、2を使用します。タイムアウト、CLI認証の問題、無効なレポート、または出力の矛盾はコード2を生成します。

レポートと一緒に検証データを保存します。これにより、チームメイトは文章の要約を信用することなく結果を検証できます。スケジュールされた実行には個別の出力パスを指定し、保持期間を設定し、アーティファクトに認証情報を保存しないようにします。

自身の信頼できるマシンでは、codex execは保存されたCLIログインを再利用できます。GitHub Actionsの場合は、認証と権限の設定について公式のCodexアクションガイドに従ってください。API認証情報をリポジトリファイルから除外し、信頼できないビルドステップに公開しないようにします。ローカルコマンドをCIに移行する前に、それらのランナー固有の要件を確認してください。

独立したチェックごとに新しい検証データを使用します。codex exec resumeは会話を継続できますが、この単発のレポートには必要ありません。この例のエフェメラルモードにより、各実行は独立したものになります。

トラブルシューティング

次のステップ

このパターンを的を絞ったデプロイメントチェックに使用し、次にアプリケーションの実際の依存関係に対するアサーションを追加します。失敗した結果が有用な次のステップを示すように、チェックを十分に小さく保ちます。

チームがClaude Codeを使用している場合、Claude Codeヘッドレスガイドでは、その結果エンベロープを使用した同じHTTPチェックを示しています。アプリケーション自体を実行するには、Lizard CLIを使用し、デプロイメントステップの後にレポートを追加します。