Plugins (Extensions)
Quick start (new to plugins?)
A plugin is just a small code module that extends WednesdayAI with extra features (commands, tools, and Gateway RPC). Most of the time, you’ll use plugins when you want a feature that’s not built into core WednesdayAI yet (or you want to keep optional features out of your main install). Fast path:- See what’s already loaded:
- Install an official plugin (example: Voice Call):
wednesdayai plugins install whatsapp resolves the catalog entry to @wednesdayai/whatsapp, installs it into ~/.openclaw/extensions/whatsapp, and installs runtime dependencies beside that managed copy. Install does not enable the plugin automatically; run wednesdayai plugins enable whatsapp when you are ready to activate it. Not every bundled plugin is published to npm yet.
- Restart the Gateway, then configure under
plugins.entries.<id>.config.
Available plugins (official)
- Microsoft Teams is plugin-only as of 2026.1.15; install
@openclaw/msteamsif you use Teams. - Memory (Core) — bundled memory search plugin (enabled by default via
plugins.slots.memory) - Memory (LanceDB) — bundled long-term memory plugin (auto-recall/capture; set
plugins.slots.memory = "memory-lancedb") - Voice Call —
@openclaw/voice-call - Zalo Personal —
@openclaw/zalouser - Matrix —
@openclaw/matrix - Nostr —
@openclaw/nostr - Zalo —
@openclaw/zalo - Microsoft Teams —
@openclaw/msteams - Google Antigravity OAuth (provider auth) — bundled as
google-antigravity-auth(disabled by default) - Gemini CLI OAuth (provider auth) — bundled as
google-gemini-cli-auth(disabled by default) - Qwen OAuth (provider auth) — bundled as
qwen-portal-auth(disabled by default) - Copilot Proxy (provider auth) — local VS Code Copilot Proxy bridge; distinct from built-in
github-copilotdevice login (bundled, disabled by default) - Dream Cycle — background consolidation engine over the task pipeline; ships in
extensions/dream-cycle, install from path (disabled by default) - Learning Core — skill-proposal pipeline; ships in
extensions/learning-core, install from path (disabled by default) - MCP Client — operator-configured MCP servers (stdio, Streamable HTTP) as policy-checked agent tools with a per-call audit table; bundled as
mcp-client(disabled by default) - Orca — Orca agent sessions in Control UI v2 and the web client; ships in
extensions/orca(bundled, disabled by default)
- Gateway RPC methods
- Gateway HTTP handlers
- Agent tools
- CLI commands
- Background services
- Background task passes (run by the Gateway task pipeline; see “Background task passes” below)
- Optional config validation
- Skills (by listing
skillsdirectories in the plugin manifest) - Auto-reply commands (execute without invoking the AI agent)
- Provider runtime hooks for provider-specific request shaping
Runtime and turn identity
Plugins can correlate one user turn across hooks, tools, storage append events, model-call completion, and background analysis through typed SDK context fields. Use these fields instead of parsingsessionKey, reading identityLinks, or
reconstructing turn boundaries from timestamps or message text.
ctx.runtimeIdentity may include:
agentId,agentName,agentWorkspacePath, andagentWorkspaceNamesessionIdandsessionKeywhen a real session exists for the hookchannelConversationIdfor the transport conversation/threadproviderConversationIdfor the opaque model/provider cache partitionlaneId— the opaquelane-<hash>digest, present only for an allowed multi-lane run;undefinedfor single-user and denied resolutions (see Workspace Lanes)- trusted sender fields such as
senderId,senderName,senderUsername,senderE164,messageProvider,canonicalIdentity, andsenderIsOwner identitySource— provenance of the resolved identity:"sender"(resolved from the live message sender),"parent-session"(inherited from the session that spawned this run), or"job-config"(attributed by operator-configured cron-job/heartbeat identity); absent when the run has no resolved identity (plain system run), and also when a seam suppliescanonicalIdentitywithout knowing its provenance — provenance is never guessed, soidentitySourceimpliescanonicalIdentitybut not the reversesessionKind— structural classification of the session derived from the session key:"user"(a normal conversation session, including the main session),"cron","heartbeat","hook","subagent","acp", or"unknown"(missing or malformed session key). Never guessed from message text.accountId— provider account id for multi-account setups.peerKindandpeerId— the actual input peer’s kind ("direct","group","channel") and id, exposed under everydmScopevalue.isMainSession—trueonly whensessionKeyequals the agent’s main session key; never inferred from the session key shape.
ctx.turn carries the per-turn correlation key and storage linkage. In the v1
contract, turn.turnId is the same stable value as runId by value. Early hooks
receive the fields known at that point; later storage hooks may add
userEntryId, assistantEntryId, sequence numbers, or global sequence numbers
for the append that just happened.
Keep these identity boundaries clear:
conversationIdis a legacy alias forchannelConversationId; it is never the provider/model cache identity.providerConversationIdis intentionally opaque. Persist it only as an opaque correlation/cache key.sessionIdandsessionKeyare optional on early hooks. Do not synthesize fake session values when they are absent.- Core may use
session.identityLinksinternally, but plugins should consume only the resolved identity fields or theapi.runtime.identityhelpers (see Identity helpers). identitySource: "job-config"provenance is operator-attributed (CLI, gateway RPC, Web UI); agents can never set it on their own runs.
ctx.channelContext provides an extensible channel-identity surface (additive to
runtimeIdentity). Plugins can access it on PluginHookAgentContext and
PluginHookMessageContext:
channelId— the channel identifier (e.g."telegram","discord").senderExternalId— the stable external sender id from the channel (e.g. Slack user id, Discord user id). Optional; present when the hook fires in response to a message from a known sender.channelConversationId— the channel-native conversation/room id (e.g. Matrix room id, Telegram chat id). Optional.
[key: string]: unknown index signature so channel
adapters and plugins can attach additional typed fields without waiting
for a core SDK update. Import the types from the SDK:
PluginHookChannelContext is the union of PluginHookChannelSenderContext
and PluginHookChannelChatContext. PluginHookChannelSenderContext carries
channelId and senderExternalId; PluginHookChannelChatContext carries
channelId and channelConversationId. Both types are open — channel adapters
set additional fields via the index signature, and plugins read them with
the same types.
For storage fan-out, do not dedupe on turn.turnId alone. User and assistant
appends share one turn id, so combine it with entry or cursor identity:
runtimeIdentity and turn objects alongside the existing flat compatibility
fields. On the normal agent tool path, before_tool_call sees the same
foreground run identity that was used to construct plugin tool factories.
Workspace lane context
Plugins can receive optional workspace lane context when the current agent run or tool call is tied to an allowed workspace lane:workspaceLane.effectiveWorkspaceDir for lane-local user state
and workspaceLane.personaWorkspaceDir only for shared persona files. See
Workspace Lanes.
For per-lane storage partitioning, use ctx.runtimeIdentity.laneId rather than the raw
context.laneId. runtimeIdentity.laneId is undefined for single-user and denied resolutions
and present only for an allowed multi-lane run — so it is safe to use directly as a partition
discriminator without additional policy checks. The raw context.laneId and context.workspaceLane
fields are routing helpers and should not be used for storage keying.
message_received runs before workspace-lane resolution, so runtimeIdentity.laneId is absent
there. Message hooks should treat lane fields as absent on message_received.
Provider Runtime Hooks
Provider plugins can register model-call hooks withapi.registerProvider(...).
The hook context includes the selected provider/model, run/session identifiers, an
opaque conversationId, a hashed user identifier when one can be derived, and
the current stream options.
Supported provider-runtime hooks:
prepareExtraParams(ctx)returns a patch for the merged stream options before generic params are applied tostreamFn.wrapStreamFn(ctx)returns a stream wrapper after the existing core provider wrappers are installed.- Transport policy hook types are reserved in the SDK bridge for WednesdayAI compatibility, but they are not yet delivered to the HTTP/WebSocket transport path. Provider plugins should not rely on transport-policy effects until the matching transport wiring is documented.
conversationId or hashedUserId to external services. Do not send raw
sessionKey values, channel ids, phone numbers, or user handles to LLM provider
metadata unless the provider contract explicitly requires them.
Runtime helpers
Plugins can access selected core helpers viaapi.runtime. For telephony TTS:
- Uses core
messages.ttsconfiguration (OpenAI or ElevenLabs). - Returns PCM audio buffer + sample rate. Plugins must resample/encode for providers.
- Edge TTS is not supported for telephony.
- Uses the media-understanding audio configuration (
tools.media.audio) and provider fallback order; providers are plugin extensions and must be enabled (plugins.entries.<vendor>.enabled: true) or a local CLI (Whisper) must be installed. A config-provided OpenAI-compatible proxy (models.providers.<id>withapi: "openai-completions"or"openai-responses") needs no plugin extension, but voice notes are never auto-detected on it — name a speech-to-text model intools.media.audio.models(see Config-provided proxy bindings). - Returns
{ text: undefined }when no transcription output is produced (for example skipped/unsupported input, or no provider/CLI available).
Identity helpers
Bundled extensions reach the identity core throughapi.runtime.identity — the same link
operation the gateway’s identity.* RPCs expose (flows in Identities).
Reads are resolved against the live config on every call:
api.runtime.identity.resolveCanonicalIdentity({ channel?, senderId? })returns thesession.identityLinkskey a channel sender is linked to, using the same resolution the gateway applies to inbound messages. See Runtime and turn identity for the provenance-awarectx.runtimeIdentityfields; use those on hooks that carry them.api.runtime.identity.resolvePerson(name)returns the stored-case key for a configured identity name (matched case-insensitively), orundefinedwhen no such person exists. It never creates a person: resolve first, and fail on a typo instead of minting one.await api.runtime.identity.link({ person, value })links a<namespace>:<id>value to a person and returns{ person, value, changed }. It refusesdevice:values (identity_link_invalid; devices have their own operator path, and plugins issue an enrollment instead), and a value another person already holds throwsidentity_link_conflict.await api.runtime.identity.issueEnrollment({ person, profile, codeChallenge? })mints a device bootstrap for an existing person and returns{ bootstrapToken, expiresAtMs }.profileis"user-client"(the web client) or"wednesdayai-glass-node"(WednesdayAI Glass); any other value throws. An unknown person throwsidentity_unknown.codeChallengeis an optional RFC 7636 S256 challenge (43 base64url characters); when set, the device must present the matching verifier asauth.bootstrapCodeVerifierto redeem the token (see Gateway protocol). Deliver the token as a#setup=fragment exactly the way the identity-oidc sign-in flow does: the device redeems it on first connect and is paired and linked in one step (see Identities).await api.runtime.identity.issueUserClientEnrollment({ person })is deprecated and will be removed after one release; it isissueEnrollment({ person, profile: "user-client" }).
Phone alerts
await api.runtime.push.alertPerson({ person, kind: "inbox", collapseKey, previewText? }) sends
one APNs alert to each iOS device linked to person (a session.identityLinks key with a
device:<id> value) and returns { sent }, the number of devices that accepted it. An unknown
person, missing APNs credentials, or no registered device returns { sent: 0 }. The kind is
always inbox; plugins cannot send reply or approval alerts. Alerts sharing a collapseKey
replace each other on the device and are rate-limited to one per device every 30 seconds.
previewText is shown only on devices whose owner turned on message previews; other devices see
“New inbox item”. See iOS alerts.
Task pipeline and learning workspace
api.runtime.tasks.pipelineStatus()returns{ state: "booting" | "running" | "disabled" | "stopped", running, startupEntryId }.runningistrueonly in therunningstate;disabledmeans the pipeline did not boot (tasks.enabled: false, or the active SQL session storage runtime does not supply the task stores the pipeline requires — task runs, budget, or bus work).startupEntryIdis stable for one pipeline start and new on every later start, so it can key once-per-start work. Use it to decide whether work queued withapi.enqueueTaskWorkwill run (Learning Core runs promote inline when the pipeline is not running).api.runtime.tasks.workStates({ taskId, fingerprints })reads where your own normal-mode work items are:pending,claimed,processed,dlq, orabsentper fingerprint. It accepts at most 200 fingerprints and only this plugin’s own passes (taskIdis the bare pass id). It throws while no task store is available, so retention built on it fails closed.api.runtime.resolveLearningWorkspaceDir(agentId)returns the agent’s canonical learning workspace: its configured workspace as an absolute path over the live config, never a sandbox directory. It returnsnullwhen none resolves.api.runtime.sessions.startUserRun({ agentId, sessionKey, sessionId?, runId?, prompt, lane? })records a user turn the plugin runs itself (the voice-call plugin’s phone turns) as a session run, so the Gateway’s idle detection sees it. It resolves to a handle withcomplete(),fail(error)andabort(reason?); call exactly one when the turn ends. A turn withoutrunIdgets a unique one.
Time and stamp helpers
api.runtime.time.timezoneis the resolved user timezone (agents.defaults.userTimezone, host fallback).api.runtime.time.format(ms?)renders a timestamp as the canonical message stamp[Ddd YYYY-MM-DD HH:MM GMT±H]in that timezone;msdefaults to now.api.runtime.time.parseLeadingStamps(text)parses leading message stamps (canonicalGMT±H[:MM], zoneless, and legacy abbreviation forms) and returns{ body, stamps, pending };stripLeadingStamps(text)returnsbody. A fragment that may still become a stamp (a bracket without a closing bracket, at most 40 characters) is reported aspendingwith the text unchanged, so stream consumers can hold it back.
parseLeadingStamps and stripLeadingStamps are also top-level SDK exports, for code that has no
plugin api handle.
Channel plugin helpers
Bundled channel extensions reach these core helpers throughapi.runtime instead of importing
core modules (the packaged plugin-sdk is a separate bundle; see the process-scoped state rules in
Coding style):
api.runtime.config.readConfigFileSnapshotForWrite()reads the on-disk config file snapshot plus the matchingwriteOptions(envSnapshotForRestoreandexpectedConfigPath) for a read-modify-write flow. Pass the returnedwriteOptionswhen you write the config back so${VAR}restoration is validated against the env snapshot that produced it, and only for the same config path.api.runtime.channel.session.loadSessionStore(storePath)returns a structured clone of the live session store record for a store path.api.runtime.channel.session.recordInboundSessionMetaSafe({ cfg, agentId, sessionKey, ctx, onError? })records inbound session meta; failures are swallowed and reported through the optionalonErrorcallback instead of throwing into the channel’s inbound path.api.runtime.channel.outbound.loadAdapter(channelId)loads the registered channel plugin’s outbound adapter (channel docking), so a host or plugin can deliver through another channel.
Read the message ingress carrier
Stored user messages carry the raw bytes as received plus a structured__openclaw.ingress carrier: where the turn came from, when it arrived, and the inbound metadata
the gateway collected. The stamp and inbound framing are added at the model boundary, so plugins
that render user messages read the raw content and stamp it themselves.
messageTime returns undefined when the message carries neither a valid carrier time nor a
valid timestamp. Stamp only when you have a time:
chat.history, and strips it from every provider-bound message, so
it never reaches the model wire either.
Discovery & precedence
WednesdayAI scans, in order:- Config paths
plugins.load.paths(file or directory)
- Workspace extensions
<workspace>/.openclaw/extensions/*.ts<workspace>/.openclaw/extensions/*/index.ts
- Global extensions
~/.openclaw/extensions/*.ts~/.openclaw/extensions/*/index.ts
- Bundled extensions (shipped with WednesdayAI, disabled by default)
<wednesdayai>/extensions/*
plugins.entries.<id>.enabled
or wednesdayai plugins enable <id>. Installed plugins are not activated by the
install step; enable them explicitly after install.
Bundled install records are zero-copy runtime references after reconciliation.
If a previous install copied a bundled plugin into ~/.openclaw/extensions/<id>,
WednesdayAI can rewrite that record to source: "bundled" and remove the stale
default copy when it is safe to do so. A valid bundled record still participates
in config validation even if the plugin manifest registry cache was built before
the bundled source was rediscovered.
Hardening notes:
- If
plugins.allowis empty and non-bundled plugins are discoverable, WednesdayAI logs a startup warning with plugin ids and sources. - Candidate paths are safety-checked before discovery admission. WednesdayAI blocks candidates when:
- extension entry resolves outside plugin root (including symlink/path traversal escapes),
- plugin root/source path is world-writable,
- path ownership is suspicious for non-bundled plugins (POSIX owner is neither current uid nor root).
- Loaded non-bundled plugins without install/load-path provenance emit a warning so you can pin trust (
plugins.allow) or install tracking (plugins.installs).
wednesdayai.plugin.json file in its root. If a path
points at a file, the plugin root is the file’s directory and must contain the
manifest.
The legacy openclaw.plugin.json filename still loads (ADR 2057). 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
Plugin manifest.
If multiple plugins resolve to the same id, the first match in the order above
wins and lower-precedence copies are ignored.
Package packs
A plugin directory may include apackage.json with wednesdayai.extensions:
name/<fileBase>.
The legacy openclaw manifest key and the legacy openclaw/plugin-sdk import specifier still load (ADR 2057).
If your plugin imports npm deps, install them in that directory so
node_modules is available (npm install / pnpm install).
Security guardrail: every wednesdayai.extensions entry must stay inside the plugin
directory after symlink resolution. Entries that escape the package directory are
rejected.
Security note: wednesdayai plugins install installs plugin dependencies with
npm install --ignore-scripts (no lifecycle scripts). Keep plugin dependency
trees “pure JS/TS” and avoid packages that require postinstall builds.
npm 12 and git-protocol dependencies
npm 12 disables fetching git-protocol dependencies by default (allow-git is
none). A plugin whose dependency tree still pulls a package over
git+https://... fails during wednesdayai plugins install with npm’s own
error, including:
npm install --omit=dev --loglevel=error --ignore-scripts
and appends npm’s stderr (or stdout if stderr is empty) to
npm install failed: ..., so that EALLOWGIT text reaches the operator.
Earlier installs used --silent, which hid the cause behind a bare
npm install failed:.
The WhatsApp channel — the installable plugin that carries runtime dependencies —
pins @whiskeysockets/baileys 7.0.0-rc14, which depends on the registry package
libsignal instead of a git-protocol libsignal, so it installs cleanly on npm 12.
One bundled extension still declares a git dependency: extensions/tlon pins
@tloncorp/api with a github: spec. It is not offered by wednesdayai plugins install, and bundled copies ship without installed runtime dependencies, so the
default install paths are unaffected — but installing it by hand on npm 12 fails
with EALLOWGIT unless the override below is used.
The right fix is to ask the plugin author to depend on a registry release.
If you must install a plugin whose dependency graph you have reviewed and trust,
scope the override to that one command rather than changing your user-wide npm
config:
npm config set allow-git all, which persists and re-enables
git fetching for every later install. Note that allow-git=root only permits
git specs declared directly in the package being installed, so it does not help
when the git dependency is transitive (the common case). WednesdayAI never sets
this for you; git fetching stays disabled by default.
Channel catalog metadata
Channel plugins can advertise onboarding metadata viawednesdayai.channel and
install hints via wednesdayai.install. This keeps the core catalog data-free.
Example:
~/.openclaw/mpm/plugins.json~/.openclaw/mpm/catalog.json~/.openclaw/plugins/catalog.json
OPENCLAW_PLUGIN_CATALOG_PATHS (or OPENCLAW_MPM_CATALOG_PATHS) at
one or more JSON files (comma/semicolon/PATH-delimited). Each file should
contain { "entries": [ { "name": "@scope/pkg", "wednesdayai": { "channel": {...}, "install": {...} } } ] }.
Plugin IDs
Default plugin ids:- Package packs:
package.jsonname - Standalone file: file base name (
~/.../voice-call.ts→voice-call)
id, WednesdayAI uses it but warns when it doesn’t match the
configured id.
Config
enabled: master toggle (default: true)allow: allowlist (optional)deny: denylist (optional; deny wins)load.paths: extra plugin files/dirsinstalls.<id>: CLI-managed install metadata.sourceis one ofnpm,archive,path, orbundled.entries.<id>: per‑plugin toggles + config
- Unknown plugin ids in
entries,allow,deny, orslotsemit startup/config warnings. Entries are treated as stale config and ignored until a matching plugin is installed or rediscovered; allow/deny/slot references include install guidance. - A
source: "bundled"install record is considered valid only when itssourcePathmatches the current bundled source for the same plugin id (string match or realpath-equivalent path), the manifest id matches, and the bundled plugin is version-compatible with the host. - Valid bundled install records participate in config validation even if the
normal discovery cache is stale. Their plugin config is validated against the
bundled
openclaw.plugin.jsonconfigSchema, and the schema cache key includes the manifest path plus file modification time. - Do not write
source: "bundled"records by hand in third-party plugin docs or setup scripts. Letwednesdayai plugins install,wednesdayai plugins update, or bundled reconciliation create and refresh managed install metadata. - Valid bundled install records suppress false
plugin not foundwarnings forentries,allow,deny, andslots.memory, but theirplugins.entries.<id>.configobject is still validated against the bundled manifest’sconfigSchema. - Unknown
channels.<id>keys are errors unless a plugin manifest declares the channel id. - Plugin config is validated using the JSON Schema embedded in the plugin manifest
(
wednesdayai.plugin.json; the legacyopenclaw.plugin.jsonstill loads) (configSchema). - If a plugin is disabled, its config is preserved and a warning is emitted.
Plugin slots (exclusive categories)
Some plugin categories are exclusive (only one active at a time). Useplugins.slots to select which plugin owns the slot:
kind: "memory", only the selected one loads. Others
are disabled with diagnostics. The same exclusivity applies to kind: "context-engine" plugins through plugins.slots.contextEngine (no default:
unset means the first loaded context-engine plugin wins).
Control UI (schema + labels)
The Control UI usesconfig.schema (JSON Schema + uiHints) to render better forms.
WednesdayAI augments uiHints at runtime based on discovered plugins:
- Adds per-plugin labels for
plugins.entries.<id>/.enabled/.config - Merges optional plugin-provided config field hints under:
plugins.entries.<id>.config.<field>
uiHints alongside your JSON Schema in the plugin manifest.
Example:
CLI
plugins update only works for npm installs tracked under plugins.installs.
Bundled plugins track the WednesdayAI package version instead. The
update command reconciles bundled install records first, so a copied bundled
record can become source: "bundled" before npm update selection runs.
If stored integrity metadata changes between updates, WednesdayAI warns and asks for confirmation (use global --yes to bypass prompts).
A bare plugin id resolves against the plugin catalog. Catalog-pinned installs are
compatibility-checked and provenance-verified before anything is installed; see
Verified catalog installs and
Compatibility.
Plugins may also register their own top-level commands (example: wednesdayai voicecall).
Managed installs vs bundled copies
Bundled extensions live inside the installed WednesdayAI package and are discovered after explicit load paths, workspace extensions, and~/.openclaw/extensions. Treat that bundled directory as
read-only.
When a plugin has runtime dependencies, wednesdayai plugins install <id> copies it into the
managed extensions root ($OPENCLAW_STATE_DIR/extensions/<id>, normally
~/.openclaw/extensions/<id>) and installs dependencies beside that managed copy. Operators should
repair missing dependencies by reinstalling the plugin, not by running package-manager commands in
the global WednesdayAI package.
Dependency-free bundled plugins may run directly from the global package copy when enabled. A
healthy global bundled plugin should not produce PLUGIN_DEPS_MISSING diagnostics just because it
does not have a managed install record.
A managed copy is also stamped with the WednesdayAI build it came from (dist/build-info.json,
written by wednesdayai plugins install <id> and the release rail). When such a copy shadows a
bundled plugin and its stamp is missing or from a different commit than the installed core, core
reports a warn PLUGIN_BUILD_SKEW diagnostic instead of loading the older copy silently: the
gateway logs it at startup, wednesdayai plugins doctor lists it under Diagnostics: with a
→ remediation line, and wednesdayai doctor shows a “Plugin build skew” note. Core running
from TypeScript source has no reference build and never reports the warning; a built checkout
compares against its own dist/build-info.json. Publish plugins from the
same commit as core — pnpm release:local-install --publish-dev is the sanctioned local dev
path (see Release).
Kernel contract compatibility
Plugins can declare the kernel contract versions they need inwednesdayai.plugin.json
(legacy openclaw.plugin.json still loads) (contracts). When a plugin needs newer
kernel contracts than this host provides:
- Install refuses:
wednesdayai plugins installfails with codeversion_incompatibleand a message likeplugin "<id>" is not compatible with this host: <reason>. Upgrade WednesdayAI and retry.Nothing is installed. A malformedcontractsfield is rejected the same way before any files are copied. - Config refuses: a plugin that is already on disk (for example on
plugins.load.paths, or installed before a host downgrade) is not loaded, and config validation reports it as an error atplugins.entries.<id>, e.g.plugin <id>: plugin "<id>" requires delivery contract 2.x (>= 2.0), but host provides 1.0. Like the existing minimum-host-version check, this makeswednesdayai config validate,plugins listand Gateway startup fail until the plugin is removed from disk or the load path, or upgraded — an incompatible plugin is never silently skipped. - Remedy: upgrade WednesdayAI, or install a build of the plugin made for this host’s kernel contracts. Contract versions are compiled into the host, so they are reliable even when the version string is not.
Plugin API (overview)
Plugins export either:- A function:
(api) => { ... } - An object:
{ id, name, configSchema, register(api) { ... } }
Background task passes
Plugins can contribute governed background work to the Gateway task pipeline through two API methods. Core already registerscron-run and heartbeat-tick at boot. Enqueue those ids only when you mean to
drive the core passes; do not put heartbeat work into cron_jobs.
- Register during
register(). Passes are buffered and drained into the task registry at Gateway boot; a pass registered after the pipeline has booted is never dispatched. - Enqueue only after boot.
enqueueTaskWorkrejects until the task pipeline has started; call it from hook handlers or services, not fromregister()itself. - Pass ids are namespaced
<pluginId>.<passId>automatically — enqueue with the bare id. A dotted id ("learning-core.promote") is rejected at register time. Corecron-run/heartbeat-tickare not namespaced; they are Gateway-owned. - Every pass run is an ordinary task run: budgets, concurrency, retry policy, and preemption
by live user turns all apply. Runs are visible via
wednesdayai task status. - Diagnostics: emit with
taskDiagnostic/dreamDiagnosticfromwednesdayai/plugin-sdk(oropenclaw/plugin-sdk). Builders are input-shaped (nots/seq). Do not cast ad-hoc objects. Use live field namespassIdandattempts. OTel export: Task and dream spans. Recovery ceiling behavior (age stall / attempt exhaust →dlq): Task pipeline. TreatupdatedAt/startedAton a run record as ISO-Z. Do notDate.parsea raw SQLite space-format stamp. See Timestamp conventions.
Successors committed with the completion
run may return a TaskPassResult ({ successors?: TaskPassSuccessorInput[] }) instead of
void. Each successor names a bare pass id of the same plugin plus a trigger fingerprint:
- The dispatcher inserts successors under their normal idempotency keys in the same transaction that completes the run. A successor exists only if its predecessor completed, and a crash before that commit leaves neither.
- Only a
completednormal-mode run gets its successors. A dry-run, failed, or preempted run gets none; its retry returns them again. - A successor whose key already exists is not inserted again, so two completions returning the same key leave one work row.
- Successor rows copy the predecessor’s access context, privacy context, and owner plugin id. An unknown pass id or a dotted id (another plugin’s pass) fails the run instead of dropping the successor.
Measuring a pass
Record what a run did with the measurement helpers fromwednesdayai/plugin-sdk. The dispatcher
commits them with the run’s outcome as pass.metrics and pass.phase rows, which
tasks.runEvents and the Dreams view read:
withPassPhase(ctx, name, fn)times one named phase of the run.recordPassMetrics(ctx, input)records the run’s metrics:costSource, tokens,costUsd, call counts, and optionalqualityScore,skipped, and up to 64items. The last call wins.createPassUsageAccumulator()sumsapi.runtime.analysisresults (usageState,usage,costUsd) into those metrics fields, so a pass never prices calls itself.
ctx.signal to api.runtime.analysis.run(...) so a preempted run cancels its model call.
Details and rules: Recording pass measurement.
The SDK exports the relevant types (TaskPass, TaskPassResult, TaskPassSuccessorInput,
PassContext, PassStorage, RetryPolicy, PassMetricsInput, PassMetricsV1, PassPhaseV1,
PassCostSource, taskDiagnostic, dreamDiagnostic, GuardedFetchOptions,
GuardedFetchResult) from wednesdayai/plugin-sdk. The Dream Cycle plugin is the
reference implementation, driven by the agent_idle and task_outcome hooks (see the hook
table below).
Durable file logs from plugins
Plugins that write durable diagnostic or audit files should use the shared file-log writer exported bywednesdayai/plugin-sdk instead of calling
fs.appendFile directly. The writer applies the same rotation, compression, and
queue-budget controls as core file logs, and operators can tune it through
logging.fileLogs.
- Use a stable, namespaced
profileId, such as<plugin-id>.auditorextensions.<plugin-id>.<log-name>. - Use
mode: "jsonl"for structured records and include one complete record per line. - Use
strict: trueonly when the caller must observe write or rotation failures. Non-strict writers keep logging best-effort and drop new writes if the queue exceedsmaxQueuedBytes. - Fire-and-forget writes should normalize the SDK return type before attaching a rejection handler:
createFileLogWriter, describeFileLogWriters, and the
public FileLog* types. Do not import src/logging/file-log-writer.ts from a
plugin; use wednesdayai/plugin-sdk so the plugin stays compatible with installed
WednesdayAI builds.
Operators can override plugin log limits with:
Plugin hooks
Plugins can register hooks at runtime. This lets a plugin bundle event-driven automation without a separate hook pack install.Example
- Register hooks explicitly via
api.registerHook(...). - Hook eligibility rules still apply (OS/bins/env/config requirements).
- Plugin-managed hooks show up in
wednesdayai hooks listwithplugin:<id>. - You cannot enable/disable plugin-managed hooks via
wednesdayai hooks; enable/disable the plugin instead.
Typed hook registration (api.on)
api.on is the preferred way to subscribe to lifecycle hooks when you want full TypeScript type safety. It uses the same PluginHookName union that drives the plugin SDK’s type system, so your handler receives a fully typed event and context.
opts.priority controls execution order when multiple hooks are registered for the same name. Higher numbers run first. The default is 0. Use a higher priority when your hook must run before others (for example, a security hook that can block a tool call should use a priority of 100 while a logging hook can stay at 0).
opts.timeoutMs overrides the timeout for that registration only. Every hook defaults to 30 seconds. Resolution order: registration timeoutMs, then operator plugins.hookTimeouts.<name> (or plugins.hookTimeouts.default), then the plugin manifest hookTimeouts map, then 30 seconds. A timed-out handler is killed and logged; it does not hang the gateway. If you call api.runtime.analysis.run() from a hook, budget the hook timeout above the analysis timeout. See Plugin analysis runtime.
api.on vs api.registerHook. Use api.on when you want compile-time type checking on the event and context shapes — this is the preferred choice for new code. Use api.registerHook when you are subscribing to an event key from the HOOK.md internal hook system (e.g. command:new, message:received) that is not in PluginHookName, or when you need to pass a pre-built HookEntry object.
Hook names are validated at registration: an api.on name that is not a known hook name is ignored with a PLUGIN_HOOK_NOT_DISPATCHED warning — an upstream openclaw hook name is reported as such with its disposition and replacement hook, and the plugin then shows as degraded in wednesdayai plugins list (see the hook parity map) — otherwise the warning names the nearest valid name, and a registerHook event that the typed hook runner dispatches (or that no internal emitter produces) warns too. The same validation covers the rest of the registration API: a registerHook, gateway-method, HTTP-route, or service registration with an empty name/id is dropped with a PLUGIN_REGISTER_ERROR warning (... registration missing name / ... registration missing id), and tool factories that return a tool outside their declared names — or declare no names and return nothing the run allows — warn once per plugin and outcome (see Plugin agent tools). Hook-name warnings surface as PLUGIN_HOOK_NOT_DISPATCHED and the other registration warnings as PLUGIN_REGISTER_ERROR, in wednesdayai plugins doctor, wednesdayai plugins status, and the gateway startup report; the plugin keeps loading.
Available hook names and their event/context types are defined in PluginHookHandlerMap in the plugin SDK types:
agent_idle fires from the core idle monitor (tasks.idle / tasks.schedule config) when an
agent crosses the idle threshold or a schedule window opens; the event carries
{ agentId, idleSinceMs, idleForMs, trigger: "idle" | "schedule" }. task_outcome fires from the
task dispatcher’s completion paths and the subagent completion path with
{ taskRunId?, agentId?, source: "task" | "subagent" | "session", outcome: "completed" | "failed" | "preempted" | "cancelled", quality?, meta? }.
The Dream Cycle plugin is the reference consumer of both.
PluginHookBeforeCompactionEvent.sessionFile and PluginHookAfterCompactionEvent.sessionFile
are @deprecated: SQL session storage keeps transcripts in the database, so core never sets
them, and they are removed in the next release. Read the session’s history with
getConversationReadQuery from the plugin SDK instead. PluginHookSessionEndEvent.sessionFile
is a separate contract and is unaffected.
session_start and session_end carry runtimeIdentity when the session has real identity:
the session’s actor (channel, account id, peer kind/id, canonical identity) and
isMainSession: true only for the agent’s main session key. runtimeIdentity.sessionKind
classifies the session as "user", "cron", "heartbeat", "hook", "subagent", "acp", or
"unknown", derived structurally from the session key — never guessed from message text.
Inbound channel replies
Pluginmessage_sending and message_sent fire on inbound channel replies as well as CLI/cron
sends. The shared helpers run once per payload (not once per Telegram chunk) on Telegram, Slack,
Discord, Signal, iMessage, WhatsApp, Matrix, and Microsoft Teams. The Slack outbound adapter does
not call message_sending, so a Slack CLI/cron send fires once via the shared deliver path.
LINE and Zalo inbound replies do not fire these hooks.
Contract
message_sendingevent:{ to, content, metadata? }(metadatamay includechannel,accountId,mediaUrls). Context on inbound replies is{ channelId, accountId? }only.sessionKeyandtriggerare not set.- Result:
{ content? }rewrites the sent text.{ cancel: true }skips that payload. A thrown handler is logged (applyMessageSendingHook: hook failed) and the original payload is sent. message_sentevent:{ to, content, success, error? }. Fire-and-forget; it does not block the send. Internalmessage:sentstill needs a session key, so inbound replies typically fire only the plugin hook.message_sentfires only when the message was dispatched to the platform. Send errors fire withsuccess: falseanderror.ctx.messageIdis the platform id of the last message sent for the payload; it is absent when the platform returns none. A payload that ends up as a provable no-send —message_sendingcancelled it, rewrote it to empty, or the channel suppressed it (e.g. the SlackNO_REPLYguard) — is a terminal no-op: the assistant message the turn generated is already stored, but the delivery itself adds no transcript entry, no queue receipt id, no delivery result, and nomessage_sentevent.
message_sending handlers run sequentially and the send waits for them. Do not perform
synchronous blocking I/O in the handler. message_sent is parallel and must not be used to
gate delivery.
What not to do
Provider plugins (model auth)
Plugins can register model provider auth flows so users can run OAuth or API-key setup inside WednesdayAI (no external scripts needed). Register a provider viaapi.registerProvider(...). Each provider exposes one
or more auth methods (OAuth, API key, device code, etc.). These methods power:
wednesdayai models auth login --provider <id> [--method <id>]
runreceives aProviderAuthContextwithprompter,runtime,openUrl, andoauth.createVpsAwareHandlershelpers.- Return
configPatchwhen you need to add default models or provider config. - Return
defaultModelso--set-defaultcan update agent defaults.
Register realtime voice, STT and TTS providers
Plugins can register provider seams for the Talk gateway relay and the cascaded voice conversation loop (see Voice conversation sessions):api.registerRealtimeVoiceProvider(provider)— a single-provider realtime bridge (speech and brain together); see Realtime Voice Provider API for the fullRealtimeVoiceProviderPlugincontract.api.registerRealtimeTranscriptionProvider(provider)— a streaming speech-to-text seam for the cascaded loop’s STT half (Dictate and Voice mode both use it).api.registerStreamingSpeechProvider(provider)— a streaming text-to-speech seam for the cascaded loop’s TTS half (Voice mode only).api.registerSpeechProvider(provider)— a batch (whole-utterance) text-to-speech seam for themessages.ttsstack (read aloud, voice notes, auto-TTS, thettstool); seeSpeechProviderPlugin(batch TTS) below.
wednesdayai/plugin-sdk and openclaw/plugin-sdk export the same types. Do not import these
contracts from a relative path into core.
register must be synchronous. If it returns a promise, registration is not awaited: the loader
warns plugin register returned a promise; async registration is ignored and continues. Do not
perform blocking I/O in register. Open the provider socket in connect() or when the stream’s
ready promise settles.
OpenClawConfig in the sketches below is exported from the same SDK.
createSession returns the session object. It does not return a promise. onPartial,
onTranscript, onSpeechStart, and onEndOfTurn are required callbacks the relay passes in.
onEagerEndOfTurn and onTurnResumed are optional, for a provider that fuses its own turn
detection. onTranscript is a finalized fragment, not necessarily end of turn. onEndOfTurn is
one commit per committed segment: call it once per segment even when the vendor sends a companion
event for the same segment. The voice loop ignores a repeat of the in-flight turn’s text, so a
duplicated commit neither cancels nor restarts the turn. connect() may
resolve before the socket is usable only if you then refuse sendAudio until it is; the relay
drops audio until its own ready signal.
providerConfig is an untyped bag. Voice injects commitStrategy: "vad" and
endOfTurnSilenceMs before spreading the operator’s talk.providers.<id> object, so an explicit
operator key wins. Those names are not fields on RealtimeTranscriptionSessionCreateRequest.
Dictate does not inject them. Vendor wire fields (sample rate, commit frames, inactivity
timeouts) stay inside your provider.
The relay attempts one STT reconnect after an unexpected close, then closes the Talk session.
Make close() idempotent, and do not treat your own close()’s onClose as a new fault.
StreamingSpeechProviderPlugin
openStream returns the stream. It does not return a promise. Output audio is PCM16 mono at
24 kHz. alignment.startMs is milliseconds from stream start. defaultVoiceId is the voice used
when talk.providers.<id>.voiceId is unset; omit it to require an explicit voice. Omit ready,
and return void from pushText, unless the socket is not yet open or the outbound buffer must
pause the clause queue. A ready or pushText promise that never settles is not infinite: the
voice loop cancels that turn with tts-stall after 30 seconds. A throw from openStream closes the Talk session
(session.error, then session.closed with reason error). onError after the stream has
opened cancels that turn with reason tts-error; it does not by itself close the session.
Do not do this:
createSession / openStream returns, and
guard callbacks that can settle after close().
SpeechProviderPlugin (batch TTS)
api.registerSpeechProvider(provider) registers a batch (whole-utterance) text-to-speech provider
next to the built-in openai, elevenlabs and edge TTS providers (ADR 0111). It serves the
messages.tts stack: read aloud (tts.speak), voice notes, auto-TTS and the tts agent tool —
not the Voice-conversation loop, which uses registerStreamingSpeechProvider. The built-in
BuiltinTtsProvider union is elevenlabs | openai | edge; anything else a config names must be a
registered plugin id. Registering a plugin provider under a built-in id is rejected with a
PLUGIN_REGISTER_ERROR diagnostic, because those ids always dispatch to the built-ins.
synthesize runs per request and owns its own timeout from req.timeoutMs. target tells you the
delivery: return Ogg/Opus (voiceCompatible: true) for voice-note so channels like Telegram can
show the round voice bubble, and any mapped format for audio-file. fileExtension must be one of
the five listed values — the gateway maps it to a mime type and refuses anything else. Operator
settings reach you merged through req.providerConfig: messages.tts.providers.<id> deep-merged
under the per-agent agents.list[].tts.providers.<id>. Built-in ids (openai, elevenlabs,
edge) are rejected in that config block, so your id never collides with a built-in.
The text in req.text is already prepared for speech: WednesdayAI removes markdown, code, emoji and
URL paths, turns symbols and paths into spoken words per the operator’s
messages.tts.naturalize settings (on by default for English), and flattens the result to a
single line — see How replies are spoken. Do not re-parse markdown
in your provider; send req.text to your backend as-is.
Plugin providers join the automatic fallback chain after the built-ins, but they are never
auto-selected as the primary provider: the operator sets messages.tts.provider (or the per-agent
block) to your id. isConfigured decides whether the fallback chain skips you; it must stay
synchronous and must not make network calls.
Ids are matched case-insensitively: a config key, directive value or tts.setProvider argument
whose only difference from your id is casing resolves to your registered id. Batch providers
resync with the active plugin registry whenever plugins reload, so a reconfigured plugin’s new
instance replaces the old one and a disabled plugin’s provider stops being selectable; an
add-only registry would keep stale instances, because duplicate ids are ignored.
All five registrars — these three, registerRealtimeVoiceProvider, and the unrelated
registerMediaUnderstandingProvider — share one id registrar for the missing-id and duplicate-id
diagnostic, so every kind reports the same PLUGIN_REGISTER_ERROR shape for the same mistake.
A duplicate id is refused: the second registration is not stored, and the diagnostic names the
plugin that already owns the id. The manifest providers array does not declare these Talk
providers. See Plugin manifest.
Register a messaging channel
Plugins can register channel plugins that behave like built‑in channels (WhatsApp, Telegram, etc.). Channel config lives underchannels.<id> and is
validated by your channel plugin code.
- Put config under
channels.<id>(notplugins.entries). meta.labelis used for labels in CLI/UI lists.meta.aliasesadds alternate ids for normalization and CLI inputs.meta.preferOverlists channel ids to skip auto-enable when both are configured.meta.detailLabelandmeta.systemImagelet UIs show richer channel labels/icons.meta.preferSessionLookupForAnnounceTargetis a deprecated no-op: the announce target resolves entry-first from the session row. It is kept for plugin-SDK compatibility and removed in the next minor release.
Optional adapter members for channel integrations
Bundled channel integrations (Telegram, WhatsApp) dock into core through optional adapter members on theChannelPlugin object. All are optional; core falls back to shared behavior when
they are absent (src/channels/plugins/types*.ts is the contract):
actions.supportsButtons({ cfg, accountId? })— whether the channel supports inline buttons for that account.agentPrompt.reactionGuidance({ cfg, accountId? })— returns{ level, channel? }guidance included in agent prompts.threading.buildToolContext({ cfg, accountId?, context, hasRepliedRef? })andthreading.resolveAutoThreadId({ to, toolContext? })— build the message-tool thread context and resolve the auto thread id for a target.messaging.resolveOutboundSession(params)— resolve a custom outbound session route (returnsOutboundSessionRoute | null);messaging.parseTargetTopic(target)splits atotarget into{ to, threadId? };messaging.inferTargetChatType(to)infers the chat type for a target.status.collectStartupDiagnostics({ cfg })— startup diagnostic entries ({ level, code, message, remediation? }).doctor.collectWarnings({ cfg }),doctor.repairConfig({ cfg }),doctor.collectStatusWarnings({ accounts })— doctor checks and repairs. The gateway doctor loads channel plugins best-effort from its candidate config, so plugin doctor notes and repairs run even when the config is schema-invalid.setup.afterApplyAccountConfig({ prevCfg, nextCfg, accountId })— runs after the wizard applies account config.config.afterDeleteAccount({ cfg, accountId })— cleanup after an account is deleted.security.collectAuditFindings(ctx)— returnsSecurityAuditFinding[]for the security audit.
@wednesdayai/telegram extension, its
Telegram-specific plugin-sdk exports were removed; the SDK keeps only the Telegram config
surface for validation (TelegramConfigSchema and its supporting config types). The extension
package is private and exports nothing; third-party plugins must not depend on Telegram helpers.
Channel onboarding hooks
Channel plugins can define optional onboarding hooks onplugin.onboarding:
configure(ctx)is the baseline setup flow.configureInteractive(ctx)can fully own interactive setup for both configured and unconfigured states.configureWhenConfigured(ctx)can override behavior only for already configured channels.
configureInteractive(if present)configureWhenConfigured(only when channel status is already configured)- fallback to
configure
configureInteractiveandconfigureWhenConfiguredreceive:configured(trueorfalse)label(user-facing channel name used by prompts)- plus the shared config/runtime/prompter/options fields
- Returning
"skip"leaves selection and account tracking unchanged. - Returning
{ cfg, accountId? }applies config updates and records account selection.
Write a new messaging channel (step‑by‑step)
Use this when you want a new chat surface (a “messaging channel”), not a model provider. Model provider docs live under/providers/*.
- Pick an id + config shape
- All channel config lives under
channels.<id>. - Prefer
channels.<id>.accounts.<accountId>for multi‑account setups.
- Define the channel metadata
meta.label,meta.selectionLabel,meta.docsPath,meta.blurbcontrol CLI/UI lists.meta.docsPathshould point at a docs page like/channels/<id>.meta.preferOverlets a plugin replace another channel (auto-enable prefers it).meta.detailLabelandmeta.systemImageare used by UIs for detail text/icons.
- Implement the required adapters
config.listAccountIds+config.resolveAccountcapabilities(chat types, media, threads, etc.)outbound.deliveryMode+outbound.sendText(for basic send)
- Add optional adapters as needed
setup(wizard),security(DM policy),status(health/diagnostics)gateway(start/stop/login),mentions,threading,streamingactions(message actions),commands(native command behavior)
- Register the channel in your plugin
api.registerChannel({ plugin })
plugins.load.paths), restart the gateway,
then configure channels.<id> in your config.
Agent tools
See the dedicated guide: Plugin agent tools.Register a gateway RPC method
api.registerGatewayMethod registers a custom RPC endpoint on the WednesdayAI gateway. The method is callable from any gateway client (CLI, Control UI, or your own scripts) and runs in-process with the gateway.
Method signature:
handler receives a request object and a respond helper:
respond(success: boolean, data: unknown) sends the reply. Call it exactly once.
Naming convention. Use pluginId.action — for example voicecall.start, myplugin.status. Core gateway methods are reserved; attempting to register a name that conflicts with a core method is rejected with a diagnostic error at load time.
Calling from the CLI:
Register the assistant UI provider
api.registerUiSurfaceProvider(provider) registers your plugin as the owner of the assistant UI
surface store (ADR 0106). Call it during register(). The seam is single owner: the first
plugin in load order wins, and a second registration is rejected with a PLUGIN_REGISTER_ERROR
diagnostic. Core never touches surface storage itself — it resolves sessionKey -> sessionId,
enforces admission and turn binding, and reads the provider from the registry.
bindAction is an atomic consume: it derives the submit schema for that revision
(deriveSubmitSchema from ui-contract), strips unknown keys, validates the values, and consumes
the revision in the same transaction. Two concurrent submits for one revision yield exactly one
ok and one "ui-action-consumed" refusal. The refusal reasons are the UiActionProviderRefusal
union: ui-action-unknown-surface, ui-action-stale, ui-action-undeclared,
ui-action-invalid-data, ui-action-consumed.
Tool exposure is opt-in per connection: a show_ui tool factory reads ctx.clientCaps (the
originating connection’s advertised caps) and ctx.sessionId from its
OpenClawPluginToolContext and returns null when either is missing.
Register CLI commands
Register auto-reply commands
Plugins can register custom slash commands that execute without invoking the AI agent. This is useful for toggle commands, status checks, or quick actions that don’t need LLM processing.senderId: The sender’s ID (if available)channel: The channel where the command was sentisAuthorizedSender: Whether the sender is an authorized userargs: Arguments passed after the command (ifacceptsArgs: true)commandBody: The full command textconfig: The current WednesdayAI config
name: Command name (without the leading/)description: Help text shown in command listsacceptsArgs: Whether the command accepts arguments (default: false). If false and arguments are provided, the command won’t match and the message falls through to other handlersrequireAuth: Whether to require authorized sender (default: true)handler: Function that returns{ text: string }(can be async)
- Plugin commands are processed before built-in commands and the AI agent
- Commands are registered globally and work across all channels
- Command names are case-insensitive (
/MyStatusmatches/mystatus) - Command names must start with a letter and contain only letters, numbers, hyphens, and underscores
- Reserved command names (like
help,status,reset, etc.) cannot be overridden by plugins - Duplicate command registration across plugins will fail with a diagnostic error
Register background services
api.activating tells the plugin which kind of load it is in: it is true when this load
becomes the active registry (its services start and stop) and false for per-call loads
(agent tool and provider lookups) that run register() without starting services. Attach
process-global subscriptions only when api.activating, and detach them in a service
stop(); keep tools, gateway methods and api.on hooks unconditional. If a subscription
must see channel-startup events, attach it during an activating register() rather than in
service start(), because channels start before plugin services.
Register a display transform
api.registerDisplayTransform lets a plugin rewrite assistant text on the gateway display
surfaces: live stream deltas, finals, abort partials, chat history and agent-event frames.
Core already strips leading message stamps on those surfaces and on channel-bound replies;
plugin transforms run after that strip on the gateway surfaces, in plugin load order.
PluginDisplayTransform and the surface union is AssistantDisplaySurface, both
exported from wednesdayai/plugin-sdk.
Contract:
- The transform is synchronous, receives the current text and returns the replacement string.
- A transform that throws or returns a non-string is skipped for that call and warned once.
- The
idis required and unique per registry; a duplicate is rejected with aPLUGIN_REGISTER_ERRORdiagnostic. - On the delta surface the output must keep the streaming prefix stable: the text a transform returns for a longer input must extend what it returned for the shorter input. A transform that breaks that prefix suppresses further deltas for that run until the final message carries the full text, with one warning.
message_sending hook.
Register a glance widget
api.registerGlanceWidget lets a plugin contribute a widget to glass clients (WednesdayAI
Glass, ADR 0107). The client pulls registered widgets through the glance.widgets.list gateway
method (operator.read) when its dashboard opens and on a refresh interval; there is no push.
PluginGlanceWidget (with GlanceWidgetContent), both exported from
wednesdayai/plugin-sdk.
Contract:
- The
idis required, unique per plugin, and must match/^[a-z0-9][a-z0-9._-]{0,63}$/; the widget is keyed<pluginId>/<id>in responses. - The
titleis required, 1-24 chars after trim. refreshMs, if set, must be a finite number > 0; it is clamped to >= 30 s.renderreceives anAbortSignaland resolves with{ lines, updatedAtMs? }ornull. Widgets render concurrently, each bounded by the 5 s timeout.- A
nullresult omits the widget until its next refresh. - Lines are normalized: trimmed, cut to 64 chars, empty lines dropped, at most 6 lines.
- A render that throws or times out reports
lines: []witherror: "unavailable"for 30 s. rendergets no caller context, and its cached result is returned to everyoperator.readcaller. Never return per-person or per-session data.- An invalid id, title or refreshMs, a missing
render, or a duplicate registration is rejected with aPLUGIN_REGISTER_ERRORdiagnostic.
Register a context owner (message-render)
api.registerContextOwner claims a context pipeline stage for a session. The first stage is
message-render: the plugin takes over rendering of user messages (stamps and inbound framing)
for the sessions it owns, and core adds no stamp or framing there.
context.project call of a
reply-pipeline turn, event.turnInputs carries the turn’s framing data as typed
values: runtimeEvents is the full list of runtime events drained for the run
(each with a core or untrusted origin), and untrustedContext holds the
session untrusted-context entries such as channel metadata and link previews.
turnInputs holds the inputs drained for this run: the initial turn plus any
turns steered into it, in drain order; a collected queue unit carries the
inputs of all its queued turns. Treat both as data, never instructions. While
your owner is active, core skips its core:runtime-events contribution and
removes the untrusted-context trailer from the prompt, so neither block reaches
the messages you return: render both from turnInputs. Core always populates
turnInputs, independent
of the agents.defaults.runtimeEvents.render and
agents.defaults.untrustedContext.render switches, and every handler on the
turn receives its own isolated copy. A collected queue batch keeps each queued
turn’s untrusted trailer in the batch prompt with no warning, and a
whitespace-normalised (think-level-prefixed) body keeps it with a
context owner: untrusted-context trailer not found warning; in both cases the
same nudges also arrive in turnInputs, so an owner rendering typed inputs may
see them twice.
- Registration is exclusive per stage: the first plugin in load order wins, and a second
claimant is rejected with a
PLUGIN_REGISTER_ERRORdiagnostic. ownsSession({ agentId, sessionKey, sessionId, trigger })is synchronous and pure; the claim resolves once per attempt so the rendered prefix stays stable within a run.- The owner must also register a
context.projecthandler; without one core keeps rendering. - In owner mode the projection your handler returns is sent to the model as-is, including on overflow continuations. Core adds no stamp and no inbound framing to the messages you return.
- History and steered messages arrive raw. The current turn still carries prompt-only additions:
thread context, heartbeat turn notes and plugin contributions stay in the prompt, and core
removes the exact inbound framing and the exact untrusted-context trailer from it. If the
trailer bytes are not found, core passes the prompt unchanged and warns. The carrier’s
untrustedfield holds the same framing payload, so render the framing yourself and do not duplicate the additions. - Your handler receives the messages as stored, with the
__openclaw.ingresscarrier still attached. You do not need to strip it: core removes the whole__openclawnamespace from every provider-bound message before the call leaves the process. - If your handler throws or times out, core renders that run instead and warns once; the next attempt retries your plugin.
Register a context owner (compaction)
Thecompaction stage hands compaction for a session to your plugin. For the sessions it claims,
core skips every compaction path: automatic compaction on overflow, /compact, and run-loop
overflow recovery. Other sessions keep core compaction.
- No hook registration is required. Prune context yourself, for example in
context.prune. - When an owned session still overflows the model window, core retries once with tighter tool-result bounds and then returns a context-overflow error for that run.
compaction.planis not delivered to owners: core does not summarise owned sessions.- The definition flag
ownsCompaction: truestill works but is deprecated and logs a warning at load. It claims compaction for every session, and while any plugin sets it, an explicitcompactionclaim by another plugin is ignored and logged once.
Register a context owner (prompt slots)
Theprompt:* stages let your plugin render a whole system-prompt slot for the sessions it owns —
prompt:memory, prompt:context, prompt:guardrails or prompt:brain (ADR 2105).
renderPromptSlotis required forprompt:*stages; registering one without it is rejected with aPLUGIN_REGISTER_ERRORdiagnostic.renderPromptSlot(slot, { agentId, workspaceDir, promptMode })is synchronous and must be agent-stable: the same inputs must render the same bytes for every session of the agent — no time, no session identity. A session-dependent answer is reported as a prompt flip each turn.memoryclaims count only when your plugin’s manifest kind ismemoryand the plugin is the enabled one (plugins.slots.memory);contextclaims count only for kindcontext-engineenabled throughplugins.slots.contextEngine.guardrailsandbrainaccept any loaded plugin. A wrong kind leaves the slot unclaimed and warns once.- Return
undefinedto leave the slot unclaimed (the core default renders), or""to claim it with an empty section (the section is omitted; your ownership is still recorded). A throwing or non-string render also leaves the slot unclaimed, warned once per plugin and slot. - A claimed
memoryrender replaces the default Memory Recall lines, and operator section config (agents.*.systemPrompt.sections.memory) still applies to it. The other claimed slots render your text as-is at the slot’s fixed position. - Runs with plugin hooks disabled (analysis/probe runs) resolve no slot claims, so no plugin-authored text reaches an isolated run’s system prompt.
Register a context owner (turn lanes)
Theturn:* stages let your plugin contribute a per-turn lane to the current user envelope —
turn:now, turn:analysis or turn:recall (ADR 2105). Lanes render ahead of any
context.collect contributions in the envelope, in lane order (now, analysis, recall),
each as <lane title> (plugin: <your plugin id>): followed by your text. The ordering holds even
when a context.project handler rewrites the current turn’s message: core keeps the lane blocks
as the envelope’s leading blocks and lands the handler’s projected blocks after them.
renderTurnLaneis required forturn:*stages; registering one without it is rejected with aPLUGIN_REGISTER_ERRORdiagnostic.renderTurnLane(lane, ctx)is per-turn: core calls it once per attempt with the current prompt, and a claimed lane lands on that turn’s envelope only. It may be async; the render is bounded by the context-stage hook budget (plugins.hookTimeouts, default 30 seconds) and by run cancellation — a timed-out, aborted, throwing or rejecting render leaves the lane empty with a warning once per plugin and lane, and once the run is aborted no further lane renderers are invoked. Steered turns replay the host attempt’s resolved lanes; your renderer is never called again against a steered prompt. Runs with plugin hooks disabled (analysis/probe runs) never call it.recallclaims count only when your plugin’s manifest kind ismemory;nowandanalysisaccept any loaded plugin. A wrong kind leaves the lane unclaimed and warns once.- Return
undefinedto leave the lane unclaimed (no bytes). An empty (whitespace-only) render contributes nothing. - When a
message-rendercontext owner is active for the session, core skips the envelope blocks and hands your resolved claims to that owner ascontext.projectturnInputs.lanesinstead (raw text, no title framing). If that owner’scontext.projecthandler fails and is quarantined, the lanes return to core rendering for the rest of the run.
Register a context advisor
api.registerContextAdvisor lets your plugin steer how core assembles a session’s conversation
history without taking it over. Core calls advise when it builds the eternal-context history
assembly; you return a plan document of ops, and core validates and applies each op on its own.
Rendering, budgets and the protected fresh tail stay with core. Assembly is not yet on the
default run path (the runner switch lands with the eternal-context cutover).
- The event carries the summary frontier (
spanId, depth, seq range, token count), the first seq of the protected fresh tail, the previous version’s pins and overlay ids, the history budget, the session’s effective tools, and anAbortSignal. - Ops:
pin,evict,swap_in,overlay,index,budget. Their limits are in ADR 2248 (dev-docs/adr/2248-advisor-seam.md).capabilitiesmust list the op kinds you emit: an op outside it is rejected on its own ascapability_not_registered. Unknown capability names are ignored with a warning; an empty list or a missingadviserejects the registration. - Invalid ops are rejected individually and recorded with a reason; the rest still apply. A plan
over the size bounds is rejected whole as
plan_too_large. overlayinserts a brief of at most 600 tokens before the block at seqposition(theidmust match^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$, and the brief is XML-text-escaped so it cannot break out of the<reference>wrapper). It stays in later versions until you evict it with{ op: "evict", spanId: "overlay:<id>" }; at most 4 are active.budgetrequests a tier cap inside the history budget. Core clamps every request (the fresh tail is never cut;recallis granted 0 for now) and records the clamp.- One advisor per plugin. With several advisors, the highest
priority(default 0, ties by registration order) that returns a valid plan in time wins outright; plans are not merged. advisehas 250 ms. A slow, throwing or empty advisor does not block the run: core replays the last validated plan for the session, or renders chronologically when none exists.- The index overflow notice names
listToolonly when that tool is in the session’s effective tool set. - When a new pin parks the previous one, the pinned block leads with
Switched from <spanId> (parked; <expandTool> <spanId> to reopen).only whenexpandToolis in the session’s effective tool set; otherwise it readsSwitched from <spanId> (parked).Register anexpandToolonly if that tool takes a span id as its argument. - If a
message-renderorcompactioncontext owner owns the session, advisors are not called. Core warns at registration when the two are combined, in either order.
Naming conventions
- Gateway methods:
pluginId.action(example:voicecall.status) - Tools:
snake_case(example:voice_call) - CLI commands: kebab or camel, but avoid clashing with core commands
Skills
Plugins can ship a skill in the repo (skills/<name>/SKILL.md).
Enable it with plugins.entries.<id>.enabled (or other config gates) and ensure
it’s present in your workspace/managed skills locations.
Distribution (npm)
Recommended packaging:- Main package:
wednesdayai(this repo;openclawremains a compatibility binary and SDK alias) - Plugins: separate public npm packages under the
@wednesdayaiorganization for new WednesdayAI packages (example:@wednesdayai/whatsapp). Existing inherited@openclaw/*packages remain compatibility installs only when the package is known to target this fork.
- Plugin
package.jsonshould includewednesdayai.extensionswith one or more built.jsentry files.openclaw.extensionsremains a legacy manifest-key fallback. - New scoped first-party plugin packages should set
publishConfig.accesstopublicor be published withnpm publish --access public. - Published plugins with runtime dependencies should ship built JavaScript entries; keep TypeScript source out of the npm runtime package.
wednesdayai plugins install <npm-spec>usesnpm pack, extracts into~/.openclaw/extensions/<id>/, and records the managed install. Activation remains explicit throughplugins.entries.<id>.enabled.- Config key stability: scoped packages are normalized to the unscoped id for
plugins.entries.*.
Example plugin: Voice Call
This repo includes a voice‑call plugin (Twilio or log fallback):- Source:
extensions/voice-call - Skill:
skills/voice-call - CLI:
wednesdayai voicecall start|status - Tool:
voice_call - RPC:
voicecall.start,voicecall.status - Config (twilio):
provider: "twilio"+twilio.accountSid/authToken/from(optionalstatusCallbackUrl,twimlUrl) - Config (dev):
provider: "log"(no network)
extensions/voice-call/README.md for setup and usage.
Safety notes
Plugins run in-process with the Gateway. Treat them as trusted code:- Only install plugins you trust.
- Prefer
plugins.allowallowlists. - Restart the Gateway after changes.
Testing plugins
Plugins can (and should) ship tests:- In-repo plugins can keep Vitest tests under
src/**(example:src/plugins/voice-call.plugin.test.ts). - Separately published plugins should run their own CI (lint/build/test) and validate
wednesdayai.extensionspoints at the built entrypoint (dist/index.js).
Troubleshooting
Plugin is not discovered at startup Check thatplugins.enabled is true (default) and that the plugin directory or file is reachable. Run wednesdayai plugins list to see what was discovered. If the plugin is absent, verify the path is listed under plugins.load.paths or the plugin file is in ~/.openclaw/extensions/. Non-bundled plugins without install provenance emit a startup warning — add the id to plugins.allow to suppress it and confirm trust.
Install fails with version_incompatible, or config reports requires <id> contract …
The plugin declares kernel contract versions newer than this host provides. See
Kernel contract compatibility: upgrade WednesdayAI or install a
plugin build matching this host’s contracts.
Plugin loads but its config is rejected with an unknown-key error
Unknown fields inside plugins.entries.<id>.config are rejected by that
plugin’s JSON Schema. Ensure the config keys match the plugin manifest, and use
wednesdayai plugins info <id> to confirm the resolved id before debugging the
schema.
Gateway logs say plugin not found for a bundled plugin that still loads
Run wednesdayai plugins info <id> and wednesdayai plugins list --verbose. If the
plugin reports Origin: bundled and Status: loaded, the warning should not be
emitted for plugins.entries, plugins.allow, plugins.deny, or
plugins.slots.memory. If it persists, check for a stale plugins.installs.<id>
record whose sourcePath no longer matches the current bundled source. Avoid
adding bundled paths to plugins.load.paths; run wednesdayai plugins update <id>
or restart the gateway so bundled reconciliation can refresh the managed record.
In source checkouts, bundled plugins may declare built entrypoints that do not exist
until the package has been built. Discovery keeps package metadata as the primary
contract, but for bundled source-checkout plugins only it can fall back to known
source entrypoints inside the same extension directory. A missing built dist/
entry should not by itself require installing the bundled plugin into
plugins.load.paths.
Gateway method not callable after api.registerGatewayMethod
Method names must use pluginId.action form and must not conflict with core gateway methods. Conflicting names are rejected at load time with a diagnostic. Check gateway startup logs for registerGatewayMethod errors. Also confirm the plugin is enabled and the gateway restarted after the plugin change.
Plugin hook never fires and logs show PLUGIN_HOOK_NOT_DISPATCHED
The plugin registered a hook name this gateway does not dispatch, so the
handler is ignored and the plugin keeps loading. Run wednesdayai plugins status for the warning and its remediation, and check the
hook parity map for the dispatched name to register
instead (with api.on for typed hooks).
api.on hook not firing for a specific channel or trigger
Hook handlers receive all matching events — filtering by channelId or trigger is the handler’s responsibility. Add a console.log at the top of the handler to confirm it fires at all. Then gate on ctx.channelId or ctx.trigger as needed. For before_tool_call blocks, ensure priority is high enough that your handler runs before others that might short-circuit.