OpenClawプラグインマニフェスト作成ガイド：必須設定と検証ルール

このファイルの役割

openclaw.plugin.json は、OpenClaw がプラグインのコードを読み込む前に参照するメタデータです。

以下の用途で使用します：

プラグインの識別
設定のバリデーション
プラグインのランタイムを起動せずに利用可能にすべき認証やオンボーディングのメタデータ
ランタイムの読み込み前に解決すべきエイリアスや自動有効化のメタデータ
ランタイムの読み込み前にプラグインを自動アクティブ化するための、簡略化されたモデルファミリー所有権のメタデータ
バンドルされた互換性の配線やコントラクトのカバレッジに使用される、静的な機能所有権のスナップショット
ランタイムをロードせずにカタログやバリデーションにマージすべき、チャネル固有の設定メタデータ
設定 UI のヒント

以下の用途には使用しないでください：

ランタイム動作の登録
コードのエントリポイントの宣言
npm install のメタデータ

これらはプラグインのコード内や 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"
      }
    }
  }
}

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

フィールド	必須	型	意味
`id`	Yes	`string`	標準的なプラグイン ID。`plugins.entries.<id>` で使用される ID です。
`configSchema`	Yes	`object`	このプラグインの設定のためのインライン JSON Schema。
`enabledByDefault`	No	`true`	バンドルされたプラグインをデフォルトで有効に設定します。省略するか `true` 以外の値を設定すると、デフォルトで無効になります。
`legacyPluginIds`	No	`string[]`	この標準プラグイン ID に正規化される古い ID のリスト。
`autoEnableWhenConfiguredProviders`	No	`string[]`	認証、設定、またはモデル参照でこれらが指定された際、プラグインを自動有効化する Provider ID。
`kind`	No	`"memory"` \| `"context-engine"`	`plugins.slots.*` で使用される排他的なプラグインの種類を宣言します。
`channels`	No	`string[]`	このプラグインが所有する Channel ID。検出と設定のバリデーションに使用されます。
`providers`	No	`string[]`	このプラグインが所有する Provider ID。
`modelSupport`	No	`object`	ランタイムの前にプラグインを自動ロードするために使用される、マニフェスト所有の簡略化されたモデルファミリーメタデータ。
`cliBackends`	No	`string[]`	このプラグインが所有する CLI 推論バックエンド ID。明示的な設定参照からの起動時自動アクティブ化に使用されます。
`commandAliases`	No	`object[]`	ランタイムがロードされる前に、プラグインを認識した設定や CLI 診断を生成すべき、このプラグインが所有するコマンド名。
`providerAuthEnvVars`	No	`Record<string, string[]>`	プラグインコードをロードせずに OpenClaw が検査できる、軽量な Provider 認証環境変数のメタデータ。
`providerAuthAliases`	No	`Record<string, string>`	認証ルックアップのために別の Provider ID を再利用すべき Provider ID。例：ベースとなる Provider の API key と認証プロファイルを共有するコーディング用 Provider など。
`channelEnvVars`	No	`Record<string, string[]>`	プラグインコードをロードせずに OpenClaw が検査できる、軽量な Channel 環境変数のメタデータ。環境駆動の Channel セットアップや、汎用的な起動/設定ヘルパーが参照すべき認証サーフェスに使用します。
`providerAuthChoices`	No	`object[]`	オンボーディングのピッカー、優先 Provider の解決、およびシンプルな CLI フラグの配線に使用される軽量な認証選択肢のメタデータ。
`contracts`	No	`object`	音声、リアルタイム文字起こし、リアルタイム音声、メディア理解、画像生成、音楽生成、ビデオ生成、Web 取得、Web 検索、およびツール所有権のための静的なバンドル機能スナップショット。
`channelConfigs`	No	`Record<string, object>`	ランタイムがロードされる前に検出およびバリデーションサーフェスにマージされる、マニフェスト所有の Channel 設定メタデータ。
`skills`	No	`string[]`	プラグインルートからの相対パスで指定する、ロードする Skill ディレクトリ。
`name`	No	`string`	人間が読める形式のプラグイン名。
`description`	No	`string`	プラグインのインターフェースに表示される短い概要。
`version`	No	`string`	情報提供用のプラグインバージョン。
`uiHints`	No	`Record<string, object>`	設定フィールドの UI ラベル、プレースホルダー、および機密性のヒント。

