Codex プラグイン

W&B Weave で、Codex のエージェント セッション、LLM Call、ツール実行をトレースします。

Weave Codex プラグインは、Codex の各ターンを自動的にトレースし、その構造化データを W&B Weave に送信します。Codex のワークフローを変更することなく、すべてのモデル Call、ツール実行、推論ステップがログされます。これらのトレースを使用して、セッションのデバッグ、ツール使用状況の監査、Runs 全体のコストとレイテンシの監視を行えます。

このプラグインは、Codex 自身のロールアウトセッションファイル (~/.codex/sessions/**/rollout-*.jsonl) を読み取り、スパンを再構築します。fire-and-forget の Stop フック を通じて Codex のクリティカルパスとは完全に切り離して実行されるため、Codex がネットワークを待つことはありません。

デフォルトでは、このプラグインはスパンの内容、つまりプロンプト、モデルの応答と推論、ツール呼び出しの引数、ツールの結果を取得します。ツールの結果には、シェルコマンド、コマンド出力、file の内容が含まれます。このデータは、お使いの Weave インスタンスに送信されます。

PII のスクラビングや機密データのマスクは実装されていません。構造、トークン使用量、モデル、タイミングのみを送信し、プロンプト、コード、出力を送信しないようにするには、WEAVE_CODEX_CAPTURE_CONTENT=0 を設定してください。セキュリティまたはコンプライアンス要件上、このデータを Weave に送信できない場合は、このプラグインをインストールしないでください。

​

前提条件

• Node.js v20 以降。
• hooks システムを備えた OpenAI Codex CLI 。
• WANDB_API_KEY 環境変数として設定した APIキー を持つ W&B アカウント。
• トレースの送信先となる Weave project ([YOUR-TEAM]/[YOUR-PROJECT]) 。

​

プラグインをインストールする

1. パッケージをインストールします

   npm install -g weave-codex
   
2. 認証情報と project を設定します

   wandb login
   export WEAVE_PROJECT="YOUR-TEAM/YOUR-PROJECT"
   

   wandb login を使う代わりに、WANDB_API_KEY を環境変数として直接設定することもできます。優先順位の詳細なルールについては、認証情報の解決順序を参照してください。

3. Stop フック をインストールします

   weave-codex install
   

   これにより、Stop フック が ~/.codex/hooks.json に追加されます。このフックは、Codex の各ターンが完了するたびにデタッチされたワーカーを起動し、セッションごとのカーソル以降の新しいロールアウト行を読み取り、スパン を再構築して Weave にエクスポートします。

4. Codex でフック を承認します

   Codex は新しく追加された フック を未信頼としてマークし、承認するまで実行しません。次回 codex を起動したときにプロンプトが表示されたら、weave-codex フック を承認してください。

   または、~/.codex/config.toml で bypass_hook_trust = true を設定して、プロンプトをスキップすることもできます。

   weave-codex status を実行して、すべてが正しく設定されていることを確認してください。

これで Codex を通常どおり実行でき、完了した各ターンが約 1 秒以内に Weave に表示されます。

​

Weave で Codex トレースを表示する

少なくとも 1 つの Codex セッションを実行したら、Weave UI で project を開きます。

1. https://wandb.ai にアクセスし、project を選択します。
2. サイドバーで、複数ターンのチャットビューとエージェントごとのバージョンのグループ化を表示するには Agents を、生のスパンツリーを表示するには Traces を選択します。
3. 会話を選択して、ターン階層全体を確認します。

Agents ビューの詳細については、エージェントのアクティビティを表示する を参照してください。

このプラグインは、GenAI semantic conventions に従って、Codex の各ターンについて 1 つの OTEL トレースを出力します。

スパン	出力タイミング	主要な属性
invoke_agent codex	ターンごと (ルートスパン)	エージェント名またはバージョン、gen_ai.conversation.id、モデル、合計 token 使用量、ユーザープロンプトと最終回答 (コンテンツ取得がオンの場合)
chat <model>	モデル Call ごと	gen_ai.usage.* (入力、出力、キャッシュ済み、推論 token) 、終了理由、server.address、アシスタント出力 (コンテンツ取得がオンの場合)
execute_tool <name>	ツール実行ごと	gen_ai.tool.name、gen_ai.tool.call.id、引数と結果 (コンテンツ取得がオンの場合) 、および MCP Call には mcp.server.name も含まれます

Weave は gen_ai.conversation.id を使用して、Agents ビューで複数のターンを 1 つの会話としてグループ化します。これは各スパンで Codex セッション ID に設定されます。スパンのタイムスタンプはロールアウト file のタイムスタンプに基づいて過去時刻へ補正されるため、継続時間には実際の実行時間が反映されます。

すべての属性が GenAI semantic conventions に従っているため、トレースは OTEL 互換の任意のバックエンドでもレンダリングされます。

