ClawRouter

ClawRouter は、複数の上流モデルプロバイダーに対して、ポリシーでスコープされた単一のキーを OpenClaw に提供します。バンドル済みの clawrouter Plugin は、そのキーに許可されたモデルのみを検出し、各モデルを宣言されたプロトコル経由でルーティングして、キーの予算と集計使用量を OpenClaw の使用量画面に報告します。

上流の認証情報とプロバイダー固有の転送処理は ClawRouter 内に保持されるため、OpenClaw ホスト上で上流プロバイダーごとの Plugin をインストールしたり認証したりする必要はありません。この Plugin は OpenClaw にバンドルされています（enabledByDefault: true）。必要なのは、発行済みの ClawRouter 認証情報だけです。

はじめに

export CLAWROUTER_API_KEY="..."openclaw onboard --auth-choice clawrouter-api-keyopenclaw plugins enable clawrouter

openclaw models list --all --provider clawrouter

openclaw models set clawrouter/<provider>/<model>

管理された非対話型デプロイ

プロキシキーはワークロードのシークレット注入に保持し、openclaw.json には SecretRef のみを保存します。標準の管理対象フィールドは次のとおりです。

たとえば、デプロイコントローラーで次の JSON5 パッチを管理できます。

{  plugins: {    entries: { clawrouter: { enabled: true } },  },  models: {    providers: {      clawrouter: {        baseUrl: "https://clawrouter.internal.example",        apiKey: {          source: "env",          provider: "default",          id: "CLAWROUTER_API_KEY",        },        headers: {          "X-ClawRouter-Project-Id": "fakeco",        },      },    },  },  agents: {    defaults: {      model: { primary: "clawrouter/openai/gpt-5.5" },    },  },}

デプロイで plugins.allow を設定する場合は、既存のエントリを保持したまま clawrouter を追加します。対話型ウィザードを使用せずに検証して適用します。

openclaw config patch --file ./clawrouter.patch.json5 --dry-run --jsonopenclaw config patch --file ./clawrouter.patch.json5

ドライランでは SecretRef を解決しますが、その値は一切出力しません。認証情報をローテーションするには、CLAWROUTER_API_KEY を供給する外部 Secret を更新し、Gateway ワークロードを再起動して新しいプロセス環境を読み込みます。設定ファイルとモデル参照は変更されません。

ソースからビルドしたスタンドアロン Docker Gateway では、ClawRouter はすでにルートランタイムに含まれています。OPENCLAW_EXTENSIONS=clickclack、slack、msteams など、個別のパッケージ化が必要なチャンネル Plugin のみを選択してください。選択した Plugin を含むソースビルドイメージを参照してください。 アーカイブ／アプライアンス形式のデプロイでは、OCI イメージを利用するのではなく、同じ取り込み済みソースを独自のアーティファクトパイプラインでパッケージ化する必要があります。

準備完了状態とライブ検証

次のチェックはそれぞれ異なる境界を検証します。相互に代用しないでください。

# ClawRouter プロセスのヘルスのみ。認証情報や上流モデルは使用されません。curl -fsS https://clawrouter.internal.example/v1/health # OpenClaw Gateway の起動準備完了状態のみ。モデル呼び出しは行われません。curl -fsS http://127.0.0.1:18789/readyz # 認証情報でスコープされたカタログの検出。openclaw models list --all --provider clawrouter --json # 設定済み ClawRouter プロバイダーを経由する最小限の実推論プローブ。openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # 許可された正確なモデル参照を使用するワークロードカナリア。openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "正確に次のように応答してください: CLAWROUTER_CANARY_OK" \  --json

例のモデルをそのままコピーせず、スコープされたカタログから返されたモデルを使用してください。/readyz の応答が成功した場合、Gateway がリクエストを処理できることを意味しますが、ClawRouter、その認証情報、または上流プロバイダーの準備が完了していることを示すものではありません。推論の検証になるのは、モデルプローブとエージェントカナリアです。

ライブ診断では、カナリアを実行し、Gateway の標準ログを確認します。既存のメタデータのみのモデル転送診断では、次の形式の行が出力されます。

[model-fetch] 開始 provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] 応答 provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200

