Plugin マニフェスト

このページでは、ネイティブ OpenClaw plugin マニフェストである openclaw.plugin.json について説明します。互換性のあるバンドルレイアウト（Codex、Claude、Cursor）については、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 デフォルト、およびサポートされているフックパックを読み取ります。

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

plugin システムの完全なガイドについてはPluginを、ネイティブのケイパビリティモデルと現在の外部互換性に関するガイダンスについてはケイパビリティモデルを参照してください。

このファイルの役割

openclaw.plugin.json は、OpenClaw がplugin コードを読み込む前に読み取るメタデータです。ここに含まれるすべての情報は、plugin ランタイムを起動せずに確認できるほど軽量である必要があります。

用途:

• plugin の識別、設定の検証、設定 UI のヒント
• 認証、オンボーディング、セットアップのメタデータ（エイリアス、自動有効化、プロバイダー環境変数、認証方式の選択肢）
• コントロールプレーン画面向けの有効化ヒント
• モデルファミリー所有権の短縮表記
• 静的なケイパビリティ所有権のスナップショット（contracts）
• ダッシュボードウィジェットのデータバインディングとアクション動詞
• plugin が有効な間に存在すべき静的 MCP サーバー
• 共有 openclaw qa ホストが確認できる QA ランナーのメタデータ
• カタログおよび検証画面にマージされる、チャンネル固有の設定メタデータ

用途に含まれないもの: ネイティブランタイムフックの登録、plugin コードのエントリポイントの宣言、npm インストールメタデータ。これらは plugin コードおよび package.json に含めます。

最小構成の例

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

詳細な例

