Übersicht über das Plugin-SDK

​

Importkonvention

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

​

Unterpfadreferenz

​

Registrierungs-API

​

Registrierung von Fähigkeiten

​

Tools und Befehle

agentPromptGuidance: [
  "Globaler Befehlshinweis.",
  { text: "Dies nur im OpenClaw-Hauptprompt anzeigen.", surfaces: ["openclaw_main"] },
];

​

Infrastruktur

​

Webhook-Arbeit nach der Bestätigung

import { runDetachedWebhookWork } from "openclaw/plugin-sdk/webhook-request-guards";

void runDetachedWebhookWork(() => processWebhookEvent(event)).catch((error) => {
  runtime.error?.(`Webhook-Versand fehlgeschlagen: ${String(error)}`);
});

​

Auf Anfragende begrenzte MCP-Verbindungen

api.registerMcpServerConnectionResolver({
  serverName: "user-email",
  resolve: async (ctx) => {
    // ctx.requesterSenderId wird vom Host als vertrauenswürdig eingestuft; erfinden Sie hier niemals eine Absenderidentität.
    const token = await lookupUserToken(ctx.requesterSenderId);
    if (!token) {
      return null; // diesen Server für die aktuelle Ausführung weglassen
    }
    return {
      url: "https://mcp.example.com/email",
      headers: { Authorization: `Bearer ${token}` },
    };
  },
});

• Der Resolver-Kontext enthält ausschließlich eine vertrauenswürdige Host-Identität (requesterSenderId, optional agentAccountId / messageChannel). Zukünftige vertrauenswürdige Felder (zum Beispiel Cron-/Subagent-Benutzerkontext) können additiv hinzugefügt werden.
• Ein Plugin besitzt genau einen Servernamen: Ein doppeltes registerMcpServerConnectionResolver für denselben serverName von einem anderen Plugin wird mit einer Fehlerdiagnose abgelehnt (die erste Registrierung gewinnt), sodass der Verbindungseigentümer niemals von der Ladereihenfolge der Plugins abhängt.
• Tool-Namen werden aus der vollständigen Menge deklarierter Server abgeleitet, sodass eine teilweise Auflösung sichere Servernamen niemals zwischen Anfragenden oder Durchläufen verändert. Der Core überprüft nicht, ob unterschiedliche Endpunkte für Anfragende identische Tool-Schemas bereitstellen; ein Resolver muss jeden Anfragenden auf denselben logischen Dienst verweisen, andernfalls unterscheiden sich Tool-Schemas (und die Stabilität des Prompt-Caches) je nach Anfragendem.
• Ausführungen ohne vertrauenswürdiges requesterSenderId (Cron, Subagent, Heartbeat, öffentliches Gateway) materialisieren niemals auf Anfragende begrenzte Server. Es gibt keine gemeinsam genutzte Fallback-Verbindung.
• resolve ist auf 10 Sekunden pro Server begrenzt; bei einer Zeitüberschreitung oder Ausnahme wird dieser Server für die Ausführung weggelassen, ohne dass statisches MCP fehlschlägt.
• Aufgelöste Verbindungen werden höchstens alle 5 Minuten pro Anfragendem erneut validiert: Bei einer Rotation wird der Transport mit neuen Anmeldedaten neu aufgebaut, und ein null-Ergebnis widerruft ihn (die zwischengespeicherte Laufzeit wird selbst mitten in einer Sitzung freigegeben). Widerrufene oder rotierte Anmeldedaten können daher bis zu 5 Minuten lang weiterverwendet werden.
• Aufgelöste headers werden niemals protokolliert oder persistiert; der Core hält nur einen flüchtigen, im Arbeitsspeicher abgelegten schlüsselbasierten Digest (prozesslokales HMAC) vor, um die Rotation von Anmeldedaten zu erkennen, und registriert aufgelöste Anmeldedatenwerte aus Headern/URLs in der Schwärzungsregistrierung für Protokollierung und Debug-Erfassung.
• Auf Anfragende begrenzte Server erzeugen keine MCP-App-Ansichten: Eine Ansicht überdauert die durch den Anfragenden authentifizierte Ausführung, und die Begrenzung der Gateway-Ansicht besitzt keine Identität des Anfragenden, daher bleiben App-Vorschauen für diese Server standardmäßig geschlossen. Tool-Ergebnisse sind davon nicht betroffen.
• Statische Server ohne Resolver behalten den bestehenden sitzungsbezogenen Lebenszyklus bei.
• Bereitstellungsregel für Harnesses: Auf Anfragende begrenzte Server gelangen niemals in die Harness-native MCP-Client-Konfiguration (Codex-Thread mcp_servers, CLI -c mcp_servers=… oder eine andere sitzungsübergreifend gemeinsam genutzte MCP-Projektion). Harnesses stellen sie stattdessen als ausführungsbezogene Tools bereit:
  • Eingebetteter Runner: Sitzungs-MCP-Laufzeit + Bundle-Tools (statisch + begrenzt).
  • Codex-App-Server: dynamische Tools über materializeRequesterScopedMcpToolsForHarnessRun (nur begrenzte Tools; statische Server verbleiben im nativen MCP-Client von Codex).