AI Setup Assistant

providerAuthChoices リファレンス

providerAuthChoices の各エントリは、オンボーディングや認証の選択肢を定義します。OpenClaw は、Provider のランタイムがロードされる前にこの情報を読み取ります。

フィールド	必須	型	説明
`provider`	はい	`string`	この選択肢が属する Provider ID。
`method`	はい	`string`	割り当てる認証メソッド ID。
`choiceId`	はい	`string`	オンボーディングや CLI フローで使用される固定の認証選択 ID。
`choiceLabel`	いいえ	`string`	ユーザー向けラベル。省略された場合、OpenClaw は `choiceId` を使用します。
`choiceHint`	いいえ	`string`	選択画面に表示される短いヘルプテキスト。
`assistantPriority`	いいえ	`number`	値が小さいほど、アシスタント駆動の対話型選択画面で先に表示されます。
`assistantVisibility`	いいえ	`"visible"` \| `"manual-only"`	アシスタントの選択画面から隠しつつ、CLI での手動選択は許可する設定。
`deprecatedChoiceIds`	いいえ	`string[]`	この新しい選択肢にユーザーをリダイレクトさせるための、古い選択 ID のリスト。
`groupId`	いいえ	`string`	関連する選択肢をグループ化するためのオプションのグループ ID。
`groupLabel`	いいえ	`string`	そのグループのユーザー向けラベル。
`groupHint`	いいえ	`string`	グループに関する短いヘルプテキスト。
`optionKey`	いいえ	`string`	シンプルなフラグ一つの認証フローに使用する内部オプションキー。
`cliFlag`	いいえ	`string`	`--openrouter-api-key` のような CLI フラグ名。
`cliOption`	いいえ	`string`	`--openrouter-api-key <key>` のような完全な CLI オプションの形式。
`cliDescription`	いいえ	`string`	CLI のヘルプで使用される説明文。
`onboardingScopes`	いいえ	`Array<"text-inference" \| "image-generation">`	この選択肢を表示するオンボーディング画面。省略時は `["text-inference"]` になります。

commandAliases リファレンス

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

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

フィールド	必須	型	説明
`name`	はい	`string`	このプラグインに属するコマンド名。
`kind`	いいえ	`"runtime-slash"`	エイリアスをルート CLI コマンドではなく、チャットのスラッシュコマンドとしてマークします。
`cliCommand`	いいえ	`string`	CLI 操作のために提案する、関連するルート CLI コマンド（存在する場合）。

uiHints リファレンス

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

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

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

フィールド	型	説明
`label`	`string`	ユーザー向けのフィールドラベル。
`help`	`string`	短いヘルプテキスト。
`tags`	`string[]`	オプションの UI タグ。
`advanced`	`boolean`	フィールドを高度な設定としてマークします。
`sensitive`	`boolean`	フィールドをシークレットまたは機密情報としてマークします。
`placeholder`	`string`	フォーム入力用のプレースホルダーテキスト。

contracts リファレンス

contracts は、OpenClaw がプラグインのランタイムをインポートせずに読み取ることができる、静的な機能の所有権メタデータにのみ使用してください。

{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

各リストはオプションです。

フィールド	型	説明
`speechProviders`	`string[]`	このプラグインが所有する Speech Provider ID。
`realtimeTranscriptionProviders`	`string[]`	このプラグインが所有する Realtime-transcription Provider ID。
`realtimeVoiceProviders`	`string[]`	このプラグインが所有する Realtime-voice Provider ID。
`mediaUnderstandingProviders`	`string[]`	このプラグインが所有する Media-understanding Provider ID。
`imageGenerationProviders`	`string[]`	このプラグインが所有する Image-generation Provider ID。
`videoGenerationProviders`	`string[]`	このプラグインが所有する Video-generation Provider ID。
`webFetchProviders`	`string[]`	このプラグインが所有する Web-fetch Provider ID。
`webSearchProviders`	`string[]`	このプラグインが所有する Web-search Provider ID。
`tools`	`string[]`	バンドルされたコントラクトチェックのために、このプラグインが所有するエージェントツール名。

channelConfigs リファレンス

ランタイムがロードされる前に、チャネルプラグインが軽量な設定メタデータを必要とする場合は、channelConfigs を使用します。

{
  "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"]
    }
  }
}

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

