Skip to main content
Weave Codex プラグインは、Codex のすべてのターンを自動的にトレースし、構造化データを W&B Weave に送信します。Codex のワークフローを変更することなく、すべてのモデルの Call、ツール実行、推論ステップがログされます。これらのトレースを使用すると、セッションのデバッグ、ツールの使用状況の監査、複数の run にわたるコストとレイテンシーのモニタリングを行えます。 このプラグインは、Codex 自身が出力するロールアウト セッションファイル (~/.codex/sessions/**/rollout-*.jsonl) を読み取ってスパンを再構築します。ファイア・アンド・フォーゲット方式の Stop フックを介して、Codex のクリティカルパスから完全に切り離された状態で実行されるため、Codex がネットワーク処理を待つことはありません。
デフォルトでは、このプラグインはスパンのコンテンツ (プロンプト、モデルの応答と推論、ツール呼び出しの引数、ツール結果) を取得します。ツール結果には、シェルコマンド、コマンドの出力、ファイルの内容が含まれます。これらのデータは Weave インスタンスに送信されます。PII のスクラブや機密データのマスキングには対応していません。構造、トークン使用量、モデル、タイミング情報のみを送信する (プロンプト、コード、出力は送信しない) 場合は、WEAVE_CODEX_CAPTURE_CONTENT=0 を設定してください。セキュリティ要件やコンプライアンス要件により、これらのデータを Weave に送信できない場合は、このプラグインをインストールしないでください。

​
前提条件

  • Node.js v20 以降。
  • フックシステムを備えた OpenAI Codex CLI。
  • CoreWeave Forge アカウントと、WANDB_API_KEY 環境変数として設定された APIキー。
  • トレースを受け取る Weave プロジェクト ([YOUR-TEAM]/[YOUR-PROJECT]) 。

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

1

パッケージをインストールする

2

認証情報と project を設定する

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

Stop フックをインストールする

これにより、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 のトレースを表示する

Codex セッションを少なくとも 1 回実行した後、Weights & Biases UI で project を開きます。
  1. Forge にアクセスし、project を選択します。
  2. サイドバーで Agents を選択すると、マルチターンのチャットビューとエージェントのバージョン別のグループ化が表示されます。生のスパンツリーを表示するには Traces を選択します。
  3. 会話を選択して、ターンの階層全体を確認します。
Agents ビューの詳細については、エージェントのアクティビティを表示するを参照してください。 プラグインは、GenAI セマンティック規約に従って、Codex のターンごとに 1 つの OTEL トレースを出力します。 Weave は、すべてのスパンで Codex セッション ID に設定される gen_ai.conversation.id を使用して、Agents ビューでターンを 1 つの会話にまとめます。スパンのタイムスタンプはロールアウトファイルのタイムスタンプに基づいて過去の時刻に設定されるため、所要時間には実際の実行時間が反映されます。 すべての属性が GenAI セマンティック規約に従っているため、トレースは OTEL 互換のどのバックエンドでもレンダリングされます。

​
既知の制限事項

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

​
設定リファレンス

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

​
認証情報の解決順序

プラグインは認証情報を以下の順序で解決します：
  1. 環境変数 (WANDB_API_KEY, WEAVE_PROJECT)。
  2. ~/.weave-codex/settings.json。
  3. Weave ホストの ~/.netrc エントリ。

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

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

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

次の CLI コマンドを使用すると、プラグインのステータスの確認や問題のトラブルシューティングを行えます。
各行には ✓ (正常) 、✗ (対応が必要) 、- (未有効ですがエラーではありません) のいずれかが表示されます。Weave にターンが表示されない場合は、コレクターのログを確認してください：

​
トラブルシューティング

以下のセクションでは、よくある問題とその解決方法を説明します。~/.weave-codex/logs/collector.log にあるコレクターのログが、診断の主なソースです。プラグインは 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 に表示されない場合は、コレクターのログでエクスポートエラーを確認し、この表と照合してください。

​
フックがロックされた環境

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

​
アンインストール

これにより、~/.codex/hooks.json から weave-codex のエントリのみが削除されます。
最終更新日 2026年9月30日