この Plugin は、該当する識別子が利用可能な場合、長さを制限した X-ClawRouter-Client、X-ClawRouter-Agent-Id、X-ClawRouter-Session-Id ヘッダーを送信します。また、モデル呼び出しの診断用 callId（<run-id>:model:<n>）を X-Request-ID にマッピングするため、OpenClaw のモデル呼び出しイベントを ClawRouter のメタデータのみの監査証跡と関連付けられます。128 文字のリクエスト ID 上限内の値は同一です。これを超える値では :model:<n> サフィックスと決定論的ハッシュが保持されるため、異なる呼び出しを上限内に収めたまま関連付けられます。X-ClawRouter-Project-Id などの静的デプロイメタデータは、プロバイダーの headers マップで設定できます。 エージェントとセッションの属性ヘッダーには、それぞれ個別の 256 文字制限が引き続き適用されます。ClawRouter の ASCII 識別子セットに含まれない文字を持つ自動リクエスト ID にも、同じ決定論的な制限形式が使用されます。 X-Request-ID の大文字小文字違いを含む、明示的に設定されたヘッダーは、自動値より優先されます。転送診断にはルーティングと応答のメタデータが記録されますが、認証情報、リクエスト ID、プロンプト、生成結果は記録されません。ClawRouter 独自の監査イベントでは、選択された上流プロバイダーとコンテンツ保持状態が提供されます。

モデル検出

GET /v1/catalog は { providers: [...] } を返します。各プロバイダーエントリには、独自の models[]（上流 ID、機能、料金を含む）と、サポートされるリクエストルートが一覧表示されます。OpenClaw は ClawRouter モデルの固定リストを別途同梱しません。カタログモデルが OpenClaw モデルとして提示される条件は次のとおりです。

• 認証情報のポリシーでそのプロバイダーが許可されている。
• カタログモデルが、サポート対象の LLM 機能（llm.responses、llm.chat、llm.messages、または対応するストリーミングルートを持つ llm.stream）を提示している。
• プロバイダーが、以下の転送方式のいずれかに対応するルートを公開している。

サポートされている ClawRouter プロバイダーにモデルを追加しても、OpenClaw のリリースは不要です。次回のカタログ更新（認証情報のスコープごとに 60 秒間キャッシュ）で検出されます。新しいワイヤープロトコルを必要とするモデルには、先に Plugin の対応が必要です。

プロトコルとプロバイダー Plugin

ClawRouter が上流の認証情報を管理し、そのカタログが使用する転送方式を OpenClaw に通知するため、上流企業ごとの認証 Plugin をすべてインストールする必要はありません。

この Plugin は、これらのファミリーに対応する再生ポリシーとツールスキーマポリシーも適用します（OpenAI／DeepSeek／Gemini／Perplexity のツールスキーマ互換性、およびネイティブ Anthropic と Google Gemini の再生ポリシー）。Perplexity モデルには厳格なスキーマ書き換えが適用されます。Perplexity はこれらを含まないツールスキーマを拒否するため、patternProperties と additionalProperties が削除され、すべてのオブジェクトスキーマで properties が宣言されます。サポートされていないリクエスト形式しか公開しないカタログプロバイダーは、意図的に OpenClaw のテキストモデルとして提示されません。互換性のないペイロードを送信するのではなく、それらのプロバイダーを ClawRouter 内でサポート対象の契約のいずれかに正規化してください。

クォータと使用量

ClawRouter の /v1/usage 応答は、通常の OpenClaw プロバイダー使用量画面に反映されます。これには、リクエスト数、トークン数、支出額の合計に加え、キーに上限がある場合は月間予算期間が含まれます。従量制限のないキーでも、割合期間なしで集計使用量が表示されます。

クォータ検索では、モデル検出と同じスコープ付きキーを使用します。クォータ検索に失敗しても、モデルの実行は妨げられません。

ライブスナップショットは次のコマンドで確認します。

openclaw status --usageopenclaw models status

同じプロバイダースナップショットは、チャット内の /status と OpenClaw の使用量 UI でも利用できます。予算はポリシー全体に適用されるため、同じ ClawRouter ポリシーを使用する別のクライアントからのリクエストによって、残りの割合が変化する可能性があります。

トラブルシューティング

セキュリティ動作

• カタログ検出の範囲は、設定されたプロキシキーに限定され、認証情報のスコープ（エージェントディレクトリ、ワークスペースディレクトリ、認証プロファイル ID、ベース URL）ごとにキャッシュされます。
• プロキシキーはリクエストのディスパッチ時にのみ付加され、モデルのメタデータには保存されません。
• 自動アトリビューション値とリクエスト相関値は、ディスパッチ前に前後の空白が除去され、制御文字が含まれている場合は拒否されます。アトリビューション値は 256 文字、リクエスト ID は 128 文字に制限されます。
• モデル転送の診断情報にはメタデータのみが含まれ、プロキシキーやモデルのコンテンツは一切含まれません。
• ネイティブの Anthropic および Gemini モデル ID は、ディスパッチ時にのみアップストリームの ID に書き換えられます。
• サポートされていない、または許可されていないカタログ行はフェイルクローズとなり、選択できません。

関連情報