Weave for Agents はパブリック プレビューです。一般提供前に、機能、API、Agents view UI は変更される可能性があります。
~/.codex/sessions/**/rollout-*.jsonl) を読み取り、スパンを再構築します。fire-and-forget の Stop フック を通じて Codex のクリティカルパスとは完全に切り離して実行されるため、Codex がネットワークを待つことはありません。
前提条件
- Node.js v20 以降。
- hooks システムを備えた OpenAI Codex CLI 。
WANDB_API_KEY環境変数として設定した APIキー を持つ W&B アカウント。- トレースの送信先となる Weave project (
[YOUR-TEAM]/[YOUR-PROJECT]) 。
プラグインをインストールする
認証情報と project を設定します
wandb login を使う代わりに、WANDB_API_KEY を環境変数として直接設定することもできます。優先順位の詳細なルールについては、認証情報の解決順序を参照してください。Stop フック をインストールします
~/.codex/hooks.json に追加されます。このフックは、Codex の各ターンが完了するたびにデタッチされたワーカーを起動し、セッションごとのカーソル以降の新しいロールアウト行を読み取り、スパン を再構築して Weave にエクスポートします。Weave で Codex トレースを表示する
- https://wandb.ai にアクセスし、project を選択します。
- サイドバーで、複数ターンのチャットビューとエージェントごとのバージョンのグループ化を表示するには Agents を、生のスパンツリーを表示するには Traces を選択します。
- 会話を選択して、ターン階層全体を確認します。
| スパン | 出力タイミング | 主要な属性 |
|---|---|---|
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 も含まれます |
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 | オフ (エラーは常にログされます) |
認証情報の解決順序
- 環境変数 (
WANDB_API_KEY、WEAVE_PROJECT) 。 ~/.weave-codex/settings.json。- Weave ホスト用の
~/.netrcエントリ。
W&B 専用クラウドまたはセルフホスト型インスタンス
WANDB_BASE_URL をインストール先のホストに設定してください。
プラグインのステータスを確認する
✓ (OK) 、✗ (要対応) 、または - (まだ有効化されていませんが、エラーではありません) が表示されます。Weave にターンが表示されない場合は、collector のログを確認してください。
トラブルシューティング
~/.weave-codex/logs/collector.log にある collector のログが、主な診断情報源です。エラーは、debug の設定にかかわらず常にログに記録されます。
Codex を実行してもトレースが表示されない
weave-codex statusを実行します。すべてのチェックにパスしていることを確認してください。- フック が信頼済みであることを確認します。初回起動時の承認プロンプトをスキップした場合は、
codexをもう一度実行し、プロンプトが表示されたら承認してください。あるいは、~/.codex/config.tomlでbypass_hook_trust = trueを設定してください。 WEAVE_PROJECTが有効なentity/projectスラッグに設定されていることを確認します。weave-codex statusには、解決された project が表示されます。- 認証ソースを確認します。
weave-codex statusには、解決された認証情報ソースが表示されます。WANDB_API_KEY envと表示されるのにキーを別の場所で設定している場合、プラグインは誤った値を読み取ります。
ターンは表示されるが、入力/出力テキストが空です
WEAVE_CODEX_CAPTURE_CONTENT が 0 に設定されていないこと、および ~/.weave-codex/settings.json で capture_content が false に設定されていないことを確認してください。
Weave へのトレース送信時のエラー
| 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 に到達できることを確認してください。 |
フックが制限された環境
allow_managed_hooks_only が有効になっている場合、カスタムフックを直接追加することはできません。代替のトリガーとして、Codex の notify プログラムを使用してください。
アンインストール
~/.codex/hooks.json から削除されるのは weave-codex のエントリのみです。