メインコンテンツへスキップ

​
プラグインマニフェスト（openclaw.plugin.json）

このページはネイティブOpenClawプラグインマニフェスト専用です。 互換バンドルのレイアウトについては、Plugin bundlesを参照してください。 互換バンドル形式では、異なるマニフェストファイルを使用します。
  • Codexバンドル: .codex-plugin/plugin.json
  • Claudeバンドル: .claude-plugin/plugin.json またはマニフェストなしのデフォルトClaudeコンポーネントレイアウト
  • Cursorバンドル: .cursor-plugin/plugin.json
OpenClawはそれらのバンドルレイアウトも自動検出しますが、ここで説明するopenclaw.plugin.jsonスキーマに対しては検証されません。 互換バンドルについて、OpenClawは現在、レイアウトがOpenClawランタイムの期待に一致する場合、バンドルメタデータに加えて、宣言されたskill root、Claude command root、Claudeバンドルのsettings.jsonデフォルト、ClaudeバンドルのLSPデフォルト、およびサポートされるhook packを読み取ります。 すべてのネイティブOpenClawプラグインは、plugin rootにopenclaw.plugin.jsonファイルを必ず含める必要があります。OpenClawはこのマニフェストを使って、プラグインコードを実行せずに設定を検証します。マニフェストがない、または無効な場合はプラグインエラーとして扱われ、設定検証がブロックされます。 完全なプラグインシステムガイドはPluginsを参照してください。 ネイティブのcapability modelと現在の外部互換性ガイダンスについては、 Capability modelを参照してください。

​
このファイルの役割

openclaw.plugin.jsonは、OpenClawがプラグインコードを読み込む前に読み取るメタデータです。 用途:
  • プラグインの識別
  • 設定検証
  • プラグインランタイムを起動しなくても利用可能であるべき認証およびオンボーディングメタデータ
  • プラグインランタイムが読み込まれる前に解決されるべきエイリアスおよび自動有効化メタデータ
  • ランタイムが読み込まれる前にプラグインを自動有効化すべき短縮モデルファミリー所有メタデータ
  • 同梱互換配線およびコントラクトカバレッジに使う静的capability ownershipスナップショット
  • ランタイムを読み込まずにカタログおよび検証サーフェスにマージされるべきチャンネル固有設定メタデータ
  • 設定UIヒント
使わないでください:
  • ランタイム動作の登録
  • コードエントリーポイントの宣言
  • npmインストールメタデータ
それらはプラグインコードおよび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-"]
  },
  "cliBackends": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["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"
      }
    }
  }
}

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

FieldRequiredType意味
idYesstring正式なplugin idです。このidはplugins.entries.<id>で使われます。
configSchemaYesobjectこのプラグイン設定用のインラインJSON Schemaです。
enabledByDefaultNotrue同梱プラグインをデフォルトで有効にすることを示します。省略するか、true以外の値を設定すると、プラグインはデフォルトで無効のままになります。
legacyPluginIdsNostring[]この正式plugin idに正規化される旧idです。
autoEnableWhenConfiguredProvidersNostring[]auth、config、またはmodel refでそれらが言及されたときにこのプラグインを自動有効化すべきprovider idです。
kindNo"memory" | "context-engine"plugins.slots.*で使われる排他的なプラグイン種別を宣言します。
channelsNostring[]このプラグインが所有するchannel idです。検出と設定検証に使われます。
providersNostring[]このプラグインが所有するprovider idです。
modelSupportNoobjectランタイム前にプラグインを自動読み込みするために使われる、マニフェスト所有の短縮モデルファミリーメタデータです。
cliBackendsNostring[]このプラグインが所有するCLI推論バックエンドidです。明示的な設定参照からの起動時自動有効化に使われます。
providerAuthEnvVarsNoRecord<string, string[]>OpenClawがプラグインコードを読み込まずに確認できる、軽量なprovider-auth環境変数メタデータです。
providerAuthAliasesNoRecord<string, string>認証参照に別のprovider idを再利用すべきprovider idです。たとえば、ベースproviderのAPIキーやauth profileを共有するコーディングproviderなどです。
channelEnvVarsNoRecord<string, string[]>OpenClawがプラグインコードを読み込まずに確認できる、軽量なchannel環境変数メタデータです。env駆動のchannelセットアップや、汎用起動/設定ヘルパーが見るべきauthサーフェスに使います。
providerAuthChoicesNoobject[]オンボーディングpicker、preferred-provider解決、および単純なCLIフラグ配線のための軽量なauth choiceメタデータです。
contractsNoobjectspeech、realtime transcription、realtime voice、media-understanding、image-generation、music-generation、video-generation、web-fetch、web search、およびtool ownership向けの静的な同梱capability snapshotです。
channelConfigsNoRecord<string, object>ランタイムが読み込まれる前に検出および検証サーフェスにマージされる、マニフェスト所有のchannel設定メタデータです。
skillsNostring[]読み込むSkillsディレクトリです。plugin rootからの相対パスです。
nameNostring人間が読むためのプラグイン名です。
descriptionNostringプラグインサーフェスに表示される短い要約です。
versionNostring参考情報としてのプラグインバージョンです。
uiHintsNoRecord<string, object>設定フィールド用のUIラベル、プレースホルダー、機密性ヒントです。

