Skip to main content

Plugin manifest (wednesdayai.plugin.json)

Every plugin must ship a wednesdayai.plugin.json file in the plugin root. WednesdayAI uses this manifest to validate configuration without executing plugin code. Missing or invalid manifests are treated as plugin errors and block config validation.

Filename and legacy fallback

  • wednesdayai.plugin.json is the primary manifest filename (ADR 2057).
  • openclaw.plugin.json is the legacy name and still loads as a fallback.
  • When a plugin root contains both files, wednesdayai.plugin.json wins and the loader records an info diagnostic naming both files.
  • wednesdayai doctor reports installed plugins that still ship only the legacy filename as information, and warns when a plugin dir holds both manifests with different plugin ids.
See the full plugin system guide: Plugins.

Required fields

Required keys:
  • id (string): canonical plugin id.
  • configSchema (object): JSON Schema for plugin config (inline).
Optional keys:
  • kind (string): plugin kind (example: "memory").
  • channels (array): channel ids registered by this plugin (example: ["matrix"]).
  • providers (array): model provider ids this plugin registers (example: ["acme"]). This is not the Talk streaming speech, realtime transcription, or batch speech provider. Those are registered in code with api.registerSpeechProvider (batch TTS for the messages.tts stack), api.registerStreamingSpeechProvider and api.registerRealtimeTranscriptionProvider, imported from wednesdayai/plugin-sdk (legacy alias openclaw/plugin-sdk). See Register realtime voice, STT and TTS providers.
  • skills (array): skill directories to load (relative to the plugin root).
  • name (string): display name for the plugin.
  • description (string): short plugin summary.
  • uiHints (object): config field labels/placeholders/sensitive flags for UI rendering.
  • version (string): plugin version (informational).
  • minWednesdayVersion (string): optional floor the host compares its own semver against, formatted >=x.y.z. Checked at catalog preflight, install and load. Prefer this over minHostVersion.
  • minHostVersion (string): legacy floor compared against the fork base (openclaw@2026.3.2). Ignored when minWednesdayVersion is also present; declare one of the two, not both.
  • contracts (object): optional map of kernel contract id to a "major.minor" version the plugin requires (example: { "delivery": "1.0" }). The host checks the map at install and at load and refuses an incompatible plugin. Entries whose value is an array of strings (upstream capability-ownership lists such as contracts.tools) are accepted and ignored for kernel contract versioning; an array holding any non-string is rejected. See Versioned kernel contracts.
  • All three compatibility fields, their exact refusal messages and the catalog feeds that publish them: Compatibility.
  • sessionConsumers (array): declares session-end consumers for the claim/ack pipeline. Each entry has effectKind (string, default "session.end"), subCursors (array, max 8, each ^[a-z][a-z0-9-]*$), consumeScopes (array of strings, authz scopes; bare strings are rejected), and consumeLanes (array of strings, lane scopes; bare strings are rejected). See Session Consumer Claims for the full SDK surface.
  • hookTimeouts (object): optional map of hook name to timeout milliseconds. Supports a default key. Operator plugins.hookTimeouts wins on the same hook name.
  • analysisConcurrency (object): optional { maxParallel?, maxSequential?, maxParallelPerPlugin?, maxSequentialPerPlugin? } hint for api.runtime.analysis.run(). Global maxParallel / maxSequential keep the most permissive value among winning enabled plugins. Inner maxParallelPerPlugin / maxSequentialPerPlugin apply only to this plugin id. Operator plugins.analysisConcurrency global fields override the merged globals when set; operator per-plugin fields are a uniform ceiling. Per-plugin values clamp inside the corresponding global limits. Omitted maxSequentialPerPlugin inherits maxSequential.
  • controlUi (object): optional { "entry": "dist/control-ui/index.js" } for Control UI v2 plugins. entry is a relative .js or .mjs path in a subdirectory of the plugin root; root-level entries, absolute paths, .. segments and .ts sources are rejected. The gateway serves the entry’s directory publicly, so give it a directory of browser assets only. The browser module it points at is loaded by the operator console only when the plugin id is allowlisted under gateway.controlUiV2.pluginUi.allow. See Control UI plugins.
  • chatUi (object): optional { "entry": "dist/chat-ui/index.js", "methods": ["<id>.notes.list"] } for web-client chat plugins. entry follows the controlUi rules. methods is an optional array of gateway method names the browser side may call, each prefixed with this plugin’s id and a dot; non-prefixed names are rejected at manifest load. The browser module is loaded by the web client only when the plugin id is allowlisted under gateway.webClient.pluginUi.allow. See Chat UI plugins.

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, and plugins.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.

Notes

  • The manifest is required for all plugins, including local filesystem loads.
  • Runtime still loads the plugin module separately; the manifest is only for discovery + validation.
  • If your plugin depends on native modules, document the build steps and any package-manager allowlist requirements (for example, pnpm allow-build-scripts
    • pnpm rebuild <package>).