Plugin-SDK-Übersicht

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.

​

Importkonvention

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

​

Unterpfadreferenz

​

Registrierungs-API

​

Capability-Registrierung

​

Tools und Befehle

​

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 besitzen.
• Vertrauenswürdige Tool-Richtlinien werden vor gewöhnlichen before_tool_call-Hooks ausgeführt und sind nur gebündelten Plugins vorbehalten, weil sie an der Host-Sicherheitsrichtlinie beteiligt sind.
• Reservierte Befehlszuständigkeit ist nur gebündelten Plugins vorbehalten. Externe Plugins sollten ihre eigenen Befehlsnamen oder Aliasse 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-Zeit-Befehlsdeskriptoren, die für CLI-Hilfe, Routing und verzögerte Plugin-CLI-Registrierung verwendet werden
• parentPath: optionaler übergeordneter Befehlspfad für verschachtelte Befehlsgruppen, zum Beispiel ["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 codex-cli/gpt-5.
• Die Backend-config verwendet dieselbe Form wie agents.defaults.cliBackends.<id>.
• Benutzerkonfiguration gewinnt weiterhin. OpenClaw führt agents.defaults.cliBackends.<id> über der Plugin-Standardeinstellung zusammen, bevor die CLI ausgeführt wird.
• Verwenden Sie normalizeConfig, wenn ein Backend nach dem Zusammenführen Kompatibilitätsumschreibungen benötigt (zum Beispiel das Normalisieren alter Flag-Formen).
• Verwenden Sie resolveExecutionArgs für anfragebezogene argv-Umschreibungen, die zum CLI-Dialekt gehören, zum Beispiel das Abbilden von OpenClaw-Denkstufen auf ein natives Effort- Flag.

​

Exklusive Slots

​

Speicher-Embedding-Adapter

• registerMemoryCapability ist die bevorzugte exklusive Speicher-Plugin-API.
• registerMemoryCapability kann auch publicArtifacts.listArtifacts(...) offenlegen, damit Companion-Plugins exportierte Speicherartefakte über openclaw/plugin-sdk/memory-host-core konsumieren können, anstatt 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 binden, zum Beispiel ollama/qwen3:8b, ohne die aktive Fallback- Kette zu erben.
• registerMemoryEmbeddingProvider lässt das aktive Speicher-Plugin eine oder mehrere Embedding-Adapter-IDs registrieren (zum Beispiel openai, gemini oder eine benutzerdefinierte, Plugin-definierte ID).
• Benutzerkonfiguration wie agents.defaults.memorySearch.provider und agents.defaults.memorySearch.fallback wird gegen diese registrierten Adapter-IDs aufgelöst.

​

Ereignisse und Lifecycle

​

Hook-Entscheidungssemantik

• 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 (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 (wie das Weglassen von block), nicht als Überschreibung.
• reply_dispatch: Die Rückgabe von { handled: true, ... } ist terminal. Sobald ein Handler den Versand beansprucht, werden Handler mit niedrigerer Priorität und der Standardpfad für Modellversand ü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 (wie das Weglassen von cancel), nicht als Überschreibung.
• message_received: Verwenden Sie das typisierte Feld threadId, wenn Sie Routing eingehender Threads/Themen 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, anstatt sich auf interne gateway:startup-Hooks zu verlassen.
• cron_changed: Beobachten Sie Gateway-eigene Cron-Lifecycle-Änderungen. Verwenden Sie event.job?.state?.nextRunAtMs und ctx.getCron?.(), wenn Sie externe Wake-Scheduler synchronisieren, und behalten Sie OpenClaw als Source of Truth 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 Echtzeit-Provider-Builder.
• @openclaw/openrouter-provider: api.ts exportiert den Provider-Builder sowie Onboarding-/Konfigurations-Helfer.

​

Verwandt