> ## 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.
# OpenClaw プラグイン
> OpenClaw のエージェントセッションを W&B Weave でトラッキングし、可観測性の確保とデバッグに役立てます。
export const AgentLensBanner = ({href}) =>
This workflow is also available in CoreWeave Agent Lens. 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.{' '}
{href ? 'See how to do this in Agent Lens' : 'Learn about Agent Lens'}.
;
Weave OpenClaw プラグインは、OpenClaw ゲートウェイ経由で実行されるすべてのエージェントセッションを自動的にトレースし、構造化データを W\&B Weave に送信します。アプリケーションコードを変更しなくても、すべてのターン、モデルの Call、ツール実行がログされます。これらのトレースを使用すると、セッションのデバッグ、ツールの使用状況の監査、複数の run にわたるコストとレイテンシーの監視を行えます。
このガイドは、ゲートウェイの背後で実行されるエージェントに対して Weave のトレースを有効にしたい OpenClaw ゲートウェイのオペレーターを対象としています。プラグインのインストールと設定、生成されたトレースの表示、よくある問題のトラブルシューティングの方法について説明します。
このプラグインは OpenClaw のセッションデータを Weave に送信します。このデータには、ユーザー プロンプト、モデルの応答、ツールの入力と出力、ツール結果、会話履歴が含まれる場合があります。
このプラグインには、個人を特定できる情報 (PII) の除去や機密データのマスキングの機能はありません。コンテンツの取得を無効にする必要がある場合は、プラグインの設定で `captureContent: false` を指定してください。セキュリティ要件やコンプライアンス要件によりこのデータを Weave に送信できない場合は、このプラグインをインストールしないでください。
前提条件
* [Node.js](https://nodejs.org/) v22.14 以降。
* プラグイン API に対応した [OpenClaw](https://openclaw.ai) `2026.4.25` 以降。
* CoreWeave Forge アカウントと [APIキー](https://forge.coreweave.com/settings#apikeys)。
* トレースの送信先となる Weave プロジェクト (`[YOUR-TEAM]/[YOUR-PROJECT]`) 。
プラグインをインストールする
以下の手順に従ってプラグインをインストールし、OpenClaw ゲートウェイに登録したうえで、トレースが Weave プロジェクトに届いていることを確認します。
```bash lines theme={"system"}
openclaw plugins install weave-openclaw
```
パッケージ名は省略せずに `weave-openclaw` と指定してください (`weave` だけでは W\&B SDK を指し、このプラグインにはなりません) 。プラグインは OpenClaw ゲートウェイが設定に基づいて読み込むため、アプリケーションコードからインポートする必要はありません。
デフォルトの設定ファイルの場所は `~/.openclaw/openclaw.json` です (JSON5 形式のため、コメントや末尾のカンマを記述できます) 。設定ファイルがまだない場合は、`openclaw onboard` を実行して雛形を作成してください。
`[YOUR-TEAM]` と `[YOUR-PROJECT]` は、お使いの project に合わせて置き換えてください。
```json lines theme={"system"}
{
plugins: {
allow: ["weave"],
entries: {
weave: {
enabled: true,
config: { entity: "YOUR-TEAM", project: "YOUR-PROJECT" },
hooks: { allowConversationAccess: true },
},
},
},
}
```
**`hooks.allowConversationAccess`** を **`true`** に設定してください。これにより、OpenClaw がコンテンツを扱うフック (`llm_input`、`llm_output`、`agent_end`) を実行するようになり、スパンに入力・出力テキスト、ツールの引数、ツール結果が含まれます。
`diagnostics.enabled` はデフォルトで有効になっています。明示的に設定する必要があるのは、無効にしたい場合のみです。
OpenClaw ゲートウェイを再起動したら、任意の OpenClaw チャット画面で `/weave status` を実行し、プラグインが有効になっていることを確認します。エージェントを初めて実行すると、数秒以内に `https://forge.coreweave.com/wandb/[YOUR-TEAM]/[YOUR-PROJECT]/weave/` にトレースが表示されます。
Weave で OpenClaw のトレースを表示する
プラグインが有効になると、エージェントセッションごとにトレースが生成され、Weights & Biases の UI で確認できます。エージェントセッションを 1 回以上実行したら、Weights & Biases の UI で project を開きます。
1. [Forge](https://forge.coreweave.com/wandb) にアクセスし、project を選択します。
2. サイドバーメニューで **Agents** を選択します。
3. **Conversations** タブを選択すると、project に保存されているすべてのエージェントの会話が表示されます。
4. 会話を選択すると、会話ツリー全体を確認できます。
Agents ビューの詳細については、[エージェントのアクティビティを表示する](/ja/products/wandb/weave/guides/tracking/view-agent-activity)を参照してください。
プラグインは、[OpenTelemetry (OTel) GenAI セマンティック規約](https://opentelemetry.io/docs/specs/semconv/gen-ai/)に従ってスパンを出力します。
| スパン | 出力タイミング | 主な属性 |
| - | - | - |
| `invoke_agent ` | エージェントの run ごと | `gen_ai.agent.name`、`gen_ai.conversation.id`、累積コスト、トークン使用量 |
| `chat ` | モデルの Call ごと | `gen_ai.request.model`、`gen_ai.usage.input_tokens`、`gen_ai.usage.output_tokens` |
| `execute_tool ` | ツール実行ごと | `gen_ai.tool.name`、`gen_ai.tool.call.id` |
設定リファレンス
このセクションでは、`openclaw.json` 内の `weave` プラグインエントリで使用できるすべての設定項目を説明します。
`apiKey` フィールドでは 4 つの認証ソースがサポートされており、次の順序で解決されます。
1. `source: "env"` または `source: "file"` を指定した `SecretRef` オブジェクト (次の例の 10 行目を参照)。
2. `apiKey` string の直接指定 (サポートされていますが、推奨されません)。
3. `WANDB_API_KEY` 環境変数。
4. `wandb login` によって作成される、Weave ホスト用の `~/.netrc` エントリ。
```json lines theme={"system"}
{
plugins: {
entries: {
weave: {
enabled: true,
config: {
entity: "YOUR-TEAM",
project: "YOUR-PROJECT",
// apiKey を省略すると、環境変数から WANDB_API_KEY を読み取ります。
// SecretRef では source: "env" または "file" を指定できます:
// { source: "env", provider: "default", id: "WANDB_API_KEY" }
// { source: "file", provider: "default", id: "/run/secrets/wandb" }
// プレーンな string も使用できますが、推奨されません。
apiKey: { source: "env", provider: "default", id: "WANDB_API_KEY" },
serviceName: "openclaw-agent",
// オプション。Agents タブでのグループ化が改善されます。
agentName: "my-agent",
agentVersion: "v1.0",
agentDescription: "What my agent does.",
// デフォルトは ON です。完全に無効にするには false に設定します（コンプライアンスや
// 保持ポリシーへの対応など）。プラグインは取得した strings をマスクしないため、
// 必要に応じて上流で除去してください。
captureContent: true,
flushIntervalMs: 1000,
},
hooks: { allowConversationAccess: true },
},
},
},
}
```
`captureContent` はデフォルトで `true` です。`captureContent` が `true` の場合、プラグインは入力メッセージと出力メッセージ、ツール引数、ツール結果も、`gen_ai.input.messages` および `gen_ai.output.messages` のペイロード形式に従って出力します。さらに、サブエージェント、コンパクションイベント、ループ検出、再試行、コンテキストサイズを、追加の属性およびスパンイベントとして記録します。
コンプライアンスやデータ保持ポリシーの要件に応じて取得を無効にするには、`captureContent` を `false` に設定します。
W\&B 専用クラウドまたはセルフホストのインスタンス
このプラグインは、エンドポイントと認証の処理を [Weave Node SDK](https://github.com/wandb/weave/tree/master/sdks/node) に委譲します。Weave の Python SDK および Node SDK と同じ規則に従って、次の環境変数を読み取ります。
| 変数 | 説明 |
| - | - |
| `WANDB_BASE_URL` | W\&B API のベース URL。デフォルト: `https://api.wandb.ai`。専用クラウドまたはセルフホスト環境の場合に設定します。 |
| `WF_TRACE_SERVER_URL` | trace-server の URL 全体を上書きします。セルフマネージド構成やプロキシ経由の構成で使用します。 |
トラブルシューティング
トレースが Weave に届かない場合や content フィールドが空の場合は、以下のセクションを使用して、よくある原因を診断してください。
ゲートウェイ のログとは、`openclaw` を実行しているプロセスのターミナル出力です。デーモン化している場合は、プロセスマネージャーのログストリームを指します。
プラグインは読み込まれたがスパンが表示されない
1. `/weave status` を実行します。lifecycle が `disabled`、`config-error`、または `not-started` の場合、プラグインは有効化されていません。ゲートウェイのログに `weave: config.entity is required`、`weave: configuration error`、または `[weave] incompatible plugin SDK` が出力されていないか確認してください。
2. ゲートウェイの設定で `diagnostics.enabled: false` を設定していないか確認します。このフィールドは `true` にする必要があります。
3. entity と project が、確認対象の Weave プロジェクトの URL スラッグと一致していることを確認します。`/weave status` を実行すると、`project=[YOUR-TEAM]/[YOUR-PROJECT]` と出力されます。
4. 認証ソースを確認します。`/weave status` を実行すると、`auth=...` と出力されます。`WANDB_API_KEY env` と表示されているのに、キーを別の環境変数に設定している場合は、プラグインが誤ったキーを読み取っています。
スパンは記録されるが入力/出力テキストが空になる
ゲートウェイ のログで次のメッセージを確認してください。
```text theme={"system"}
[plugins] typed hook "llm_input" blocked because non-bundled plugins must set
plugins.entries.weave.hooks.allowConversationAccess=true
[plugins] typed hook "llm_output" blocked ...
[plugins] typed hook "agent_end" blocked ...
```
OpenClaw では、会話の内容を扱うフックを使用するには、オペレーターによるオプトインが必要です。設定で `plugins.entries.weave.hooks.allowConversationAccess: true` を指定し、ゲートウェイを再起動してください。スパンの構造やコスト・使用量のデータは、フックではなく診断イベントを通じて取得されます。そのため、`allowConversationAccess` が `false` の場合でも、これらは引き続き機能します。
Weave へのトレース送信エラー
プラグインが実行中でスパンを生成しているにもかかわらず Weave に表示されない場合は、ゲートウェイ のログでエクスポートエラーを確認し、次の表と照らし合わせてください。
| 症状 | 考えられる主な原因 | 対処法 |
| - | - | - |
| `trace.wandb.ai` から `401` または `403` が返される | APIキーが無効、またはスコープが制限されている | キーが有効期限内であること、およびチームがその entity と project を所有していることを確認してください。`wandb login` を実行すると `~/.netrc` が更新されます。 |
| エージェントのエンドポイントから `404` が返される | ベース URL または trace-server の URL が誤っている | 専用クラウドのインストールでは、`WANDB_BASE_URL` をインストール先のホストに設定してください。セルフマネージドまたはプロキシ経由の場合は、`WF_TRACE_SERVER_URL` を trace-server の URL に設定してください。 |
| 接続拒否または DNS エラー | DNS、プロキシ、またはファイアウォール | ゲートウェイのホストから、ポート `443` で `trace.wandb.ai`(クラウド)またはインストール先のホスト(専用クラウド)に接続できることを確認してください。 |