> ## 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 プラグイン

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

export const AgentLensBanner = ({href}) => <Tip>
    <strong>This workflow is also available in CoreWeave Agent Lens.</strong> Agent Lens is the Forge experience built for tracing, monitoring, and analyzing AI agents, with automated insights into agent failures and user intents. It uses the same trace data as Weights & Biases Weave, so the traces you already send appear there with nothing to migrate.{' '}
    <a href={href || '/products/agent-lens'}>{href ? 'See how to do this in Agent Lens' : 'Learn about Agent Lens'}</a>.
  </Tip>;

<AgentLensBanner href="/ja/products/agent-lens/integrations/codex" />

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

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

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

  PII のスクラブや機密データのマスキングには対応していません。構造、トークン使用量、モデル、タイミング情報のみを送信する (プロンプト、コード、出力は送信しない) 場合は、`WEAVE_CODEX_CAPTURE_CONTENT=0` を設定してください。セキュリティ要件やコンプライアンス要件により、これらのデータを Weave に送信できない場合は、このプラグインをインストールしないでください。
</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)。
* トレースを受け取る Weave プロジェクト (`[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 の各ターンが完了するたびに、フックはデタッチされたワーカーを起動します。このワーカーは、セッションごとのカーソル位置以降に追加されたロールアウト行を読み取り、スパンを再構築して Weave にエクスポートします。
  </Step>

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

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

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

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

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

Codex セッションを少なくとも 1 回実行した後、Weights & Biases UI で project を開きます。

1. [Forge](https://forge.coreweave.com/wandb) にアクセスし、project を選択します。
2. サイドバーで **Agents** を選択すると、マルチターンのチャットビューとエージェントのバージョン別のグループ化が表示されます。生のスパンツリーを表示するには **Traces** を選択します。
3. 会話を選択して、ターンの階層全体を確認します。

Agents ビューの詳細については、[エージェントのアクティビティを表示する](/ja/products/wandb/weave/guides/tracking/view-agent-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` も含まれます |

Weave は、すべてのスパンで Codex セッション ID に設定される `gen_ai.conversation.id` を使用して、Agents ビューでターンを 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` キー | デフォルト |
| - | - | - | - |
| W\&B APIキー | `WANDB_API_KEY` | `wandb_api_key` | `~/.netrc` (`wandb login` を通じて) |
| Weave プロジェクト | `WEAVE_PROJECT` | `weave_project` | None (必須、`entity/project`) |
| ベース URL | `WANDB_BASE_URL` | `wandb_base_url` | `https://trace.wandb.ai` |
| コンテンツの取得 | `WEAVE_CODEX_CAPTURE_CONTENT` | `capture_content` | `true` |
| デバッグログ | `WEAVE_CODEX_DEBUG` | `debug` | Off (エラーは常にログされます) |

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

プラグインは認証情報を以下の順序で解決します：

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

<h3 id="wb-dedicated-cloud-or-self-hosted-instances">
  W\&B 専用クラウドまたはセルフホストのインスタンス
</h3>

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

```bash lines theme={"system"}
export WANDB_BASE_URL=https://YOUR-INSTANCE.wandb.io
```

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

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

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

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

```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` スラッグが設定されていることを確認します。`weave-codex status` は、解決された project を表示します。
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-weave">
  Weave へのトレース送信時のエラー
</h3>

プラグインが有効で、生成されたスパンが Weave に表示されない場合は、コレクターのログでエクスポートエラーを確認し、この表と照合してください。

| 症状 | 最も可能性の高い原因 | 対処方法 |
| - | - | - |
| `trace.wandb.ai` からの 401 または 403 | APIキーが無効、またはスコープが制限されている | キーが現在有効で、チームが entity と project を所有していることを確認してください。`weave-codex status` で解決された認証情報ソースを確認してください。 |
| エージェントのエンドポイントからの 404 | ベース URL が誤っている | 専用クラウド環境では、`WANDB_BASE_URL` をインストール先のホストに設定してください。 |
| 接続拒否または 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` のエントリのみが削除されます。