~/.codex/sessions/**/rollout-*.jsonl) を読み取ってスパンを再構築します。ファイア・アンド・フォーゲット方式の Stop フックを介して、Codex のクリティカルパスから完全に切り離された状態で動作するため、Codex がネットワークの応答を待つことはありません。
これは Weights & Biases Weave のプラグインです。CoreWeave Forge 版はまだ提供されていません。Agent Lens と Weave は同じトレースデータを共有しているため、このプラグインが送信したトレースは Agent Lens に表示されます。
前提条件
- Node.js v20 以降。
- フック システムに対応した OpenAI Codex CLI。
- CoreWeave Forge アカウント、および
WANDB_API_KEY環境変数に設定した APIキー。 - トレースの送信先となる Agent Lens project (
[YOUR-TEAM]/[YOUR-PROJECT]) 。
プラグインをインストールする
1
パッケージをインストールする
2
認証情報と project を設定する
wandb login を使用する代わりに、環境変数 WANDB_API_KEY を直接設定することもできます。優先順位のルールの詳細については、認証情報の解決順序を参照してください。3
Stop フックをインストールする
~/.codex/hooks.json にマージされます。Codex の各ターンが完了するたびに、フックはデタッチされたワーカーを起動します。このワーカーは、セッションごとのカーソル位置以降に追加されたロールアウト行を読み取り、スパンを再構築して Agent Lens にエクスポートします。4
Codex でフックを承認する
Codex は新しく追加されたフックを未信頼として扱い、承認されるまで実行しません。次回
codex を起動した際に、プロンプトが表示されたら weave-codex フックを承認してください。または、~/.codex/config.toml で bypass_hook_trust = true を設定すると、このプロンプトを省略できます。weave-codex status を実行して、すべてが正しく設定されていることを確認してください。Agent Lens で Codex のトレースを表示する
Codex セッションを 1 回以上実行したら、Agent Lens UI で project を開きます。- CoreWeave Forge にアクセスし、プロダクト メニューから Agent Lens を選択して、サイド メニュー上部の project セレクターで対象の project を選択します。
- サイド メニューで Conversations を選択します。
- 会話を選択すると、ターンの階層全体を確認できます。
gen_ai.conversation.id はすべてのスパンで Codex のセッション ID に設定され、Agent Lens はこの値を使用して、Conversations タブでターンを 1 つの会話にまとめます。スパンのタイムスタンプはロールアウト ファイルのタイムスタンプに合わせて遡って設定されるため、所要時間には実際の実行時間が反映されます。
すべての属性が GenAI セマンティック規約に準拠しているため、トレースは OTEL 互換の任意のバックエンドでもレンダリングできます。
既知の制限事項
codex(インタラクティブ TUI) コマンドとcodex execコマンドがサポートされています。codex mcpコマンドとapp-serverコマンドはフックを発火しないため、サポート対象外です。- 生成されたサブエージェントは、
spawn_agentのツール呼び出しとしてのみ表示されます。サブエージェント自体のモデルの Call やツール実行は取得されません。 - Stop フックは、中断されたターンやエラーで終了したターンでは発火しません。そのため、これらのターンは取得されません。
設定リファレンス
このセクションでは、プラグインの動作をカスタマイズするための設定を示します。設定ファイルとランタイムファイルは~/.weave-codex/ に保存されます。これには settings.json、フック シム、セッションごとのカーソル、logs/collector.log のログファイルが含まれます。
認証情報の解決順序
プラグインは、次の順序で認証情報を解決します。- 環境変数 (
WANDB_API_KEY、WEAVE_PROJECT) ~/.weave-codex/settings.json~/.netrc内の Agent Lens ホストのエントリ
プラグインのステータスを確認する
以下の CLI コマンドを使用すると、プラグインのステータスの確認や問題のトラブルシューティングを行えます。✓ (OK) 、✗ (対応が必要) 、- (まだ有効ではないが、エラーではない) のいずれかが表示されます。Agent Lens にターンが表示されない場合は、コレクターのログを確認してください。
トラブルシューティング
以下のセクションでは、よくある問題とその解決方法について説明します。問題の診断には、主に~/.weave-codex/logs/collector.log にあるコレクターのログを使用します。プラグインは、debug の設定に関係なく、常にエラーをログします。
Codex の実行後にトレースが表示されない
weave-codex statusを実行し、すべてのチェックに合格していることを確認します。- フックが信頼済みであることを確認します。初回起動時に承認プロンプトをスキップした場合は、
codexを再度実行し、プロンプトが表示されたら承認してください。または、~/.codex/config.tomlでbypass_hook_trust = trueを設定します。 WEAVE_PROJECTに有効なentity/projectスラッグが設定されていることを確認します。解決された project はweave-codex statusの出力で確認できます。- 認証ソースを確認します。解決された認証情報ソースは
weave-codex statusの出力で確認できます。WANDB_API_KEY envと表示されているのに、キーを別の場所で設定している場合は、プラグインが誤った値を読み取っています。
ターンは表示されるが入力/出力のテキストが空になる
コンテンツの取得が無効になっている可能性があります。WEAVE_CODEX_CAPTURE_CONTENT が 0 に設定されていないこと、および ~/.weave-codex/settings.json の capture_content が false に設定されていないことを確認してください。
Agent Lens へのトレース送信時のエラー
プラグインが有効でスパンが生成されているにもかかわらず Agent Lens に表示されない場合は、コレクターのログでエクスポートエラーを確認し、次の表と照らし合わせてください。フックがロックされた環境
Codex の設定でallow_managed_hooks_only が設定されている場合、カスタムフックを直接追加することはできません。代わりに、Codex の notify プログラムをフォールバック用のトリガーとして使用してください。
アンインストール
~/.codex/hooks.json から weave-codex のエントリのみが削除されます。