​
providerAuthChoicesリファレンス

各providerAuthChoicesエントリーは、1つのオンボーディングまたは認証選択肢を記述します。 OpenClawはこれをproviderランタイムが読み込まれる前に読み取ります。
FieldRequiredType意味
providerYesstringこのchoiceが属するprovider idです。
methodYesstringディスパッチ先のauth method idです。
choiceIdYesstringオンボーディングおよびCLIフローで使われる安定したauth-choice idです。
choiceLabelNostringユーザー向けラベルです。省略した場合、OpenClawはchoiceIdへフォールバックします。
choiceHintNostringpicker用の短い補助テキストです。
assistantPriorityNonumberassistant主導の対話型pickerで、値が小さいほど先に並びます。
assistantVisibilityNo"visible" | "manual-only"assistant pickerからは隠しつつ、手動CLI選択は引き続き許可します。
deprecatedChoiceIdsNostring[]この置き換えchoiceへユーザーをリダイレクトすべき旧choice idです。
groupIdNostring関連するchoiceをグループ化するための任意のgroup idです。
groupLabelNostringそのグループのユーザー向けラベルです。
groupHintNostringグループ用の短い補助テキストです。
optionKeyNostring単一フラグの単純なauthフロー用の内部option keyです。
cliFlagNostring--openrouter-api-keyのようなCLIフラグ名です。
cliOptionNostring--openrouter-api-key <key>のような完全なCLIオプション形状です。
cliDescriptionNostringCLIヘルプで使われる説明です。
onboardingScopesNoArray<"text-inference" | "image-generation">このchoiceを表示すべきオンボーディングサーフェスです。省略した場合、["text-inference"]がデフォルトになります。

​
uiHintsリファレンス

uiHintsは、設定フィールド名から小さなレンダリングヒントへのマップです。 
{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "Used for OpenRouter requests",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}
各フィールドヒントには次を含められます。
FieldType意味
labelstringユーザー向けフィールドラベルです。
helpstring短い補助テキストです。
tagsstring[]任意のUIタグです。
advancedbooleanフィールドを高度な項目として示します。
sensitivebooleanフィールドをシークレットまたは機密として示します。
placeholderstringフォーム入力用のプレースホルダーテキストです。

​
contractsリファレンス

contractsは、OpenClawがプラグインランタイムをimportせずに読める静的なcapability ownershipメタデータにのみ使ってください。 
{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}
各リストは任意です。
FieldType意味
speechProvidersstring[]このプラグインが所有するspeech provider idです。
realtimeTranscriptionProvidersstring[]このプラグインが所有するrealtime-transcription provider idです。
realtimeVoiceProvidersstring[]このプラグインが所有するrealtime-voice provider idです。
mediaUnderstandingProvidersstring[]このプラグインが所有するmedia-understanding provider idです。
imageGenerationProvidersstring[]このプラグインが所有するimage-generation provider idです。
videoGenerationProvidersstring[]このプラグインが所有するvideo-generation provider idです。
webFetchProvidersstring[]このプラグインが所有するweb-fetch provider idです。
webSearchProvidersstring[]このプラグインが所有するweb-search provider idです。
toolsstring[]同梱コントラクトチェック用にこのプラグインが所有するagent tool名です。

​
channelConfigsリファレンス

