wednesdayai plugins
Manage Gateway plugins/extensions (loaded in-process).
The legacy openclaw plugins alias remains supported. New examples use
wednesdayai plugins.
The singular form is a supported alias: wednesdayai plugin install <id> is identical to
wednesdayai plugins install <id>. The canonical command is plugins; all WednesdayAI
messages and docs use that form.
Related:
- Plugin system: Plugins
- Plugin manifest + schema: Plugin manifest
- Analysis runtime (operators): Plugin analysis runtime operations
- Security hardening: Security
Hook timeouts and analysis limits
Plugin hooks default to a 30 second timeout so a stuck plugin cannot freeze the gateway. Plugin-owned LLM analysis (analysis.run) defaults to 2 concurrent slots across plugins
and 1 concurrent slot per plugin. Each plugin’s inner budget comes from its own winning
manifest unless you set plugins.analysisConcurrency.maxParallelPerPlugin as a uniform
ceiling. Raise maxParallelPerPlugin for more active same-plugin runs, subject to
maxParallel. To queue overflow, raise both maxSequential and
maxSequentialPerPlugin.
You do not set these from the CLI. Put them in openclaw.json under plugins.hookTimeouts
and plugins.analysisConcurrency, then restart the gateway. Full keys:
Configuration reference.
Operators: Plugin analysis runtime operations.
Commands
plugins enable to
activate them.
Use plugins list --verbose or plugins info <id> to confirm where a plugin is
loading from. Bundled plugins report Origin: bundled; installed copies under
~/.openclaw/extensions report a managed install source instead.
All plugins must ship a wednesdayai.plugin.json file with an inline JSON Schema
(configSchema, even if empty). Missing/invalid manifests or schemas prevent
the plugin from loading and fail config validation. The legacy
openclaw.plugin.json filename still loads (ADR 2057); when a plugin root
contains both files, wednesdayai.plugin.json wins.
Catalog
WednesdayAI maintains a plugin catalog that maps bare plugin ids to their npm install specs. The catalog has two layers:- Static local — baked into the package (
src/plugins/catalog.json). Lists bundled plugins and core plugins available for managed install. - Remote — fetched from the WednesdayAI-plugins repository and merged on top of the local catalog. Cached in memory for one hour per gateway process; fail-open to local-only on any fetch error.
list, info, and install commands automatically refresh the remote
catalog before resolving a bare plugin id against it.
Pinned entries and verification
Remote catalog entries must pin an exactversion and a sha512 integrity digest. If any
remote entry is missing its pin, the whole remote payload is rejected and WednesdayAI uses the
bundled offline snapshot instead. The snapshot carries a pinned brave-search entry for
exactly this case: a feed outage must never resolve a bare catalog id to an unrelated unscoped
npm package. The published feed is never empty either; the release pipeline replaces pinned
entries in place rather than clearing the feed.
Catalog-pinned installs are verified, not trusted. See
Verified catalog installs and
Compatibility for the refusal messages.
Remote fetching can be disabled entirely (airgap / mirror mode) or pointed at an
alternate URL via environment variables:
List
Origin). After refreshing the
remote catalog, also shows catalog entries that are not yet installed as
“not installed” with Source: catalog. A plugin shows as “degraded” when
it loaded, but at least one warning is attributed to it — for example a hook that
core does not dispatch; run wednesdayai plugins status for the details. A plugin
that did not load because an optional dependency is missing shows as
“deps missing”, not as an error. Use --enabled to filter to active plugins
only (degraded plugins are included) or --json for machine-readable output.
Info
Status: line reports not installed, disabled, enabled, degraded,
or error. degraded means the plugin loaded and is enabled but has at least
one warning attributed to it — for example a hook name core does not dispatch;
run wednesdayai plugins status for the details.
For catalog-only (not installed) plugins, displays the catalog entry — kind,
npmSpec, and the install command.
Status
OK, DEGRADED (at least one
warning that belongs to a plugin), or ERROR (at least one error). Each plugin
row uses the health vocabulary: loaded, warned (at least one warning is
attributed to it, for example a hook name core does not dispatch on a loaded
plugin, or a missing optional dependency on a disabled one), error,
disabled, or skipped. Warnings and errors are listed under Issues: with
their diagnostic code and remediation — for example a
PLUGIN_HOOK_NOT_DISPATCHED warning with its hook parity map link. The command
exits 1 when the overall status is ERROR. --json prints the raw health
report, with registry-level diagnostics under registryDiagnostics.
Some diagnostics come from the registry itself and name no plugin — an invalid
plugins.slots value, for instance. They are listed under a
Not attributed to a plugin: heading inside Issues:. A warning of that kind
does not make the overall status DEGRADED, because no plugin row would show
the cause; an error of that kind still makes it ERROR.
The gateway logs the same health report once at startup: a summary line such as
[plugins] startup: 0 loaded, 1 warning — see warnings below, with every
warning listed beneath it, including hook registration ones and unattributed
ones (labelled (no plugin)).
Doctor
PLUGIN_HOOK_NOT_DISPATCHED hook registration
warnings and PLUGIN_BUILD_SKEW build-skew warnings). Warn and error
diagnostics print under Diagnostics: as - <id>: <message>, with a
→ <remediation> line beneath each diagnostic that carries one — for
PLUGIN_BUILD_SKEW the remediation names the lockstep reinstall or the
plugins update path. Prints No plugin issues detected. when everything is
healthy, and links to the plugin docs otherwise.
Install
--ignore-scripts for safety.
If a bare install spec matches a bundled plugin id (for example whatsapp or
diffs), WednesdayAI installs from the bundled source. If there is no bundled
match, the spec is resolved against the remote catalog: if a catalog entry exists
with a matching id, WednesdayAI installs the entry’s npmSpec instead. An npm
install failure falls back to the bundled source. To install an npm package
with the same name as a catalog entry, use an explicit scoped spec (for example
@scope/diffs).
Legacy upstream specs (@openclaw/<id>, with or without a version or tag) resolve
to the bundled copy of the plugin with that id before npm is contacted. Upstream
openclaw owns the @openclaw npm scope, so these specs never install upstream’s
package (ADR 2057).
Some bundled plugins are install-only: their runtime dependencies are not part of
the WednesdayAI package, so the shipped copy cannot load on its own. They are
acpx, diagnostics-otel, diffs, feishu, identity-oidc, matrix,
mcp-client, memory-lancedb, msteams, nostr, tlon, twitch, whatsapp
and zalouser. Enabling one without installing it shows deps missing in
plugins list, and plugins doctor prints the fix:
$OPENCLAW_STATE_DIR/extensions/<id>, normally ~/.openclaw/extensions/<id>), and
the managed copy takes precedence over the bundled one. Do not repair these plugins
by running npm install inside the global WednesdayAI package directory.
Every other bundled plugin gets its dependencies from the WednesdayAI package itself
and runs directly from the shipped copy once enabled. plugins list, plugins doctor,
and config validation should not report missing dependencies for those.
Bundled installs are reconciled back to the bundled copy that shipped with the
current WednesdayAI package. During that reconciliation WednesdayAI may remove the old
per-user copy under ~/.openclaw/extensions/<id> when it is the default copied
directory and does not contain node_modules. Copies that carry installed
dependencies are left in place. Do not add the bundled source directory to
plugins.load.paths; the install record is enough.
If gateway startup logs say plugin not found for a bundled plugin, check
wednesdayai plugins info <id> before reinstalling. Origin: bundled with
Status: loaded means the plugin is already available from the shipped copy.
Supported archives: .zip, .tgz, .tar.gz, .tar.
Installing a local path or archive over an existing install fails with
plugin already exists: <targetDir> (delete it first). Pass --force to
replace the existing install in place:
--link to avoid copying a local directory (adds to plugins.load.paths):
--pin on npm installs to save the resolved exact spec (name@version) in
plugins.installs while keeping the default behavior unpinned.
:::warning
Installing verifies the plugin by loading it, which imports the plugin’s entry module and
runs its top-level code in the CLI process. Dependency lifecycle scripts stay disabled
(npm install --ignore-scripts), and the plugin’s register() is not called until you run
plugins enable, but module-level side effects do run at install time. For a catalog-pinned
install the artifact’s digest and provenance are verified first. For a direct npm spec, local
path or archive there is no such verification, so only install sources you trust.
:::
Verified catalog installs
When a bare id resolves to a pinned catalog entry (one with aversion and a sha512
integrity), plugins install takes the verified rail instead of a plain npm install:
-
Compatibility preflight with no network: the entry’s
minWednesdayVersion,minHostVersionandcontractsare checked against this host. See Compatibility. -
Sigstore provenance: the npm SLSA attestation is fetched and verified against the exact
signer identity
https://github.com/ExpansionX/WednesdayAI-plugins/.github/workflows/release.yml@refs/heads/mainand the catalog-pinned digest. -
Integrity-checked install: the npm tarball is installed with the pinned digest as
expectedIntegrity; a downloaded artifact whose digest differs is refused. The install runs in a stage directory and is verified by loading it before it is promoted; nothing touches the live directory until verification passes. -
The command then logs:
npmSpec, so the default
record stays unpinned unless you pass --pin. --force replaces an existing install.
Refusals on this path always mean nothing was installed:
plugin "<id>" <version> is not compatible with this host: <reason>. Run `wednesdayai update` to upgrade WednesdayAI, then retry.— the pinned version does not fit this host. Runwednesdayai updateand retry.refusing to install "<id>" <version>: provenance verification failed: <detail>— the artifact is not attested, is signed by the wrong workflow or ref, or its digest does not match the catalog. Do not retry from npm; the artifact must be re-published. Full message reference: Compatibility.
wednesdayai plugins enable <id>.
Uninstall
uninstall removes plugin records from plugins.entries, plugins.installs,
the plugin allowlist, and linked plugins.load.paths entries when applicable.
For active memory plugins, the memory slot resets to memory-core.
By default, uninstall also removes the plugin install directory under the active
state dir extensions root ($OPENCLAW_STATE_DIR/extensions/<id>). Use
--keep-files to keep files on disk.
--keep-config is supported as a deprecated alias for --keep-files.
Update
plugins.installs).
Bundled plugins update with the WednesdayAI package itself; plugins update first
reconciles bundled install records so stale copied-bundled records stop looking
like missing managed installs.
When a stored integrity hash exists and the fetched artifact hash changes,
WednesdayAI prints a warning and asks for confirmation before proceeding. Use
global --yes to bypass prompts in CI/non-interactive runs.
A plugin whose id is a pinned catalog entry for the same package updates to the
catalog-pinned version through the same verified rail as install: compatibility preflight,
Sigstore provenance against the catalog digest, then an integrity-checked staged install, and
the Verified <spec>: sha512 pinned by catalog, provenance signed by <signer identity> line.
Refusals use the install refusal messages, nothing is staged, and the current install stays in
place. The integrity-drift prompt does not apply on this path — the catalog digest is
authoritative, so a mismatch is refused outright.