OpenClaw Plugin Manifest Explained

openclaw.plugin.json is the native plugin manifest OpenClaw reads before it loads plugin runtime code. The docs are direct: every native OpenClaw plugin must ship this file in the plugin root, and missing or invalid manifests block config validation.

30-second answer

Use the manifest for cheap, static metadata: plugin identity, config validation, UI hints, auth and onboarding metadata, activation hints, model-family ownership, capability contracts, QA runner metadata, and channel-specific config metadata. Do not use it for runtime behavior. Runtime registration belongs in the plugin entrypoint.

Why it exists

OpenClaw needs to validate config without executing untrusted or broken plugin code. The manifest lets the Gateway understand what config keys are legal, which setup surfaces exist, which provider or channel ids a plugin owns, and what activation hints apply before the runtime module is imported.

The manifest is only for native OpenClaw plugins. Compatible bundle layouts use their own manifest files, such as Codex, Claude, or Cursor bundle metadata. OpenClaw can detect those bundle layouts, but they are not validated against the native openclaw.plugin.json schema.

Schema requirements

Every native plugin must ship a JSON Schema, even if it accepts no config. An empty strict schema is acceptable. Schemas are validated at config read and write time, not delayed until runtime. Bundled plugin schemas are strict, so forks that add new config keys must update their manifest schema in the same change.

Activation and contracts

Activation metadata helps OpenClaw decide when startup, command, provider, channel, or harness planning should include the plugin. Contracts declare static capability ownership snapshots, such as tools, hooks, memory embedding providers, realtime voice providers, media understanding providers, generation providers, web fetch providers, and web search providers.

Discovery rules

The docs warn that stale local copies should not accidentally shadow bundled plugins. To override a bundled plugin with a local one, pin it through config rather than relying on workspace discovery. Duplicate drops are logged so diagnostics can point at discarded copies.

Operator checklist

For a plugin you depend on, inspect the manifest before debugging runtime. Confirm the id, config schema, setup metadata, provider or channel ownership, activation hints, and install metadata. If config validation fails, fix the manifest/schema mismatch before restarting the Gateway repeatedly.

The OpenClaw Playbook treats manifests as the contract between extension authors and operators: if OpenClaw cannot know it before loading code, it probably does not belong in the manifest; if config safety depends on it, it definitely does.

Rollout plan

Treat OpenClaw Plugin Manifest Explained as a workflow you roll out in stages, not a switch you flip once. Start with the smallest harmless proof: a status check, dry run, local-only call, private session, or read-only inspection. Confirm the documented behavior matches your installed OpenClaw version, then write the exact commands and expected output into the workspace so the next agent does not rely on memory or vibes.

For a production runbook, document decision owner, source document, acceptance check, upgrade risk, and where future agents should look before changing the behavior. Also write down what the agent may do alone, what requires approval, and what must stop immediately. That boundary is the difference between useful autonomy and a workflow that surprises the operator at the worst possible time.

Keep one rollback note beside the guide. It can be as simple as the command to disable a plugin, the channel to pause, the config key to revert, or the owner who must approve the next run. Include the proof that tells you rollback worked, and keep it visible near the production checklist for future maintainers. Agents are most useful when recovery is obvious.

After the first live run, review the transcript or logs while the details are fresh. Look for missing prerequisites, stale assumptions, broad prompts, confusing errors, and any external side effect that should have been gated. Tighten the guide, then repeat with one wider scope. The OpenClaw Playbook is built around this operating rhythm: cautious first proof, written runbook, verified automation, then gradual autonomy once the evidence is boring.