Skip to main content

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:
  1. See what’s already loaded:
  1. Install an official plugin (example: Voice Call):
Npm specs are registry-only (package name + optional version/tag). Git and URL specs are rejected; local directory and archive paths are also supported (see CLI below). WhatsApp is published as the first dependency-bearing first-party npm plugin. 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.
  1. Restart the Gateway, then configure under plugins.entries.<id>.config.
See Voice Call for a concrete example plugin. Looking for third-party listings? See Community plugins.

Available plugins (official)

  • Microsoft Teams is plugin-only as of 2026.1.15; install @openclaw/msteams if 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-copilot device 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)
WednesdayAI plugins are TypeScript modules loaded at runtime via jiti. Config validation does not execute plugin code; it uses the plugin manifest and JSON Schema instead. See Plugin manifest. Plugins can register:
  • 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 skills directories in the plugin manifest)
  • Auto-reply commands (execute without invoking the AI agent)
  • Provider runtime hooks for provider-specific request shaping
Plugins run in‑process with the Gateway, so treat them as trusted code. Tool authoring guide: Plugin agent tools.

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 parsing sessionKey, reading identityLinks, or reconstructing turn boundaries from timestamps or message text.
ctx.runtimeIdentity may include:
  • agentId, agentName, agentWorkspacePath, and agentWorkspaceName
  • sessionId and sessionKey when a real session exists for the hook
  • channelConversationId for the transport conversation/thread
  • providerConversationId for the opaque model/provider cache partition
  • laneId — the opaque lane-<hash> digest, present only for an allowed multi-lane run; undefined for single-user and denied resolutions (see Workspace Lanes)
  • trusted sender fields such as senderId, senderName, senderUsername, senderE164, messageProvider, canonicalIdentity, and senderIsOwner
  • 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 supplies canonicalIdentity without knowing its provenance — provenance is never guessed, so identitySource implies canonicalIdentity but not the reverse
  • sessionKind — 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.
  • peerKind and peerId — the actual input peer’s kind ("direct", "group", "channel") and id, exposed under every dmScope value.
  • isMainSession — true only when sessionKey equals 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:
  • conversationId is a legacy alias for channelConversationId; it is never the provider/model cache identity.
  • providerConversationId is intentionally opaque. Persist it only as an opaque correlation/cache key.
  • sessionId and sessionKey are optional on early hooks. Do not synthesize fake session values when they are absent.
  • Core may use session.identityLinks internally, but plugins should consume only the resolved identity fields or the api.runtime.identity helpers (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.
The context uses an [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:
Plugin tool factories and tool lifecycle hooks receive the same optional 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:
These fields are additive. Existing plugins should treat them as optional and keep their current behavior when they are absent. Use 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 with api.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 to streamFn.
  • 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.
Provider hooks should pass opaque provider-safe identifiers such as 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 via api.runtime. For telephony TTS:
Notes:
  • Uses core messages.tts configuration (OpenAI or ElevenLabs).
  • Returns PCM audio buffer + sample rate. Plugins must resample/encode for providers.
  • Edge TTS is not supported for telephony.
For STT/transcription, plugins can call:
Notes:
  • 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> with api: "openai-completions" or "openai-responses") needs no plugin extension, but voice notes are never auto-detected on it — name a speech-to-text model in tools.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 through api.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 the session.identityLinks key a channel sender is linked to, using the same resolution the gateway applies to inbound messages. See Runtime and turn identity for the provenance-aware ctx.runtimeIdentity fields; 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), or undefined when 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 refuses device: values (identity_link_invalid; devices have their own operator path, and plugins issue an enrollment instead), and a value another person already holds throws identity_link_conflict.
  • await api.runtime.identity.issueEnrollment({ person, profile, codeChallenge? }) mints a device bootstrap for an existing person and returns { bootstrapToken, expiresAtMs }. profile is "user-client" (the web client) or "wednesdayai-glass-node" (WednesdayAI Glass); any other value throws. An unknown person throws identity_unknown. codeChallenge is an optional RFC 7636 S256 challenge (43 base64url characters); when set, the device must present the matching verifier as auth.bootstrapCodeVerifier to 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 is issueEnrollment({ 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 }. running is true only in the running state; disabled means 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). startupEntryId is 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 with api.enqueueTaskWork will 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, or absent per fingerprint. It accepts at most 200 fingerprints and only this plugin’s own passes (taskId is 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 returns null when 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 with complete(), fail(error) and abort(reason?); call exactly one when the turn ends. A turn without runId gets a unique one.

Time and stamp helpers

  • api.runtime.time.timezone is 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; ms defaults to now.
  • api.runtime.time.parseLeadingStamps(text) parses leading message stamps (canonical GMT±H[:MM], zoneless, and legacy abbreviation forms) and returns { body, stamps, pending }; stripLeadingStamps(text) returns body. A fragment that may still become a stamp (a bracket without a closing bracket, at most 40 characters) is reported as pending with 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 through api.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 matching writeOptions (envSnapshotForRestore and expectedConfigPath) for a read-modify-write flow. Pass the returned writeOptions when 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 optional onError callback 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:
The carrier is data, never display text: core never renders it, strips it from every client-facing payload such as chat.history, and strips it from every provider-bound message, so it never reaches the model wire either.

Discovery & precedence

WednesdayAI scans, in order:
  1. Config paths
  • plugins.load.paths (file or directory)
  1. Workspace extensions
  • <workspace>/.openclaw/extensions/*.ts
  • <workspace>/.openclaw/extensions/*/index.ts
  1. Global extensions
  • ~/.openclaw/extensions/*.ts
  • ~/.openclaw/extensions/*/index.ts
  1. Bundled extensions (shipped with WednesdayAI, disabled by default)
  • <wednesdayai>/extensions/*
Bundled plugins must be enabled explicitly via 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.allow is 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).
Each plugin must include a 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 a package.json with wednesdayai.extensions:
Each entry becomes a plugin. If the pack lists multiple extensions, the plugin id becomes 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:
The installer runs 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:
Prefer this over 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 via wednesdayai.channel and install hints via wednesdayai.install. This keeps the core catalog data-free. Example:
WednesdayAI can also merge external channel catalogs (for example, an MPM registry export). Drop a JSON file at one of:
  • ~/.openclaw/mpm/plugins.json
  • ~/.openclaw/mpm/catalog.json
  • ~/.openclaw/plugins/catalog.json
Or point 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.json name
  • Standalone file: file base name (~/.../voice-call.ts → voice-call)
If a plugin exports id, WednesdayAI uses it but warns when it doesn’t match the configured id.

Config

Fields:
  • enabled: master toggle (default: true)
  • allow: allowlist (optional)
  • deny: denylist (optional; deny wins)
  • load.paths: extra plugin files/dirs
  • installs.<id>: CLI-managed install metadata. source is one of npm, archive, path, or bundled.
  • entries.<id>: per‑plugin toggles + config
Config changes require a gateway restart. Validation rules:
  • Unknown plugin ids in entries, allow, deny, or slots emit 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 its sourcePath matches 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.json configSchema, 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. Let wednesdayai plugins install, wednesdayai plugins update, or bundled reconciliation create and refresh managed install metadata.
  • Valid bundled install records suppress false plugin not found warnings for entries, allow, deny, and slots.memory, but their plugins.entries.<id>.config object is still validated against the bundled manifest’s configSchema.
  • 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 legacy openclaw.plugin.json still 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). Use plugins.slots to select which plugin owns the slot:
If multiple plugins declare 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 uses config.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>
If you want your plugin config fields to show good labels/placeholders (and mark secrets as sensitive), provide 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 in wednesdayai.plugin.json (legacy openclaw.plugin.json still loads) (contracts). When a plugin needs newer kernel contracts than this host provides:
  • Install refuses: wednesdayai plugins install fails with code version_incompatible and a message like plugin "<id>" is not compatible with this host: <reason>. Upgrade WednesdayAI and retry. Nothing is installed. A malformed contracts field 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 at plugins.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 makes wednesdayai config validate, plugins list and 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.
Details, the full contract table and the versioning rules: Versioned kernel contracts.

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 registers cron-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.
Rules that matter:
  • 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. enqueueTaskWork rejects until the task pipeline has started; call it from hook handlers or services, not from register() itself.
  • Pass ids are namespaced <pluginId>.<passId> automatically — enqueue with the bare id. A dotted id ("learning-core.promote") is rejected at register time. Core cron-run / heartbeat-tick are 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 / dreamDiagnostic from wednesdayai/plugin-sdk (or openclaw/plugin-sdk). Builders are input-shaped (no ts/seq). Do not cast ad-hoc objects. Use live field names passId and attempts. OTel export: Task and dream spans. Recovery ceiling behavior (age stall / attempt exhaust → dlq): Task pipeline. Treat updatedAt / startedAt on a run record as ISO-Z. Do not Date.parse a 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 completed normal-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 from wednesdayai/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 optional qualityScore, skipped, and up to 64 items. The last call wins.
  • createPassUsageAccumulator() sums api.runtime.analysis results (usageState, usage, costUsd) into those metrics fields, so a pass never prices calls itself.
Pass 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 by wednesdayai/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.
Guidance:
  • Use a stable, namespaced profileId, such as <plugin-id>.audit or extensions.<plugin-id>.<log-name>.
  • Use mode: "jsonl" for structured records and include one complete record per line.
  • Use strict: true only when the caller must observe write or rotation failures. Non-strict writers keep logging best-effort and drop new writes if the queue exceeds maxQueuedBytes.
  • Fire-and-forget writes should normalize the SDK return type before attaching a rejection handler:
The SDK also exports 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

Notes:
  • Register hooks explicitly via api.registerHook(...).
  • Hook eligibility rules still apply (OS/bins/env/config requirements).
  • Plugin-managed hooks show up in wednesdayai hooks list with plugin:<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.
Method signature:
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

Plugin message_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_sending event: { to, content, metadata? } (metadata may include channel, accountId, mediaUrls). Context on inbound replies is { channelId, accountId? } only. sessionKey and trigger are 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_sent event: { to, content, success, error? }. Fire-and-forget; it does not block the send. Internal message:sent still needs a session key, so inbound replies typically fire only the plugin hook.
  • message_sent fires only when the message was dispatched to the platform. Send errors fire with success: false and error. ctx.messageId is 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_sending cancelled it, rewrote it to empty, or the channel suppressed it (e.g. the Slack NO_REPLY guard) — 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 no message_sent event.
Blocking the send 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
Operator overview: Inbound channel replies.

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 via api.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>]
Example:
Notes:
  • run receives a ProviderAuthContext with prompter, runtime, openUrl, and oauth.createVpsAwareHandlers helpers.
  • Return configPatch when you need to add default models or provider config.
  • Return defaultModel so --set-default can 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 full RealtimeVoiceProviderPlugin contract.
  • 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 the messages.tts stack (read aloud, voice notes, auto-TTS, the tts tool); see SpeechProviderPlugin (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:
Do this instead: defer every callback until after 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 under channels.<id> and is validated by your channel plugin code.
Notes:
  • Put config under channels.<id> (not plugins.entries).
  • meta.label is used for labels in CLI/UI lists.
  • meta.aliases adds alternate ids for normalization and CLI inputs.
  • meta.preferOver lists channel ids to skip auto-enable when both are configured.
  • meta.detailLabel and meta.systemImage let UIs show richer channel labels/icons.
  • meta.preferSessionLookupForAnnounceTarget is 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 the ChannelPlugin 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? }) and threading.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 (returns OutboundSessionRoute | null); messaging.parseTargetTopic(target) splits a to target 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) — returns SecurityAuditFinding[] for the security audit.
When Telegram was extracted from core into the bundled @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 on plugin.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.
Hook precedence in the wizard:
  1. configureInteractive (if present)
  2. configureWhenConfigured (only when channel status is already configured)
  3. fallback to configure
Context details:
  • configureInteractive and configureWhenConfigured receive:
    • configured (true or false)
    • 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/*.
  1. Pick an id + config shape
  • All channel config lives under channels.<id>.
  • Prefer channels.<id>.accounts.<accountId> for multi‑account setups.
  1. Define the channel metadata
  • meta.label, meta.selectionLabel, meta.docsPath, meta.blurb control CLI/UI lists.
  • meta.docsPath should point at a docs page like /channels/<id>.
  • meta.preferOver lets a plugin replace another channel (auto-enable prefers it).
  • meta.detailLabel and meta.systemImage are used by UIs for detail text/icons.
  1. Implement the required adapters
  • config.listAccountIds + config.resolveAccount
  • capabilities (chat types, media, threads, etc.)
  • outbound.deliveryMode + outbound.sendText (for basic send)
  1. Add optional adapters as needed
  • setup (wizard), security (DM policy), status (health/diagnostics)
  • gateway (start/stop/login), mentions, threading, streaming
  • actions (message actions), commands (native command behavior)
  1. Register the channel in your plugin
  • api.registerChannel({ plugin })
Minimal config example:
Minimal channel plugin (outbound‑only):
Load the plugin (extensions dir or 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:
The 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:
Use cases: custom health checks, plugin-specific data queries, triggering plugin-managed actions (start a call, flush a cache, reload config) without touching core gateway methods. Full example:

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.
Command handler context:
  • senderId: The sender’s ID (if available)
  • channel: The channel where the command was sent
  • isAuthorizedSender: Whether the sender is an authorized user
  • args: Arguments passed after the command (if acceptsArgs: true)
  • commandBody: The full command text
  • config: The current WednesdayAI config
Command options:
  • name: Command name (without the leading /)
  • description: Help text shown in command lists
  • acceptsArgs: 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 handlers
  • requireAuth: Whether to require authorized sender (default: true)
  • handler: Function that returns { text: string } (can be async)
Example with authorization and arguments:
Notes:
  • 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 (/MyStatus matches /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.
The type is 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 id is required and unique per registry; a duplicate is rejected with a PLUGIN_REGISTER_ERROR diagnostic.
  • 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.
What not to do on the delta surface:
Use display transforms for output cleanup on gateway consumers (UI streams, history, agent events). Display transforms do not run on channel sends: to rewrite channel-bound payloads, use the 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.
The type is PluginGlanceWidget (with GlanceWidgetContent), both exported from wednesdayai/plugin-sdk. Contract:
  • The id is required, unique per plugin, and must match /^[a-z0-9][a-z0-9._-]{0,63}$/; the widget is keyed <pluginId>/<id> in responses.
  • The title is required, 1-24 chars after trim.
  • refreshMs, if set, must be a finite number > 0; it is clamped to >= 30 s.
  • render receives an AbortSignal and resolves with { lines, updatedAtMs? } or null. Widgets render concurrently, each bounded by the 5 s timeout.
  • A null result 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: [] with error: "unavailable" for 30 s.
  • render gets no caller context, and its cached result is returned to every operator.read caller. Never return per-person or per-session data.
  • An invalid id, title or refreshMs, a missing render, or a duplicate registration is rejected with a PLUGIN_REGISTER_ERROR diagnostic.

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.
Turn framing is part of the hand-off. On every 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.
Contract:
  • Registration is exclusive per stage: the first plugin in load order wins, and a second claimant is rejected with a PLUGIN_REGISTER_ERROR diagnostic.
  • 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.project handler; 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 untrusted field 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.ingress carrier still attached. You do not need to strip it: core removes the whole __openclaw namespace 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)

The compaction 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.
Contract:
  • 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.plan is not delivered to owners: core does not summarise owned sessions.
  • The definition flag ownsCompaction: true still works but is deprecated and logs a warning at load. It claims compaction for every session, and while any plugin sets it, an explicit compaction claim by another plugin is ignored and logged once.

Register a context owner (prompt slots)

The prompt:* 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).
Contract:
  • renderPromptSlot is required for prompt:* stages; registering one without it is rejected with a PLUGIN_REGISTER_ERROR diagnostic.
  • 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.
  • memory claims count only when your plugin’s manifest kind is memory and the plugin is the enabled one (plugins.slots.memory); context claims count only for kind context-engine enabled through plugins.slots.contextEngine. guardrails and brain accept any loaded plugin. A wrong kind leaves the slot unclaimed and warns once.
  • Return undefined to 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 memory render 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)

The turn:* 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.
Contract:
  • renderTurnLane is required for turn:* stages; registering one without it is rejected with a PLUGIN_REGISTER_ERROR diagnostic.
  • 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.
  • recall claims count only when your plugin’s manifest kind is memory; now and analysis accept any loaded plugin. A wrong kind leaves the lane unclaimed and warns once.
  • Return undefined to leave the lane unclaimed (no bytes). An empty (whitespace-only) render contributes nothing.
  • When a message-render context owner is active for the session, core skips the envelope blocks and hands your resolved claims to that owner as context.project turnInputs.lanes instead (raw text, no title framing). If that owner’s context.project handler 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).
Contract:
  • 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 an AbortSignal.
  • Ops: pin, evict, swap_in, overlay, index, budget. Their limits are in ADR 2248 (dev-docs/adr/2248-advisor-seam.md). capabilities must list the op kinds you emit: an op outside it is rejected on its own as capability_not_registered. Unknown capability names are ignored with a warning; an empty list or a missing advise rejects 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.
  • overlay inserts a brief of at most 600 tokens before the block at seq position (the id must 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.
  • budget requests a tier cap inside the history budget. Core clamps every request (the fresh tail is never cut; recall is 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.
  • advise has 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 listTool only 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 when expandTool is in the session’s effective tool set; otherwise it reads Switched from <spanId> (parked). Register an expandTool only if that tool takes a span id as its argument.
  • If a message-render or compaction context 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; openclaw remains a compatibility binary and SDK alias)
  • Plugins: separate public npm packages under the @wednesdayai organization for new WednesdayAI packages (example: @wednesdayai/whatsapp). Existing inherited @openclaw/* packages remain compatibility installs only when the package is known to target this fork.
Publishing contract:
  • Plugin package.json should include wednesdayai.extensions with one or more built .js entry files. openclaw.extensions remains a legacy manifest-key fallback.
  • New scoped first-party plugin packages should set publishConfig.access to public or be published with npm 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> uses npm pack, extracts into ~/.openclaw/extensions/<id>/, and records the managed install. Activation remains explicit through plugins.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 (optional statusCallbackUrl, twimlUrl)
  • Config (dev): provider: "log" (no network)
See Voice Call and 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.allow allowlists.
  • 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.extensions points at the built entrypoint (dist/index.js).

Troubleshooting

Plugin is not discovered at startup Check that plugins.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.