channelConfigsは、channel pluginがランタイム読み込み前に軽量な設定メタデータを必要とする場合に使ってください。 
{
  "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",
      "preferOver": ["matrix-legacy"]
    }
  }
}
各channelエントリーには次を含められます。
FieldType意味
schemaobjectchannels.<id>用のJSON Schemaです。宣言された各channel設定エントリーで必須です。
uiHintsRecord<string, object>そのchannel設定セクション用の任意のUIラベル/プレースホルダー/機密性ヒントです。
labelstringランタイムメタデータがまだ準備できていないときにpickerおよびinspectサーフェスへマージされるchannelラベルです。
descriptionstringinspectおよびcatalogサーフェス用の短いchannel説明です。
preferOverstring[]選択サーフェスでこのchannelが優先されるべき旧plugin idまたは低優先度plugin idです。

​
modelSupportリファレンス

modelSupportは、gpt-5.4やclaude-sonnet-4.6のような短縮model idから、プラグインランタイム読み込み前にOpenClawがprovider pluginを推測すべき場合に使います。 
{
  "modelSupport": {
    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],
    "modelPatterns": ["^computer-use-preview"]
  }
}
OpenClawは次の優先順位を適用します。
  • 明示的なprovider/model参照では、所有するprovidersマニフェストメタデータを使います
  • modelPatternsはmodelPrefixesより優先されます
  • 非同梱プラグイン1つと同梱プラグイン1つの両方が一致する場合、非同梱プラグインが優先されます
  • それ以外の曖昧さは、ユーザーまたは設定がproviderを指定するまで無視されます
フィールド:
FieldType意味
modelPrefixesstring[]短縮model idに対してstartsWithで一致させるプレフィックスです。
modelPatternsstring[]profile suffix削除後の短縮model idに対して一致させるregex sourceです。
旧来のトップレベルcapabilityキーは非推奨です。speechProviders、realtimeTranscriptionProviders、 realtimeVoiceProviders、mediaUnderstandingProviders、 imageGenerationProviders、videoGenerationProviders、 webFetchProviders、およびwebSearchProvidersをcontracts配下へ移動するにはopenclaw doctor --fixを使ってください。通常のマニフェスト読み込みでは、これらのトップレベルフィールドをcapability ownershipとしては扱いません。

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

この2つのファイルは異なる役割を持ちます。
File用途
openclaw.plugin.json検出、設定検証、auth-choiceメタデータ、およびプラグインコード実行前に存在している必要があるUIヒント
package.jsonnpmメタデータ、依存関係インストール、およびエントリーポイント、インストールゲート、セットアップ、またはcatalogメタデータに使うopenclawブロック
どこにメタデータを置くべきか迷う場合は、次のルールを使ってください。
  • OpenClawがプラグインコードを読み込む前に知っておく必要があるなら、openclaw.plugin.jsonに置きます
  • パッケージング、エントリーファイル、またはnpmインストール動作に関するものなら、package.jsonに置きます

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

一部のランタイム前プラグインメタデータは、openclaw.plugin.jsonではなく、package.jsonのopenclawブロック配下に意図的に置かれています。 重要な例:
Field意味
openclaw.extensionsネイティブプラグインのエントリーポイントを宣言します。
openclaw.setupEntryオンボーディングおよび遅延channel起動時に使われる、軽量なセットアップ専用エントリーポイントです。
openclaw.channelラベル、docs path、エイリアス、選択用コピーなどの軽量なchannel catalogメタデータです。
openclaw.channel.configuredState完全なchannelランタイムを読み込まずに「envのみのセットアップはすでに存在するか？」へ答えられる、軽量なconfigured-state checkerメタデータです。
openclaw.channel.persistedAuthState完全なchannelランタイムを読み込まずに「何かがすでにサインイン済みか？」へ答えられる、軽量なpersisted-auth checkerメタデータです。
openclaw.install.npmSpec / openclaw.install.localPath同梱および外部公開プラグイン用のインストール/更新ヒントです。
openclaw.install.defaultChoice複数のインストール元が利用可能な場合の優先インストールパスです。
openclaw.install.minHostVersion>=2026.3.22のようなsemver floorを使う、サポートされる最小OpenClaw host versionです。
openclaw.install.allowInvalidConfigRecovery設定が無効な場合に、限定的な同梱プラグイン再インストール回復パスを許可します。
openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen起動中、完全なchannelプラグインより先にセットアップ専用channelサーフェスを読み込めるようにします。
openclaw.install.minHostVersionは、インストール時とmanifest registry読み込み時に適用されます。無効な値は拒否され、新しすぎるが有効な値は古いhost上でそのプラグインをスキップします。 openclaw.install.allowInvalidConfigRecoveryは意図的に限定的です。任意の壊れた設定をインストール可能にするものではありません。現時点では、特定の古い同梱プラグインアップグレード失敗、たとえば同梱プラグインパスの欠落や、その同じ同梱プラグインに対する古いchannels.<id>エントリーのような場合から、インストールフローが回復することだけを許可します。無関係な設定エラーは引き続きインストールをブロックし、オペレーターはopenclaw doctor --fixに誘導されます。 openclaw.channel.persistedAuthStateは、小さなchecker module向けのpackageメタデータです。 
{
  "openclaw": {
    "channel": {
      "id": "whatsapp",
      "persistedAuthState": {
        "specifier": "./auth-presence",
        "exportName": "hasAnyWhatsAppAuth"
      }
    }
  }
}
これは、セットアップ、doctor、またはconfigured-stateフローが、完全なchannel pluginを読み込む前に軽量なyes/no auth probeを必要とする場合に使います。対象のexportは永続化状態のみを読む小さな関数にしてください。完全なchannel runtime barrelを経由させないでください。 openclaw.channel.configuredStateも、軽量なenv-only configured check用に同じ形を取ります。 
{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "specifier": "./configured-state",
        "exportName": "hasTelegramConfiguredState"
      }
    }
  }
}
これは、channelがenvやその他の小さな非ランタイム入力からconfigured-stateに答えられる場合に使います。その判定に完全なconfig解決または実際のchannel runtimeが必要なら、そのロジックは代わりにプラグインのconfig.hasConfiguredStateフックに置いてください。