• Begrenzte Tool-Spezifikationen sind nach der ersten erfolgreichen Auflösung in dieser Sitzung sitzungsstabil, sodass Harnesses mit gemeinsam genutzten Threads (Codex) bei einem Wechsel der Absender keine Threads rotieren. Bevor ein Anfragender erfolgreich aufgelöst wurde, werden keine begrenzten Spezifikationen angekündigt.
• Nicht authentifizierte Anfragende in einem Harness mit gemeinsam genutzten Threads sehen weiterhin die angekündigten begrenzten Tools; der Aufruf eines solchen Tools gibt für diesen Anfragenden einen eindeutigen Tool-Fehler wegen fehlender Verbindung zurück. OpenClaw greift niemals auf die Anmeldedaten eines anderen Anfragenden zurück.

​

Host-Hooks für Workflow-Plugins

api.session.controls.registerControlUiDescriptor({
  surface: "tab",
  id: "logbook",
  label: "Logbuch",
  description: "Ihr Tag als Zeitleiste, erstellt aus Bildschirmaufnahmen.",
  icon: "sun",
  group: "control",
  requiredScopes: ["operator.write"],
});

• 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, Injektionen für den nächsten Durchlauf und normale Hooks verwalten.
• Vertrauenswürdige Tool-Richtlinien werden vor gewöhnlichen before_tool_call-Hooks ausgeführt und sind vom Host als vertrauenswürdig eingestuft. Gebündelte Richtlinien werden zuerst ausgeführt; Richtlinien installierter Plugins erfordern eine explizite Aktivierung sowie ihre lokalen IDs in contracts.trustedToolPolicies und werden anschließend in der Ladereihenfolge der Plugins ausgeführt. Richtlinien-IDs sind auf das registrierende Plugin beschränkt.
• Die Eigentümerschaft reservierter Befehle ist ausschließlich 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 und enqueueNextTurnInjection.

​

Registrierung der Gateway-Erkennung

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 im Besitz des Registrierenden
• descriptors: Befehlsdeskriptoren für die Analysephase, die für CLI-Hilfe, Routing und verzögerte Plugin-CLI-Registrierung verwendet werden
• parentPath: optionaler Pfad des übergeordneten Befehls für verschachtelte Befehlsgruppen, beispielsweise ["nodes"]

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Matrix-Konten, Verifizierung, Geräte und Profilstatus verwalten",
        hasSubcommands: true,
      },
    ],
  },
);

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Canvas-Inhalte von einem gekoppelten Node erfassen oder rendern",
        hasSubcommands: true,
      },
    ],
  },
);

​

Registrierung von CLI-Backends

• Die Backend-id wird zum Provider-Präfix in Modellreferenzen wie my-cli/gpt-5.
• Die Backend-config ist der maßgebliche Befehlsadapter: argv, Umgebung, Parser-, Sitzungs-, Bild- und Zuverlässigkeitsverhalten befinden sich im Plugin-Code.
• Benutzer wählen das Backend über Modellreferenzen oder modellbezogene agentRuntime.id aus; openclaw.json schreibt den Adapter nicht um.
• Verwenden Sie normalizeConfig, wenn registrierte statische Felder einen laufzeitabhängigen Normalisierungsdurchlauf benötigen.
• Verwenden Sie resolveExecutionArgs für anfragebezogene argv-Umschreibungen, die zum CLI-Dialekt gehören, etwa um OpenClaw-Denkstufen einem nativen Aufwands-Flag zuzuordnen. 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 ansonsten stets aktive CLI zuverlässig deaktivieren, deklarieren Sie außerdem sideQuestionToolMode: "disabled".
• Verwenden Sie prepareExecution für Backend-eigene Startumgebungen oder temporäre Authentifizierungs-/Konfigurationsbrücken. Das zugehörige ctx.contextTokenBudget ist das effektive Token-Limit, das für den Lauf ausgewählt wurde, sodass Backends mit nativer Compaction ihren eigenen Schwellenwert ohne providerspezifische Core-Verzweigungen abstimmen können. Es erhält außerdem die vom Core vorbereitete ctx.env, wenn das Backend-Staging gebündelte MCP-Einstellungen erweitern muss.
• Backends, die alle nativen Tools für einen bestimmten Lauf deaktivieren können, dürfen nativeToolMode: "selectable" deklarieren. Eingeschränkte Aufrufe übergeben eine exakte ctx.toolAvailability.native-Liste sowie kanonische ctx.toolAvailability.openClaw-Namen. Deklarieren Sie toolAvailabilityEnforcement: "execution-args" und setzen Sie den Vertrag in den endgültigen argv für neue oder fortgesetzte Sitzungen durch, oder deklarieren Sie "prepare-execution", setzen Sie ihn in der bereitgestellten Richtlinie durch und geben Sie toolAvailabilityEnforced: true zurück. OpenClaw deaktiviert native Tools für Laufzeitbeschränkungen wie Cron-toolsAllow und schlägt geschlossen fehl, wenn der deklarierte Durchsetzungspfad unvollständig ist.

