Überblick über das Plugin SDK

​

Importkonvention

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

​

Subpfad-Referenz

​

Registrierungs-API

​

Capability-Registrierung

​

Tools und Befehle

agentPromptGuidance: [
  "Global command hint.",
  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },
];

​

Infrastruktur

​

Host-Hooks für Workflow-Plugins

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

• Externe Plugins können Sitzungserweiterungen, UI-Deskriptoren, Befehle, Tool- Metadaten, Next-Turn-Injektionen und normale Hooks verantworten.
• Vertrauenswürdige Tool-Richtlinien werden vor gewöhnlichen before_tool_call-Hooks ausgeführt und sind host-vertrauenswürdig. Gebündelte Richtlinien laufen zuerst; Richtlinien installierter Plugins erfordern explizite Aktivierung plus ihre lokalen IDs in contracts.trustedToolPolicies und laufen anschließend in Plugin-Ladereihenfolge. Richtlinien-IDs sind auf das registrierende Plugin beschränkt.
• Reservierte Befehlszuständigkeit ist nur gebündelt verfügbar. Externe Plugins sollten ihre eigenen Befehlsnamen oder Aliase verwenden.
• allowPromptInjection=false deaktiviert Prompt-verändernde Hooks einschließlich agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, Prompt-Felder aus dem alten before_agent_start und enqueueNextTurnInjection.

​

Gateway-Discovery-Registrierung

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-Registrierungsmetadaten

• commands: explizite Befehlsnamen, die dem Registrar gehören
• descriptors: Parse-Time-Befehlsdeskriptoren, die für CLI-Hilfe, Routing und Lazy-Plugin-CLI-Registrierung verwendet werden
• parentPath: optionaler übergeordneter Befehlspfad für verschachtelte Befehlsgruppen, etwa ["nodes"]

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,
      },
    ],
  },
);

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Capture or render canvas content from a paired node",
        hasSubcommands: true,
      },
    ],
  },
);

​

CLI-Backend-Registrierung

• Die Backend-id wird zum Provider-Präfix in Modellreferenzen wie my-cli/gpt-5.
• Die Backend-config verwendet dieselbe Form wie agents.defaults.cliBackends.<id>.
• Die Benutzerkonfiguration hat weiterhin Vorrang. OpenClaw führt agents.defaults.cliBackends.<id> mit dem Plugin-Standard zusammen, bevor die CLI ausgeführt wird.
• Verwenden Sie normalizeConfig, wenn ein Backend nach dem Zusammenführen Kompatibilitätsumschreibungen benötigt (zum Beispiel zum Normalisieren alter Flag-Formen).
• Verwenden Sie resolveExecutionArgs für anfragebezogene argv-Umschreibungen, die zum CLI-Dialekt gehören, etwa das Zuordnen von OpenClaw-Denkstufen zu einem nativen Effort- Flag. Der Hook erhält ctx.executionMode; verwenden Sie "side-question", um backend-native Isolations-Flags für kurzlebige /btw-Aufrufe hinzuzufügen. Wenn diese Flags native Tools für eine sonst immer aktive CLI zuverlässig deaktivieren, deklarieren Sie zusätzlich sideQuestionToolMode: "disabled".

​

Exklusive Slots

​

Veraltete Speicher-Embedding-Adapter

• registerMemoryCapability ist die bevorzugte exklusive Speicher-Plugin-API.
• registerMemoryCapability kann außerdem publicArtifacts.listArtifacts(...) verfügbar machen, damit Begleit-Plugins exportierte Speicherartefakte über openclaw/plugin-sdk/memory-host-core nutzen können, statt in das private Layout eines bestimmten Speicher-Plugins zu greifen.
• registerMemoryPromptSection, registerMemoryFlushPlan und registerMemoryRuntime sind legacy-kompatible exklusive Speicher-Plugin-APIs.
• MemoryFlushPlan.model kann den Flush-Turn an eine exakte provider/model- Referenz wie ollama/qwen3:8b binden, ohne die aktive Fallback- Kette zu erben.
• registerMemoryEmbeddingProvider ist veraltet. Neue Embedding-Provider sollten api.registerEmbeddingProvider(...) und contracts.embeddingProviders verwenden.
• Bestehende speicherspezifische Provider funktionieren während des Migrationsfensters weiterhin, aber Plugin-Inspektionsberichte weisen dies bei nicht gebündelten Plugins als Kompatibilitätsschuld aus.

​

Ereignisse und Lifecycle

​

Semantik von Hook-Entscheidungen

• before_tool_call: Die Rückgabe von { block: true } ist terminal. Sobald ein Handler sie setzt, werden Handler mit niedrigerer Priorität übersprungen.
• before_tool_call: Die Rückgabe von { block: false } wird als keine Entscheidung behandelt (genauso wie das Weglassen von block), nicht als Überschreibung.
• before_install: Die Rückgabe von { block: true } ist terminal. Sobald ein Handler sie setzt, werden Handler mit niedrigerer Priorität übersprungen.
• before_install: Die Rückgabe von { block: false } wird als keine Entscheidung behandelt (genauso wie das Weglassen von block), nicht als Überschreibung.
• reply_dispatch: Die Rückgabe von { handled: true, ... } ist terminal. Sobald ein Handler den Dispatch beansprucht, werden Handler mit niedrigerer Priorität und der Standardpfad für Modell-Dispatch übersprungen.
• message_sending: Die Rückgabe von { cancel: true } ist terminal. Sobald ein Handler sie setzt, werden Handler mit niedrigerer Priorität übersprungen.
• message_sending: Die Rückgabe von { cancel: false } wird als keine Entscheidung behandelt (genauso wie das Weglassen von cancel), nicht als Überschreibung.
• message_received: Verwenden Sie das typisierte Feld threadId, wenn Sie eingehendes Thread-/Themen-Routing benötigen. Behalten Sie metadata für kanalspezifische Extras bei.
• message_sending: Verwenden Sie die typisierten Routing-Felder replyToId / threadId, bevor Sie auf kanalspezifische metadata zurückfallen.
• gateway_start: Verwenden Sie ctx.config, ctx.workspaceDir und ctx.getCron?.() für Gateway-eigenen Startzustand, statt sich auf interne gateway:startup-Hooks zu verlassen.
• cron_changed: Beobachtet Änderungen am Gateway-eigenen Cron-Lifecycle. Verwenden Sie event.job?.state?.nextRunAtMs und ctx.getCron?.(), wenn Sie externe Wake-Scheduler synchronisieren, und behalten Sie OpenClaw als maßgebliche Quelle für Fälligkeitsprüfungen und Ausführung bei.

​

API-Objektfelder

​

Interne Modulkonvention

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: öffentliche api.ts- / contract-api.ts-Nahtstelle für Claude- Beta-Header- und service_tier-Stream-Helfer.
• @openclaw/openai-provider: api.ts exportiert Provider-Builder, Standardmodell-Helfer und Realtime-Provider-Builder.
• @openclaw/openrouter-provider: api.ts exportiert den Provider-Builder plus Onboarding-/Konfigurationshelfer.

​

Verwandt