​

Plugin manifest (openclaw.plugin.json)

• Codex bundle: .codex-plugin/plugin.json
• Claude bundle: .claude-plugin/plugin.json or the default Claude component layout without a manifest
• Cursor bundle: .cursor-plugin/plugin.json

​

What this file does

• plugin identity
• config validation
• auth and onboarding metadata that should be available without booting plugin runtime
• static capability ownership snapshots used for bundled compat wiring and contract coverage
• config UI hints

• registering runtime behavior
• declaring code entrypoints
• npm install metadata

​

Minimal example

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

​

Rich example

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "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"
      }
    }
  }
}

​

Top-level field reference

​

providerAuthChoices reference

​

uiHints reference

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

​

contracts reference

{
  "contracts": {
    "speechProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

​

Manifest versus package.json

• if OpenClaw must know it before loading plugin code, put it in openclaw.plugin.json
• if it is about packaging, entry files, or npm install behavior, put it in package.json

​

JSON Schema requirements

• Every plugin must ship a JSON Schema, even if it accepts no config.
• An empty schema is acceptable (for example, { "type": "object", "additionalProperties": false }).
• Schemas are validated at config read/write time, not at runtime.

​

Validation behavior

• Unknown channels.* keys are errors, unless the channel id is declared by a plugin manifest.
• plugins.entries.<id>, plugins.allow, plugins.deny, and plugins.slots.* must reference discoverable plugin ids. Unknown ids are errors.
• If a plugin is installed but has a broken or missing manifest or schema, validation fails and Doctor reports the plugin error.
• If plugin config exists but the plugin is disabled, the config is kept and a warning is surfaced in Doctor + logs.

​

Notes

• The manifest is required for native OpenClaw plugins, including local filesystem loads.
• Runtime still loads the plugin module separately; the manifest is only for discovery + validation.
• Only documented manifest fields are read by the manifest loader. Avoid adding custom top-level keys here.
• providerAuthEnvVars is the cheap metadata path for auth probes, env-marker validation, and similar provider-auth surfaces that should not boot plugin runtime just to inspect env names.
• providerAuthChoices is the cheap metadata path for auth-choice pickers, --auth-choice resolution, preferred-provider mapping, and simple onboarding CLI flag registration before provider runtime loads. For runtime wizard metadata that requires provider code, see Provider runtime hooks.
• Exclusive plugin kinds are selected through plugins.slots.*.
  • kind: "memory" is selected by plugins.slots.memory.
  • kind: "context-engine" is selected by plugins.slots.contextEngine (default: built-in legacy).
• channels, providers, cliBackends, and skills can be omitted when a plugin does not need them.
• If your plugin depends on native modules, document the build steps and any package-manager allowlist requirements (for example, pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

Related

• Building Plugins — getting started with plugins
• Plugin Architecture — internal architecture
• SDK Overview — Plugin SDK reference