Plugin manifest (wednesdayai.plugin.json)
Every plugin must ship awednesdayai.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.jsonis the primary manifest filename (ADR 2057).openclaw.plugin.jsonis the legacy name and still loads as a fallback.- When a plugin root contains both files,
wednesdayai.plugin.jsonwins and the loader records an info diagnostic naming both files. wednesdayai doctorreports installed plugins that still ship only the legacy filename as information, and warns when a plugin dir holds both manifests with different plugin ids.
Required fields
id(string): canonical plugin id.configSchema(object): JSON Schema for plugin config (inline).
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 withapi.registerSpeechProvider(batch TTS for themessages.ttsstack),api.registerStreamingSpeechProviderandapi.registerRealtimeTranscriptionProvider, imported fromwednesdayai/plugin-sdk(legacy aliasopenclaw/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 overminHostVersion.minHostVersion(string): legacy floor compared against the fork base (openclaw@2026.3.2). Ignored whenminWednesdayVersionis 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 ascontracts.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 haseffectKind(string, default"session.end"),subCursors(array, max 8, each^[a-z][a-z0-9-]*$),consumeScopes(array of strings, authz scopes; bare strings are rejected), andconsumeLanes(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 adefaultkey. Operatorplugins.hookTimeoutswins on the same hook name.analysisConcurrency(object): optional{ maxParallel?, maxSequential?, maxParallelPerPlugin?, maxSequentialPerPlugin? }hint forapi.runtime.analysis.run(). GlobalmaxParallel/maxSequentialkeep the most permissive value among winning enabled plugins. InnermaxParallelPerPlugin/maxSequentialPerPluginapply only to this plugin id. Operatorplugins.analysisConcurrencyglobal fields override the merged globals when set; operator per-plugin fields are a uniform ceiling. Per-plugin values clamp inside the corresponding global limits. OmittedmaxSequentialPerPlugininheritsmaxSequential.controlUi(object): optional{ "entry": "dist/control-ui/index.js" }for Control UI v2 plugins.entryis a relative.jsor.mjspath in a subdirectory of the plugin root; root-level entries, absolute paths,..segments and.tssources 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 undergateway.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.entryfollows thecontrolUirules.methodsis 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 undergateway.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, 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.
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-scriptspnpm rebuild <package>).