​

Plugin SDK Overview

​

Import convention

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

​

Subpath reference

​

Plugin entry

​

Registration API

​

Capability registration

​

Tools and commands

​

Infrastructure

​

CLI registration metadata

• commands: explicit command roots owned by the registrar
• descriptors: parse-time command descriptors used for root CLI help, routing, and lazy plugin CLI registration

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Manage Matrix accounts, verification, devices, and profile state",
        hasSubcommands: true,
      },
    ],
  },
);

​

CLI backend registration

• The backend id becomes the provider prefix in model refs like codex-cli/gpt-5.
• The backend config uses the same shape as agents.defaults.cliBackends.<id>.
• User config still wins. OpenClaw merges agents.defaults.cliBackends.<id> over the plugin default before running the CLI.
• Use normalizeConfig when a backend needs compatibility rewrites after merge (for example normalizing old flag shapes).

​

Exclusive slots

​

Memory embedding adapters

• registerMemoryCapability is the preferred exclusive memory-plugin API.
• registerMemoryCapability may also expose publicArtifacts.listArtifacts(...) so companion plugins can consume exported memory artifacts through openclaw/plugin-sdk/memory-host-core instead of reaching into a specific memory plugin’s private layout.
• registerMemoryPromptSection, registerMemoryFlushPlan, and registerMemoryRuntime are legacy-compatible exclusive memory-plugin APIs.
• registerMemoryEmbeddingProvider lets the active memory plugin register one or more embedding adapter ids (for example openai, gemini, or a custom plugin-defined id).
• User config such as agents.defaults.memorySearch.provider and agents.defaults.memorySearch.fallback resolves against those registered adapter ids.

​

Events and lifecycle

​

Hook decision semantics

• before_tool_call: returning { block: true } is terminal. Once any handler sets it, lower-priority handlers are skipped.
• before_tool_call: returning { block: false } is treated as no decision (same as omitting block), not as an override.
• before_install: returning { block: true } is terminal. Once any handler sets it, lower-priority handlers are skipped.
• before_install: returning { block: false } is treated as no decision (same as omitting block), not as an override.
• reply_dispatch: returning { handled: true, ... } is terminal. Once any handler claims dispatch, lower-priority handlers and the default model dispatch path are skipped.
• message_sending: returning { cancel: true } is terminal. Once any handler sets it, lower-priority handlers are skipped.
• message_sending: returning { cancel: false } is treated as no decision (same as omitting cancel), not as an override.
• message_received: use the typed threadId field when you need inbound thread/topic routing. Keep metadata for channel-specific extras.
• message_sending: use typed replyToId / threadId routing fields before falling back to channel-specific metadata.
• gateway_start: use ctx.config, ctx.workspaceDir, and ctx.getCron?.() for gateway-owned startup state instead of relying on internal gateway:startup hooks.

​

API object fields

​

Internal module convention

my-plugin/
  api.ts            # Public exports for external consumers
  runtime-api.ts    # Internal-only runtime exports
  index.ts          # Plugin entry point
  setup-entry.ts    # Lightweight setup-only entry (optional)

• @openclaw/openai-provider: api.ts exports provider builders, default-model helpers, and realtime provider builders
• @openclaw/openrouter-provider: api.ts exports the provider builder plus onboarding/config helpers

​

Related

• Entry Points — definePluginEntry and defineChannelPluginEntry options
• Runtime Helpers — full api.runtime namespace reference
• Setup and Config — packaging, manifests, config schemas
• Testing — test utilities and lint rules
• SDK Migration — migrating from deprecated surfaces
• Plugin Internals — deep architecture and capability model