{  "id": "openrouter",  "name": "OpenRouter",  "description": "OpenRouter プロバイダー 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"  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "OpenRouter API キー",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter API キー",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API キー",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

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

MCP サーバーリファレンス

mcpServers を使用すると、ネイティブ Plugin は MCP App を含む MCP サーバーを同梱でき、運用者がその静的なプロセス定義を openclaw.json に重複して記述する必要がなくなります。

{  "mcpServers": {    "example": {      "transport": "stdio",      "command": "node",      "args": ["./mcp-server.js"]    }  }}

OpenClaw は、所有元の Plugin が有効な間のみ、これらのサーバーを含めます。相対 command、args、cwd、および workingDirectory パスは、Plugin のルートを基準に解決されます。ユーザー設定が引き続き優先されます。mcp.servers.<name> で Plugin のデフォルトを置き換えるか、enabled: false を設定して除外できます。MCP App のレンダリングとサーバーツールの呼び出しには、引き続き通常の MCP Apps 設定と有効なツールポリシーが必要です。サーバーを宣言しても、どちらの境界も回避されません。

ダッシュボードリファレンス

dashboard を使用すると、有効な Plugin は、コアに Plugin ポリシーを追加することなく、権限を付与されたダッシュボードウィジェットへ既存の Gateway RPC を公開できます。データバインディングには、同じ Plugin が operator.read で登録するメソッドを指定する必要があります。アクション動詞には、同じ Plugin が operator.write で登録するメソッドを指定する必要があります。不一致がある場合、登録時に Plugin が拒否されます。

{  "dashboard": {    "dataBindings": [      {        "id": "items.list",        "method": "example.items.list",        "description": "サンプル項目を一覧表示します。"      }    ],    "actionVerbs": [      {        "id": "refresh",        "method": "example.items.refresh",        "description": "サンプル項目を更新します。",        "paramShape": {          "type": "object",          "additionalProperties": false,          "properties": {            "force": { "type": "boolean" }          }        }      }    ]  }}

マニフェスト ID は Plugin ローカルです。ウィジェットの権限付与では、example.items.list や example.refresh などの <plugin-id>.<id> を使用します。永続化された権限付与の名前空間を曖昧さなく保つため、OpenClaw は Plugin ID セグメント内の % と . を、それぞれ %25 と %2E としてエスケープします。通常の Plugin ID は自然な形式のままです。paramShape は任意の JSON Schema であり、OpenClaw が Plugin RPC を呼び出す前にアクションパラメータオブジェクトへ適用されます。

カタログリファレンス

catalog は、Plugin ブラウザーに任意の表示ヒントを提供します。ホストはこれらのヒントを無視できます。これらによって Plugin がインストールまたは有効化されることはなく、ランタイム動作や信頼レベルも変更されません。

{  "catalog": {    "featured": true,    "order": 10  }}

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

生成プロバイダーメタデータフィールドは、対応する 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 エントリでは、上記の共通 configSignals/authSignals フィールドに加えて、optional（Plugin の有効化にそのツールが必須ではないことを示す）および replaySafe（モデルのターンが未完了に終わった後でも、ツールの実行を安全に繰り返せることを示す）も指定できます。

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

providerAuthChoices リファレンス

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

appGuidedDiscovery が true の場合、対応するプロバイダー認証方式は appGuidedSetup.detect および appGuidedSetup.prepare を公開する必要があります。検出は 読み取り専用でなければなりません。ログイン、モデルのプル、ダウンロード、設定の書き込みは行いません。準備処理では、 選択された正確なモデルを再確認して設定案を返します。OpenClaw はその 設定案を分離環境でライブテストし、成功した場合にのみコミットします。

commandAliases リファレンス

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

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

activation リファレンス

Plugin を有効化または読み込みプランに含める必要があるコントロールプレーンイベントを、低コストで宣言できる場合は、activation を使用します。

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

所有権をすでに表している最も限定的なメタデータを優先してください。providers、channels、commandAliases、セットアップディスクリプター、または contracts で関係を表現できる場合は、それらのフィールドを使用します。これらの所有権フィールドでは表現できない追加のプランナーヒントには、activation を使用します。claude-cli、my-cli、google-gemini-cli などの CLI ランタイムエイリアスには、トップレベルの cliBackends を使用します。activation.onAgentHarnesses は、所有権フィールドがまだ存在しない組み込みエージェントハーネス ID 専用です。

すべての Plugin で activation.onStartup を意図的に設定する必要があります。Gateway の起動中に Plugin を実行する必要がある場合にのみ、true に設定します。Plugin が起動時には何もせず、より限定的なトリガーによってのみ読み込まれるべき場合は、false に設定します。onStartup を省略しても、Plugin が起動時に暗黙的に読み込まれることはなくなりました。起動、チャネル、設定、エージェントハーネス、メモリ、またはその他のより限定的な有効化トリガーには、明示的な有効化メタデータを使用してください。

{  "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[] を使用します。
• チャンネルによってトリガーされるセットアップ／チャンネル計画では、明示的なチャンネル有効化メタデータがない場合、従来の channels[] の所有権にフォールバックします。
• 起動時の Plugin 計画では、バンドルされたブラウザー Plugin の browser ブロックなど、チャンネル以外のルート設定サーフェスに activation.onConfigPaths を使用します。
• プロバイダーによってトリガーされるセットアップ／ランタイム計画では、明示的なプロバイダー有効化メタデータがない場合、従来の providers[] およびトップレベルの cliBackends[] の所有権にフォールバックします。

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

qaRunners リファレンス

Plugin が共有 openclaw qa ルート配下に 1 つ以上のトランスポートランナーを提供する場合は、qaRunners を使用します。 このメタデータは低コストかつ静的に保ってください。実際の CLI 登録は引き続き Plugin ランタイムが担当し、一致する qaRunnerCliRegistrations をエクスポートする軽量な runtime-api.ts サーフェスを介して行います。オプションの adapterFactory は、登録済みコマンドのランナーを変更せずに、共有 QA シナリオへ トランスポートを公開します。

{  "qaRunners": [    {      "commandName": "matrix",      "description": "使い捨てのホームサーバーに対して、Docker ベースの Matrix ライブ QA レーンを実行する"    }  ]}

adapterFactory ID は commandName と一致する必要があります。マニフェストに存在しない コマンドの登録をエクスポートしないでください。

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 のローカル認証情報"          }        ]      }    ],    "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 を含めます。セットアップおよびステータス用の環境メタデータはそこに配置してください。

請求または組織レベルの認証情報によって、推論用認証情報にすることなく resolveUsageAuth を有効化する必要がある場合は、providerUsageAuthEnvVars を使用します。これらの名前は、ワークスペースの dotenv ブロック、ACP 子プロセスからの除去、サンドボックスのシークレットフィルタリング、および広範なシークレット消去の対象に加わります。プロバイダーランタイムは引き続き resolveUsageAuth 内で値を読み取り、分類します。

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

これらの記述子だけでセットアップサーフェスに十分な場合にのみ、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 は、設定フィールド名から小さなレンダリングヒントへのマップです。ネストされた設定フィールドではキーにドットを使用できますが、パスセグメントを __proto__、constructor、または prototype にすることはできません。セットアップではこれらの名前が拒否されます。

{  "uiHints": {    "apiKey": {      "label": "API キー",      "help": "OpenRouter リクエストに使用",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

各フィールドヒントには次を含められます。

contracts リファレンス

contracts は、Plugin ランタイムをインポートせずに OpenClaw が読み取れる静的なケイパビリティ所有権メタデータにのみ使用してください。

{  "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"],    "musicGenerationProviders": ["stability-audio"],    "documentExtractors": ["example-docs"],    "webContentExtractors": ["firecrawl"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "workerProviders": ["example-worker"],    "usageProviders": ["acme-ai"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

各リストは省略可能です。

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

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

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

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

resolveUsageAuth と fetchUsageSnapshot の両方を実装するプロバイダー Plugin は、自動検出される各プロバイダー ID を contracts.usageProviders で宣言する必要があります。使用量検出はランタイムコードを読み込む前にこのコントラクトを読み取り、宣言された所有者のみを読み込んだ後に両方のフックを検証します。

汎用埋め込みプロバイダーは、api.registerEmbeddingProvider(...) で登録する各アダプターについて contracts.embeddingProviders を宣言する必要があります。メモリ検索で使用されるプロバイダーを含む、再利用可能なベクトル生成には汎用コントラクトを使用してください。contracts.memoryEmbeddingProviders は非推奨のメモリ固有互換機能であり、既存のプロバイダーが汎用埋め込みプロバイダー接続点へ移行する間だけ維持されます。

ワーカープロバイダーは、各 api.registerWorkerProvider(...) ID を contracts.workerProviders で宣言する必要があります。コアは provision を呼び出す前に永続的な意図を保存します。プロバイダーは外部割り当て前に設定を検証し、同じ操作 ID による呼び出しが繰り返された場合は、同じリースを引き継ぐ必要があります。また、コアは検証済みの設定スナップショットを永続化し、名前付きプロファイルが変更または削除された後も含め、leaseId とともに inspect({ leaseId, profile }) および destroy({ leaseId, profile }) に渡します。破棄は冪等であり、検査ではクローズドな active / destroyed / unknown ステータスユニオンを返します。SSH 秘密鍵の内容は SecretRef を介してのみ参照されます。プロビジョニングされた SSH エンドポイントには、信頼済みプロビジョニング出力から得た公開 hostKey も、ホスト名やコメントを付けずに正確に algorithm base64 として含める必要があります。これにより、コアは接続前にホストをピン留めできます。動的な ID 参照を発行するプロバイダーは、権威ある resolveSshIdentity({ leaseId, profile, keyRef }) を実装できます。実装しないプロバイダーでは、コアの汎用シークレットリゾルバーが使用されます。権威ある unknown はアクティブなローカルレコードを孤立状態にし、破棄リクエストの永続化後は解体を確認します。

contracts.gatewayMethodDispatch は現在 "authenticated-request" を受け入れます。これは、意図的にプロセス内で Gateway コントロールプレーンメソッドをディスパッチするネイティブ Plugin HTTP ルート向けの API 衛生ゲートであり、悪意のあるネイティブ Plugin に対するサンドボックスではありません。Gateway HTTP 認証をすでに必要とする、厳密にレビューされたバンドル済みまたはオペレーター向けサーフェスにのみ使用してください。権限が付与されたルートは、Gateway のルートワーク受付が閉じている間でも、そのルートが auth: "gateway" とルート固有の gatewayRuntimeScopeSurface: "trusted-operator" も宣言している場合に限り到達可能なままです。同じ Plugin の通常の兄弟ルートは、引き続き受付境界の内側に留まります。これにより、Plugin 全体に受付バイパスを付与することなく、一時停止状態の確認と再開を利用可能なまま維持できます。解析とレスポンス整形はディスパッチの外側で限定的に行ってください。実質的な処理や変更を伴う処理は、受付とスコープの適用を担う Gateway メソッドディスパッチを経由する必要があります。

configContracts リファレンス

Plugin ランタイムをインポートせずに汎用コアヘルパーが必要とする、マニフェスト所有の設定動作（危険なフラグの検出、SecretRef の移行先、レガシー設定パスの絞り込み）には configContracts を使用します。

{  "configContracts": {    "compatibilityMigrationPaths": ["legacyProvider"],    "compatibilityRuntimePaths": ["legacyProvider.webhook"],    "dangerousFlags": [      {        "path": "accounts.*.allowUnverifiedSenders",        "equals": true      }    ],    "secretInputs": {      "bundledDefaultEnabled": false,      "paths": [        {          "path": "routes.*.secret",          "expected": "string",          "ownerKind": "route"        }      ]    }  }}

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

secretInputs は以下をサポートします。

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"],      "documentModels": {        "pdf": {          "textExtraction": "example-doc-text-latest",          "image": "example-doc-vision-latest"        }      }    }  }}

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

channelConfigs リファレンス

チャンネル Plugin がランタイムのロード前に低コストの設定メタデータを必要とする場合は、channelConfigs を使用します。セットアップエントリが利用できない場合、または setup.requiresRuntime: false がセットアップランタイムは不要であると宣言している場合、読み取り専用のチャンネルセットアップ／状態検出では、設定済みの外部チャンネルに対してこのメタデータを直接使用できます。

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

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

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

channels[] を宣言する非バンドル Plugin は、一致する channelConfigs エントリも宣言する必要があります。これらがなくても OpenClaw は Plugin をロードできますが、コールドパスの設定スキーマ、セットアップ、および Control UI サーフェスは、Plugin ランタイムが実行されるまで、チャンネル所有オプションの形状や表示専用 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"]    }  }}

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

別のチャンネル Plugin の置き換え

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

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

channels.chat が設定されている場合、OpenClaw はチャンネル ID と優先される Plugin ID の両方を考慮します。優先度の低い Plugin が、バンドルされているかデフォルトで有効であるという理由だけで選択されていた場合、OpenClaw は有効なランタイム設定でその Plugin を無効にし、1 つの Plugin がチャンネルとそのツールを所有するようにします。明示的なユーザー選択は引き続き優先されます。ユーザーが両方の Plugin を明示的に有効にした場合（plugins.allow または実質的な plugins.entries 設定を使用）、OpenClaw は要求された Plugin セットを暗黙に変更する代わりに、その選択を維持し、チャンネルまたはツールの重複に関する診断を報告します。

preferOver は、実際に同じチャンネルを提供できる Plugin ID のみに限定してください。これは汎用的な優先度フィールドではなく、ユーザー設定キーの名前を変更するものでもありません。

modelSupport リファレンス

Plugin ランタイムを読み込む前に、OpenClaw が gpt-5.6-sol や 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 リファレンス

Plugin ランタイムを読み込む前に、OpenClaw がプロバイダーモデルのメタデータを認識する必要がある場合は、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／ベース URL オーバーライドを適用できます。エイリアスは、フィルタリングされていないカタログ一覧を展開しません。広範な一覧では、所有元の正規プロバイダー行のみが出力されます。

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

プロバイダーのフィールド：

モデルのフィールド：

抑制フィールド：

ランタイム専用データを modelCatalog に含めないでください。マニフェストの行が十分に完全で、プロバイダーで絞り込んだリストおよびピッカーの画面でレジストリやランタイムの検出を省略できる場合にのみ、static を使用します。マニフェストの行が一覧表示可能なシードまたは補足として役立つものの、後から更新やキャッシュによって行を追加できる場合は、refreshable を使用します。更新可能な行だけでは信頼できる情報源になりません。リストを把握するために OpenClaw がプロバイダーのランタイムを読み込む必要がある場合は、runtime を使用します。

modelIdNormalization リファレンス

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

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

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

providerEndpoints リファレンス

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

正式に外部化されたプロバイダープラグインはコアの配布物から除外されるため、 インストールされるまでそのマニフェストは参照できません。プラグインがなくても エンドポイント分類が機能し続けるように、その providerEndpoints も scripts/lib/official-external-provider-catalog.json にミラーリングする必要があります。このミラーリングは コントラクトテストによって強制されます。

エンドポイントのフィールド:

providerRequest リファレンス

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

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

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

secretProviderIntegrations リファレンス

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

{  "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 は現在のプラグインマニフェストのメタデータを読み込み、所有元プラグインがインストール済みで有効であることを確認し、マニフェストから exec コマンドを実体化して、そのプロバイダーを解決します。プラグインを無効化または削除すると、有効な SecretRef に対するプロバイダーが取り消されます。スタンドアロンの exec 設定を使用するオペレーターは、手動の command/args プロバイダーを引き続き直接記述できます。

現在サポートされているのは source: "exec" プリセットのみです。command は ${node} である必要があり、args[0] はプラグインルートを基準とする ./ リゾルバースクリプトである必要があります。OpenClaw は起動時または再読み込み時に、現在の Node 実行ファイルとプラグイン内スクリプトの絶対パスへ実体化します。--require、--import、--loader、--env-file、--eval、--print などの Node オプションは、マニフェストプリセットのコントラクトには含まれません。Node 以外のコマンドが必要なオペレーターは、スタンドアロンの手動 exec プロバイダーを直接設定できます。

OpenClaw は、マニフェストプリセットの trustedDirs をプラグインルートから導出し、${node} プリセットの場合は現在の Node 実行ファイルのディレクトリからも導出します。マニフェストに記述された trustedDirs は無視されます。timeoutMs、noOutputTimeoutMs、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 プロバイダーインデックス

OpenClaw プロバイダーインデックスは、プラグインがまだインストールされていない可能性があるプロバイダー向けの、OpenClaw が所有するプレビューメタデータです。これはプラグインマニフェストの一部ではありません。インストール済みプラグインについては、引き続きプラグインマニフェストが信頼できる情報源です。プロバイダーインデックスは、プロバイダープラグインがインストールされていない場合に、将来のインストール可能プロバイダー画面やインストール前のモデルピッカー画面が利用する内部フォールバックコントラクトです。

カタログの優先順位:

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

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

Provider Index エントリには、Plugin がコアから移動済み、またはまだインストールされていないプロバイダー向けに、インストール可能な Plugin のメタデータを含めることもできます。このメタデータはチャンネルカタログのパターンを踏襲します。パッケージ名、npm インストール仕様、想定される整合性、簡易な認証選択肢ラベルがあれば、インストール可能なセットアップオプションを表示するには十分です。Plugin がインストールされると、そのマニフェストが優先され、そのプロバイダーの Provider Index エントリは無視されます。

openclaw doctor --fix は、従来のトップレベルマニフェスト機能キーのうち、小規模で閉じた一式を contracts.* に移行します。対象は speechProviders、mediaUnderstandingProviders、imageGenerationProviders、tools です。これら（およびその他の機能リスト）は、トップレベルのマニフェストフィールドとしては読み込まれなくなりました。通常のマニフェスト読み込みでは、contracts 配下にあるものだけが認識されます。

マニフェストと 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 フィールドを使用する必要があります。

主な例：

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

openclaw.channel.cliAddOptions には、--initial-sync-limit <n> のような Commander の長形式オプション構文を使用してください。Plugin セットアップアダプターが受け取る前に、負でない整数として解析するには valueType: "int" を、カンマ、セミコロン、または改行で区切られた入力を文字列に分割するには valueType: "list" を設定します。解析済みの Commander 値を変更せずに渡す場合は、valueType を省略します。

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

openclaw.install.requiredPlatformPackages は、任意のプラットフォーム固有エイリアスを通じて必須のネイティブバイナリを公開する npm パッケージ向けです。サポートするすべてのプラットフォームエイリアスについて、修飾なしの npm パッケージ名を記載します。npm のインストール中、OpenClaw は lockfile の制約が現在のホストと一致する宣言済みエイリアスのみを検証します。npm が成功を報告してもそのエイリアスが欠落している場合、OpenClaw は新しいキャッシュで 1 回再試行し、それでもエイリアスが欠落していればインストールをロールバックします。

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

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

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

openclaw.install.allowInvalidConfigRecovery は意図的に限定されています。任意の壊れた設定をインストール可能にするものではありません。現在は、バンドル済みプラグインのパスが見つからない場合や、同じバンドル済みプラグインの古い channels.<id> エントリがある場合など、バンドル済みプラグインのアップグレードに関する特定の古い状態からインストールフローを復旧できるようにするだけです。無関係な設定エラーは引き続きインストールをブロックし、運用担当者を openclaw doctor --fix に誘導します。

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

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

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

openclaw.channel.configuredState は、低コストな設定済みチェックをサポートします。環境変数で十分な場合は、宣言的な環境メタデータを優先してください。

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "env": {          "allOf": ["TELEGRAM_BOT_TOKEN"]        }      }    }  }}

列挙されたすべての変数が必須の場合は env.allOf を使用し、空でない変数がいずれか 1 つあれば十分な場合は env.anyOf を使用します。小規模な非ランタイムチェックで環境メタデータ以上のものが必要な場合は、persistedAuthState の例のように specifier と exportName を使用します。env が存在する場合、OpenClaw はそのモジュールを読み込まずにこれを使用します。チェックに完全な設定解決または実際のチャンネルランタイムが必要な場合は、そのロジックをプラグインの config.hasConfiguredState フックに残してください。

検出の優先順位（重複するプラグイン ID）

OpenClaw は 3 つのルートからプラグインを検出し、次の順序で確認します。OpenClaw に同梱されるバンドル済みプラグイン、グローバルインストールルート（~/.openclaw/extensions）、現在のワークスペースルート（<workspace>/.openclaw/extensions）に加え、明示的な plugins.load.paths エントリです。

2 つの検出結果が同じ id を共有する場合、最も優先順位の高いマニフェストだけが保持されます。優先順位の低い重複は、並べて読み込まれるのではなく破棄されます。優先順位は高い順に次のとおりです。

1. 設定で選択済み — plugins.entries.<id> で明示的に固定されたパス
2. 追跡対象のインストール記録と一致するグローバルインストール — openclaw plugin install/openclaw plugin update を介してインストールされ、その ID がバンドル済みプラグインにも属している場合でも、同じ ID に対して OpenClaw のインストール追跡が認識しているプラグイン
3. バンドル済み — OpenClaw に同梱されるプラグイン
4. ワークスペース — 現在のワークスペースを基準に検出されたプラグイン
5. その他の検出候補

影響は次のとおりです。

• ワークスペースまたはグローバルルートに未追跡の状態で置かれた、バンドル済みプラグインのフォークまたは古いコピーが、バンドル済みビルドを隠すことはありません。
• バンドル済みプラグインを上書きするには、その ID に対して openclaw plugin install を実行して、追跡対象のグローバルインストールがバンドル済みコピーより高い優先順位になるようにするか、plugins.entries.<id> で特定のパスを固定し、設定で選択済みの優先順位によって勝つようにします。
• 重複の破棄はログに記録されるため、Doctor と起動診断で破棄されたコピーを示せます。
• 設定で選択された重複の上書きは、診断では明示的な上書きとして表現されますが、古いフォークや意図しない隠蔽を可視化したままにするため、引き続き警告されます。

JSON Schema の要件

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

スキーマ拡張の例:

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

検証の動作

• 不明な channels.* キーは、チャンネル ID がプラグインマニフェストで宣言されている場合を除き、エラーです。同じ ID が plugins.allow、plugins.entries、または plugins.installs（参照されているものの、現在は検出できないプラグイン）にも存在する場合、OpenClaw はこれを代わりに警告へ格下げします。
• 不明なプラグイン ID を参照する plugins.entries.<id>、plugins.allow、および plugins.deny は、エラーではなく警告（「古い設定エントリを無視しました」）になります。そのため、アップグレードや削除済みまたは名前変更済みのプラグインによって Gateway の起動がブロックされることはありません。
• 不明なプラグイン ID を参照する plugins.slots.memory はエラーです。ただし、既知の公式外部プラグイン memory-lancedb の場合は、代わりに警告になります。
• プラグインがインストールされていても、マニフェストまたはスキーマが壊れているか欠落している場合、検証は失敗し、Doctor がプラグインエラーを報告します。
• プラグイン設定が存在していてもプラグインが無効の場合、設定は保持され、Doctor とログに警告が表示されます。

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

注記

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

関連項目