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.

Updated June 17, 2026