​

Plugins (Extensions)

​

Quick start (new to plugins?)

1. See what’s already loaded:

openclaw plugins list

2. Install an official plugin (example: Voice Call):

wednesdayai plugins install voice-call

3. 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/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)

• Gateway RPC methods
• Gateway HTTP handlers
• Agent tools
• CLI commands
• Background services
• 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

​

Runtime and turn identity

import type { OpenClawPluginDefinition } from "wednesdayai/plugin-sdk";

const plugin: OpenClawPluginDefinition = {
  id: "turn-audit",
  async activate(api) {
    api.on("storage.afterAppend", (event, ctx) => {
      const identity = ctx.runtimeIdentity;
      const turn = ctx.turn;

      if (!turn?.turnId) return;

      const appendKey = [
        turn.turnId,
        turn.userEntryId ?? turn.assistantEntryId ?? event.cursor?.entryId ?? event.entry.rawSha256,
      ].join(":");

      api.logger.info("captured append", {
        appendKey,
        agentId: identity?.agentId,
        canonicalIdentity: identity?.canonicalIdentity,
        providerConversationId: identity?.providerConversationId,
      });
    });
  },
};

export default plugin;

• 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

• 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 api.runtime.identity.resolveCanonicalIdentity(...).

const dedupeKey = `${ctx.turn?.turnId}:${event.entry.entryId ?? event.cursor?.entryId ?? event.entry.rawSha256}`;

​

Workspace lane context

context.canonicalIdentity;
context.laneId;
context.workspaceLane;

​

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 OpenClaw 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.

​

Runtime helpers

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

• 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.

const { text } = await api.runtime.stt.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• Uses core media-understanding audio configuration (tools.media.audio) and provider fallback order.
• Returns { text: undefined } when no transcription output is produced (for example skipped/unsupported input).

​

Discovery & precedence

1. Config paths

• plugins.load.paths (file or directory)

2. Workspace extensions

• <workspace>/.openclaw/extensions/*.ts
• <workspace>/.openclaw/extensions/*/index.ts

3. Global extensions

• ~/.openclaw/extensions/*.ts
• ~/.openclaw/extensions/*/index.ts

4. Bundled extensions (shipped with WednesdayAI, disabled by default)

