Plugin manifests and contracts#

OpenClaw plugins declare their identity, capabilities, and activation requirements through openclaw.plugin.json manifests. The manifest system drives discovery, validation, enablement decisions, activation planning, and registry construction without requiring full runtime execution for metadata-only flows.

Manifests are read during config validation and startup auto-enable, plugin inventory and doctor checks, gateway bootstrap, and CLI metadata resolution. Runtime behavior such as tools, providers, and channels is still supplied by the plugin's registration code.

Manifest file#

The manifest lives at <plugin-root>/openclaw.plugin.json.

Required top-level fields:

id: stable plugin identifier (lowercase, hyphenated)
name, description, version

Optional top-level fields used by the system:

kind
enabledByDefault, enabledByDefaultOnPlatforms
legacyPluginIds
autoEnableWhenConfiguredProviders
channels, providers, skills
modelSupport
modelCatalog, modelPricing, modelIdNormalization
providerEndpoints, providerRequest
secretProviderIntegrations
cliBackends, syntheticAuthRefs, nonSecretAuthMarkers
commandAliases
providerAuthEnvVars, providerAuthAliases, channelEnvVars
providerAuthChoices
activation
setup
qaRunners
contracts
mediaUnderstandingProviderMetadata, imageGenerationProviderMetadata, videoGenerationProviderMetadata, musicGenerationProviderMetadata, toolMetadata
configContracts
channelConfigs

Example:

{
  "id": "whatsapp",
  "kind": ["channel"],
  "channels": ["whatsapp"],
  "providers": ["baileys"]
}

Contracts#

The contracts object is a static, manifest-only declaration of capability ownership. It narrows candidate sets before runtime load and supports contract coverage diagnostics.

Supported contract keys include:

embeddedExtensionFactories
agentToolResultMiddleware
trustedToolPolicies
externalAuthProviders
embeddingProviders
memoryEmbeddingProviders
speechProviders
realtimeTranscriptionProviders
realtimeVoiceProviders
mediaUnderstandingProviders
transcriptSourceProviders
documentExtractors
imageGenerationProviders
videoGenerationProviders
musicGenerationProviders
webContentExtractors
webFetchProviders
webSearchProviders
migrationProviders
gatewayMethodDispatch
tools

Declaring a contract does not replace the runtime registration call.

Activation planning#

The activation object supplies planner hints consulted before broader registries are loaded.

Fields:

onStartup: boolean that forces inclusion during gateway startup
onProviders, onAgentHarnesses, onCommands, onChannels, onRoutes, onConfigPaths: arrays of ids or paths
onCapabilities: broad hints such as "provider", "channel", "tool", "hook"

Fallback ownership still comes from providers, channels, commandAliases, setup.providers, contracts.tools, and hooks. The planner reports reason labels for diagnostics.

Manifest registry and lookup#

OpenClaw builds a registry of parsed manifests, diagnostics, owner maps, and provenance. A PluginMetadataSnapshot is materialized at gateway startup and kept as a replaceable runtime product. Repeated operations such as channel ownership, provider discovery, CLI backend lookup, and config schema validation borrow the snapshot when available.

The snapshot is cleared or replaced on shutdown, config changes, plugin inventory changes, and installed-index writes.

Bundled versus external plugins#

Bundled plugins live under the extensions directory (or the path set by OPENCLAW_BUNDLED_PLUGIN_DIR) and ship with the packaged distribution. External plugins are installed via the CLI, recorded in the installed plugin index, and loaded from workspace or global plugin roots.

During development the workspace root uses extensions directly. Postinstall and build steps copy bundled plugin assets. Runtime distinguishes provenance for diagnostics and boundary checks.

Official external plugins can be installed by spec from the catalog or npm.

See Plugin SDK for the runtime registration surface that complements manifest declarations. Plugin configuration appears under the plugins section of the gateway config.