~/.codex/sessions/**/rollout-*.jsonl) を読み取ってスパンを再構築します。ターンが終了すると Stop フックがデタッチされたコレクターを起動するため、Codex がネットワーク処理を待つことはありません。同じ Codex セッション内のターンは会話 ID を共有するため、Agent Lens では 1 つの会話としてまとめて表示されます。
前提条件
- macOS または Linux。Windows はサポートされていません。
- Node.js v20.6 以降。
- フックとロールアウトのログ記録を有効にした OpenAI Codex CLI。
codex --ephemeralはロールアウトファイルを書き出さないため、サポートされていません。 - CoreWeave Forge アカウントと Forge API キー。
- トレースの送信先となる Agent Lens project (
[YOUR-TEAM]/[YOUR-PROJECT]) 。
プラグインをインストールする
1
パッケージをインストールする
このプラグインは、Weave ガイドで説明している
weave-codex プラグインとは別のものです。パッケージ名は @coreweave/forge-agent-lens-for-codex で、コマンド、環境変数、設定ディレクトリには forge-agent-lens-for-codex および FORGE_ という名前を使用します。weave-codex をインストール済みの場合は、2 つのプラグインが重複したトレースを送信しないよう、このプラグインをインストールする前に weave-codex uninstall と npm uninstall -g weave-codex を実行してください。FORGE_TRACE_PROJECT には、WEAVE_PROJECT に使用していた値を設定します。このプラグインは weave-codex の設定を読み取りません。2
project と APIキーを設定する
[YOUR-TEAM]/[YOUR-PROJECT] を Agent Lens の project に、[YOUR-API-KEY] を APIキーに置き換えてから、エクスポートします。WANDB_API_KEY を設定する代わりに wandb login を実行することもできます。プラグインが各設定を解決する仕組みについては、設定リファレンスを参照してください。3
Stop フックをインストールする
~/.codex/hooks.json にマージし、元のファイルを一度だけ hooks.json.bak にバックアップします。また、既存の Codex セッションはスキップされるため、Agent Lens に送信されるのはインストール後に実行したターンのみです。過去の履歴を明示的に送信するには、過去のセッションを収集するを参照してください。4
Codex でフックを承認する
Codex では、新しく追加されたフックは承認するまで実行されません。
-
ターミナルを開いて次のコマンドを実行します。
-
シェルではなく、Codex の対話型画面で次のように入力します。
- Stop イベントで Forge Agent Lens フックを選択し、有効化または信頼します。
--dangerously-bypass-hook-trust フラグも使用できます。forge-agent-lens-for-codex status を実行して、フックがインストールされ、プラグインが ready になっていることを確認します。Agent Lens で Codex のトレースを表示する
Codex セッションを 1 回以上実行したら、Agent Lens UI で project を開きます。- CoreWeave Forge にアクセスし、プロダクト メニューから Agent Lens を選択して、サイド メニュー上部の project セレクターで対象の project を選択します。
- サイド メニューで Conversations を選択します。
- 会話を選択すると、ターンの階層全体を確認できます。
スパンのタイムスタンプはロールアウト ファイルから取得されるため、所要時間には実際の実行時間が反映されます。各ターンは 1 回だけ送信されます。エクスポートに失敗した場合、プラグインは次に Stop フックが実行されたときにそのターンを再送信します。
既知の制限事項
codex(対話型 TUI)およびcodex execコマンドがサポートされています。codex mcp、app-server や API との直接のセッション、および Stop イベントが発生しないまま中断されたターンは対象外です。- 起動されたサブエージェントは、ツールスパンとしてのみ表示されます。サブエージェント個別のロールアウトファイルはネストされたトレースとして再構築されないため、サブエージェント自身のモデルの Call やツール実行は取得されません。
- 一部の
codex exec環境では Stop フックが実行されません。詳しくは、プラグインの README の Headless runs and explicit collection を参照してください。
設定リファレンス
このセクションでは、プラグインの動作をカスタマイズするための設定を一覧で示します。状態、設定、ログファイルは~/.forge-agent-lens-for-codex/ に保存されます (settings.json と logs/collector.log を含みます) 。FORGE_CODEX_HOME は、分離された開発環境またはテスト環境でのみ設定してください。
Codex がプロキシまたはブリッジを経由して別のモデルプロバイダーにリクエストを送信する場合は、
FORGE_CODEX_PROVIDER_NAME を設定してください。プラグインはこの値をモデルのスパンに記録します。
認証情報の解決順序
このプラグインが APIキーをsettings.json に書き込むことはありません。キーは次の順序で検索されます。
WANDB_API_KEY環境変数api.wandb.aiの~/.netrcエントリ (WANDB_BASE_URLを設定している場合は、そのホストのエントリ)
settings.json、デフォルトの順に優先されます。
トレースサーバーとトランスポートは Forge SDK によって解決されます。カスタムデプロイメントを使用する場合は、WANDB_BASE_URL を設定します。トレースサーバーを明示的に上書きするには、WF_TRACE_SERVER_URL を設定します。
コンテンツの取得を無効にする
FORGE_CODEX_INCLUDE_CONTENT=false を設定すると、プロンプト、アシスタントの出力、推論、ツールの引数と結果、および作業ディレクトリが省略されます。スパンには、モデル名、トークン使用量、タイミング、ツール名、Call ID、MCP サーバー名が引き続き記録されます。
対話型の Stop フックで収集する場合は、代わりに ~/.forge-agent-lens-for-codex/settings.json で include_content を false に設定してください。codex コマンドにのみ設定した変数は、すでに実行中の Codex アプリサーバーが実行するフックには反映されない場合があるため、ファイルで設定するほうが確実です。フックプロセスの環境変数は設定ファイルよりも優先されるため、その環境で FORGE_CODEX_INCLUDE_CONTENT=true が設定されていないことを確認してください。この変数が未設定の場合、プラグインは settings.json の値を使用します。forge-agent-lens-for-codex collect を明示的に実行する場合は、環境変数で設定する方法が確実です。
過去のセッションを収集する
collect --all は明示的なバックフィルです。すべてのロールアウトセッションから、まだエクスポートされていないターンを送信します。カーソルのないロールアウトは先頭から読み取られるため、このコマンドを実行すると、プラグインのインストール前に作成された履歴も送信されることがあります。
--json を追加します。
プラグインのステータスを確認する
プラグインのステータスの確認や問題のトラブルシューティングには、次のコマンドを使用します。--json を付けると、同じ内容を JSON 形式で出力できます。
Agent Lens にターンが表示されない場合は、コレクターのログを確認してください。
トラブルシューティング
以下のセクションでは、よくある問題とその解決方法について説明します。問題の診断には、主に~/.forge-agent-lens-for-codex/logs/collector.log にあるコレクターのログを使用します。プラグインは、debug の設定に関係なく、常にエラーをログします。
Codex の実行後にトレースが表示されない
forge-agent-lens-for-codex statusを実行します。最終行がnot readyの場合は、表示された理由に従って問題を解決します。- フックがインストールされ、有効になっていることを確認します。承認をスキップした場合は、
codexを実行してから/hooksを実行し、フックを有効にします。 FORGE_TRACE_PROJECTに有効なentity/projectスラッグ (/を 1 つだけ含むもの) が設定されていることを確認します。解決された project はstatusで確認できます。- APIキーが解決されていることを確認します。
statusではキーが解決されたかどうかはわかりますが、その取得元は表示されません。プラグインが誤ったキーを読み取っている場合は、WANDB_API_KEYと~/.netrcを確認してください。 - Codex が
--ephemeral付きで実行されていないことを確認します。このフラグを指定すると、プラグインが読み取るロールアウトファイルが生成されません。 - パッケージをアップグレードした場合や Node.js のバージョンを切り替えた場合は、
forge-agent-lens-for-codex installを再度実行します。フックには、インストール時の Node.js とパッケージのパスが記録されているためです。
ターンは表示されるが入力と出力のテキストが空になる
コンテンツの取得が無効になっている可能性があります。FORGE_CODEX_INCLUDE_CONTENT が false に設定されていないこと、および ~/.forge-agent-lens-for-codex/settings.json の include_content が false に設定されていないことを確認してください。status を実行すると、最終的に適用される include content の値が表示されます。
Agent Lens へのトレース送信時のエラー
プラグインが有効でスパンが生成されているにもかかわらず Agent Lens に表示されない場合は、コレクターのログでエクスポートエラーを確認し、次の表と照らし合わせてください。プラグインをアップグレードする
フックは、インストール時に使用された Node.js とパッケージのパスを記録します。アップグレードする場合や Node.js のバージョンを切り替えた後は、パッケージを再インストールしてからinstall をもう一度実行してください：