​

既知の制限事項

• codex (対話型TUI) および codex exec コマンドはサポートされます。codex mcp と app-server コマンドはフックが発火しないため、対象外です。
• 起動されたサブエージェントは、spawn_agent ツール Call としてのみ表示されます。サブエージェント自身のモデルの Call とツール実行は、取得されません。
• Stop フックは中断されたターンやエラーが発生したターンでは発火しないため、それらは取得されません。

​

設定リファレンス

このセクションでは、プラグインの動作をカスタマイズするために使用できる設定を一覧で示します。設定ファイルと実行時ファイルは ~/.weave-codex/ に保存されます。これには、settings.json、hook shim、セッションごとのカーソル、logs/collector.log にあるログファイルが含まれます。

設定	環境変数	settings.json キー	デフォルト
W&B APIキー	WANDB_API_KEY	wandb_api_key	~/.netrc (wandb login 経由)
Weave project	WEAVE_PROJECT	weave_project	なし (必須、entity/project)
ベース URL	WANDB_BASE_URL	wandb_base_url	https://trace.wandb.ai
コンテンツ取得	WEAVE_CODEX_CAPTURE_CONTENT	capture_content	true
デバッグロギング	WEAVE_CODEX_DEBUG	debug	オフ (エラーは常にログされます)

​

認証情報の解決順序

プラグインは認証情報を次の順序で参照します。

1. 環境変数 (WANDB_API_KEY、WEAVE_PROJECT) 。
2. ~/.weave-codex/settings.json。
3. Weave ホスト用の ~/.netrc エントリ。

​

W&B 専用クラウドまたはセルフホスト型インスタンス

Codex を実行する前に、WANDB_BASE_URL をインストール先のホストに設定してください。

export WANDB_BASE_URL=https://YOUR-INSTANCE.wandb.io

​

プラグインのステータスを確認する

これらのCLIコマンドを使用すると、プラグインのステータスを確認したり、問題のトラブルシューティングを行ったりできます。

weave-codex status

各行には ✓ (OK) 、✗ (要対応) 、または - (まだ有効化されていませんが、エラーではありません) が表示されます。Weave にターンが表示されない場合は、collector のログを確認してください。

cat ~/.weave-codex/logs/collector.log

​

トラブルシューティング

以下のセクションでは、よくある問題とその解決方法について説明します。~/.weave-codex/logs/collector.log にある collector のログが、主な診断情報源です。エラーは、debug の設定にかかわらず常にログに記録されます。

​

Codex を実行してもトレースが表示されない

1. weave-codex status を実行します。すべてのチェックにパスしていることを確認してください。
2. フック が信頼済みであることを確認します。初回起動時の承認プロンプトをスキップした場合は、codex をもう一度実行し、プロンプトが表示されたら承認してください。あるいは、~/.codex/config.toml で bypass_hook_trust = true を設定してください。
3. WEAVE_PROJECT が有効な entity/project スラッグに設定されていることを確認します。weave-codex status には、解決された project が表示されます。
4. 認証ソースを確認します。weave-codex status には、解決された認証情報ソースが表示されます。WANDB_API_KEY env と表示されるのにキーを別の場所で設定している場合、プラグインは誤った値を読み取ります。

​

ターンは表示されるが、入力/出力テキストが空です

コンテンツの取得が無効になっている可能性があります。WEAVE_CODEX_CAPTURE_CONTENT が 0 に設定されていないこと、および ~/.weave-codex/settings.json で capture_content が false に設定されていないことを確認してください。

​

Weave へのトレース送信時のエラー

プラグインが有効で、Weave に表示されないスパンが生成されている場合は、collector ログでエクスポート エラーを確認し、この表と照らし合わせてください。

Symptom	Most likely cause	Fix
trace.wandb.ai からの 401 または 403	無効な APIキー、またはスコープが制限された APIキー	キーが有効であること、およびチームが該当の entity と project を所有していることを確認してください。実際に使用されている認証情報のソースは weave-codex status で確認できます。
agents endpoint からの 404	誤った ベース URL	専用クラウド環境では、WANDB_BASE_URL をご利用のインストール ホストに設定してください。
接続拒否または DNS エラー	DNS、プロキシ、またはファイアウォール	ホストから trace.wandb.ai (クラウド) またはご利用のインストール ホスト (専用クラウド) のポート 443 に到達できることを確認してください。

​

フックが制限された環境

Codex の設定で allow_managed_hooks_only が有効になっている場合、カスタムフックを直接追加することはできません。代替のトリガーとして、Codex の notify プログラムを使用してください。

# ~/.codex/config.toml
notify = ["sh", "/Users/you/.weave-codex/stop-hook.sh"]

​

アンインストール

weave-codex uninstall

これにより、~/.codex/hooks.json から削除されるのは weave-codex のエントリのみです。