• <wednesdayai>/extensions/*

• 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).

​

Package packs

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"]
  }
}

​

npm 12 and git-protocol dependencies

npm error code EALLOWGIT
npm error Fetching packages of type "git" have been disabled

NPM_CONFIG_ALLOW_GIT=all wednesdayai plugins install <plugin>

​

Channel catalog metadata

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "extensions/nextcloud-talk",
      "defaultChoice": "npm"
    }
  }
}

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

Plugin IDs

• Package packs: package.json name
• Standalone file: file base name (~/.../voice-call.ts → voice-call)

​

Config

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    installs: {
      telegram: {
        source: "bundled",
        sourcePath: "/path/to/extensions/telegram",
        version: "0.4.4",
      },
    },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

• 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

• 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 openclaw.plugin.json (configSchema).
• If a plugin is disabled, its config is preserved and a warning is emitted.

​

Plugin slots (exclusive categories)

{
  plugins: {
    slots: {
      memory: "memory-core", // or "none" to disable memory plugins
    },
  },
}

​

Control UI (schema + labels)

• Adds per-plugin labels for plugins.entries.<id> / .enabled / .config
• Merges optional plugin-provided config field hints under: plugins.entries.<id>.config.<field>

{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": { "type": "string" },
      "region": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API Key", "sensitive": true },
    "region": { "label": "Region", "placeholder": "us-east-1" }
  }
}

​

CLI

wednesdayai plugins list
wednesdayai plugins info <id>
wednesdayai plugins install <path>                 # copy a local file/dir into ~/.openclaw/extensions/<id>
wednesdayai plugins install ./extensions/voice-call # relative path ok
wednesdayai plugins install ./plugin.tgz           # install from a local tarball
wednesdayai plugins install ./plugin.zip           # install from a local zip
wednesdayai plugins install -l ./extensions/voice-call # link (no copy) for dev
wednesdayai plugins install @wednesdayai/voice-call # install from npm
wednesdayai plugins install @wednesdayai/voice-call --pin # store exact resolved name@version
wednesdayai plugins update <id>
wednesdayai plugins update --all
wednesdayai plugins enable <id>
wednesdayai plugins disable <id>
wednesdayai plugins doctor

​

Managed installs vs bundled copies

​

Plugin API (overview)

• A function: (api) => { ... }
• An object: { id, name, configSchema, register(api) { ... } }

​

Durable file logs from plugins

import os from "node:os";
import path from "node:path";
import { appendFileLog } from "wednesdayai/plugin-sdk";

export async function recordAuditEvent(event: unknown) {
  const file = path.join(os.homedir(), ".openclaw", "logs", "my-plugin-audit.jsonl");
  await appendFileLog(`${JSON.stringify(event)}\n`, {
    profileId: "my-plugin.audit",
    file,
    mode: "jsonl",
    fileMode: 0o600,
    strict: true,
  });
}

• 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:

void Promise.resolve(
  appendFileLog(`${JSON.stringify(event)}\n`, {
    profileId: "my-plugin.diagnostics",
    file: path.join(os.homedir(), ".openclaw", "logs", "my-plugin-diagnostics.jsonl"),
    mode: "jsonl",
  }),
).catch(() => undefined);

{
  logging: {
    fileLogs: {
      profiles: {
        "my-plugin.audit": {
          maxFileBytes: 5242880,
          maxBackups: 10,
          compress: "gzip",
          maxQueuedBytes: 262144,
        },
      },
    },
  },
}

​

Plugin hooks

​

Example

export default function register(api) {
  api.registerHook(
    "command:new",
    async () => {
      // Hook logic here.
    },
    {
      name: "my-plugin.command-new",
      description: "Runs when /new is invoked",
    },
  );
}

• Register hooks explicitly via api.registerHook(...).
• Hook eligibility rules still apply (OS/bins/env/config requirements).
• Plugin-managed hooks show up in openclaw hooks list with plugin:<id>.
• You cannot enable/disable plugin-managed hooks via openclaw hooks; enable/disable the plugin instead.

​

Typed hook registration (api.on)

import type { OpenClawPluginApi } from "wednesdayai/plugin-sdk";

export default function (api: OpenClawPluginApi) {
  api.on("message_received", async (event, ctx) => {
    // event is PluginHookMessageReceivedEvent
    // ctx is PluginHookMessageContext
    api.logger.info(`[${ctx.channelId}] body: ${event.content}`);
  });
}

api.on<K extends PluginHookName>(
  hookName: K,
  handler: PluginHookHandlerMap[K],
  opts?: { priority?: number },
): void

// High-priority hook that can block tool calls
api.on(
  "before_tool_call",
  async (event, ctx) => {
    if (event.toolName === "shell_exec" && !isAllowed(ctx.sessionKey)) {
      return { block: true, blockReason: "not authorized" };
    }
  },
  { priority: 100 },
);

// Low-priority logging hook
api.on(
  "after_tool_call",
  async (event, ctx) => {
    logAudit({ tool: event.toolName, sessionKey: ctx.sessionKey });
  },
  { priority: 0 },
);

​

Provider plugins (model auth)

• openclaw models auth login --provider <id> [--method <id>]

api.registerProvider({
  id: "acme",
  label: "AcmeAI",
  auth: [
    {
      id: "oauth",
      label: "OAuth",
      kind: "oauth",
      run: async (ctx) => {
        // Run OAuth flow and return auth profiles.
        return {
          profiles: [
            {
              profileId: "acme:default",
              credential: {
                type: "oauth",
                provider: "acme",
                access: "...",
                refresh: "...",
                expires: Date.now() + 3600 * 1000,
              },
            },
          ],
          defaultModel: "acme/opus-1",
        };
      },
    },
  ],
});

• 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 a messaging channel

const myChannel = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "demo channel plugin.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async () => ({ ok: true }),
  },
};

export default function (api) {
  api.registerChannel({ plugin: myChannel });
}

• 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.

​

Channel onboarding hooks

• 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.

1. configureInteractive (if present)
2. configureWhenConfigured (only when channel status is already configured)
3. fallback to configure

• 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)

1. Pick an id + config shape

• All channel config lives under channels.<id>.
• Prefer channels.<id>.accounts.<accountId> for multi‑account setups.

2. 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.

3. Implement the required adapters

• config.listAccountIds + config.resolveAccount
• capabilities (chat types, media, threads, etc.)
• outbound.deliveryMode + outbound.sendText (for basic send)

4. 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)

5. Register the channel in your plugin

• api.registerChannel({ plugin })

{
  channels: {
    acmechat: {
      accounts: {
        default: { token: "ACME_TOKEN", enabled: true },
      },
    },
  },
}

const plugin = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "AcmeChat messaging channel.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => {
      // deliver `text` to your channel here
      return { ok: true };
    },
  },
};

export default function (api) {
  api.registerChannel({ plugin });
}

​

Agent tools

​

Register a gateway RPC method

api.registerGatewayMethod(method: string, handler: GatewayRequestHandler): void

api.registerGatewayMethod("myplugin.status", ({ params, respond }) => {
  // params is the JSON object passed by the caller
  const detail = params?.verbose ? { uptime: process.uptime() } : {};
  respond(true, { ok: true, ...detail });
});

openclaw gateway call myplugin.status
openclaw gateway call myplugin.status --params '{"verbose": true}'

import type { OpenClawPluginApi } from "wednesdayai/plugin-sdk";

export default function (api: OpenClawPluginApi) {
  let requestCount = 0;

  api.registerGatewayMethod("myplugin.stats", ({ respond }) => {
    respond(true, { requestCount, uptime: process.uptime() });
  });

  api.registerGatewayMethod("myplugin.reset-stats", ({ respond }) => {
    requestCount = 0;
    respond(true, { ok: true });
  });
}

​

Register CLI commands

export default function (api) {
  api.registerCli(
    ({ program }) => {
      program.command("mycmd").action(() => {
        console.log("Hello");
      });
    },
    { commands: ["mycmd"] },
  );
}

​

Register auto-reply commands

export default function (api) {
  api.registerCommand({
    name: "mystatus",
    description: "Show plugin status",
    handler: (ctx) => ({
      text: `Plugin is running! Channel: ${ctx.channel}`,
    }),
  });
}

• 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 OpenClaw config

• 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)

api.registerCommand({
  name: "setmode",
  description: "Set plugin mode",
  acceptsArgs: true,
  requireAuth: true,
  handler: async (ctx) => {
    const mode = ctx.args?.trim() || "default";
    await saveMode(mode);
    return { text: `Mode set to: ${mode}` };
  },
});

• 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

export default function (api) {
  api.registerService({
    id: "my-service",
    start: () => api.logger.info("ready"),
    stop: () => api.logger.info("bye"),
  });
}

​

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

​

Distribution (npm)

• 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.

• 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

• Source: extensions/voice-call
• Skill: skills/voice-call
• CLI: openclaw 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)

​

Safety notes

• Only install plugins you trust.
• Prefer plugins.allow allowlists.
• Restart the Gateway after changes.

​

Testing plugins

• 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 openclaw.extensions points at the built entrypoint (dist/index.js).

​

Troubleshooting

​

Related

• Plugin manifest
• Plugin agent tools
• Hooks
• Voice Call plugin
• Community plugins