> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenClaw プラグイン
> W&B Weave で OpenClaw エージェントセッションをトラッキングし、可観測性の向上とデバッグに役立てます。
Weave OpenClaw プラグインは、OpenClaw ゲートウェイを介して実行されるすべてのエージェントセッションを自動的にトレースし、その構造化データを W\&B Weave に送信します。アプリケーションコードを変更しなくても、すべてのターン、モデル呼び出し、ツール実行がログされます。これらのトレースを使用して、セッションのデバッグ、ツール使用状況の監査、Runs 全体でのコストとレイテンシの監視を行えます。
このガイドは、ゲートウェイの背後で実行されるエージェントに対して Weave トレースを有効にしたい OpenClaw ゲートウェイ運用担当者向けです。プラグインのインストール、設定、生成されたトレースの確認方法、および一般的な問題のトラブルシューティングについて説明します。
このプラグインは、OpenClaw のセッションデータを Weave に送信します。このデータには、ユーザープロンプト、モデル応答、ツールの入力と出力、ツールの結果、会話履歴が含まれる場合があります。
このプラグインは、個人を特定できる情報 (PII) の除去や機密データのマスキングを実装していません。コンテンツの取得を抑止する必要がある場合は、プラグイン設定で `captureContent: false` を設定してください。セキュリティ要件またはコンプライアンス要件により、このデータを Weave に送信できない場合は、このプラグインをインストールしないでください。
## 前提条件
* [Node.js](https://nodejs.org/) v22.14 以降。
* プラグイン API を備えた [OpenClaw](https://openclaw.ai) `2026.4.25` 以降。
* W\&B アカウントと [APIキー](https://wandb.ai/authorize)。
* トレースの受信先となる Weave プロジェクト (`[YOUR-TEAM]/[YOUR-PROJECT]`)。
## プラグインをインストールする
以下の手順を実行して、プラグインをインストールし、OpenClaw ゲートウェイ に登録して、トレースが Weave project に届くことを確認します。
```bash lines theme={null}
openclaw plugins install weave-openclaw
```
完全な名前 `weave-openclaw` を使用してください (`weave` 単体はこのプラグインではなく W\&B SDK です) 。プラグインは OpenClaw ゲートウェイ が設定を通じて読み込みます。アプリケーションコードから `import` する必要はありません。
デフォルトの設定ファイルの場所は `~/.openclaw/openclaw.json` です (JSON5 形式のため、コメントと末尾のカンマを使用できます) 。まだファイルがない場合は、`openclaw onboard` を実行してひな形を生成します。
ご利用の project に合わせて `[YOUR-TEAM]` と `[YOUR-PROJECT]` を更新してください。
```json lines theme={null}
{
plugins: {
allow: ["weave"],
entries: {
weave: {
enabled: true,
config: { entity: "YOUR-TEAM", project: "YOUR-PROJECT" },
hooks: { allowConversationAccess: true },
},
},
},
}
```
OpenClaw がコンテンツを含む hooks (`llm_input`、`llm_output`、`agent_end`) を実行し、スパン に入力テキストと出力テキスト、tool の引数、および tool の結果が含まれるように、**`hooks.allowConversationAccess`** を **`true`** に設定します。
`diagnostics.enabled` はデフォルトで有効です。無効にする必要がある場合にのみ、明示的に設定してください。
OpenClaw ゲートウェイ を再起動し、その後、任意の OpenClaw チャット画面で `/weave status` を実行して、プラグインが有効になっていることを確認します。最初のエージェント run から数秒以内に、`https://wandb.ai/[YOUR-TEAM]/[YOUR-PROJECT]` にトレースが表示されます。
## Weave で OpenClaw のトレースを表示する
プラグインが有効になると、各エージェントセッションで Weave UI で確認できるトレースが生成されます。少なくとも 1 つのエージェントセッションを実行した後、Weave UI で project を開きます。
1. [https://wandb.ai](https://wandb.ai) にアクセスし、project を選択します。
2. サイドバーメニューで **Agents** を選択します。
3. **Conversations** タブを選択して、project に保存されているすべてのエージェント会話を表示します。
4. 会話を選択して、会話ツリー全体を確認します。
Agents ビューの詳細については、[View agent activity](/ja/weave/guides/tracking/view-agent-activity) を参照してください。
プラグインは、[OpenTelemetry (OTel) GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) に従って スパン を出力します。
| スパン | 出力タイミング | 主な属性 |
| ---------------------- | -------------- | --------------------------------------------------------------------------------- |
| `invoke_agent ` | 各エージェント run ごと | `gen_ai.agent.name`, `gen_ai.conversation.id`, 累積コスト、トークン使用量 |
| `chat ` | 各モデル呼び出しごと | `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. Weave ホスト用の `~/.netrc` エントリ (`wandb login` によって設定されます) 。
```json lines theme={null}
{
plugins: {
entries: {
weave: {
enabled: true,
config: {
entity: "YOUR-TEAM",
project: "YOUR-PROJECT",
// apiKey を省略した場合、env から WANDB_API_KEY を読み取ります。
// SecretRef は source: "env" または "file" をサポートします:
// { source: "env", provider: "default", id: "WANDB_API_KEY" }
// { source: "file", provider: "default", id: "/run/secrets/wandb" }
// プレーン文字列はサポートされますが、推奨しません。
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 を設定してください。プラグインは取得した
// 文字列をマスクしないため、必要に応じて上流で除去してください。
captureContent: true,
flushIntervalMs: 1000,
},
hooks: { allowConversationAccess: true },
},
},
},
}
```
`captureContent` のデフォルト値は `true` です。`captureContent` が `true` の場合、プラグインは、入力メッセージと出力メッセージ、tool の引数、tool の結果も、`gen_ai.input.messages` および `gen_ai.output.messages` の payload 形式に従って出力します。プラグインは、サブエージェント、compaction イベント、loop detection、retry attempts、context sizing を、追加の属性および スパン イベントとして付与します。
コンプライアンス要件または保持ポリシーのために取得を無効にするには、`captureContent` を `false` に設定します。
### W\&B Dedicated Cloud またはセルフホスト環境のインスタンス
このプラグインは、エンドポイントと認証を [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`。Dedicated Cloud またはセルフホスト環境にインストールする場合は、これを設定します。 |
| `WF_TRACE_SERVER_URL` | trace-server の完全な URL を上書きします。セルフマネージド環境またはプロキシ経由の構成で使用します。 |
## トラブルシューティング
トレースが Weave に届かない場合やコンテンツフィールドが空の場合は、最も一般的な原因を診断するために以下のセクションを使用してください。
ゲートウェイ のログ は、`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 project の URL スラッグと一致していることを確認してください。`/weave status` には `project=[YOUR-TEAM]/[YOUR-PROJECT]` と表示されるはずです。
4. 認証の取得元を確認してください。`/weave status` には `auth=...` と表示されるはずです。`WANDB_API_KEY env` と表示されているのに、キーを別の環境変数に設定している場合は、プラグインが誤ったキーを読み取っています。
### スパン は届くものの、input/output テキストが空です
ゲートウェイ のログ で次を確認してください。
```text theme={null}
[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 では、コンテンツを含む hook は operator が明示的に有効化した場合にのみ利用できます。設定で `plugins.entries.weave.hooks.allowConversationAccess: true` を設定し、ゲートウェイを再起動してください。スパン構造とコストおよび使用量データは hook ではなく診断イベント経由で送信されるため、`allowConversationAccess` が `false` の場合でも引き続き動作します。
### Weave へのトレース送信エラー
プラグインが有効でスパンを生成しているのに Weave に表示されない場合は、エクスポート エラーがないかゲートウェイ のログを確認し、以下の表と照らし合わせてください。
| 症状 | 最も可能性の高い原因 | 対処方法 |
| ------------------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `trace.wandb.ai` からの `401` または `403` | 無効な APIキー、またはスコープが制限された APIキー | キーが現在も有効であり、チームが entity と project を所有していることを確認してください。`wandb login` を実行すると `~/.netrc` が更新されます。 |
| agents endpoint からの `404` | ベース URL または trace-server URL が誤っている | Dedicated インストールでは、`WANDB_BASE_URL` をインストール先ホストに設定してください。セルフマネージド環境またはプロキシ環境では、`WF_TRACE_SERVER_URL` を trace-server URL に設定してください。 |
| 接続拒否または DNS エラー | DNS、プロキシ、またはファイアウォール | ゲートウェイ ホストから `trace.wandb.ai` (クラウド) またはインストール先ホスト (Dedicated) の `443` に到達できることを確認してください。 |