OpenClaw plugin manifest: validate configuration before runtime code

An OpenClaw plugin manifest is the file OpenClaw reads before it loads a native plugin’s runtime code. Put the plugin’s identity, configuration schema, and static setup facts in openclaw.plugin.json; keep hooks, side effects, and live service work in the plugin code. That split gives configuration validation a chance to fail early, before a broken extension becomes a Gateway problem.

This matters most when a plugin owns a provider, channel, command, or local tool that other people will install. A package can compile and still be a poor installation: its config may be unreadable, its command metadata may be missing, or its setup may require starting code that should not run during discovery. The manifest is the contract that lets OpenClaw inspect those facts first.

OpenClaw v2026.6.34 reinforced the boundary while flagging older plugin SDK surfaces for migration. The release notes direct maintainers away from broad imports and older environment-variable metadata toward focused SDK subpaths and manifest setup descriptors. The practical takeaway is simple: make the static part of a plugin explicit, then test the package that an operator will actually install.

Contents

• What an OpenClaw plugin manifest does
• Start with a small, strict manifest
• Put setup facts in metadata, not startup code
• Treat configuration validation as an installation gate
• Avoid two common manifest mistakes
• A practical review sequence
• FAQ
• Keep the static boundary honest

What an OpenClaw plugin manifest does

Every native plugin needs an openclaw.plugin.json file at its root. OpenClaw parses it to validate configuration without executing the plugin. A missing or invalid manifest is a plugin error, which is preferable to discovering a malformed config after runtime code has started.

The manifest is suited to facts the host can safely inspect:

Put this in openclaw.plugin.json	Keep this in plugin runtime code
Plugin id and configuration schema	Hook registrations and tool handlers
Provider, channel, or command ownership	API calls, OAuth exchanges, and background work
Setup and onboarding descriptors	Request-time model routing or message delivery
Static CLI help and activation hints	Dynamic state reads and writes
Static MCP definitions and capability metadata	Anything that needs secrets or network access to answer

That line is useful in review. If a field changes what a user can configure or what the host can identify without loading the plugin, it probably belongs in the manifest. If it performs work, it belongs in the runtime entrypoint.

For the surrounding control-plane model, see how OpenClaw works. Plugins extend a runtime that already owns sessions, policies, channels, tools, and delivery. The manifest helps that runtime reason about an extension without treating arbitrary package code as configuration metadata.

Start with a small, strict manifest

A minimal native manifest needs an id and a configSchema. The schema should describe the config your plugin genuinely accepts and reject accidental extras.

{
  "id": "example-status",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "enabled": { "type": "boolean" }
    }
  }
}

The exact schema can be richer, but the behavior should remain boring: an operator can see what the plugin expects, OpenClaw can validate it before loading the package, and a typo does not quietly become an ignored setting.

Do not use the manifest as a second package.json. Native runtime entrypoints and npm install metadata still belong in the package. Likewise, a manifest is not a place to register runtime hooks. Keeping those responsibilities apart prevents a config file from becoming a hidden execution surface.

Put setup facts in metadata, not startup code

The most valuable manifest fields describe setup that a host needs to understand before plugin runtime loads. The OpenClaw manifest reference uses the setup object for onboarding and configuration descriptors, including provider environment-variable metadata.

That separation has a concrete operational benefit. An operator can inspect configuration requirements and validate a provider’s setup without booting the provider client or making a network call. It also makes a plugin package easier to review because the required inputs are declared in one static file.

OpenClaw’s v2026.6.34 notes specifically call out providerAuthEnvVars and channelEnvVars as older surfaces to move toward current manifest setup descriptors. Do not erase a compatibility field solely because it is old. First check the versions your package supports and the migration guidance for that field. If older supported hosts need the adapter, retain it deliberately and record when it can disappear.

For a broader migration workflow, OpenClaw Plugin SDK migration covers focused imports, hook stages, compatibility windows, and package validation. The manifest work is one slice of that larger maintenance task.

Treat configuration validation as an installation gate

A manifest is most useful when it catches errors before the plugin reaches production. Review these points before publishing or installing a new build:

1. The manifest is at the plugin root. Native OpenClaw plugins need openclaw.plugin.json where discovery expects it.
2. The id is stable. The canonical id is used in plugins.entries.<id> and related configuration. Changing it casually leaves stale configuration behind.
3. The schema matches the runtime. Every accepted setting should have a real owner in code. Every required runtime setting should be represented in the schema or documented setup path.
4. Static claims are genuinely static. CLI command hints, provider ownership, activation information, and setup descriptors should be cheap to inspect. Do not import a heavy runtime module to calculate them.
5. The installed artifact validates. Test the generated package, not only the source checkout. Packaging errors often involve missing output files, a stale manifest, or a version mismatch that TypeScript never sees.

This is the same boundary that makes typed OpenClaw tool plugins easier to operate. A tool plugin can expose its identity and schema before an agent calls any handler. The operator gets a smaller unknown surface, and the host gets a clearer failure mode.

Avoid two common manifest mistakes

The first mistake is making the manifest too clever. Dynamic imports, environment reads, and network lookups belong in runtime code. The host needs a fast, deterministic file it can parse before it trusts the package enough to load it.

The second is assuming a valid JSON file proves the integration is ready. The schema can be valid while the package is missing its runtime build, declares a command that the code never registers, or exposes an outdated compatibility surface. Validate the package and test it against the OpenClaw versions you support.

That distinction becomes more important when extensions are updated independently. OpenClaw plugin update correction releases explains why install and update metadata deserve their own checks. An update that looks small can still fail at the package boundary.

A practical review sequence

Use a narrow review sequence when adding or changing a manifest:

1. Write or update the id and configSchema first.
2. Add only the static metadata that OpenClaw needs for discovery, validation, setup, or help surfaces.
3. Compare each manifest field with the code that consumes it. Remove metadata that has no runtime owner.
4. Build the package and validate the artifact from a clean install path.
5. Run one configuration failure case and one valid configuration case before shipping.
6. If the plugin supports multiple OpenClaw versions, test the oldest and newest supported versions, including any documented compatibility adapter.

This sequence is deliberately less exciting than debugging a Gateway after a plugin update. It also produces a useful review diff: readers can see what configuration the extension claims, whether the claim is static, and how the runtime enforces it.

FAQ

Is openclaw.plugin.json required for every OpenClaw extension?

It is required for native OpenClaw plugins, including local filesystem loads. Compatible bundle formats such as Claude, Codex, and Cursor use their own bundle metadata instead, which OpenClaw can detect without validating it as a native manifest.

Can a plugin manifest contain secrets?

No. A manifest is static package metadata. Put secrets in the appropriate configuration or secret-management path, and keep the manifest limited to declarative details such as configuration shape or environment-variable names.

Does manifest validation replace runtime tests?

No. It catches a different class of failure: malformed configuration and mismatched package metadata. You still need tests for runtime hooks, network calls, authentication, delivery behavior, and any action that changes state.

Should I remove legacy SDK metadata immediately?

Follow the documented migration window and your package’s supported-host policy. OpenClaw’s compatibility process retains adapters before removal. Move new code to the current documented contract, then remove old metadata when the supported version range allows it.

Keep the static boundary honest

A good OpenClaw plugin manifest makes a package easier to inspect, validate, and upgrade. It tells the host what the plugin is before the host runs it. Keep the file small, let the runtime own behavior, and make artifact validation part of every release.

Sources: OpenClaw plugin manifest reference, OpenClaw Plugin SDK migration reference, OpenClaw v2026.6.34 release notes, OpenClaw plugin CLI reference, OpenClaw plugin architecture