フィールド	型	説明
`schema`	`object`	`channels.<id>` のための JSON Schema。宣言された各チャネル設定エントリに必須です。
`uiHints`	`Record<string, object>`	そのチャネル設定セクションの UI ラベル、プレースホルダー、機密情報のヒント（任意）。
`label`	`string`	ランタイムのメタデータが準備できていない場合に、ピッカーやインスペクト画面に表示されるチャネルラベル。
`description`	`string`	インスペクトやカタログ画面用の短いチャネル説明。
`preferOver`	`string[]`	選択画面において、このチャネルが優先されるべきレガシーまたは低優先度のプラグイン ID。

modelSupport リファレンス

プラグインのランタイムがロードされる前に、gpt-5.4 や claude-sonnet-4.6 といった短縮モデル ID から OpenClaw にプロバイダープラグインを推論させたい場合は、modelSupport を使用します。

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

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

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

フィールド詳細：

フィールド	型	説明
`modelPrefixes`	`string[]`	短縮モデル ID に対して `startsWith` でマッチングされる接頭辞。
`modelPatterns`	`string[]`	プロファイルサフィックスの削除後、短縮モデル ID に対してマッチングされる正規表現。

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

Manifest と package.json の比較

これら 2 つのファイルは、それぞれ異なる役割を担っています。

ファイル	用途
`openclaw.plugin.json`	プラグインのコードが実行される前に存在する必要がある、検出（Discovery）、設定のバリデーション、認証選択のメタデータ、および UI のヒント。
`package.json`	npm のメタデータ、依存関係のインストール、およびエントリーポイント、インストールの制限、セットアップ、またはカタログのメタデータに使用される `openclaw` ブロック。

あるメタデータをどちらに記述すべきか迷ったときは、次のルールを参考にしてください。

OpenClaw がプラグインのコードをロードする前に知っておく必要がある情報なら、openclaw.plugin.json に記述します。
パッケージング、エントリーファイル、または npm インストールの挙動に関するものなら、package.json に記述します。

検出に影響を与える package.json のフィールド

実行前のプラグインメタデータの中には、意図的に openclaw.plugin.json ではなく package.json の openclaw ブロック内に配置されているものがあります。

重要な例は以下の通りです。

フィールド	意味
`openclaw.extensions`	ネイティブプラグインのエントリーポイントを宣言します。
`openclaw.setupEntry`	オンボーディングや遅延チャネル起動時に使用される、セットアップ専用の軽量なエントリーポイントです。
`openclaw.channel`	ラベル、ドキュメントのパス、エイリアス、選択時のコピーなど、軽量なチャネルカタログのメタデータです。
`openclaw.channel.configuredState`	チャネルのフルランタイムをロードすることなく、「環境変数のみのセットアップが既に存在するか？」に回答できる軽量な設定状態チェッカーのメタデータです。
`openclaw.channel.persistedAuthState`	チャネルのフルランタイムをロードすることなく、「何らかのサインインが既に完了しているか？」に回答できる軽量な永続認証チェッカーのメタデータです。
`openclaw.install.npmSpec` / `openclaw.install.localPath`	同梱されたプラグインや外部に公開されたプラグインの、インストールおよびアップデートに関するヒントです。
`openclaw.install.defaultChoice`	複数のインストールソースが利用可能な場合に優先されるインストールパスです。
`openclaw.install.minHostVersion`	サポートされる OpenClaw ホストの最小バージョンです。`>=2026.3.22` のような semver 形式を使用します。
`openclaw.install.allowInvalidConfigRecovery`	設定が無効な場合に、同梱プラグインの再インストールによる限定的なリカバリパスを許可します。
`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`	起動時に、フルチャネルプラグインよりも先にセットアップ専用のチャネル画面をロードできるようにします。

openclaw.install.minHostVersion は、インストール時および Manifest レジストリのロード時に適用されます。無効な値は拒否され、有効であってもホストのバージョンより新しい場合は、そのプラグインのロードはスキップされます。

