Plugin-Einstiegspunkte

​

Paketeinstiege

{
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"],
    "setupEntry": "./src/setup-entry.ts",
    "runtimeSetupEntry": "./dist/setup-entry.js"
  }
}

• extensions und setupEntry sind Quelleinstiege, die für die Entwicklung in Workspaces und Git- Checkouts verwendet werden.
• runtimeExtensions und runtimeSetupEntry werden für installierte Pakete bevorzugt: Dadurch können npm-Pakete auf die TypeScript-Kompilierung zur Laufzeit verzichten.
• runtimeExtensions muss, falls vorhanden, hinsichtlich der Array-Länge mit extensions übereinstimmen (die Einträge werden positionsweise zugeordnet). runtimeSetupEntry erfordert setupEntry.
• Wenn ein runtimeExtensions-/runtimeSetupEntry-Artefakt deklariert ist, aber fehlt, schlägt die Installation/Erkennung mit einem Paketierungsfehler fehl; OpenClaw greift nicht stillschweigend auf den Quellcode zurück. Der Rückgriff auf den Quellcode (siehe unten) gilt nur, wenn überhaupt kein Laufzeiteinstieg deklariert ist.
• Wenn ein installiertes Paket nur einen TypeScript-Quelleinstieg deklariert, sucht OpenClaw nach einem passenden gebauten dist/*.js-Peer (oder .mjs/.cjs) und verwendet diesen; andernfalls greift es auf den TypeScript-Quellcode zurück.
• Alle Einstiegspfade müssen innerhalb des Plugin-Paketverzeichnisses bleiben. Laufzeit- einstiege und abgeleitete gebaute JS-Peers machen einen ausbrechenden extensions- oder setupEntry-Quellpfad nicht gültig.

​

defineToolPlugin

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

export default defineToolPlugin({
  id: "stock-quotes",
  name: "Stock Quotes",
  description: "Fetch stock quotes.",
  configSchema: Type.Object({
    apiKey: Type.Optional(Type.String({ description: "API key." })),
  }),
  tools: (tool) => [
    tool({
      name: "quote",
      label: "Quote",
      description: "Fetch a quote.",
      parameters: Type.Object({
        symbol: Type.String({ description: "Ticker symbol." }),
      }),
      outputSchema: Type.Object(
        {
          symbol: Type.String(),
          hasKey: Type.Boolean(),
        },
        { additionalProperties: false },
      ),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

• configSchema ist optional; wird es weggelassen, kommt ein striktes Schema für ein leeres Objekt zum Einsatz (das generierte Manifest enthält weiterhin configSchema).
• execute gibt eine einfache Zeichenfolge oder einen JSON-serialisierbaren Wert zurück; die Hilfsfunktion verpackt diesen als Text-Tool-Ergebnis, wobei details auf den ursprünglichen (nicht in eine Zeichenfolge umgewandelten) Rückgabewert gesetzt wird.
• outputSchema beschreibt optional diesen ursprünglichen details-Wert für Code Mode und Tool Search. Katalogaufrufe weisen ein ungültiges Schema vor der Ausführung zurück und validieren den endgültigen Wert, bevor sie ihn zurückgeben.
• Für benutzerdefinierte Tool-Ergebnisse exportiert openclaw/plugin-sdk/tool-results textResult und jsonResult.
• Tool-Namen sind statisch, daher leitet openclaw plugins build contracts.tools aus den deklarierten Tools ab, ohne Namen manuell zu duplizieren.
• Das Laden zur Laufzeit bleibt strikt: Installierte Plugins benötigen weiterhin openclaw.plugin.json und package.json openclaw.extensions. OpenClaw führt niemals Plugin-Code aus, um fehlende Manifestdaten abzuleiten.

​

definePluginEntry

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

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({/* ... */});
    api.registerTool({/* ... */});
  },
});

• id muss mit Ihrem openclaw.plugin.json-Manifest übereinstimmen.
• Externe Sitzungskataloge verwenden openclaw/plugin-sdk/session-catalog und api.registerSessionCatalog({ id, label, list, read, continueSession?, archive? }). Der Core ist für die sessions.catalog.*-Gateway-Methoden zuständig; Provider geben Host-, Sitzungs- und normalisierte Transkriptprojektionen zurück, ohne RPCs zu registrieren. Ein Listen-Provider sollte den optionalen onHost(host)-Callback aufrufen, sobald jeder Host abgeschlossen ist; das zurückgegebene Host-Array bleibt als endgültiger Kompatibilitäts- Snapshot erforderlich.
• kind ist veraltet: Deklarieren Sie stattdessen einen exklusiven Slot ("memory" oder "context-engine") im Feld kind des openclaw.plugin.json-Manifests. Der Laufzeiteinstieg kind bleibt lediglich als Kompatibilitätsrückfall für ältere Plugins erhalten.
• configSchema kann zur verzögerten Auswertung eine Funktion sein. OpenClaw löst das Schema beim ersten Zugriff auf und speichert es zwischen, sodass aufwendige Schema-Builder nur einmal ausgeführt werden.
• Ein nodeHostCommands-Deskriptor kann isAvailable({ config, env }) definieren. Die Rückgabe von false lässt diesen Befehl und seine Fähigkeit aus der Gateway- Deklaration des Headless-Nodes weg. OpenClaw wertet ihn anhand der Node-lokalen Startkonfiguration aus; Befehlshandler sollten die Verfügbarkeit beim Aufruf dennoch validieren.

