Plugin manifest

This page is for the native OpenClaw plugin manifest only.

For compatible bundle layouts, see Plugin bundles.

Compatible bundle formats use different manifest files:

• Codex bundle:
  text

  Copy

  .codex-plugin/plugin.json
• Claude bundle:
  text

  Copy

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

  Copy

  .cursor-plugin/plugin.json

OpenClaw auto-detects those bundle layouts too, but they are not validated against the

schema described here.

For compatible bundles, OpenClaw currently reads bundle metadata plus declared skill roots, Claude command roots, Claude bundle

defaults, Claude bundle LSP defaults, and supported hook packs when the layout matches OpenClaw runtime expectations.

Every native OpenClaw plugin must ship a

file in the plugin root. OpenClaw uses this manifest to validate configuration without executing plugin code. Missing or invalid manifests are treated as plugin errors and block config validation.

See the full plugin system guide: Plugins. For the native capability model and current external-compatibility guidance: Capability model.

What this file does

is the metadata OpenClaw reads before it loads your plugin code. Everything below must be cheap enough to inspect without booting plugin runtime.

Use it for:

• plugin identity, config validation, and config UI hints
• auth, onboarding, and setup metadata (alias, auto-enable, provider env vars, auth choices)
• activation hints for control-plane surfaces
• shorthand model-family ownership
• static capability-ownership snapshots (
  text

  Copy

  contracts
  )
• QA runner metadata the shared
  text

  Copy

  openclaw qa
  host can inspect
• channel-specific config metadata merged into catalog and validation surfaces

Do not use it for: registering runtime behavior, declaring code entrypoints, or npm install metadata. Those belong in your plugin code and

.

Minimal example

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

Rich example

json
Copy
{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider 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"],
  "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"
      }
    }
  }
}

Top-level field reference

providerAuthChoices reference

Each

entry describes one onboarding or auth choice. OpenClaw reads this before provider runtime loads. Provider setup lists use these manifest choices, descriptor-derived setup choices, and install-catalog metadata without loading provider runtime.

commandAliases reference

Use

when a plugin owns a runtime command name that users may mistakenly put in or try to run as a root CLI command. OpenClaw uses this metadata for diagnostics without importing plugin runtime code.

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

activation reference

Use

when the plugin can cheaply declare which control-plane events should include it in an activation/load plan.

This block is planner metadata, not a lifecycle API. It does not register runtime behavior, does not replace

, and does not promise that plugin code has already executed. The activation planner uses these fields to narrow candidate plugins before falling back to existing manifest ownership metadata such as , , , , , and hooks.

Prefer the narrowest metadata that already describes ownership. Use

, , , setup descriptors, or when those fields express the relationship. Use for extra planner hints that cannot be represented by those ownership fields. Use top-level for CLI runtime aliases such as , , or ; is only for embedded agent harness ids that do not already have an ownership field.

This block is metadata only. It does not register runtime behavior, and it does not replace

, , or other runtime/plugin entrypoints. Current consumers use it as a narrowing hint before broader plugin loading, so missing activation metadata usually only costs performance; it should not change correctness while legacy manifest ownership fallbacks still exist.

Every plugin should set

intentionally as OpenClaw moves away from implicit startup imports. Set it to only when the plugin must run during Gateway startup. Set it to when the plugin is inert at startup and should load only from narrower triggers. Omitting keeps the deprecated legacy implicit startup sidecar fallback for plugins with no static capability metadata; future versions may stop startup-loading those plugins unless they declare . Plugin status and compatibility reports warn with when a plugin still relies on that fallback.

For migration testing, set

to disable only that deprecated fallback. This opt-in mode does not block explicit plugins or plugins loaded by channel, config, agent-harness, memory, or other narrower activation triggers.

json
Copy
{
  "activation": {
    "onStartup": false,
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onConfigPaths": ["browser"],
    "onCapabilities": ["provider", "tool"]
  }
}

Current live consumers:

• Gateway startup planning uses
  text

  Copy

  activation.onStartup
  for explicit startup import and opt-out of deprecated implicit sidecar startup fallback
• command-triggered CLI planning falls back to legacy
  text

  Copy

  commandAliases[].cliCommand
  or
  text

  Copy

  commandAliases[].name
