> ## 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 のエージェントセッションを Agent Lens でトラッキングし、可観測性の向上とデバッグに役立てます。
OpenClaw 用の Weave プラグインは、OpenClaw ゲートウェイ経由で実行されるすべてのエージェントセッションを自動的にトレースし、構造化データを Agent Lens に送信します。アプリケーションコードを変更しなくても、すべてのターン、モデルの Call、ツール実行がログされます。これらのトレースを使用すると、セッションのデバッグ、ツールの使用状況の監査、複数の run にわたるコストとレイテンシーの監視を行えます。
このガイドは、ゲートウェイの背後で実行されるエージェントに対して Agent Lens のトレースを有効にしたい OpenClaw ゲートウェイのオペレーターを対象としています。プラグインのインストールと設定、生成されたトレースの表示、よくある問題のトラブルシューティングの方法について説明します。
これは Weights & Biases Weave のプラグインです。CoreWeave Forge 版はまだ提供されていません。Agent Lens と Weave は同じトレースデータを共有しているため、プラグインが送信したトレースは Agent Lens に表示されます。
このプラグインは、OpenClaw のセッションデータを Agent Lens に送信します。このデータには、ユーザープロンプト、モデルの応答、ツールの入力と出力、ツール結果、会話履歴が含まれる場合があります。
このプラグインには、個人を特定できる情報 (PII) の除去や機密データのマスキングの機能はありません。コンテンツの取得を抑制する必要がある場合は、プラグインの設定で `captureContent: false` を設定してください。セキュリティ要件やコンプライアンス要件により、このデータを Agent Lens に送信できない場合は、このプラグインをインストールしないでください。
前提条件
* [Node.js](https://nodejs.org/) v22.14 以降。
* プラグイン API に対応した [OpenClaw](https://openclaw.ai) `2026.4.25` 以降。
* CoreWeave Forge のアカウントと [APIキー](https://forge.coreweave.com/settings#apikeys)。
* トレースの送信先となる Agent Lens の project (`[YOUR-TEAM]/[YOUR-PROJECT]`) 。
プラグインをインストールする
以下の手順で、プラグインをインストールして OpenClaw ゲートウェイに登録し、トレースが Agent Lens の project に届くことを確認します。
```bash lines theme={"system"}
openclaw plugins install weave-openclaw
```
パッケージ名は `weave-openclaw` と正確に指定してください (`weave` だけでは Weave 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/agent-lens/[YOUR-TEAM]/[YOUR-PROJECT]` にトレースが表示されます。
Agent Lens で OpenClaw のトレースを表示する
プラグインが有効になると、エージェントセッションごとにトレースが生成され、Agent Lens UI で確認できるようになります。エージェントセッションを 1 回以上実行したら、Agent Lens UI で project を開きます。
1. [CoreWeave Forge](https://forge.coreweave.com) にアクセスし、プロダクトメニューから Agent Lens を選択して、サイドメニュー上部の project セレクターで対象の project を選択します。
2. サイドメニューで **Conversations** を選択します。
3. **Conversations** タブを選択すると、project に保存されたすべてのエージェントの会話が表示されます。
4. 会話を選択すると、会話ツリー全体を確認できます。
Conversations タブの詳細については、[エージェントのアクティビティを表示する](/ja/products/agent-lens/conversations/view-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` によって追加される、Agent Lens ホスト用の `~/.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" }
// プレーンな文字列も使用できますが、推奨されません。
apiKey: { source: "env", provider: "default", id: "WANDB_API_KEY" },
serviceName: "openclaw-agent",
// オプション。Conversations タブでのグループ化が改善されます。
agentName: "my-agent",
agentVersion: "v1.0",
agentDescription: "What my agent does.",
// デフォルトで有効です。完全に無効にするには false に設定します（コンプライアンスや
// データ保持ポリシーへの対応など）。プラグインは取得した文字列をマスクしないため、
// 必要に応じて上流でマスクしてください。
captureContent: true,
flushIntervalMs: 1000,
},
hooks: { allowConversationAccess: true },
},
},
},
}
```
`captureContent` のデフォルトは `true` です。`captureContent` が `true` の場合、プラグインは `gen_ai.input.messages` および `gen_ai.output.messages` のペイロード形式に従って、入力メッセージと出力メッセージ、ツールの引数、ツール結果も出力します。また、サブエージェント、コンパクションイベント、ループ検出、再試行、コンテキストのサイズも、追加の属性およびスパンイベントとして記録します。
コンプライアンスやデータ保持ポリシーに対応するためにコンテンツの取得を無効にするには、`captureContent` を `false` に設定します。
トラブルシューティング
トレースが Agent Lens に届かない場合や、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 が、確認対象の Agent Lens project の 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` の場合でも引き続き記録されます。
Agent Lens へのトレース送信エラー
プラグインが有効でスパンを生成しているにもかかわらず Agent Lens に表示されない場合は、ゲートウェイ のログでエクスポートエラーを確認し、次の表と照らし合わせてください。
| 症状 | 考えられる主な原因 | 対処法 |
| - | - | - |
| `trace.wandb.ai` から `401` または `403` が返される | APIキーが無効であるか、スコープが制限されている | キーが最新であること、およびチームが entity と project を所有していることを確認します。`wandb login` を実行すると `~/.netrc` が更新されます。 |
| 接続が拒否される、または DNS エラーが発生する | DNS、プロキシ、またはファイアウォール | ゲートウェイのホストがポート `443` で `trace.wandb.ai` に接続できることを確認します。 |