Plugin マニフェスト

このページは OpenClaw ネイティブ Plugin マニフェスト専用です。

互換バンドルレイアウトについては、Plugin バンドルを参照してください。

互換バンドル形式では、別のマニフェストファイルを使用します。

• Codex バンドル: .codex-plugin/plugin.json
• Claude バンドル: .claude-plugin/plugin.json、またはマニフェストなしのデフォルト Claude コンポーネント レイアウト
• Cursor バンドル: .cursor-plugin/plugin.json

OpenClaw はこれらのバンドルレイアウトも自動検出しますが、ここで説明する openclaw.plugin.json スキーマに対しては検証されません。

互換バンドルについて、OpenClaw は現在、レイアウトが OpenClaw ランタイムの期待に一致する場合に、 バンドルメタデータに加えて、宣言された skill ルート、Claude コマンドルート、Claude バンドルの settings.json デフォルト、 Claude バンドルの LSP デフォルト、およびサポートされている hook pack を読み取ります。

すべてのネイティブ OpenClaw Plugin は、Plugin ルートに openclaw.plugin.json ファイルを同梱する必要があります。OpenClaw はこのマニフェストを使用して、Plugin コードを実行せずに設定を検証します。マニフェストがない、または無効な場合は Plugin エラーとして扱われ、設定検証がブロックされます。

Plugin システム全体のガイドを参照してください: Plugins。 ネイティブ capability モデルと現在の外部互換性ガイダンスについては、次を参照してください: Capability model。

このファイルの役割

openclaw.plugin.json は、OpenClaw が Plugin コードをロードする前に読み取るメタデータです。以下のすべては、Plugin ランタイムを起動せずに検査できる程度に軽量である必要があります。

用途:

• Plugin の識別情報、設定検証、設定 UI ヒント
• 認証、オンボーディング、セットアップメタデータ（エイリアス、自動有効化、プロバイダー環境変数、認証の選択肢）
• コントロールプレーンのサーフェス向けの有効化ヒント
• 省略形モデルファミリーの所有権
• 静的な capability 所有権スナップショット（contracts）
• 共有 openclaw qa ホストが検査できる QA ランナーメタデータ
• カタログおよび検証サーフェスにマージされるチャネル固有の設定メタデータ

使用しない用途: ランタイム動作の登録、コードエントリポイントの宣言、 または npm インストールメタデータ。これらは Plugin コードと package.json に属します。

最小例