​

defineChannelPluginEntry

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

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

• setRuntime wird in jedem Modus außer "cli-metadata" und "tool-discovery" ausgeführt. Speichern Sie hier die Laufzeitreferenz, üblicherweise über createPluginRuntimeStore.
• registerCliMetadata wird für "cli-metadata", "discovery" und "full" ausgeführt. Verwenden Sie dies als kanonische Stelle für kanaleigene CLI-Deskriptoren, damit die Root-Hilfe nicht aktivierend bleibt, Erkennungs-Snapshots statische Befehlsmetadaten enthalten und die normale CLI-Registrierung mit vollständigen Plugin-Ladevorgängen kompatibel bleibt.
• registerFull wird nur für "full" und "tool-discovery" ausgeführt. Für "tool-discovery" wird es anstelle der Kanalregistrierung ausgeführt: OpenClaw überspringt registerChannel/setRuntime vollständig und ruft nur registerFull auf. Daher muss jede Provider-/Tool-Registrierung, die Ihr Kanal für die eigenständige Tool-Erkennung oder -Ausführung benötigt, dort erfolgen und darf nicht hinter der normalen Kanaleinrichtung liegen.
• Die Erkennungsregistrierung ist nicht aktivierend, aber nicht importfrei: OpenClaw kann den vertrauenswürdigen Plugin-Einstieg und das Kanal-Plugin-Modul auswerten, um den Snapshot zu erstellen. Halten Sie Importe auf oberster Ebene frei von Seiteneffekten und platzieren Sie Sockets, Clients, Worker und Dienste ausschließlich hinter "full"-Pfaden.
• Wie definePluginEntry kann configSchema eine verzögerte Factory sein; OpenClaw speichert das aufgelöste Schema beim ersten Zugriff zwischen.

• Verwenden Sie api.registerCli(..., { descriptors: [...] }) für Plugin-eigene Stamm- CLI-Befehle, die verzögert geladen werden sollen, ohne aus dem Parse-Baum der Stamm-CLI zu verschwinden. Deskriptornamen dürfen nur Buchstaben, Zahlen, Bindestriche und Unterstriche enthalten und müssen mit einem Buchstaben oder einer Zahl beginnen; OpenClaw lehnt andere Formen ab und entfernt Terminal-Steuersequenzen aus Beschreibungen, bevor die Hilfe dargestellt wird. Decken Sie jeden vom Registrar bereitgestellten Stamm eines Befehls der obersten Ebene ab. commands allein verbleibt im früh geladenen Kompatibilitätspfad.
• Verwenden Sie api.registerNodeCliFeature(...) für Feature-Befehle gekoppelter Nodes, damit sie unter openclaw nodes eingeordnet werden (entspricht registerCli(registrar, { parentPath: ["nodes"], ... })).
• Fügen Sie für andere verschachtelte Plugin-Befehle parentPath hinzu und registrieren Sie Befehle auf dem program-Objekt, das an den Registrar übergeben wird; OpenClaw löst es zum übergeordneten Befehl auf, bevor das Plugin aufgerufen wird.
• Registrieren Sie bei Channel-Plugins CLI-Deskriptoren aus registerCliMetadata und beschränken Sie registerFull auf reine Laufzeitarbeit.
• Wenn registerFull auch Gateway-RPC-Methoden registriert, verwenden Sie dafür ein Plugin-spezifisches Präfix. Reservierte administrative Core-Namensräume (config.*, exec.approvals.*, wizard.*, update.*) werden immer zu operator.admin umgewandelt.

​

defineSetupPluginEntry

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
  registerSetupRuntime(api) {
    api.registerHttpRoute({
      path: "/my-channel/events",
      auth: "plugin",
      handler: async (req, res) => {
        /* einrichtungssichere Route */
      },
    });
  },
});

​

Registrierungsmodus

register(api) {
  if (
    api.registrationMode === "cli-metadata" ||
    api.registrationMode === "discovery" ||
    api.registrationMode === "full"
  ) {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  if (api.registrationMode === "tool-discovery") {
    // Nur funktionsbezogene Oberflächen (Provider/Tools) registrieren, keinen Channel.
    return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Umfangreiche reine Laufzeitregistrierungen
  api.registerService(/* ... */);
}

api.registerService({
  id: "index-events",
  start(ctx) {
    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });
  },
});

​

Plugin-Formen

​

Verwandte Themen

• SDK-Übersicht - Registrierungs-API und Unterpfadreferenz
• Laufzeithilfen - api.runtime und createPluginRuntimeStore
• Einrichtung und Konfiguration - Manifest, Einrichtungseinstiegspunkt, verzögertes Laden
• Channel-Plugins - Erstellen des ChannelPlugin-Objekts
• Provider-Plugins - Provider-Registrierung und Hooks