Plugin SDK overview

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Import convention

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

​

Subpath reference

​

Registration API

​

Capability registration

​

Tools and commands

​

Infrastructure

​

Host hooks for workflow plugins

• External plugins can own session extensions, UI descriptors, commands, tool metadata, next-turn injections, and normal hooks.
• Trusted tool policies run before ordinary before_tool_call hooks and are bundled-only because they participate in host safety policy.
• Reserved command ownership is bundled-only. External plugins should use their own command names or aliases.
• allowPromptInjection=false disables prompt-mutating hooks including agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, prompt fields from legacy before_agent_start, and enqueueNextTurnInjection.

​

Gateway discovery registration

api.registerGatewayDiscoveryService({
  id: "my-discovery",
  async advertise(ctx) {
    const handle = await startMyAdvertiser({
      gatewayPort: ctx.gatewayPort,
      tls: ctx.gatewayTlsEnabled,
      displayName: ctx.machineDisplayName,
    });
    return { stop: () => handle.stop() };
  },
});

​

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).
• Use resolveExecutionArgs for request-scoped argv rewrites that belong to the CLI dialect, such as mapping OpenClaw thinking levels to a native effort flag.

​

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.
• MemoryFlushPlan.model can pin the flush turn to an exact provider/model reference, such as ollama/qwen3:8b, without inheriting the active fallback chain.
• 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.
• cron_changed: observe gateway-owned cron lifecycle changes. Use event.job?.state?.nextRunAtMs and ctx.getCron?.() when syncing external wake schedulers, and keep OpenClaw as the source of truth for due checks and execution.

​

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)

• Anthropic: public api.ts / contract-api.ts seam for Claude beta-header and service_tier stream helpers.
• @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