{  "id": "voice-call",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

詳細な例

{  "id": "openrouter",  "name": "OpenRouter",  "description": "OpenRouter provider plugin",  "version": "1.0.0",  "providers": ["openrouter"],  "modelSupport": {    "modelPrefixes": ["router-"]  },  "modelIdNormalization": {    "providers": {      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  },  "providerEndpoints": [    {      "endpointClass": "openrouter",      "hostSuffixes": ["openrouter.ai"]    }  ],  "providerRequest": {    "providers": {      "openrouter": {        "family": "openrouter"      }    }  },  "cliBackends": ["openrouter-cli"],  "syntheticAuthRefs": ["openrouter-cli"],  "setup": {    "providers": [      {        "id": "openrouter",        "envVars": ["OPENROUTER_API_KEY"]      }    ]  },  "providerAuthAliases": {    "openrouter-coding": "openrouter"  },  "channelEnvVars": {    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "OpenRouter API key",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter API key",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API key",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

トップレベルフィールドのリファレンス

生成プロバイダーメタデータリファレンス

生成プロバイダーメタデータフィールドは、対応する contracts.*GenerationProviders リストで宣言されたプロバイダーの静的認証シグナルを記述します。 OpenClaw はプロバイダーランタイムが読み込まれる前にこれらのフィールドを読み取るため、コアツールはすべてのプロバイダー Plugin をインポートせずに生成プロバイダーが利用可能かどうかを判断できます。

これらのフィールドは、低コストで宣言的な事実にのみ使用してください。トランスポート、リクエスト変換、トークン更新、認証情報の検証、実際の生成動作は Plugin ランタイムに留まります。

{  "contracts": {    "imageGenerationProviders": ["example-image"]  },  "imageGenerationProviderMetadata": {    "example-image": {      "aliases": ["example-image-oauth"],      "authProviders": ["example-image"],      "configSignals": [        {          "rootPath": "plugins.entries.example-image.config",          "overlayPath": "image",          "mode": {            "path": "mode",            "default": "local",            "allowed": ["local"]          },          "requiredAny": ["workflow", "workflowPath"],          "required": ["promptNodeId"]        }      ],      "authSignals": [        {          "provider": "example-image"        },        {          "provider": "example-image-oauth",          "providerBaseUrl": {            "provider": "example-image",            "defaultBaseUrl": "https://api.example.com/v1",            "allowedBaseUrls": ["https://api.example.com/v1"]          }        }      ]    }  }}

各メタデータエントリは以下をサポートします。

各 configSignals エントリは以下をサポートします。

各 mode ガードは以下をサポートします。

各 authSignals エントリは以下をサポートします。

各 providerBaseUrl ガードは以下をサポートします。

ツールメタデータリファレンス

toolMetadata は、ツール名をキーとして、生成プロバイダーメタデータと同じ configSignals および authSignals の形を使用します。contracts.tools は所有権を宣言します。toolMetadata は低コストな可用性エビデンスを宣言し、OpenClaw がツールファクトリから null が返るかどうかを確認するだけのために Plugin ランタイムをインポートすることを避けられるようにします。

{  "setup": {    "providers": [      {        "id": "example",        "envVars": ["EXAMPLE_API_KEY"]      }    ]  },  "contracts": {    "tools": ["example_search"]  },  "toolMetadata": {    "example_search": {      "authSignals": [        {          "provider": "example"        }      ],      "configSignals": [        {          "rootPath": "plugins.entries.example.config",          "overlayPath": "search",          "required": ["apiKey"]        }      ]    }  }}

ツールに toolMetadata がない場合、OpenClaw は既存の動作を維持し、ツール契約がポリシーに一致するときに所有元の Plugin を読み込みます。ファクトリが認証や設定に依存するホットパスのツールでは、Plugin 作成者は、問い合わせのためにコアへランタイムをインポートさせるのではなく、toolMetadata を宣言するべきです。

providerAuthChoices リファレンス

各 providerAuthChoices エントリは、1 つのオンボーディングまたは認証の選択肢を記述します。 OpenClaw はプロバイダーランタイムが読み込まれる前にこれを読み取ります。 プロバイダーセットアップリストは、プロバイダーランタイムを読み込まずに、これらのマニフェスト選択肢、記述子から導出されたセットアップ選択肢、インストールカタログメタデータを使用します。

commandAliases リファレンス

Plugin が、ユーザーが誤って plugins.allow に入れたりルート CLI コマンドとして実行しようとしたりする可能性のあるランタイムコマンド名を所有する場合は、commandAliases を使用する。OpenClaw は、Plugin ランタイムコードをインポートせずに診断のためにこのメタデータを使用する。

{  "commandAliases": [    {      "name": "dreaming",      "kind": "runtime-slash",      "cliCommand": "memory"    }  ]}

activation リファレンス

Plugin が、どのコントロールプレーンイベントで activation/load 計画に含めるべきかを安価に宣言できる場合は、activation を使用する。

このブロックはプランナーのメタデータであり、ライフサイクル API ではない。ランタイム動作を登録せず、register(...) を置き換えず、Plugin コードがすでに実行済みであることも約束しない。activation プランナーは、既存のマニフェスト所有権メタデータ（providers、channels、commandAliases、setup.providers、contracts.tools、フックなど）にフォールバックする前に、これらのフィールドを使用して候補 Plugin を絞り込む。

所有権をすでに説明している最も狭いメタデータを優先する。関係を表現できる場合は、providers、channels、commandAliases、セットアップ記述子、または contracts を使用する。これらの所有権フィールドでは表現できない追加のプランナーヒントには activation を使用する。 claude-cli、my-cli、google-gemini-cli などの CLI ランタイムエイリアスにはトップレベルの cliBackends を使用する。activation.onAgentHarnesses は、所有権フィールドをまだ持たない埋め込みエージェントハーネス id 専用。

このブロックはメタデータのみ。ランタイム動作を登録せず、register(...)、setupEntry、その他のランタイム/Plugin エントリポイントを置き換えない。現在のコンシューマーは、より広範な Plugin ロードの前に絞り込みヒントとして使用するため、起動時以外の activation メタデータが欠けていても、通常は性能に影響するだけである。マニフェスト所有権フォールバックがまだ存在する限り、正しさは変わらないはずである。

すべての Plugin は activation.onStartup を意図的に設定するべきである。Plugin が Gateway 起動中に実行される必要がある場合にのみ true に設定する。Plugin が起動時には不活性で、より狭いトリガーからのみロードされるべき場合は false に設定する。onStartup を省略しても、Plugin は暗黙に起動時ロードされなくなった。起動、チャネル、設定、エージェントハーネス、メモリ、またはその他のより狭い activation トリガーには、明示的な activation メタデータを使用する。

{  "activation": {    "onStartup": false,    "onProviders": ["openai"],    "onCommands": ["models"],    "onChannels": ["web"],    "onRoutes": ["gateway-webhook"],    "onConfigPaths": ["browser"],    "onCapabilities": ["provider", "tool"]  }}

現在のライブコンシューマー:

• Gateway 起動計画は、明示的な起動インポートに activation.onStartup を使用する
• コマンドトリガーの CLI 計画は、従来の commandAliases[].cliCommand または commandAliases[].name にフォールバックする
• エージェントランタイムの起動計画は、埋め込みハーネスには activation.onAgentHarnesses を、CLI ランタイムエイリアスにはトップレベルの cliBackends[] を使用する
• チャネルトリガーの setup/channel 計画は、明示的なチャネル activation メタデータが欠けている場合、従来の channels[] 所有権にフォールバックする
• 起動時の Plugin 計画は、バンドルされたブラウザー Plugin の browser ブロックなど、チャネルではないルート設定面に activation.onConfigPaths を使用する
• プロバイダートリガーの setup/runtime 計画は、明示的なプロバイダー activation メタデータが欠けている場合、従来の providers[] とトップレベルの cliBackends[] 所有権にフォールバックする

プランナー診断は、明示的な activation ヒントとマニフェスト所有権フォールバックを区別できる。たとえば、activation-command-hint は activation.onCommands が一致したことを意味し、manifest-command-alias はプランナーが代わりに commandAliases 所有権を使用したことを意味する。これらの理由ラベルはホスト診断とテスト用である。Plugin 作者は、所有権を最もよく説明するメタデータを宣言し続けるべきである。

qaRunners リファレンス

Plugin が共有の openclaw qa ルート配下に 1 つ以上のトランスポートランナーを提供する場合は、qaRunners を使用する。このメタデータは安価で静的に保つ。実際の CLI 登録は、qaRunnerCliRegistrations をエクスポートする軽量な runtime-api.ts サーフェスを通じて、引き続き Plugin ランタイムが所有する。

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"    }  ]}

setup リファレンス

ランタイムのロード前に、セットアップとオンボーディングのサーフェスが安価な Plugin 所有メタデータを必要とする場合は、setup を使用します。

{  "setup": {    "providers": [      {        "id": "openai",        "authMethods": ["api-key"],        "envVars": ["OPENAI_API_KEY"],        "authEvidence": [          {            "type": "local-file-with-env",            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",            "requiresAllEnv": ["OPENAI_PROJECT"],            "credentialMarker": "openai-local-credentials",            "source": "openai local credentials"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

トップレベルの cliBackends は引き続き有効で、CLI 推論バックエンドを説明し続けます。setup.cliBackends は、メタデータのみのままにすべきコントロールプレーン/セットアップフロー向けの、セットアップ専用ディスクリプターサーフェスです。

存在する場合、setup.providers と setup.cliBackends は、セットアップ検出のための推奨されるディスクリプター優先ルックアップサーフェスです。ディスクリプターが候補 Plugin を絞り込むだけで、セットアップがセットアップ時ランタイムフックをさらに必要とする場合は、requiresRuntime: true を設定し、フォールバック実行パスとして setup-api を保持します。

OpenClaw は、汎用プロバイダー認証と環境変数ルックアップにも setup.providers[].envVars を含めます。providerAuthEnvVars は非推奨期間中、互換性アダプターを通じて引き続きサポートされますが、まだこれを使用している非バンドル Plugin はマニフェスト診断を受け取ります。新しい Plugin は、セットアップ/ステータスの環境メタデータを setup.providers[].envVars に置くべきです。

セットアップエントリが利用できない場合、または setup.requiresRuntime: false がセットアップランタイム不要を宣言している場合、OpenClaw は setup.providers[].authMethods から単純なセットアップ選択肢を導出することもできます。明示的な providerAuthChoices エントリは、カスタムラベル、CLI フラグ、オンボーディングスコープ、アシスタントメタデータでは引き続き優先されます。

requiresRuntime: false は、それらのディスクリプターがセットアップサーフェスに十分な場合にのみ設定してください。OpenClaw は明示的な false をディスクリプターのみの契約として扱い、セットアップルックアップのために setup-api または openclaw.setupEntry を実行しません。ディスクリプターのみの Plugin がそれらのセットアップランタイムエントリのいずれかをまだ同梱している場合、OpenClaw は追加診断を報告し、それを無視し続けます。requiresRuntime を省略すると従来のフォールバック動作が保持されるため、このフラグなしでディスクリプターを追加した既存の Plugin は壊れません。

セットアップルックアップは Plugin 所有の setup-api コードを実行できるため、正規化された setup.providers[].id と setup.cliBackends[] の値は、検出された Plugin 全体で一意である必要があります。所有権が曖昧な場合は、検出順から勝者を選ぶのではなく、フェイルクローズします。

セットアップランタイムが実行される場合、setup-api がマニフェストディスクリプターで宣言されていないプロバイダーまたは CLI バックエンドを登録した場合、またはディスクリプターに一致するランタイム登録がない場合、セットアップレジストリ診断はディスクリプターのドリフトを報告します。これらの診断は追加的なものであり、従来の Plugin を拒否しません。

setup.providers リファレンス

authEvidence は、ランタイムコードをロードせずに検証できる、プロバイダー所有のローカル認証情報マーカー用です。これらのチェックは安価かつローカルのままでなければなりません。ネットワーク呼び出し、キーチェーンまたはシークレットマネージャーの読み取り、シェルコマンド、プロバイダー API プローブは行いません。

サポートされる証拠エントリ:

setup フィールド

uiHints リファレンス

uiHints は、設定フィールド名から小さなレンダリングヒントへのマップです。

{  "uiHints": {    "apiKey": {      "label": "API key",      "help": "Used for OpenRouter requests",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

各フィールドヒントには次を含めることができます。

contracts リファレンス

contracts は、OpenClaw が Plugin ランタイムをインポートせずに読める静的な機能所有権メタデータにのみ使用します。

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"],    "trustedToolPolicies": ["workflow-budget"],    "externalAuthProviders": ["acme-ai"],    "embeddingProviders": ["openai-compatible"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

各リストは任意です:

contracts.embeddedExtensionFactories は、バンドル済み Codex app-server 専用拡張ファクトリーのために保持されます。バンドル済みツール結果変換は、 代わりに contracts.agentToolResultMiddleware を宣言し、 api.registerAgentToolResultMiddleware(...) で登録する必要があります。インストール済みプラグインは、 明示的に有効化され、かつ contracts.agentToolResultMiddleware で宣言したランタイムに対してのみ、 同じミドルウェアの継ぎ目を使用できます。

ホスト信頼の事前ツールポリシー階層を必要とするインストール済みプラグインは、 登録される各ローカル ID を contracts.trustedToolPolicies で宣言し、明示的に 有効化されている必要があります。バンドル済みプラグインは既存の信頼済みポリシーパスを維持しますが、 未宣言のポリシー ID を持つインストール済みプラグインは登録前に拒否されます。ポリシー ID は 登録するプラグインにスコープされるため、2 つのプラグインがどちらも workflow-budget を宣言して登録できます。ただし、1 つのプラグインが同じローカル ID を 2 回登録することはできません。

ランタイムの api.registerTool(...) 登録は contracts.tools と一致する必要があります。 ツール探索ではこのリストを使用し、要求されたツールを所有できるプラグインランタイムだけを 読み込みます。

resolveExternalAuthProfiles を実装するプロバイダープラグインは contracts.externalAuthProviders を宣言する必要があります。未宣言の外部認証フックは無視されます。

汎用埋め込みプロバイダーは、api.registerEmbeddingProvider(...) で登録される 各アダプターについて contracts.embeddingProviders を宣言する必要があります。メモリ検索で 消費されるプロバイダーを含む、再利用可能なベクトル生成には汎用契約を使用してください。 contracts.memoryEmbeddingProviders は非推奨のメモリ専用互換性であり、 既存プロバイダーが汎用埋め込みプロバイダーの継ぎ目へ移行する間だけ残ります。

contracts.gatewayMethodDispatch は現在 "authenticated-request" を受け入れます。これは、Gateway コントロールプレーンメソッドを プロセス内で意図的にディスパッチするネイティブプラグイン HTTP ルート向けの API 衛生ゲートであり、 悪意あるネイティブプラグインに対するサンドボックスではありません。Gateway HTTP 認証をすでに要求する、 厳密にレビューされたバンドル済みまたはオペレーター向けサーフェスにのみ使用してください。

mediaUnderstandingProviderMetadata リファレンス

メディア理解プロバイダーに、デフォルトモデル、自動認証フォールバック優先度、または ランタイム読み込み前に汎用コアヘルパーが必要とするネイティブドキュメント対応がある場合は、 mediaUnderstandingProviderMetadata を使用します。キーは contracts.mediaUnderstandingProviders でも宣言されている必要があります。

{  "contracts": {    "mediaUnderstandingProviders": ["example"]  },  "mediaUnderstandingProviderMetadata": {    "example": {      "capabilities": ["image", "audio"],      "defaultModels": {        "image": "example-vision-latest",        "audio": "example-transcribe-latest"      },      "autoPriority": {        "image": 40      },      "nativeDocumentInputs": ["pdf"]    }  }}

各プロバイダーエントリには次を含めることができます。

channelConfigs リファレンス

チャンネルプラグインがランタイム読み込み前に軽量な設定メタデータを必要とする場合は、 channelConfigs を使用します。読み取り専用のチャンネルセットアップまたはステータス探索では、 セットアップエントリが利用できない場合、または setup.requiresRuntime: false がセットアップランタイム不要を 宣言している場合に、設定済み外部チャンネルに対してこのメタデータを直接使用できます。

channelConfigs はプラグインマニフェストメタデータであり、新しいトップレベルのユーザー設定 セクションではありません。ユーザーは引き続き channels.<channel-id> の下でチャンネルインスタンスを 設定します。OpenClaw はマニフェストメタデータを読み取り、プラグインランタイムコードが実行される前に、 どのプラグインがその設定済みチャンネルを所有するかを決定します。

チャンネルプラグインでは、configSchema と channelConfigs は異なるパスを記述します。

• configSchema は plugins.entries.<plugin-id>.config を検証します
• channelConfigs.<channel-id>.schema は channels.<channel-id> を検証します

channels[] を宣言する非バンドルプラグインは、一致する channelConfigs エントリも宣言する必要があります。それらがない場合でも、OpenClaw はプラグインを読み込めますが、 コールドパスの設定スキーマ、セットアップ、および Control UI サーフェスは、プラグインランタイムが実行されるまで チャンネル所有オプションの形を知ることができません。

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled と nativeSkillsAutoEnabled は、チャンネルランタイムの読み込み前に実行されるコマンド設定チェック用の 静的な auto デフォルトを宣言できます。バンドル済みチャンネルは、他のパッケージ所有チャンネルカタログ メタデータと並べて、package.json#openclaw.channel.commands を通じて同じデフォルトを公開することもできます。

{  "channelConfigs": {    "matrix": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "homeserverUrl": { "type": "string" }        }      },      "uiHints": {        "homeserverUrl": {          "label": "Homeserver URL",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Matrix homeserver connection",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

各チャンネルエントリには次を含めることができます。

別のチャンネルプラグインを置き換える

別のプラグインも提供できるチャンネル ID について、自分のプラグインが優先所有者である場合は preferOver を使用します。一般的なケースとして、名前変更されたプラグイン ID、 バンドル済みプラグインを置き換えるスタンドアロンプラグイン、または設定互換性のために 同じチャンネル ID を維持するメンテナンス済みフォークがあります。

{  "id": "acme-chat",  "channels": ["chat"],  "channelConfigs": {    "chat": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "webhookUrl": { "type": "string" }        }      },      "preferOver": ["chat"]    }  }}

channels.chat が設定されている場合、OpenClaw はチャンネル ID と 優先プラグイン ID の両方を考慮します。低優先度のプラグインが、バンドル済みである、またはデフォルトで有効化されている という理由だけで選択されていた場合、OpenClaw は有効なランタイム設定内でそれを無効化し、 1 つのプラグインがそのチャンネルとツールを所有するようにします。明示的なユーザー選択は引き続き優先されます。 ユーザーが両方のプラグインを明示的に有効化した場合、OpenClaw は要求されたプラグインセットを 暗黙に変更するのではなく、その選択を保持し、重複するチャンネルまたはツールの診断を報告します。

preferOver は、本当に同じチャンネルを提供できるプラグイン ID にスコープしてください。 これは汎用の優先度フィールドではなく、ユーザー設定キーをリネームするものでもありません。

modelSupport リファレンス

OpenClaw が Plugin ランタイムを読み込む前に、gpt-5.5 や claude-sonnet-4.6 のような短縮モデル ID からプロバイダー Plugin を推論する必要がある場合は、modelSupport を使用します。

{  "modelSupport": {    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],    "modelPatterns": ["^computer-use-preview"]  }}

OpenClaw はこの優先順位を適用します。

• 明示的な provider/model 参照は、所有元の providers マニフェストメタデータを使用します
• modelPatterns は modelPrefixes より優先されます
• 非バンドル Plugin とバンドル Plugin の両方が一致する場合、非バンドル Plugin が優先されます
• 残る曖昧さは、ユーザーまたは設定がプロバイダーを指定するまで無視されます

フィールド:

modelPatterns エントリは compileSafeRegex を通じてコンパイルされ、ネストした繰り返しを含むパターン（例: (a+)+$）は拒否されます。安全性チェックに失敗したパターンは、構文的に無効な正規表現と同様に、黙ってスキップされます。パターンは単純に保ち、ネストした量指定子は避けてください。

modelCatalog リファレンス

OpenClaw が Plugin ランタイムを読み込む前に、プロバイダーモデルのメタデータを把握する必要がある場合は、modelCatalog を使用します。これは、固定カタログ行、プロバイダーエイリアス、抑制ルール、検出モードについて、マニフェストが所有するソースです。ランタイム更新は引き続きプロバイダーランタイムコードに属しますが、マニフェストはランタイムが必要になるタイミングをコアへ伝えます。

{  "providers": ["openai"],  "modelCatalog": {    "providers": {      "openai": {        "baseUrl": "https://api.openai.com/v1",        "api": "openai-responses",        "models": [          {            "id": "gpt-5.4",            "name": "GPT-5.4",            "input": ["text", "image"],            "reasoning": true,            "contextWindow": 256000,            "maxTokens": 128000,            "cost": {              "input": 1.25,              "output": 10,              "cacheRead": 0.125            },            "status": "available",            "tags": ["default"]          }        ]      }    },    "aliases": {      "azure-openai-responses": {        "provider": "openai",        "api": "azure-openai-responses"      }    },    "suppressions": [      {        "provider": "azure-openai-responses",        "model": "gpt-5.3-codex-spark",        "reason": "not available on Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

トップレベルフィールド:

aliases は、モデルカタログ計画におけるプロバイダー所有権の検索に参加します。エイリアスのターゲットは、同じ Plugin が所有するトップレベルプロバイダーでなければなりません。プロバイダーでフィルターされたリストがエイリアスを使用する場合、OpenClaw は所有元マニフェストを読み、プロバイダーランタイムを読み込まずにエイリアスの API/base URL オーバーライドを適用できます。 エイリアスはフィルターなしのカタログ一覧を展開しません。広範な一覧では、所有元の正規プロバイダー行のみが出力されます。

suppressions は、古いプロバイダーランタイムの suppressBuiltInModel フックを置き換えます。抑制エントリは、プロバイダーが Plugin に所有されている場合、または所有済みプロバイダーをターゲットとする modelCatalog.aliases キーとして宣言されている場合にのみ尊重されます。モデル解決中にランタイム抑制フックは呼び出されなくなりました。

プロバイダーフィールド:

モデルフィールド:

抑制フィールド:

ランタイム専用データを modelCatalog に入れないでください。プロバイダーでフィルターされた一覧やピッカー画面がレジストリ/ランタイム検出をスキップするのに十分なほどマニフェスト行が完全な場合にのみ、static を使用します。マニフェスト行が一覧表示可能な有用な種データまたは補助データだが、更新/キャッシュによって後からさらに行を追加できる場合は、refreshable を使用します。refreshable 行はそれ自体では権威ある情報ではありません。OpenClaw が一覧を把握するためにプロバイダーランタイムを読み込む必要がある場合は、runtime を使用します。

modelIdNormalization リファレンス

プロバイダーランタイムの読み込み前に行う必要がある、低コストでプロバイダー所有のモデル ID クリーンアップには、modelIdNormalization を使用します。これにより、短いモデル名、プロバイダー内のレガシー ID、プロキシプレフィックスルールなどのエイリアスを、コアのモデル選択テーブルではなく、所有元 Plugin マニフェスト内に保持できます。

{  "providers": ["anthropic", "openrouter"],  "modelIdNormalization": {    "providers": {      "anthropic": {        "aliases": {          "sonnet-4.6": "claude-sonnet-4-6"        }      },      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  }}

プロバイダーフィールド:

providerEndpoints リファレンス

汎用リクエストポリシーがプロバイダーランタイムの読み込み前に把握する必要があるエンドポイント分類には、providerEndpoints を使用します。各 endpointClass の意味は引き続きコアが所有します。Plugin マニフェストはホストと base URL メタデータを所有します。

Endpoint フィールド:

providerRequest リファレンス

汎用リクエストポリシーがプロバイダーランタイムを読み込まずに必要とする、低コストなリクエスト互換性メタデータには providerRequest を使用する。動作固有のペイロード書き換えは、プロバイダーランタイムフックまたは共有プロバイダーファミリーヘルパーに保持する。

{  "providers": ["vllm"],  "providerRequest": {    "providers": {      "vllm": {        "family": "vllm",        "openAICompletions": {          "supportsStreamingUsage": true        }      }    }  }}

プロバイダーフィールド:

secretProviderIntegrations リファレンス

Plugin が再利用可能な SecretRef exec プロバイダープリセットを公開できる場合は、secretProviderIntegrations を使用する。OpenClaw は Plugin ランタイムが読み込まれる前にこのメタデータを読み取り、Plugin の所有権を secrets.providers.<alias>.pluginIntegration に保存し、実際のシークレット解決は SecretRef ランタイムに任せる。プリセットは、バンドル済み Plugin と、git や ClawHub インストールなどの管理対象 Plugin インストールルートから検出されたインストール済み Plugin にのみ公開される。

{  "secretProviderIntegrations": {    "secret-store": {      "providerAlias": "team-secrets",      "displayName": "Team secrets",      "source": "exec",      "command": "${node}",      "args": ["./bin/resolve-secrets.mjs"]    }  }}

マップキーは統合 ID。providerAlias が省略された場合、OpenClaw は統合 ID を SecretRef プロバイダーエイリアスとして使用する。プロバイダーエイリアスは、通常の SecretRef プロバイダーエイリアスパターンに一致する必要がある。例: team-secrets または onepassword-work。

オペレーターがプリセットを選択すると、OpenClaw は次のようなプロバイダー参照を書き込む:

{  "secrets": {    "providers": {      "team-secrets": {        "source": "exec",        "pluginIntegration": {          "pluginId": "acme-secrets",          "integrationId": "secret-store"        }      }    }  }}

起動時またはリロード時に、OpenClaw は現在の Plugin マニフェストメタデータを読み込み、所有元 Plugin がインストール済みかつ有効であることを確認し、マニフェストから exec コマンドを具現化することで、そのプロバイダーを解決する。Plugin を無効化または削除すると、アクティブな SecretRefs に対するプロバイダーは取り消される。スタンドアロンの exec 設定が必要なオペレーターは、手動の command/args プロバイダーを直接記述できる。

現在サポートされているのは source: "exec" プリセットのみ。command は ${node} でなければならず、args[0] は ./ で始まる Plugin ルート相対のリゾルバースクリプトでなければならない。OpenClaw は起動時またはリロード時に、それを現在の Node 実行ファイルと Plugin 内スクリプトの絶対パスに具現化する。--require、--import、--loader、--env-file、--eval、--print などの Node オプションは、マニフェストプリセット契約の一部ではない。Node 以外のコマンドが必要なオペレーターは、スタンドアロンの手動 exec プロバイダーを直接設定できる。

OpenClaw は、マニフェストプリセットの trustedDirs を Plugin ルートから導出し、${node} プリセットの場合は現在の Node 実行ファイルディレクトリからも導出する。マニフェストで記述された trustedDirs は無視される。timeoutMs、maxOutputBytes、jsonOnly、env、passEnv、allowInsecurePath などのその他の exec プロバイダーオプションは、通常の SecretRef exec プロバイダー設定へそのまま渡される。

modelPricing リファレンス

プロバイダーがランタイム読み込み前にコントロールプレーンの価格設定動作を制御する必要がある場合は、modelPricing を使用する。Gateway 価格キャッシュは、プロバイダーランタイムコードをインポートせずにこのメタデータを読み取る。

{  "providers": ["ollama", "openrouter"],  "modelPricing": {    "providers": {      "ollama": {        "external": false      },      "openrouter": {        "openRouter": {          "passthroughProviderModel": true        },        "liteLLM": false      }    }  }}

プロバイダーフィールド:

ソースフィールド:

OpenClaw Provider Index

OpenClaw Provider Index は、まだ Plugin がインストールされていない可能性があるプロバイダー向けの、OpenClaw 所有のプレビューメタデータ。Plugin マニフェストの一部ではない。Plugin マニフェストは引き続き、インストール済み Plugin の権威である。Provider Index は、プロバイダー Plugin がインストールされていない場合に、将来のインストール可能プロバイダーおよび事前インストールのモデルピッカー画面が利用する内部フォールバック契約である。

カタログ権威の順序:

1. ユーザー設定。
2. インストール済み Plugin マニフェストの modelCatalog。
3. 明示的な更新によるモデルカタログキャッシュ。
4. OpenClaw Provider Index プレビュー行。

Provider Index には、シークレット、有効状態、ランタイムフック、ライブのアカウント固有モデルデータを含めてはならない。そのプレビューカタログは、Plugin マニフェストと同じ modelCatalog プロバイダー行形状を使用するが、api、baseUrl、価格設定、互換性フラグなどのランタイムアダプターフィールドをインストール済み Plugin マニフェストと意図的に同期させる場合を除き、安定した表示メタデータに限定するべきである。ライブ /models 検出を持つプロバイダーは、通常の一覧表示やオンボーディングでプロバイダー API を呼び出す代わりに、明示的なモデルカタログキャッシュパスを通じて更新済み行を書き込むべきである。

Provider Index エントリは、Plugin がコア外へ移動した、またはまだインストールされていないプロバイダーについて、インストール可能な Plugin メタデータも保持できる。このメタデータはチャネルカタログパターンを反映する。パッケージ名、npm インストール指定、期待される整合性、低コストな認証選択ラベルがあれば、インストール可能なセットアップオプションを表示するには十分である。Plugin がインストールされると、そのマニフェストが優先され、そのプロバイダーの Provider Index エントリは無視される。

レガシーなトップレベルの capability キーは非推奨。speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders、webSearchProviders を contracts 配下に移動するには openclaw doctor --fix を使用する。通常のマニフェスト読み込みでは、これらのトップレベルフィールドを capability 所有権として扱わなくなった。

マニフェストと package.json の違い

この 2 つのファイルは異なる役割を持つ:

メタデータをどこに置くべきか迷った場合は、次のルールを使う:

• OpenClaw が Plugin コードを読み込む前に知る必要があるなら、openclaw.plugin.json に置く
• パッケージング、エントリファイル、または npm インストール動作に関するものなら、package.json に置く

検出に影響する package.json フィールド

一部のランタイム前 Plugin メタデータは、意図的に openclaw.plugin.json ではなく、package.json の openclaw ブロック配下に置かれる。openclaw.bundle と openclaw.bundle.json は OpenClaw Plugin 契約ではない。ネイティブ Plugin は、openclaw.plugin.json と、以下でサポートされる package.json#openclaw フィールドを使用しなければならない。

重要な例:

マニフェストメタデータは、ランタイムが読み込まれる前にオンボーディングに表示される provider/チャネル/セットアップの選択肢を決定します。package.json#openclaw.install は、ユーザーがそれらの選択肢のいずれかを選んだときに、その Plugin を取得または有効化する方法をオンボーディングに伝えます。インストールヒントを openclaw.plugin.json に移動しないでください。

openclaw.install.minHostVersion は、非バンドル Plugin ソースのインストール時とマニフェストレジストリ読み込み時に強制されます。無効な値は拒否されます。より新しいが有効な値は、古いホスト上の外部 Plugin をスキップします。バンドル済みソース Plugin は、ホストチェックアウトと同じバージョンで管理されているものと見なされます。

openclaw.install.requiredPlatformPackages は、必須のネイティブバイナリを任意のプラットフォーム固有エイリアス経由で公開する npm パッケージ向けです。サポートされるすべてのプラットフォームエイリアスについて、素の npm パッケージ名を列挙してください。npm インストール中、OpenClaw は、lockfile 制約が現在のホストに一致する宣言済みエイリアスのみを検証します。npm が成功を報告してもそのエイリアスを省略した場合、OpenClaw は新しいキャッシュで一度だけ再試行し、それでもエイリアスが存在しない場合はインストールをロールバックします。

openclaw.compat.pluginApi は、非バンドル Plugin ソースのパッケージインストール時に強制されます。パッケージがビルドされた対象の OpenClaw Plugin SDK/ランタイム API 下限として使ってください。Plugin パッケージがより新しい API を必要としつつ、他のフロー向けには低いインストールヒントを維持する場合、これは minHostVersion より厳しくできます。公式 OpenClaw リリース同期は、既存の公式 Plugin API 下限をデフォルトで OpenClaw リリースバージョンまで引き上げますが、Plugin のみのリリースでは、パッケージが意図的に古いホストをサポートする場合に低い下限を維持できます。互換性契約としてパッケージバージョンだけを使わないでください。peerDependencies.openclaw は npm パッケージメタデータのままです。OpenClaw はインストール互換性の判断に openclaw.compat.pluginApi 契約を使います。

公式のオンデマンドインストールメタデータは、Plugin が ClawHub で公開されている場合は clawhubSpec を使うべきです。オンボーディングはそれを優先リモートソースとして扱い、インストール後に ClawHub アーティファクト情報を記録します。npmSpec は、まだ ClawHub に移行していないパッケージ向けの互換性フォールバックのままです。

正確な npm バージョン固定は、たとえば "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3" のように、すでに npmSpec にあります。公式外部カタログエントリでは、更新フローが取得した npm アーティファクトが固定リリースと一致しなくなった場合にフェイルクローズするよう、正確な spec と expectedIntegrity を組み合わせるべきです。対話型オンボーディングは互換性のため、素のパッケージ名や dist-tag を含む、信頼済みレジストリの npm spec を引き続き提示します。カタログ診断は、正確、浮動、integrity 固定、integrity 欠落、パッケージ名不一致、無効なデフォルト選択ソースを区別できます。また、expectedIntegrity が存在するものの、それを固定できる有効な npm ソースがない場合にも警告します。expectedIntegrity が存在する場合、インストール/更新フローはそれを強制します。省略されている場合、レジストリ解決は integrity 固定なしで記録されます。

チャネル Plugin は、ステータス、チャネル一覧、または SecretRef スキャンが完全なランタイムを読み込まずに設定済みアカウントを識別する必要がある場合、openclaw.setupEntry を提供すべきです。セットアップエントリは、チャネルメタデータに加え、セットアップ安全な設定、ステータス、シークレットアダプターを公開するべきです。ネットワーククライアント、Gateway リスナー、トランスポートランタイムはメイン拡張エントリポイントに置いてください。

ランタイムエントリポイントフィールドは、ソースエントリポイントフィールドに対するパッケージ境界チェックを上書きしません。たとえば、openclaw.runtimeExtensions によって、外へ抜ける openclaw.extensions パスを読み込み可能にすることはできません。

openclaw.install.allowInvalidConfigRecovery は意図的に限定されています。任意の壊れた設定をインストール可能にするものではありません。現在は、バンドル済み Plugin パスの欠落や、同じバンドル済み Plugin に対する古い channels.<id> エントリなど、特定の古いバンドル済み Plugin アップグレード失敗からインストールフローが復旧することだけを許可します。無関係な設定エラーは引き続きインストールをブロックし、オペレーターに openclaw doctor --fix を案内します。

openclaw.channel.persistedAuthState は、小さなチェッカーモジュール向けのパッケージメタデータです。

{  "openclaw": {    "channel": {      "id": "whatsapp",      "persistedAuthState": {        "specifier": "./auth-presence",        "exportName": "hasAnyWhatsAppAuth"      }    }  }}

セットアップ、doctor、ステータス、または読み取り専用 presence フローが、完全なチャネル Plugin を読み込む前に低コストな yes/no 認証プローブを必要とする場合に使います。永続化認証状態は、設定済みチャネル状態ではありません。このメタデータを使って Plugin を自動有効化したり、ランタイム依存関係を修復したり、チャネルランタイムを読み込むべきかどうかを判断したりしないでください。対象 export は、永続化状態だけを読む小さな関数であるべきです。完全なチャネルランタイム barrel 経由にしないでください。

openclaw.channel.configuredState は、低コストな env のみの設定済みチェック向けに同じ形に従います。

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "specifier": "./configured-state",        "exportName": "hasTelegramConfiguredState"      }    }  }}

チャネルが env やその他の小さな非ランタイム入力から設定済み状態に答えられる場合に使います。チェックに完全な設定解決や実際のチャネルランタイムが必要な場合は、そのロジックを Plugin の config.hasConfiguredState hook に残してください。

検出の優先順位（重複する Plugin ID）

OpenClaw は複数のルートから Plugin を検出します。生のファイルシステムスキャン順序については、Plugin スキャン順序を参照してください。2 つの検出結果が同じ id を共有する場合、最高優先順位のマニフェストだけが保持されます。優先順位の低い重複は、並べて読み込まれるのではなく破棄されます。

優先順位は高い順に次のとおりです。

1. 設定で選択済み — plugins.entries.<id> で明示的に固定されたパス
2. バンドル済み — OpenClaw に同梱される Plugin
3. グローバルインストール — グローバル OpenClaw Plugin ルートにインストールされた Plugin
4. ワークスペース — 現在のワークスペースを基準に検出された Plugin

影響:

• ワークスペースに置かれた、バンドル済み Plugin の fork や古いコピーは、バンドル済みビルドをシャドーイングしません。
• ローカルのものによってバンドル済み Plugin を実際に上書きするには、ワークスペース検出に頼るのではなく、plugins.entries.<id> 経由で固定し、優先順位で勝つようにしてください。
• 重複の破棄はログに記録されるため、Doctor と起動診断は破棄されたコピーを示せます。
• 設定で選択された重複上書きは、診断では明示的な上書きとして表現されますが、古い fork や意図しないシャドーイングが見えるように、引き続き警告されます。

JSON Schema 要件

• すべての Plugin は JSON Schema を同梱する必要があります。設定を受け付けない場合でも同様です。
• 空のスキーマも許容されます（例: { "type": "object", "additionalProperties": false }）。
• スキーマは実行時ではなく、設定の読み書き時に検証されます。
• 新しい設定キーで同梱 Plugin を拡張またはフォークする場合は、その Plugin の openclaw.plugin.json の configSchema も同時に更新してください。同梱 Plugin のスキーマは厳密なため、configSchema.properties に myNewKey を追加せずにユーザー設定へ plugins.entries.<id>.config.myNewKey を追加すると、Plugin ランタイムが読み込まれる前に拒否されます。

スキーマ拡張の例:

{  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "myNewKey": {        "type": "string"      }    }  }}

検証の動作

• 不明な channels.* キーは、チャネル ID が Plugin マニフェストで宣言されていない限り エラー です。
• plugins.entries.<id>、plugins.allow、plugins.deny、plugins.slots.* は、検出可能な Plugin ID を参照する必要があります。不明な ID は エラー です。
• Plugin がインストールされていても、マニフェストまたはスキーマが壊れているか存在しない場合、検証は失敗し、Doctor が Plugin エラーを報告します。
• Plugin 設定が存在していても Plugin が 無効 の場合、設定は保持され、Doctor とログに 警告 が表示されます。

完全な plugins.* スキーマについては、設定リファレンス を参照してください。

注記

• マニフェストは、ローカルファイルシステムからの読み込みを含む ネイティブ OpenClaw Plugin では必須 です。ランタイムは引き続き Plugin モジュールを別途読み込みます。マニフェストは検出と検証のためだけに使用されます。
• ネイティブマニフェストは JSON5 で解析されるため、最終的な値がオブジェクトである限り、コメント、末尾のカンマ、引用符なしのキーを使用できます。
• マニフェストローダーが読み取るのは、ドキュメント化されたマニフェストフィールドのみです。独自のトップレベルキーは避けてください。
• Plugin が不要とする場合、channels、providers、cliBackends、skills はすべて省略できます。
• providerCatalogEntry は軽量に保つ必要があり、広範なランタイムコードをインポートすべきではありません。リクエスト時の実行ではなく、静的なプロバイダーカタログメタデータや限定的な検出記述子に使用してください。
• 排他的な Plugin 種別は plugins.slots.* で選択されます。kind: "memory" は plugins.slots.memory、kind: "context-engine" は plugins.slots.contextEngine（デフォルトは legacy）を使用します。
• このマニフェストで排他的な Plugin 種別を宣言してください。ランタイムエントリの OpenClawPluginDefinition.kind は非推奨であり、古い Plugin 向けの互換フォールバックとしてのみ残されています。
• 環境変数メタデータ（setup.providers[].envVars、非推奨の providerAuthEnvVars、および channelEnvVars）は宣言専用です。ステータス、監査、Cron 配信検証、その他の読み取り専用サーフェスでは、環境変数を設定済みとして扱う前に、引き続き Plugin の信頼性と有効なアクティベーションポリシーが適用されます。
• プロバイダーコードを必要とするランタイムウィザードメタデータについては、プロバイダーランタイムフック を参照してください。
• Plugin がネイティブモジュールに依存する場合は、ビルド手順と、必要なパッケージマネージャーの許可リスト要件（例: pnpm allow-build-scripts + pnpm rebuild <package>）をドキュメント化してください。

関連