> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex プラグイン

> Codex のエージェント型セッション、LLM Call、ツール実行を Agent Lens でトレースします。

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

このプラグインは、Codex 自身のロールアウトセッションファイル (`~/.codex/sessions/**/rollout-*.jsonl`) を読み取ってスパンを再構築します。ファイア・アンド・フォーゲット方式の Stop フックを介して、Codex のクリティカルパスから完全に切り離された状態で動作するため、Codex がネットワークの応答を待つことはありません。

<Note>
  これは Weights & Biases Weave のプラグインです。CoreWeave Forge 版はまだ提供されていません。Agent Lens と Weave は同じトレースデータを共有しているため、このプラグインが送信したトレースは Agent Lens に表示されます。
</Note>

<Warning>
  デフォルトでは、このプラグインはスパンのコンテンツ (プロンプト、モデルの応答と推論、ツール呼び出しの引数、ツール結果) を取得します。ツール結果には、シェルコマンド、コマンドの出力、ファイルの内容が含まれます。これらのデータは Agent Lens インスタンスに送信されます。

  PII の除去や機密データのマスキングには対応していません。構造、トークン使用量、モデル、タイミングのみを送信する (プロンプト、コード、出力は送信しない) には、`WEAVE_CODEX_CAPTURE_CONTENT=0` を設定してください。セキュリティやコンプライアンス上の要件により、これらのデータを Agent Lens に送信できない場合は、このプラグインをインストールしないでください。
</Warning>

<h2 id="prerequisites">
  前提条件
</h2>

* [Node.js](https://nodejs.org/) v20 以降。
* フック システムに対応した [OpenAI Codex CLI](https://github.com/openai/codex)。
* CoreWeave Forge アカウント、および `WANDB_API_KEY` 環境変数に設定した [APIキー](https://forge.coreweave.com/settings#apikeys)。
* トレースの送信先となる Agent Lens project (`[YOUR-TEAM]/[YOUR-PROJECT]`) 。

<h2 id="install-the-plugin">
  プラグインをインストールする
</h2>

<Steps>
  <Step title="パッケージをインストールする">
    ```bash lines theme={"system"}
    npm install -g weave-codex
    ```
  </Step>

  <Step title="認証情報と project を設定する">
    ```bash lines theme={"system"}
    wandb login
    export WEAVE_PROJECT="YOUR-TEAM/YOUR-PROJECT"
    ```

    `wandb login` を使用する代わりに、環境変数 `WANDB_API_KEY` を直接設定することもできます。優先順位のルールの詳細については、[認証情報の解決順序](#credential-resolution-order)を参照してください。
  </Step>

  <Step title="Stop フックをインストールする">
    ```bash lines theme={"system"}
    weave-codex install
    ```

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

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

    または、`~/.codex/config.toml` で `bypass_hook_trust = true` を設定すると、このプロンプトを省略できます。

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

これで、Codex を通常どおり使用できます。完了した各ターンは、約 1 秒以内に Agent Lens に表示されます。

<h2 id="view-codex-traces-in-agent-lens">
  Agent Lens で Codex のトレースを表示する
</h2>

Codex セッションを 1 回以上実行したら、Agent Lens UI で project を開きます。

1. [CoreWeave Forge](https://forge.coreweave.com) にアクセスし、プロダクト メニューから Agent Lens を選択して、サイド メニュー上部の project セレクターで対象の project を選択します。
2. サイド メニューで **Conversations** を選択します。
3. 会話を選択すると、ターンの階層全体を確認できます。

Conversations タブの詳細については、[エージェントのアクティビティを表示する](/ja/products/agent-lens/conversations/view-activity)を参照してください。

このプラグインは、[GenAI セマンティック規約](https://opentelemetry.io/docs/specs/semconv/gen-ai/)に従って、Codex のターンごとに 1 つの OTEL トレースを出力します。

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

`gen_ai.conversation.id` はすべてのスパンで Codex のセッション ID に設定され、Agent Lens はこの値を使用して、Conversations タブでターンを 1 つの会話にまとめます。スパンのタイムスタンプはロールアウト ファイルのタイムスタンプに合わせて遡って設定されるため、所要時間には実際の実行時間が反映されます。

すべての属性が GenAI セマンティック規約に準拠しているため、トレースは OTEL 互換の任意のバックエンドでもレンダリングできます。

<h3 id="known-limitations">
  既知の制限事項
</h3>

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

<h2 id="configuration-reference">
  設定リファレンス
</h2>

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

| 設定 | 環境変数 | `settings.json` のキー | デフォルト |
| - | - | - | - |
| Forge APIキー | `WANDB_API_KEY` | `wandb_api_key` | `~/.netrc` (`wandb login` で設定) |
| Agent Lens project | `WEAVE_PROJECT` | `weave_project` | なし (必須、`entity/project`) |
| コンテンツの取得 | `WEAVE_CODEX_CAPTURE_CONTENT` | `capture_content` | `true` |
| デバッグログ | `WEAVE_CODEX_DEBUG` | `debug` | オフ (エラーは常にログされます) |

<h3 id="credential-resolution-order">
  認証情報の解決順序
</h3>

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

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

<h2 id="check-plugin-status">
  プラグインのステータスを確認する
</h2>

以下の CLI コマンドを使用すると、プラグインのステータスの確認や問題のトラブルシューティングを行えます。

```bash lines theme={"system"}
weave-codex status
```

各行には `✓` (OK) 、`✗` (対応が必要) 、`-` (まだ有効ではないが、エラーではない) のいずれかが表示されます。Agent Lens にターンが表示されない場合は、コレクターのログを確認してください。

```bash lines theme={"system"}
cat ~/.weave-codex/logs/collector.log
```

<h2 id="troubleshooting">
  トラブルシューティング
</h2>

以下のセクションでは、よくある問題とその解決方法について説明します。問題の診断には、主に `~/.weave-codex/logs/collector.log` にあるコレクターのログを使用します。プラグインは、`debug` の設定に関係なく、常にエラーをログします。

<h3 id="no-traces-appear-after-running-codex">
  Codex の実行後にトレースが表示されない
</h3>

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

<h3 id="turns-appear-but-inputoutput-text-is-empty">
  ターンは表示されるが入力/出力のテキストが空になる
</h3>

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

<h3 id="errors-sending-traces-to-agent-lens">
  Agent Lens へのトレース送信時のエラー
</h3>

プラグインが有効でスパンが生成されているにもかかわらず Agent Lens に表示されない場合は、コレクターのログでエクスポートエラーを確認し、次の表と照らし合わせてください。

| 症状 | 考えられる主な原因 | 対処方法 |
| - | - | - |
| `trace.wandb.ai` から 401 または 403 が返される | APIキーが無効であるか、スコープが制限されている | キーが有効であること、およびチームがその entity と project を所有していることを確認してください。解決された認証情報ソースは `weave-codex status` で確認できます。 |
| 接続拒否または DNS エラー | DNS、プロキシ、またはファイアウォール | ホストからポート 443 で `trace.wandb.ai` に接続できることを確認してください。 |

<h3 id="hook-locked-environments">
  フックがロックされた環境
</h3>

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

```toml lines theme={"system"}
# ~/.codex/config.toml
notify = ["sh", "/Users/you/.weave-codex/stop-hook.sh"]
```

<h2 id="uninstall">
  アンインストール
</h2>

```bash lines theme={"system"}
weave-codex uninstall
```

この操作では、`~/.codex/hooks.json` から `weave-codex` のエントリのみが削除されます。