openclaw.install.allowInvalidConfigRecovery は、意図的に範囲を絞った機能です。これによって、壊れた設定を何でもインストール可能にするわけではありません。現在は、同梱プラグインのパスが見つからない場合や、そのプラグインの channels.<id> エントリが古い場合など、特定の古い同梱プラグインのアップグレード失敗からリカバリすることだけを目的としています。これに関係のない設定エラーは、引き続きインストールをブロックし、オペレーターに openclaw doctor --fix の実行を促します。

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

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

セットアップ、doctor、または設定状態の確認フローにおいて、フルチャネルプラグインをロードする前に、認証の有無を軽量にチェックしたい場合に使用してください。ターゲットとなるエクスポートは、永続化された状態のみを読み取る小さな関数である必要があります。フルチャネルランタイムのバレルファイルを経由させないでください。

openclaw.channel.configuredState も、環境変数などに基づいた軽量な設定済みチェックのために、同じ形式に従います。

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

チャネルが環境変数やその他のランタイム以外の小さな入力から設定状態を回答できる場合に使用します。もしチェックに完全な設定の解決や実際のチャネルランタイムが必要な場合は、そのロジックはプラグインの config.hasConfiguredState Hook に記述したままにしてください。

JSON Schema の要件

すべてのプラグインは、たとえ設定を受け取らない場合でも JSON Schema を同梱する必要があります。
空のスキーマ（例: { "type": "object", "additionalProperties": false }）でも受け入れられます。
スキーマは実行時ではなく、設定の読み取りおよび書き込み時にバリデーションされます。

バリデーションの挙動

channels.* に未知のキーがある場合はエラーになります。ただし、plugin manifest でその channel ID が宣言されている場合は例外です。
plugins.entries.<id>、plugins.allow、plugins.deny、および plugins.slots.* は、検出可能（discoverable）な plugin ID を参照しなければなりません。不明な ID はエラーとなります。
plugin がインストールされていても、manifest や schema が壊れている、あるいは見つからない場合はバリデーションに失敗し、Doctor がその plugin のエラーを報告します。
plugin の設定が存在していても、その plugin が無効（disabled）に設定されている場合、設定内容は保持されますが、Doctor およびログに警告が表示されます。

plugins.* の完全な schema については、Configuration reference を参照してください。

注意事項

ローカルファイルシステムからの読み込みを含め、native な OpenClaw plugins には manifest が必須です。
Runtime は plugin モジュールを別途読み込みます。manifest はあくまで検出とバリデーションのために使用されるものです。
native の manifest は JSON5 でパースされます。そのため、最終的な値がオブジェクトであれば、コメントや末尾のカンマ、クォートされていないキーも許容されます。
manifest loader は、ドキュメント化されている manifest フィールドのみを読み取ります。ここに独自のトップレベルキーを追加するのは避けてください。
providerAuthEnvVars は、auth の確認や環境変数のバリデーションなど、環境変数の名前を確認するためだけに plugin runtime を起動させたくない場合に適した、軽量なメタデータ用パスです。
providerAuthAliases を使用すると、別の provider の auth 環境変数、auth プロファイル、設定ベースの auth、API key のオンボーディング設定などを再利用できます。コア部分にその関係性をハードコードする必要はありません。
channelEnvVars は、シェル環境のフォールバックやセットアップ時のプロンプトなど、環境変数名を確認するためだけに plugin runtime を起動させたくない場合に適した、軽量なメタデータ用パスです。
providerAuthChoices は、auth 選択画面や --auth-choice の解決、優先 provider のマッピング、および provider runtime がロードされる前のシンプルなオンボーディング CLI flag 登録のための軽量なメタデータ用パスです。provider のコードを必要とする runtime ウィザードのメタデータについては、Provider runtime hooks を参照してください。
特定の plugin kind は plugins.slots.* を通じて選択されます。
- kind: "memory" は plugins.slots.memory で選択します。
- kind: "context-engine" は plugins.slots.contextEngine で選択します（デフォルトは組み込みの legacy）。
channels、providers、cliBackends、および skills は、plugin で必要ない場合は省略できます。
plugin が native モジュールに依存している場合は、ビルド手順やパッケージマネージャーの allowlist 要件（例：pnpm の allow-build-scripts - pnpm rebuild <package>）をドキュメントに記載してください。

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。