provider plugin の構築
このガイドでは、OpenClaw にモデル provider (LLM)を追加する provider plugin の構築手順を説明します。最終的には、モデル catalog、 API キー認証、および動的モデル解決を備えた provider が完成します。まだ OpenClaw plugin を一度も作成したことがない場合は、まず
基本的なパッケージ構造と manifest 設定について
はじめに を読んでください。
ウォークスルー
パッケージと manifest
providerAuthEnvVars を宣言することで、OpenClaw が
plugin ランタイムを読み込まずに認証情報を検出できるようにします。ある provider バリアントで別の provider id の auth を再利用させたい場合は、providerAuthAliases
を追加してください。modelSupport
は任意で、ランタイムフックが存在する前でも、acme-large のような短縮モデル id から OpenClaw が provider plugin を自動読み込みできるようにします。provider を
ClawHub で公開する場合、これらの openclaw.compat および openclaw.build フィールドは
package.json 内で必須です。provider を登録する
最小限の provider に必要なのは、これで動作する provider になります。ユーザーは
auth フローで、オンボーディング中に
id、label、auth、および catalog です:index.ts
openclaw onboard --acme-ai-api-key <key> を実行して、
モデルとして acme-ai/acme-large を選択できるようになります。アップストリーム provider が OpenClaw と異なる制御トークンを使う場合は、
ストリーム経路を置き換えるのではなく、小さな双方向テキスト変換を追加してください:input は、転送前に最終システムプロンプトとテキストメッセージ内容を書き換えます。
output は、assistant テキスト差分と最終テキストを、OpenClaw が自身の
制御マーカーやチャネル配信を解析する前に書き換えます。API キー認証と単一の catalog ベースランタイムを持つ
1 つのテキスト provider だけを登録するバンドル provider では、より狭い
defineSingleProviderPluginEntry(...) ヘルパーを優先してください:models.providers.*、aliases、
およびエージェントのデフォルトモデルも更新する必要がある場合は、
openclaw/plugin-sdk/provider-onboard の preset ヘルパーを使用してください。最も狭い
ヘルパーは createDefaultModelPresetAppliers(...)、
createDefaultModelsPresetAppliers(...)、および
createModelCatalogPresetAppliers(...) です。provider ネイティブエンドポイントが、通常の
openai-completions 転送でストリーミング usage ブロックをサポートしている場合は、provider-id チェックをハードコードするのではなく
openclaw/plugin-sdk/provider-catalog-shared の共通 catalog ヘルパーを優先してください。
supportsNativeStreamingUsageCompat(...) と
applyProviderNativeStreamingUsageCompat(...) は、エンドポイント capability map からサポートを検出するため、custom provider id を使う plugin でも、ネイティブ Moonshot/DashScope 形式エンドポイントをオプトインさせられます。動的モデル解決を追加する
provider が任意のモデル ID を受け付ける場合(プロキシやルーターのようなケース)は、
解決にネットワーク呼び出しが必要な場合は、非同期ウォームアップ用に
resolveDynamicModel を追加します:prepareDynamicModel を使ってください — 完了後に resolveDynamicModel が再度実行されます。ランタイムフックを追加する(必要に応じて)
ほとんどの provider では 現在利用可能な replay ファミリー:
実際のバンドル例:
実際のバンドル例:
catalog + resolveDynamicModel だけで十分です。provider に必要になったら、
フックを段階的に追加してください。共通ヘルパービルダーは、現在最も一般的な replay/tool-compat
ファミリーをカバーしているため、plugin では通常、各フックを 1 つずつ手作業で接続する必要はありません:| ファミリー | 接続される内容 |
|---|---|
openai-compatible | OpenAI 互換転送向けの共有 OpenAI スタイル replay ポリシー。tool-call-id のサニタイズ、assistant-first 順序の修正、およびその転送で必要な場合の汎用 Gemini ターン検証を含みます |
anthropic-by-model | modelId によって選ばれる Claude 対応 replay ポリシー。Anthropic-message 転送では、解決されたモデルが実際に Claude id の場合にのみ Claude 固有の thinking-block クリーンアップが適用されます |
google-gemini | ネイティブ Gemini replay ポリシーに加え、bootstrap replay サニタイズとタグ付き reasoning-output モード |
passthrough-gemini | OpenAI 互換プロキシ転送上で動作する Gemini モデル向けの Gemini thought-signature サニタイズ。ネイティブ Gemini replay 検証や bootstrap 書き換えは有効にしません |
hybrid-anthropic-openai | 1 つの plugin 内で Anthropic-message と OpenAI 互換のモデルサーフェスを混在させる provider 向けのハイブリッドポリシー。任意の Claude 専用 thinking-block 除去は Anthropic 側に限定されます |
googleとgoogle-gemini-cli:google-geminiopenrouter、kilocode、opencode、およびopencode-go:passthrough-geminiamazon-bedrockとanthropic-vertex:anthropic-by-modelminimax:hybrid-anthropic-openaimoonshot、ollama、xai、およびzai:openai-compatible
| ファミリー | 接続される内容 |
|---|---|
google-thinking | 共有ストリーム経路上での Gemini thinking ペイロード正規化 |
kilocode-thinking | 共有プロキシストリーム経路上での Kilo reasoning ラッパー。kilo/auto と未対応のプロキシ reasoning id では注入された thinking をスキップ |
moonshot-thinking | config + /think レベルからの Moonshot バイナリ native-thinking ペイロードマッピング |
minimax-fast-mode | 共有ストリーム経路上での MiniMax fast-mode モデル書き換え |
openai-responses-defaults | 共有のネイティブ OpenAI/Codex Responses ラッパー: attribution headers、/fast/serviceTier、text verbosity、ネイティブ Codex web search、reasoning-compat ペイロード整形、および Responses コンテキスト管理 |
openrouter-thinking | プロキシ経路向けの OpenRouter reasoning ラッパー。未対応モデル/auto スキップは中央処理されます |
tool-stream-default-on | Z.AI のような provider 向けのデフォルト有効 tool_stream ラッパー。明示的に無効化されない限りツールストリーミングを使用 |
googleとgoogle-gemini-cli:google-thinkingkilocode:kilocode-thinkingmoonshot:moonshot-thinkingminimaxとminimax-portal:minimax-fast-modeopenaiとopenai-codex:openai-responses-defaultsopenrouter:openrouter-thinkingzai:tool-stream-default-on
openclaw/plugin-sdk/provider-model-shared は、replay-family
enum と、それらのファミリーの土台となる共有ヘルパーもエクスポートします。一般的な公開エクスポートには次が含まれます:ProviderReplayFamilybuildProviderReplayFamilyHooks(...)buildOpenAICompatibleReplayPolicy(...)、buildAnthropicReplayPolicyForModel(...)、buildGoogleGeminiReplayPolicy(...)、およびbuildHybridAnthropicOrOpenAIReplayPolicy(...)のような共有 replay ビルダーsanitizeGoogleGeminiReplayHistory(...)やresolveTaggedReasoningOutputMode()のような Gemini replay ヘルパーresolveProviderEndpoint(...)、normalizeProviderId(...)、normalizeGooglePreviewModelId(...)、およびnormalizeNativeXaiModelId(...)のような endpoint/model ヘルパー
openclaw/plugin-sdk/provider-stream は、family builder と、
それらのファミリーが再利用する公開ラッパーヘルパーの両方を公開します。一般的な公開エクスポート
には次が含まれます:ProviderStreamFamilybuildProviderStreamFamilyHooks(...)composeProviderStreamWrappers(...)createOpenAIAttributionHeadersWrapper(...)、createOpenAIFastModeWrapper(...)、createOpenAIServiceTierWrapper(...)、createOpenAIResponsesContextManagementWrapper(...)、およびcreateCodexNativeWebSearchWrapper(...)のような共有 OpenAI/Codex ラッパーcreateOpenRouterWrapper(...)、createToolStreamWrapper(...)、およびcreateMinimaxFastModeWrapper(...)のような共有 proxy/provider ラッパー
@openclaw/anthropic-provider は
wrapAnthropicProviderStream、resolveAnthropicBetas、
resolveAnthropicFastMode、resolveAnthropicServiceTier、および
より低レベルの Anthropic ラッパービルダーを公開 api.ts /
contract-api.ts シームからエクスポートします。これらのヘルパーが Anthropic 固有のままなのは、
Claude OAuth beta 処理と context1m ゲーティングもエンコードしているためです。他のバンドル provider も、動作がファミリー間でうまく共有できない場合は、
転送固有ラッパーをローカルに保持します。現在の例: バンドルされた
xAI plugin は、ネイティブ xAI Responses 整形を自身の
wrapStreamFn 内に保持しています。これには /fast エイリアス書き換え、デフォルトの tool_stream、
未対応 strict-tool クリーンアップ、および xAI 固有の reasoning-payload
除去が含まれます。openclaw/plugin-sdk/provider-tools は現在、1つの共有
tool-schema ファミリーと共有 schema/compat ヘルパーを公開しています:ProviderToolCompatFamilyは、現在の共有ファミリー一覧を文書化します。buildProviderToolCompatFamilyHooks("gemini")は、Gemini-safe なツールスキーマが必要な provider 向けに Gemini スキーマ クリーンアップ + diagnostics を接続します。normalizeGeminiToolSchemas(...)とinspectGeminiToolSchemas(...)は、その土台となる公開 Gemini スキーマヘルパーです。resolveXaiModelCompatPatch()は、バンドルされた xAI compat patch を返します:toolSchemaProfile: "xai"、未対応スキーマキーワード、ネイティブweb_searchサポート、および HTML entity のツール呼び出し引数デコードです。applyXaiModelCompat(model)は、同じ xAI compat patch を 解決済みモデルに適用してから runner に渡します。
normalizeResolvedModel と
contributeResolvedModelCompat を使い、その compat メタデータを
core に xAI ルールをハードコードするのではなく provider 側で管理しています。同じ package-root パターンは、他のバンドル provider でも使われています:@openclaw/openai-provider:api.tsは provider builder、 default-model ヘルパー、および realtime provider builder をエクスポート@openclaw/openrouter-provider:api.tsは provider builder に加えて onboarding/config ヘルパーをエクスポート
- トークン交換
- カスタムヘッダー
- ネイティブ転送 ID
- 使用量と請求
各推論呼び出しの前にトークン交換が必要な provider の場合:
利用可能なすべての provider フック
利用可能なすべての provider フック
OpenClaw は次の順序でフックを呼び出します。ほとんどの provider では 2〜3 個しか使いません:
ランタイムフォールバックに関する注意:
| # | フック | 使用するタイミング |
|---|---|---|
| 1 | catalog | モデル catalog または base URL のデフォルト |
| 2 | applyConfigDefaults | config マテリアライズ時の provider 所有グローバルデフォルト |
| 3 | normalizeModelId | 参照前の legacy/preview model-id エイリアスクリーンアップ |
| 4 | normalizeTransport | 汎用モデル組み立て前の provider-family api / baseUrl クリーンアップ |
| 5 | normalizeConfig | models.providers.<id> config を正規化 |
| 6 | applyNativeStreamingUsageCompat | config provider 向けネイティブ streaming-usage compat 書き換え |
| 7 | resolveConfigApiKey | provider 所有の env-marker auth 解決 |
| 8 | resolveSyntheticAuth | local/self-hosted または config ベースの synthetic auth |
| 9 | shouldDeferSyntheticProfileAuth | synthetic な保存済み profile プレースホルダーを env/config auth より後ろに下げる |
| 10 | resolveDynamicModel | 任意のアップストリームモデル ID を受け入れる |
| 11 | prepareDynamicModel | 解決前の非同期メタデータ取得 |
| 12 | normalizeResolvedModel | runner 前の転送書き換え |
-
normalizeConfigは、まず一致した provider を確認し、その後 実際に config を変更するものが見つかるまで、他の フック対応 provider plugin を確認します。 サポート対象の Google-family config エントリを書き換える provider フックがなければ、 バンドルされた Google config normalizer が引き続き適用されます。 -
resolveConfigApiKeyは、公開されている場合は provider フックを使います。バンドルされたamazon-bedrock経路にも、ここに組み込みの AWS env-marker resolver がありますが、 Bedrock ランタイム auth 自体は引き続き AWS SDK デフォルト チェーンを使います。 | 13 |contributeResolvedModelCompat| 別の互換転送の背後にある vendor モデル向け compat フラグ | | 14 |capabilities| legacy な静的 capability バッグ。互換性専用 | | 15 |normalizeToolSchemas| 登録前の provider 所有ツールスキーマクリーンアップ | | 16 |inspectToolSchemas| provider 所有ツールスキーマ diagnostics | | 17 |resolveReasoningOutputMode| タグ付き vs ネイティブ reasoning-output 契約 | | 18 |prepareExtraParams| デフォルトリクエストパラメータ | | 19 |createStreamFn| 完全カスタムの StreamFn 転送 | | 20 |wrapStreamFn| 通常ストリーム経路上のカスタムヘッダー/ボディラッパー | | 21 |resolveTransportTurnState| ネイティブなターンごとのヘッダー/メタデータ | | 22 |resolveWebSocketSessionPolicy| ネイティブ WS セッションヘッダー/クールダウン | | 23 |formatApiKey| カスタムランタイムトークン形式 | | 24 |refreshOAuth| カスタム OAuth リフレッシュ | | 25 |buildAuthDoctorHint| auth 修復ガイダンス | | 26 |matchesContextOverflowError| provider 所有のオーバーフロー検出 | | 27 |classifyFailoverReason| provider 所有のレート制限/過負荷分類 | | 28 |isCacheTtlEligible| プロンプトキャッシュ TTL ゲーティング | | 29 |buildMissingAuthMessage| カスタムの認証欠落ヒント | | 30 |suppressBuiltInModel| 古くなったアップストリーム行を非表示 | | 31 |augmentModelCatalog| synthetic な forward-compat 行 | | 32 |isBinaryThinking| バイナリ thinking のオン/オフ | | 33 |supportsXHighThinking|xhighreasoning サポート | | 34 |resolveDefaultThinkingLevel| デフォルト/thinkポリシー | | 35 |isModernModelRef| live/smoke モデルマッチング | | 36 |prepareRuntimeAuth| 推論前のトークン交換 | | 37 |resolveUsageAuth| カスタム使用量認証情報解析 | | 38 |fetchUsageSnapshot| カスタム使用量エンドポイント | | 39 |createEmbeddingProvider| memory/search 用の provider 所有 embedding アダプター | | 40 |buildReplayPolicy| カスタム transcript replay/compaction ポリシー | | 41 |sanitizeReplayHistory| 汎用クリーンアップ後の provider 固有 replay 書き換え | | 42 |validateReplayTurns| 埋め込み runner 前の厳格な replay-turn 検証 | | 43 |onModelSelected| 選択後コールバック(例: telemetry) | プロンプトチューニングに関する注意:resolveSystemPromptContributionを使うと、provider はモデルファミリー向けにキャッシュを意識した システムプロンプトガイダンスを注入できます。動作が 1 つの provider/モデル ファミリーに属し、安定/動的キャッシュ分割を維持すべき場合は、before_prompt_buildよりこちらを優先してください。
追加機能を加える(任意)
provider plugin は、テキスト推論に加えて、speech、realtime transcription、realtime
voice、メディア理解、画像生成、動画生成、web fetch、
および web search を登録できます:OpenClaw はこれを hybrid-capability plugin と分類します。これは
会社単位の plugin(ベンダーごとに 1 plugin)に推奨される
パターンです。
Internals: Capability Ownership を参照してください。動画生成では、上記のようなモード認識 capability 形状を優先してください:
generate、imageToVideo、videoToVideo。maxInputImages、maxInputVideos、maxDurationSeconds のような
フラットな集約フィールドだけでは、
transform-mode サポートや無効なモードを適切に表現できません。音楽生成 provider も同じパターンに従う必要があります:
プロンプトのみの生成には generate、参照画像ベースの
生成には edit を使用します。maxInputImages、
supportsLyrics、supportsFormat のようなフラットな集約フィールドだけでは
edit サポートを表現できません。明示的な generate / edit
ブロックが期待される契約です。ClawHub に公開する
provider plugin は、他の外部コード plugin と同じ方法で公開します:clawhub package publish を使う必要があります。
ファイル構成
catalog order リファレンス
catalog.order は、組み込み
provider に対して catalog をいつマージするかを制御します:
| Order | タイミング | 使用例 |
|---|---|---|
simple | 最初のパス | プレーンな API キー provider |
profile | simple の後 | auth profile によって制御される provider |
paired | profile の後 | 複数の関連エントリを合成する |
late | 最後のパス | 既存の provider を上書きする(衝突時に優先) |
次のステップ
- Channel Plugins — plugin がチャネルも提供する場合
- SDK Runtime —
api.runtimeヘルパー(TTS、search、subagent) - SDK Overview — 完全な subpath import リファレンス
- Plugin Internals — フック詳細とバンドル例