​

Exklusive Slots

​

Veraltete Adapter für Speicher-Embeddings

• registerMemoryCapability ist die exklusive Speicher-Plugin-API.
• registerMemoryCapability kann außerdem publicArtifacts.listArtifacts(...) für vom Host verwaltete Exporte bereitstellen. Begleit-Plugins, die diese deklarierten Artefakte auflisten, verwenden weiterhin listActiveMemoryPublicArtifacts(...) aus der beibehaltenen openclaw/plugin-sdk/memory-host-core-Fassade, bis eine gezielte öffentliche Verbraucher-API verfügbar ist; sie dürfen nicht auf die private Struktur eines anderen Plugins zugreifen.
• MemoryFlushPlan.model kann den Flush-Durchlauf an eine exakte provider/model- Referenz wie ollama/qwen3:8b binden, ohne die aktive Fallback-Kette zu übernehmen.
• registerMemoryEmbeddingProvider ist veraltet. Neue Embedding-Provider sollten api.registerEmbeddingProvider(...) und contracts.embeddingProviders verwenden.
• Bestehende speicherspezifische Provider funktionieren während des Migrationszeitraums weiterhin, bei der Plugin-Inspektion wird dies für nicht gebündelte Plugins jedoch als Kompatibilitätsschuld ausgewiesen.

​

Ereignisse und Lebenszyklus

​

Entscheidungssemantik von Hooks

• before_tool_call: Die Rückgabe von { block: true } ist endgültig. Sobald ein Handler diesen Wert setzt, werden Handler mit niedrigerer Priorität übersprungen.
• before_tool_call: Die Rückgabe von { block: false } gilt als keine Entscheidung (wie das Auslassen von block), nicht als Überschreibung.
• before_install: Die Rückgabe von { block: true } ist endgültig. Sobald ein Handler diesen Wert setzt, werden Handler mit niedrigerer Priorität übersprungen.
• before_install: Die Rückgabe von { block: false } gilt als keine Entscheidung (wie das Auslassen von block), nicht als Überschreibung.
• reply_dispatch: Die Rückgabe von { handled: true, ... } ist endgültig. Sobald ein Handler den Dispatch beansprucht, werden Handler mit niedrigerer Priorität und der standardmäßige Modell-Dispatch-Pfad übersprungen.
• message_sending: Die Rückgabe von { cancel: true } ist endgültig. Sobald ein Handler diesen Wert setzt, werden Handler mit niedrigerer Priorität übersprungen.
• message_sending: Die Rückgabe von { cancel: false } gilt als keine Entscheidung (wie das Auslassen 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 Zusatzangaben bei.
• message_sending: Verwenden Sie die typisierten Routing-Felder replyToId / threadId, bevor Sie auf das kanalspezifische metadata zurückgreifen.
• gateway_start: Verwenden Sie ctx.config, ctx.workspaceDir und ctx.getCron?.() für den Gateway-eigenen Startstatus, anstatt sich auf interne gateway:startup-Hooks zu verlassen. Cron wird zu diesem Zeitpunkt möglicherweise noch geladen.
• cron_reconciled: Erstellen Sie nach dem Start oder dem erneuten Laden des Schedulers eine vollständige externe Cron-Projektion neu. Sie umfasst reason und den effektiven enabled-Status einschließlich enabled: false, während ctx.getCron?.() den exakt abgeglichenen Scheduler zurückgibt. Übergeben Sie ctx.abortSignal an dauerhafte Projektionsarbeiten; der Vorgang wird abgebrochen, wenn dieser Scheduler-Snapshot ersetzt oder das Gateway geschlossen wird.
• cron_changed: Beobachten Sie Änderungen am Gateway-eigenen Cron-Lebenszyklus. scheduled- und removed-Ereignisse sind Abgleichhinweise nach dem Commit und kein geordnetes Delta-Protokoll. Das event.nextRunAtMs eines geplanten Ereignisses fehlt, wenn der Auftrag keinen nächsten Aktivierungszeitpunkt hat; ein Entfernungsereignis enthält weiterhin den Snapshot des gelöschten Auftrags.

​

Felder des API-Objekts

​

Konvention für interne Module

my-plugin/
  api.ts            # Öffentliche Exporte für externe Verbraucher
  runtime-api.ts    # Nur interne Laufzeitexporte
  index.ts          # Plugin-Einstiegspunkt
  setup-entry.ts    # Schlanker Einstieg nur für die Einrichtung (optional)

• Anthropic: öffentliche api.ts- / contract-api.ts-Schnittstelle für Claude- Beta-Header- und service_tier-Stream-Hilfsprogramme.
• @openclaw/openai-provider: api.ts exportiert Provider-Builder, Hilfsprogramme für Standardmodelle und Echtzeit-Provider-Builder.
• @openclaw/openrouter-provider: api.ts exportiert den Provider-Builder sowie Hilfsprogramme für Onboarding und Konfiguration.

​

Verwandte Themen