Plugin manifest (openclaw.plugin.json)
This page is for the native Agdi plugin manifest only. For compatible bundle layouts, see Plugin bundles. Compatible bundle formats use different manifest files:- Codex bundle:
.codex-plugin/plugin.json - Claude bundle:
.claude-plugin/plugin.jsonor the default Claude component layout without a manifest - Cursor bundle:
.cursor-plugin/plugin.json
openclaw.plugin.json schema described here.
For compatible bundles, Agdi currently reads bundle metadata plus declared
skill roots, Claude command roots, Claude bundle settings.json defaults, and
supported hook packs when the layout matches Agdi runtime expectations.
Every native Agdi plugin must ship an openclaw.plugin.json file in the
plugin root. Agdi uses this manifest to validate configuration
without executing plugin code. Missing or invalid manifests are treated as
plugin errors and block config validation.
The manifest filename remains
openclaw.plugin.json for compatibility during
the Agdi transition. New plugin code should still use agdi/plugin-sdk/*
imports.What this file does
openclaw.plugin.json is the metadata Agdi reads before it loads your
plugin code.
Use it for:
- plugin identity
- config validation
- auth and onboarding metadata that should be available without booting plugin runtime
- config UI hints
- registering runtime behavior
- declaring code entrypoints
- npm install metadata
package.json.
Minimal example
Rich example
Top-level field reference
providerAuthChoices reference
EachproviderAuthChoices entry describes one onboarding or auth choice.
Agdi reads this before provider runtime loads.
uiHints reference
uiHints is a map from config field names to small rendering hints.
Manifest versus package.json
The two files serve different jobs:
If you are unsure where a piece of metadata belongs, use this rule:
- if Agdi 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, andplugins.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.
plugins.* schema.
Notes
- The manifest is required for native Agdi 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.
providerAuthEnvVarsis 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.providerAuthChoicesis the cheap metadata path for auth-choice pickers,--auth-choiceresolution, 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 byplugins.slots.memory.kind: "context-engine"is selected byplugins.slots.contextEngine(default: built-inlegacy).
channels,providers, andskillscan 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-scriptspnpm rebuild <package>).