​

Plugin Manifest（openclaw.plugin.json）

• Codex bundle: .codex-plugin/plugin.json
• Claude bundle: .claude-plugin/plugin.json または、manifestを持たない デフォルトのClaude componentレイアウト
• Cursor bundle: .cursor-plugin/plugin.json

​

このファイルの役割

• plugin identity
• config validation
• plugin runtimeを起動しなくても利用できるauthおよびonboarding metadata
• plugin runtimeが読み込まれる前に解決されるべきaliasとauto-enable metadata
• plugin runtimeが読み込まれる前にpluginを自動有効化すべき shorthand model-family ownership metadata
• bundled compat wiringおよびcontract coverageに使われる静的capability ownership snapshot
• runtimeを読み込まずにcatalogおよびvalidation surfacesへマージされるべきchannel固有config metadata
• config UI hints

• runtime behaviorの登録
• code entrypointsの宣言
• npm install metadata

​

最小例

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

​

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

​

providerAuthChoicesリファレンス

​

uiHintsリファレンス

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

​

contractsリファレンス

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

​

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

​

modelSupportリファレンス

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

• 明示的な provider/model refsは、manifest metadata内の所有 providers を使います
• modelPatterns は modelPrefixes より優先されます
• 1つのnon-bundled pluginと1つのbundled pluginの両方が一致した場合、non-bundled pluginが勝ちます
• 残る曖昧さは、ユーザーまたはconfigがproviderを指定するまで無視されます

​

manifestとpackage.jsonの違い

• OpenClawがplugin codeを読み込む前に知る必要があるなら、openclaw.plugin.json に置く
• packaging、entry files、またはnpm install behaviorに関するものなら、package.json に置く

​

discoveryに影響するpackage.json fields

​

JSON Schema要件

• すべてのpluginはJSON Schemaを含めなければなりません。configを受け付けない場合でも必要です。
• 空のschemaでも構いません（例: { "type": "object", "additionalProperties": false }）。
• Schemaはruntime時ではなく、config read/write時に検証されます。

​

検証の挙動

• plugin manifestでchannel idが宣言されていない限り、不明な channels.* keysはエラーです。
• plugins.entries.<id>、plugins.allow、plugins.deny、および plugins.slots.* は discoverable なplugin idsを参照しなければなりません。不明なidsはエラーです。
• pluginがインストールされていてもmanifestまたはschemaが壊れている、あるいは欠けている場合、 validationは失敗し、Doctorがplugin errorを報告します。
• plugin configが存在してもpluginが無効なら、そのconfigは保持され、 Doctor + logsで警告が表示されます。

​

注意

• manifestは、ローカルfilesystem loadを含むネイティブOpenClaw pluginsで必須です。
• runtimeは引き続きplugin moduleを別途読み込みます。manifestは discovery + validation専用です。
• ネイティブmanifestはJSON5で解析されるため、最終値がobjectである限り、 comments、trailing commas、unquoted keysが受け付けられます。
• manifest loaderが読むのは文書化されたmanifest fieldsだけです。ここに 独自のトップレベルkeysを追加するのは避けてください。
• providerAuthEnvVars は、auth probes、env-marker validation、そのほかenv名を調べるためだけにplugin runtimeを起動したくない provider-auth surfaces向けの軽量metadata経路です。
• providerAuthChoices は、auth-choice pickers、 --auth-choice 解決、preferred-provider mapping、provider runtime読み込み前の単純なonboarding CLI flag登録向けの軽量metadata経路です。provider codeが必要なruntime wizard metadataについては、 Provider runtime hooks を参照してください。
• 排他的plugin kindsは plugins.slots.* で選択されます。
  • kind: "memory" は plugins.slots.memory で選択されます。
  • kind: "context-engine" は plugins.slots.contextEngine で選択されます（デフォルト: built-in legacy）。
• pluginが不要なら、channels、providers、cliBackends、skills は省略できます。
• pluginがnative modulesに依存する場合は、build stepsと package-manager allowlist要件（たとえば pnpm allow-build-scripts
  • pnpm rebuild <package>）を文書化してください。

​

関連

• Building Plugins — pluginのはじめに
• Plugin Architecture — 内部アーキテクチャ
• SDK Overview — Plugin SDKリファレンス