​
JSON Schema要件

  • すべてのプラグインはJSON Schemaを必ず含める必要があります。設定を受け付けない場合でも同様です。
  • 空のスキーマでも構いません（例: { "type": "object", "additionalProperties": false }）。
  • スキーマはランタイム時ではなく、設定の読み書き時に検証されます。

​
検証の挙動

  • 不明なchannels.*キーは、channel idがプラグインマニフェストで宣言されていない限りエラーです。
  • plugins.entries.<id>、plugins.allow、plugins.deny、およびplugins.slots.*は、検出可能なplugin idを参照していなければなりません。不明なidはエラーです。
  • プラグインがインストールされていても、マニフェストまたはスキーマが壊れているか欠けている場合、検証は失敗し、Doctorはそのプラグインエラーを報告します。
  • プラグイン設定が存在していても、プラグインが無効の場合、設定は保持され、Doctorとログに警告が表示されます。
完全なplugins.*スキーマについては、Configuration referenceを参照してください。

​
注意

  • マニフェストは、ローカルファイルシステム読み込みを含むネイティブOpenClawプラグインで必須です。
  • ランタイムは引き続きプラグインモジュールを別途読み込みます。マニフェストは検出と検証専用です。
  • ネイティブマニフェストはJSON5で解析されるため、最終値がオブジェクトである限り、コメント、末尾カンマ、引用符なしキーを受け付けます。
  • マニフェストローダーが読むのは、文書化されたマニフェストフィールドのみです。ここに独自のトップレベルキーを追加するのは避けてください。
  • providerAuthEnvVarsは、auth probe、env-marker検証、および環境変数名を確認するだけのためにプラグインランタイムを起動すべきでない類似のprovider-authサーフェス向けの軽量メタデータ経路です。
  • providerAuthAliasesにより、providerバリアントは、別のproviderのauth env vars、auth profile、設定ベースauth、およびAPIキーのオンボーディング選択肢を、コアにその関係をハードコードせずに再利用できます。
  • channelEnvVarsは、shell-envフォールバック、セットアッププロンプト、および環境変数名を確認するだけのためにプラグインランタイムを起動すべきでない類似のchannelサーフェス向けの軽量メタデータ経路です。
  • providerAuthChoicesは、providerランタイム読み込み前のauth-choice picker、--auth-choice解決、preferred-providerマッピング、および単純なオンボーディングCLIフラグ登録向けの軽量メタデータ経路です。providerコードを必要とするランタイムのウィザードメタデータについては、Provider runtime hooksを参照してください。
  • 排他的なプラグイン種別はplugins.slots.*を通じて選択されます。
    • kind: "memory" はplugins.slots.memoryで選択されます。
    • kind: "context-engine" はplugins.slots.contextEngineで選択されます （デフォルト: 組み込みのlegacy）。
  • channels、providers、cliBackends、およびskillsは、プラグインでそれらが不要な場合は省略できます。
  • プラグインがネイティブモジュールに依存する場合は、ビルド手順と、必要なpackage manager allowlist要件（たとえばpnpm allow-build-scripts
    • pnpm rebuild <package>）を文書化してください。

​
関連