• agent-runtime startup planning uses
  text

  Copy

  activation.onAgentHarnesses
  for embedded harnesses and top-level
  text

  Copy

  cliBackends[]
  for CLI runtime aliases
• channel-triggered setup/channel planning falls back to legacy
  text

  Copy

  channels[]
  ownership when explicit channel activation metadata is missing
• startup plugin planning uses
  text

  Copy

  activation.onConfigPaths
  for non-channel root config surfaces such as the bundled browser plugin's
  text

  Copy

  browser
  block
• provider-triggered setup/runtime planning falls back to legacy
  text

  Copy

  providers[]
  and top-level
  text

  Copy

  cliBackends[]
  ownership when explicit provider activation metadata is missing

Planner diagnostics can distinguish explicit activation hints from manifest ownership fallback. For example,

means matched, while means the planner used ownership instead. These reason labels are for host diagnostics and tests; plugin authors should keep declaring the metadata that best describes ownership.

qaRunners reference

Use

when a plugin contributes one or more transport runners beneath the shared root. Keep this metadata cheap and static; the plugin runtime still owns actual CLI registration through a lightweight surface that exports .

json
Copy
{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
    }
  ]
}

setup reference

Use

when setup and onboarding surfaces need cheap plugin-owned metadata before runtime loads.

json
Copy
{
  "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 local credentials"
          }
        ]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}

Top-level

stays valid and continues to describe CLI inference backends. is the setup-specific descriptor surface for control-plane/setup flows that should stay metadata-only.

When present,

and are the preferred descriptor-first lookup surface for setup discovery. If the descriptor only narrows the candidate plugin and setup still needs richer setup-time runtime hooks, set and keep in place as the fallback execution path.

OpenClaw also includes

in generic provider auth and env-var lookups. remains supported through a compatibility adapter during the deprecation window, but non-bundled plugins that still use it receive a manifest diagnostic. New plugins should put setup/status env metadata on .

OpenClaw can also derive simple setup choices from

when no setup entry is available, or when declares setup runtime unnecessary. Explicit entries stay preferred for custom labels, CLI flags, onboarding scope, and assistant metadata.

Set

only when those descriptors are sufficient for the setup surface. OpenClaw treats explicit as a descriptor-only contract and will not execute or for setup lookup. If a descriptor-only plugin still ships one of those setup runtime entries, OpenClaw reports an additive diagnostic and continues ignoring it. Omitted keeps legacy fallback behavior so existing plugins that added descriptors without the flag do not break.

Because setup lookup can execute plugin-owned

code, normalized and values must stay unique across discovered plugins. Ambiguous ownership fails closed instead of picking a winner from discovery order.

When setup runtime does execute, setup registry diagnostics report descriptor drift if

registers a provider or CLI backend that the manifest descriptors do not declare, or if a descriptor has no matching runtime registration. These diagnostics are additive and do not reject legacy plugins.

setup.providers reference

is for provider-owned local credential markers that can be verified without loading runtime code. These checks must stay cheap and local: no network calls, no keychain or secret-manager reads, no shell commands, and no provider API probes.

Supported evidence entries:

setup fields

uiHints reference

is a map from config field names to small rendering hints.

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

Each field hint can include:

contracts reference

Use

only for static capability ownership metadata that OpenClaw can read without importing the plugin runtime.

json
Copy
{
  "contracts": {
    "agentToolResultMiddleware": ["pi", "codex"],
    "externalAuthProviders": ["acme-ai"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "memoryEmbeddingProviders": ["local"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "migrationProviders": ["hermes"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

Each list is optional:

is retained for bundled Codex app-server-only extension factories. Bundled tool-result transforms should declare and register with instead. External plugins cannot register tool-result middleware because the seam can rewrite high-trust tool output before the model sees it.

Provider plugins that implement

should declare . Plugins without the declaration still run through a deprecated compatibility fallback, but that fallback is slower and will be removed after the migration window.

Bundled memory embedding providers should declare

for every adapter id they expose, including built-in adapters such as . Standalone CLI paths use this manifest contract to load only the owning plugin before the full Gateway runtime has registered providers.

mediaUnderstandingProviderMetadata reference

Use

when a media-understanding provider has default models, auto-auth fallback priority, or native document support that generic core helpers need before runtime loads. Keys must also be declared in .

json
Copy
{
  "contracts": {
    "mediaUnderstandingProviders": ["example"]
  },
  "mediaUnderstandingProviderMetadata": {
    "example": {
      "capabilities": ["image", "audio"],
      "defaultModels": {
        "image": "example-vision-latest",
        "audio": "example-transcribe-latest"
      },
      "autoPriority": {
        "image": 40
      },
      "nativeDocumentInputs": ["pdf"]
    }
  }
}

Each provider entry can include:

channelConfigs reference

Use

when a channel plugin needs cheap config metadata before runtime loads. Read-only channel setup/status discovery can use this metadata directly for configured external channels when no setup entry is available, or when declares setup runtime unnecessary.

is plugin manifest metadata, not a new top-level user config section. Users still configure channel instances under . OpenClaw reads manifest metadata to decide which plugin owns that configured channel before plugin runtime code executes.

For a channel plugin,

and describe different paths:

• text

  Copy

  configSchema
  validates
  text

  Copy

  plugins.entries.<plugin-id>.config
• text

  Copy

  channelConfigs.<channel-id>.schema
  validates
  text

  Copy

  channels.<channel-id>

Non-bundled plugins that declare

should also declare matching entries. Without them, OpenClaw can still load the plugin, but cold-path config schema, setup, and Control UI surfaces cannot know the channel-owned option shape until plugin runtime executes.

and can declare static defaults for command config checks that run before channel runtime loads. Bundled channels can also publish the same defaults through alongside their other package-owned channel catalog metadata.

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

Each channel entry can include:

Replacing another channel plugin

Use

when your plugin is the preferred owner for a channel id that another plugin can also provide. Common cases are a renamed plugin id, a standalone plugin that supersedes a bundled plugin, or a maintained fork that keeps the same channel id for config compatibility.

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

When

is configured, OpenClaw considers both the channel id and the preferred plugin id. If the lower-priority plugin was only selected because it is bundled or enabled by default, OpenClaw disables it in the effective runtime config so one plugin owns the channel and its tools. Explicit user selection still wins: if the user explicitly enables both plugins, OpenClaw preserves that choice and reports duplicate channel/tool diagnostics instead of silently changing the requested plugin set.

Keep

scoped to plugin ids that can really provide the same channel. It is not a general priority field and it does not rename user config keys.

modelSupport reference

Use

when OpenClaw should infer your provider plugin from shorthand model ids like or before plugin runtime loads.

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

OpenClaw applies this precedence:

• explicit
  text

  Copy

  provider/model
  refs use the owning
  text

  Copy

  providers
  manifest metadata
• text

  Copy

  modelPatterns
  beat
  text

  Copy

  modelPrefixes
• if one non-bundled plugin and one bundled plugin both match, the non-bundled plugin wins
• remaining ambiguity is ignored until the user or config specifies a provider

Fields:

modelCatalog reference

Use

when OpenClaw should know provider model metadata before loading plugin runtime. This is the manifest-owned source for fixed catalog rows, provider aliases, suppression rules, and discovery mode. Runtime refresh still belongs in provider runtime code, but the manifest tells core when runtime is required.

json
Copy
{
  "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"
    }
  }
}

Top-level fields:

participates in provider ownership lookup for model-catalog planning. Alias targets must be top-level providers owned by the same plugin. When a provider-filtered list uses an alias, OpenClaw can read the owning manifest and apply alias API/base URL overrides without loading provider runtime. Aliases do not expand unfiltered catalog listings; broad lists emit the owning canonical provider rows only.

replaces the old provider runtime hook. Suppression entries are honored only when the provider is owned by the plugin or declared as a key that targets an owned provider. Runtime suppression hooks are no longer called during model resolution.

Provider fields:

Model fields:

Suppression fields:

Do not put runtime-only data in

. Use only when manifest rows are complete enough for provider-filtered list and picker surfaces to skip registry/runtime discovery. Use when manifest rows are useful listable seeds or supplements but a refresh/cache can add more rows later; refreshable rows are not authoritative by themselves. Use when OpenClaw must load provider runtime to know the list.

modelIdNormalization reference

Use

for cheap provider-owned model-id cleanup that must happen before provider runtime loads. This keeps aliases such as short model names, provider-local legacy ids, and proxy prefix rules in the owning plugin manifest instead of in core model-selection tables.

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

Provider fields:

providerEndpoints reference

Use

for endpoint classification that generic request policy must know before provider runtime loads. Core still owns the meaning of each ; plugin manifests own the host and base URL metadata.

Endpoint fields:

providerRequest reference

Use

for cheap request-compatibility metadata that generic request policy needs without loading provider runtime. Keep behavior-specific payload rewriting in provider runtime hooks or shared provider-family helpers.

json
Copy
{
  "providers": ["vllm"],
  "providerRequest": {
    "providers": {
      "vllm": {
        "family": "vllm",
        "openAICompletions": {
          "supportsStreamingUsage": true
        }
      }
    }
  }
}

Provider fields:

modelPricing reference

Use

when a provider needs control-plane pricing behavior before runtime loads. The Gateway pricing cache reads this metadata without importing provider runtime code.

json
Copy
{
  "providers": ["ollama", "openrouter"],
  "modelPricing": {
    "providers": {
      "ollama": {
        "external": false
      },
      "openrouter": {
        "openRouter": {
          "passthroughProviderModel": true
        },
        "liteLLM": false
      }
    }
  }
}

Provider fields:

Source fields:

OpenClaw Provider Index

The OpenClaw Provider Index is OpenClaw-owned preview metadata for providers whose plugins may not be installed yet. It is not part of a plugin manifest. Plugin manifests remain the installed-plugin authority. The Provider Index is the internal fallback contract that future installable-provider and pre-install model picker surfaces will consume when a provider plugin is not installed.

Catalog authority order:

1. User config.
2. Installed plugin manifest
   text

   Copy

   modelCatalog
   .
3. Model catalog cache from explicit refresh.
4. OpenClaw Provider Index preview rows.

The Provider Index must not contain secrets, enabled state, runtime hooks, or live account-specific model data. Its preview catalogs use the same

provider row shape as plugin manifests, but should stay limited to stable display metadata unless runtime adapter fields such as , , pricing, or compatibility flags are intentionally kept aligned with the installed plugin manifest. Providers with live discovery should write refreshed rows through the explicit model catalog cache path instead of making normal listing or onboarding call provider APIs.

Provider Index entries may also carry installable-plugin metadata for providers whose plugin has moved out of core or is otherwise not installed yet. This metadata mirrors the channel catalog pattern: package name, npm install spec, expected integrity, and cheap auth-choice labels are enough to show an installable setup option. Once the plugin is installed, its manifest wins and the Provider Index entry is ignored for that provider.

Legacy top-level capability keys are deprecated. Use

to move , , , , , , , and under ; normal manifest loading no longer treats those top-level fields as capability ownership.

Manifest versus package.json

The two files serve different jobs:

If you are unsure where a piece of metadata belongs, use this rule:

• if OpenClaw must know it before loading plugin code, put it in
  text

  Copy

  openclaw.plugin.json
• if it is about packaging, entry files, or npm install behavior, put it in
  text

  Copy

  package.json

package.json fields that affect discovery

Some pre-runtime plugin metadata intentionally lives in

under the block instead of .

Important examples:

Manifest metadata decides which provider/channel/setup choices appear in onboarding before runtime loads.

tells onboarding how to fetch or enable that plugin when the user picks one of those choices. Do not move install hints into .

is enforced during install and manifest registry loading. Invalid values are rejected; newer-but-valid values skip the plugin on older hosts.

Exact npm version pinning already lives in

, for example . Official external catalog entries should pair exact specs with so update flows fail closed if the fetched npm artifact no longer matches the pinned release. Interactive onboarding still offers trusted registry npm specs, including bare package names and dist-tags, for compatibility. Catalog diagnostics can distinguish exact, floating, integrity-pinned, missing-integrity, package-name mismatch, and invalid default-choice sources. They also warn when is present but there is no valid npm source it can pin. When is present, install/update flows enforce it; when it is omitted, the registry resolution is recorded without an integrity pin.

Channel plugins should provide

when status, channel list, or SecretRef scans need to identify configured accounts without loading the full runtime. The setup entry should expose channel metadata plus setup-safe config, status, and secrets adapters; keep network clients, gateway listeners, and transport runtimes in the main extension entrypoint.

Runtime entrypoint fields do not override package-boundary checks for source entrypoint fields. For example,

cannot make an escaping path loadable.

is intentionally narrow. It does not make arbitrary broken configs installable. Today it only allows install flows to recover from specific stale bundled-plugin upgrade failures, such as a missing bundled plugin path or a stale entry for that same bundled plugin. Unrelated config errors still block install and send operators to .

is package metadata for a tiny checker module:

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

Use it when setup, doctor, status, or read-only presence flows need a cheap yes/no auth probe before the full channel plugin loads. Persisted auth state is not configured channel state: do not use this metadata to auto-enable plugins, repair runtime dependencies, or decide whether a channel runtime should load. The target export should be a small function that reads persisted state only; do not route it through the full channel runtime barrel.

follows the same shape for cheap env-only configured checks:

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

Use it when a channel can answer configured-state from env or other tiny non-runtime inputs. If the check needs full config resolution or the real channel runtime, keep that logic in the plugin

hook instead.

Discovery precedence (duplicate plugin ids)

OpenClaw discovers plugins from several roots (bundled, global install, workspace, explicit config-selected paths). If two discoveries share the same

, only the highest-precedence manifest is kept; lower-precedence duplicates are dropped instead of loading beside it.

Precedence, highest to lowest:

1. Config-selected — a path explicitly pinned in
   text

   Copy

   plugins.entries.<id>
2. Bundled — plugins shipped with OpenClaw
3. Global install — plugins installed into the global OpenClaw plugin root
4. Workspace — plugins discovered relative to the current workspace

Implications:

• A forked or stale copy of a bundled plugin sitting in the workspace will not shadow the bundled build.
• To actually override a bundled plugin with a local one, pin it via
  text

  Copy

  plugins.entries.<id>
  so it wins by precedence rather than relying on workspace discovery.
• Duplicate drops are logged so Doctor and startup diagnostics can point at the discarded copy.

JSON Schema requirements

• Every plugin must ship a JSON Schema, even if it accepts no config.
• An empty schema is acceptable (for example,
  text

  Copy

  { "type": "object", "additionalProperties": false }
  ).
• Schemas are validated at config read/write time, not at runtime.

Validation behavior

• Unknown
  text

  Copy

  channels.*
  keys are errors, unless the channel id is declared by a plugin manifest.
• text

  Copy

  plugins.entries.<id>
  ,
  text

  Copy

  plugins.allow
  ,
  text

  Copy

  plugins.deny
  , and
  text

  Copy

  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.

See Configuration reference for the full

schema.

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.
• Native manifests are parsed with JSON5, so comments, trailing commas, and unquoted keys are accepted as long as the final value is still an object.
• Only documented manifest fields are read by the manifest loader. Avoid custom top-level keys.
• text

  Copy

  channels
  ,
  text

  Copy

  providers
  ,
  text

  Copy

  cliBackends
  , and
  text

  Copy

  skills
  can all be omitted when a plugin does not need them.
• text

  Copy

  providerDiscoveryEntry
  must stay lightweight and should not import broad runtime code; use it for static provider catalog metadata or narrow discovery descriptors, not request-time execution.
• Exclusive plugin kinds are selected through
  text

  Copy

  plugins.slots.*
  :
  text

  Copy

  kind: "memory"
  via
  text

  Copy

  plugins.slots.memory
  ,
  text

  Copy

  kind: "context-engine"
  via
  text

  Copy

  plugins.slots.contextEngine
  (default
  text

  Copy

  legacy
  ).
• Declare exclusive plugin kind in this manifest. Runtime-entry
  text

  Copy

  OpenClawPluginDefinition.kind
  is deprecated and remains only as a compatibility fallback for older plugins.
• Env-var metadata (
  text

  Copy

  setup.providers[].envVars
  , deprecated
  text

  Copy

  providerAuthEnvVars
  , and
  text

  Copy

  channelEnvVars
  ) is declarative only. Status, audit, cron delivery validation, and other read-only surfaces still apply plugin trust and effective activation policy before treating an env var as configured.
• For runtime wizard metadata that requires provider code, see Provider runtime hooks.
• If your plugin depends on native modules, document the build steps and any package-manager allowlist requirements (for example, pnpm
  text

  Copy

  allow-build-scripts
  +
  text

  Copy

  pnpm rebuild <package>
  ).

Related