Interna der Plugin-Architektur

​

Lade-Pipeline

1. potenzielle Plugin-Wurzelverzeichnisse ermitteln
2. native oder kompatible Bundle-Manifeste und Paketmetadaten lesen
3. unsichere Kandidaten ablehnen
4. Plugin-Konfiguration normalisieren (plugins.enabled, allow, deny, entries, slots, load.paths)
5. Aktivierung für jeden Kandidaten festlegen
6. aktivierte native Module laden: Erstellte gebündelte Module verwenden einen nativen Loader; lokale TypeScript-Quellen von Drittanbietern verwenden als Notlösung den Jiti-Fallback
7. native register(api)-Hooks aufrufen und Registrierungen in der Plugin-Registry erfassen
8. die Registry für Befehle und Runtime-Oberflächen bereitstellen

• sein aufgelöster Einstiegspunkt außerhalb des Plugin-Wurzelverzeichnisses liegt
• sein Pfad (oder sein Wurzelverzeichnis) für alle Benutzer beschreibbar ist
• bei nicht gebündelten Plugins der Pfadeigentümer nicht mit der aktuellen uid (oder root) übereinstimmt

​

Manifest-zuerst-Verhalten

• das Plugin zu identifizieren
• deklarierte Kanäle/Skills/Konfigurationsschemata oder Bundle-Funktionen zu ermitteln
• plugins.entries.<id>.config zu validieren
• Beschriftungen/Platzhalter der Control UI zu ergänzen
• Installations-/Katalogmetadaten anzuzeigen
• leichtgewichtige Aktivierungs- und Einrichtungsdeskriptoren zu erhalten, ohne die Plugin-Runtime zu laden

• Beim Laden der CLI wird auf Plugins eingegrenzt, denen der angeforderte primäre Befehl gehört
• Bei der Kanaleinrichtung/Plugin-Auflösung wird auf Plugins eingegrenzt, denen die angeforderte Kanal-ID gehört
• Bei der expliziten Provider-Einrichtung/Runtime-Auflösung wird auf Plugins eingegrenzt, denen die angeforderte Provider-ID gehört
• Die Startplanung des Gateways verwendet activation.onStartup für explizite Start- Importe; Plugins ohne Startmetadaten werden nur durch engere Aktivierungsauslöser geladen

​

Plugin-Cache-Grenze

• PluginLoaderCacheState und kompatible aktive Runtime-Registries
• Jiti-/Modul-Caches und Loader-Caches für öffentliche Oberflächen, die verhindern, dass dieselbe Runtime-Oberfläche wiederholt importiert wird
• Dateisystem-Caches für installierte Plugin-Artefakte
• kurzlebige Maps pro Aufruf für die Pfadnormalisierung oder Auflösung von Duplikaten

• Ermittlungsergebnisse
• direkte Manifest-Registries
• aus dem Index installierter Plugins rekonstruierte Manifest-Registries
• Suche nach Provider-Zuständigen, Modellunterdrückung, Provider-Richtlinien oder Metadaten öffentlicher Artefakte
• andere aus Manifesten abgeleitete Antworten, bei denen ein geändertes Manifest, ein geänderter installierter Index oder ein geänderter Ladepfad beim nächsten Lesen der Metadaten sichtbar sein sollte

​

Registry-Modell

• Plugin-Modul -> Registry-Registrierung
• Kern-Runtime -> Registry-Nutzung

​

Callbacks für Konversationsbindungen

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // Für dieses Plugin und diese Konversation besteht jetzt eine Bindung.
        console.log(event.binding?.conversationId);
        return;
      }

      // Die Anfrage wurde abgelehnt; lokalen ausstehenden Zustand löschen.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" oder "denied"
• decision: "allow-once", "allow-always" oder "deny"
• binding: die aufgelöste Bindung für genehmigte Anfragen
• request: die Zusammenfassung der ursprünglichen Anfrage, der Hinweis zum Trennen, die Absender-ID und die Konversationsmetadaten

​

Provider-Runtime-Hooks

• Manifest-Metadaten für eine leichtgewichtige Suche vor der Runtime: setup.providers[].envVars, providerAuthAliases, providerAuthChoices und channelConfigs.
• Hooks zur Konfigurationszeit: catalog plus applyConfigDefaults.
• Runtime-Hooks: mehr als 40 optionale Hooks für Authentifizierung, Modellauflösung, Stream-Wrapper, Denkstufen, Wiederholungsrichtlinien und Nutzungsendpunkte. Siehe Hook-Reihenfolge und Nutzung.

​

Reihenfolge und Verwendung der Hooks

​

Provider-Beispiel

api.registerProvider({
  id: "example-proxy",
  label: "Beispiel-Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Automatisch" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

Integrierte Beispiele

​

Runtime-Hilfsfunktionen

const clip = await api.runtime.tts.textToSpeech({
  text: "Hallo von OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hallo von OpenClaw",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech gibt die normale TTS-Ausgabe-Payload des Kerns für Datei-/Sprachnachrichtenoberflächen zurück.
• Verwendet die Kernkonfiguration tts und die Provider-Auswahl.
• Gibt einen PCM-Audiopuffer und die Abtastrate zurück. Plugins müssen für Provider neu abtasten/kodieren.
• listVoices ist pro Provider optional. Verwenden Sie es für anbietereigene Sprachauswahl- oder Einrichtungsabläufe.
• Der Kern übergibt eine aufgelöste Anfragefrist an Provider-Hooks vom Typ listVoices; Provider-spezifische Zeitüberschreitungseinstellungen können sie überschreiben.
• Sprachlisten können umfangreichere Metadaten wie Gebietsschema, Geschlecht und Persönlichkeits-Tags für Provider-bewusste Auswahlfelder enthalten.
• OpenAI und ElevenLabs unterstützen derzeit Telefonie. Microsoft nicht.

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme-Sprache",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• Belassen Sie TTS-Richtlinien, Fallback und Antwortzustellung im Kern.
• Verwenden Sie Sprachanbieter für anbietereigenes Syntheseverhalten.
• Die ältere Microsoft-Eingabe edge wird auf die Provider-ID microsoft normalisiert.
• Das bevorzugte Zuständigkeitsmodell ist unternehmensorientiert: Ein Anbieter-Plugin kann Text-, Sprach-, Bild- und zukünftige Medien-Provider verwalten, wenn OpenClaw diese Fähigkeitsverträge hinzufügt.

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• Belassen Sie Orchestrierung, Fallback, Konfiguration und Kanalverdrahtung im Kern.
• Belassen Sie anbieterspezifisches Verhalten im Provider-Plugin.
• Additive Erweiterungen sollten typisiert bleiben: neue optionale Methoden, neue optionale Ergebnisfelder, neue optionale Fähigkeiten.
• Die Videoerzeugung folgt bereits demselben Muster:
  • Der Kern verwaltet den Fähigkeitsvertrag und die Runtime-Hilfsfunktion.
  • Anbieter-Plugins registrieren api.registerVideoGenerationProvider(...).
  • Funktions-/Kanal-Plugins verwenden api.runtime.videoGeneration.*.

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.6-sol",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Verwenden Sie die gedruckten Felder als maßgebliche Quelle." },
  ],
  instructions: "Geben Sie Entitäten und durchsuchbare Tags zurück.",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional, wenn der MIME-Typ nicht zuverlässig abgeleitet werden kann:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* ist die bevorzugte gemeinsame Oberfläche für das Verstehen von Bildern, Audio und Videos.
• extractStructuredWithModel(...) ist die Plugin-seitige Schnittstelle für begrenzte, Provider-eigene, bildorientierte Extraktion. Fügen Sie mindestens eine Bildeingabe ein; Texteingaben sind ergänzender Kontext. Produkt-Plugins verwalten ihre Routen und Schemas, während OpenClaw die Provider-/Runtime-Grenze verwaltet.
• Verwendet die Audio-Kernkonfiguration für Medienverständnis (tools.media.audio) und die Provider-Fallback-Reihenfolge.
• Gibt { text: undefined } zurück, wenn keine Transkriptionsausgabe erzeugt wird (beispielsweise bei übersprungener/nicht unterstützter Eingabe).

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Erweitern Sie diese Abfrage zu gezielten Folgesuchen.",
  toolsAlsoAllow: ["my_plugin_progress"],
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider und model sind optionale Überschreibungen pro Lauf und keine dauerhaften Sitzungsänderungen.
• toolsAlsoAllow akzeptiert exakte, eindeutig zugeordnete Werkzeugnamen, die vom aufrufenden Plugin registriert wurden. Kernnamen und mehrdeutige Namen werden abgelehnt. Es ergänzt das normale Profil, doch Betreiber-Zulassungs- und Sperrlisten bleiben maßgeblich.
• OpenClaw berücksichtigt diese Überschreibungsfelder nur für vertrauenswürdige Aufrufer.
• Für Plugin-eigene Fallback-Läufe müssen Betreiber sich mit plugins.entries.<id>.subagent.allowModelOverride: true ausdrücklich dafür entscheiden.
• Verwenden Sie plugins.entries.<id>.subagent.allowedModels, um vertrauenswürdige Plugins auf bestimmte kanonische provider/model-Ziele zu beschränken, oder "*", um ausdrücklich jedes Ziel zuzulassen.
• Subagent-Läufe nicht vertrauenswürdiger Plugins funktionieren weiterhin, Überschreibungsanforderungen werden jedoch abgelehnt, statt stillschweigend auf einen Fallback zurückzugreifen.
• Von Plugins erstellte Subagent-Sitzungen werden mit der ID des erstellenden Plugins gekennzeichnet. Fallback api.runtime.subagent.deleteSession(...) darf nur diese zugehörigen Sitzungen löschen; das Löschen beliebiger Sitzungen erfordert weiterhin eine Gateway-Anfrage mit Administratorbereich.

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "Runtime-Hilfsfunktionen für OpenClaw-Plugins",
    count: 5,
  },
});

• Belassen Sie Provider-Auswahl, Auflösung von Zugangsdaten und gemeinsame Anfragesemantik im Kern.
• Verwenden Sie Websuch-Provider für anbieterspezifische Suchtransporte.
• api.runtime.webSearch.* ist die bevorzugte gemeinsame Oberfläche für Funktions-/Kanal-Plugins, die Suchverhalten benötigen, ohne vom Wrapper des Agentenwerkzeugs abhängig zu sein.

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "Ein freundliches Hummer-Maskottchen", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): Generiert ein Bild mithilfe der konfigurierten Provider-Kette für die Bilderzeugung.
• listProviders(...): Listet verfügbare Provider für die Bilderzeugung und deren Fähigkeiten auf.

​

Gateway-HTTP-Routen

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: Routenpfad unter dem Gateway-HTTP-Server.
• auth: Erforderlich, "gateway" oder "plugin". Verwenden Sie "gateway", um die normale Gateway-Authentifizierung zu verlangen, oder "plugin" für eine vom Plugin verwaltete Authentifizierung/Webhook-Verifizierung.
• match: Optional. "exact" (Standard) oder "prefix".
• handleUpgrade: Optionaler Handler für WebSocket-Upgrade-Anfragen auf derselben Route.
• replaceExisting: Optional. Ermöglicht demselben Plugin, seine eigene vorhandene Routenregistrierung zu ersetzen.
• handler: Gibt true zurück, wenn die Route die Anfrage verarbeitet hat.

• api.registerHttpHandler(...) wurde entfernt und verursacht einen Fehler beim Laden des Plugins. Verwenden Sie stattdessen api.registerHttpRoute(...).
• Plugin-Routen müssen auth ausdrücklich deklarieren.
• Exakte Konflikte bei path + match werden abgelehnt, außer bei replaceExisting: true; außerdem kann ein Plugin die Route eines anderen Plugins nicht ersetzen.
• Überlappende Routen mit unterschiedlichen auth-Stufen werden abgelehnt. Behalten Sie exact-/prefix-Durchreichungsketten ausschließlich auf derselben Authentifizierungsstufe.
• auth: "plugin"-Routen erhalten nicht automatisch Laufzeitbereiche für Operatoren. Sie sind für vom Plugin verwaltete Webhooks bzw. Signaturverifizierung vorgesehen, nicht für privilegierte Aufrufe von Gateway-Hilfsfunktionen.
• auth: "gateway"-Routen werden innerhalb eines Gateway-Anfragelaufzeitbereichs ausgeführt. Die Standardoberfläche (gatewayRuntimeScopeSurface: "write-default") ist absichtlich restriktiv:
  • Die Bearer-Authentifizierung mit gemeinsamem Geheimnis (gateway.auth.mode = "token" / "password") sowie jede Authentifizierungsmethode ohne vertrauenswürdigen Proxy erhalten einen einzelnen operator.write-Bereich, selbst wenn der Aufrufer x-openclaw-scopes sendet.
  • trusted-proxy-Aufrufer ohne expliziten x-openclaw-scopes-Header behalten ebenfalls die bisherige, ausschließlich auf operator.write beschränkte Oberfläche.
  • trusted-proxy-Aufrufer, die x-openclaw-scopes senden, erhalten stattdessen die deklarierten Bereiche.
  • Eine Route kann gatewayRuntimeScopeSurface: "trusted-operator" aktivieren, um x-openclaw-scopes bei identitätstragenden Authentifizierungsmodi stets zu berücksichtigen (fehlt der Header, wird auf den vollständigen Standardsatz der CLI-Bereiche zurückgegriffen).
• Sandbox-isolierte externe Control-UI-Registerkarten, die auf auth: "gateway"-Routen basieren, verwenden eine kurzlebige, signierte Cookie-Berechtigung, die ausschließlich durch einen authentifizierten Bootstrap ausgestellt wird; Registerkarten mit Plugin-Authentifizierung behalten ihren direkten iframe-Pfad. Vor dem Einbinden führt das übergeordnete Element innerhalb derselben opaken Sandbox eine routeneigene Prüfung aus und verweigert den Zugriff, wenn die Datenschutzrichtlinie des Browsers das Cookie blockiert. Die Berechtigung ist an das zuständige Plugin, den Stamm der übereinstimmenden Route und die aktuelle Authentifizierungsgeneration gebunden. Ihr prozesszufälliger Cookie-Name verhindert, dass vertrauenswürdige Gateways auf demselben Host einander überschreiben; Cookies isolieren jedoch niemals TCP-Ports. Der Gateway-Hostname bildet daher eine einzelne Grenze für Anmeldedaten: Stellen Sie auf diesem Hostnamen keine gegenseitig nicht vertrauenswürdigen Dienste bereit, auch nicht auf anderen Ports. Die Routenzustellung lehnt eine Wiederverwendung für eine verschachtelte Route ab, die einem anderen Plugin gehört. Da Sandbox-Nachfahren für Cookie-Zwecke websiteübergreifend sind, akzeptiert die Berechtigung ausschließlich GET und HEAD mit operator.read; Änderungen und WebSocket-Upgrades verbleiben auf explizit Gateway-authentifizierten Oberflächen. Das Cookie kann absichtlich kein CHIPS verwenden: Aktuelle Browser beziehen ein Bit für websiteübergreifende Vorfahren in den Partitionierungsschlüssel ein, sodass verschachtelte opake Sandbox-Frames den Zugriff auf Ressourcen derselben Route verlieren würden. Das Cookie erfordert einen sicheren Kontext und die Browserberechtigung für websiteübergreifende Cookies. Daher sind Gateway-authentifizierte externe Registerkarten auf reinen HTTP-LAN-Ursprüngen oder bei vollständiger Blockierung von Drittanbieter-Cookies nicht verfügbar; verwenden Sie HTTPS/Tailscale Serve oder einen vom Browser als vertrauenswürdig eingestuften Loopback mit einer kompatiblen Cookie-Richtlinie.
• Die Berechtigung verhindert die Offenlegung des Gateway-Bearer-Tokens und eine versehentliche Wiederverwendung von Routen oder Bereichen; sie schafft keine Sicherheitsgrenze zwischen nativen Plugins. Nativer Plugin-Code und die von ihm bereitgestellten UI-Inhalte bleiben Teil derselben vertrauenswürdigen, prozessinternen Plugin-Grenze.
• Praktische Regel: Gehen Sie nicht davon aus, dass eine Gateway-authentifizierte Plugin-Route implizit eine Administratoroberfläche ist. Wenn Ihre Route ausschließlich Administratoren vorbehaltenes Verhalten benötigt, aktivieren Sie die trusted-operator-Bereichsoberfläche, verlangen Sie einen identitätstragenden Authentifizierungsmodus und dokumentieren Sie den expliziten Vertrag für den x-openclaw-scopes-Header.
• Nach Routenabgleich und Authentifizierung nehmen gewöhnliche Handler an der Zulassung von Gateway-Stammaufgaben teil. Ein vorbereitetes oder neu startendes Gateway gibt 503 zurück, bevor es den Handler aufruft. Die enge Ausnahme bildet eine durch das Manifest berechtigte auth: "gateway"-Route, die zusätzlich die routenspezifische trusted-operator-Oberfläche aktiviert. Sie bleibt erreichbar, damit die Zustellung der Aussetzungssteuerung nicht blockiert wird, während gewöhnliche gleichgeordnete Routen desselben Plugins hinter der Zulassungsgrenze verbleiben. Der Besitz eines WebSocket-handleUpgrade verwendet dieselbe atomare Zulassungsgrenze. Sobald der Handler einen Socket akzeptiert, liegt dessen weitere Lebensdauer in der Verantwortung des Plugins und wird von dieser Grenze nicht nachverfolgt.

​

Importpfade des Plugin-SDK

• index.js — Einstiegspunkt des gebündelten Plugins
• api.js — Barrel für Hilfsfunktionen und Typen
• runtime-api.js — ausschließlich für die Laufzeit vorgesehenes Barrel
• setup-entry.js — Einstiegspunkt des Einrichtungs-Plugins

​

Schemas für Nachrichtenwerkzeuge

• presentation für semantische Darstellungsblöcke (text, context, divider, chart, table, buttons, select)
• delivery-pin für angeheftete Zustellungsanfragen

​

Auflösung von Kanalzielen

• messaging.inferTargetChatType({ to }) entscheidet vor der Verzeichnissuche, ob ein normalisiertes Ziel als direct, group oder channel behandelt werden soll.
• messaging.targetResolver.looksLikeId(raw, normalized) teilt dem Kern mit, ob eine Eingabe direkt zur ID-ähnlichen Auflösung wechseln und die Verzeichnissuche überspringen soll.
• messaging.targetResolver.reservedLiterals listet einzelne Wörter auf, die Kanal-/Sitzungsreferenzen für diesen Provider sind. Bei der Auflösung bleiben konfigurierte Verzeichniseinträge erhalten, bevor reservierte Literale abgelehnt werden; anschließend wird bei einem Fehlschlag im Verzeichnis der Zugriff verweigert.
• messaging.targetResolver.resolveTarget(...) ist der Plugin-Rückfall, wenn der Kern nach der Normalisierung oder einem Fehlschlag im Verzeichnis eine abschließende, dem Provider zugeordnete Auflösung benötigt.
• messaging.resolveOutboundSessionRoute(...) besitzt die Provider-spezifische Konstruktion der Sitzungsroute, sobald ein Ziel aufgelöst wurde.

• Verwenden Sie inferTargetChatType für Kategorieentscheidungen, die vor der Suche nach Peers/Gruppen erfolgen sollen.
• Verwenden Sie looksLikeId für Prüfungen nach dem Muster „Dies als explizite/native Ziel-ID behandeln“.
• Verwenden Sie resolveTarget als Provider-spezifischen Rückfall für die Normalisierung, nicht für eine umfassende Verzeichnissuche.
• Bewahren Sie Provider-native IDs wie Chat-IDs, Thread-IDs, JIDs, Handles und Raum-IDs in target-Werten oder Provider-spezifischen Parametern auf, nicht in generischen SDK-Feldern.

​

Konfigurationsgestützte Verzeichnisse

• durch eine Positivliste gesteuerte DM-Peers
• konfigurierte Kanal-/Gruppenzuordnungen
• kontobezogene statische Verzeichnisrückfälle

• Abfragefilterung
• Anwendung von Begrenzungen
• Hilfsfunktionen für Deduplizierung/Normalisierung
• Erstellung von ChannelDirectoryEntry[]

​

Provider-Kataloge

• { provider } für einen Provider-Eintrag
• { providers } für mehrere Provider-Einträge

• simple: einfache API-Schlüssel- oder umgebungsgesteuerte Provider
• profile: Provider, die angezeigt werden, wenn Authentifizierungsprofile vorhanden sind
• paired: Provider, die mehrere zusammengehörige Provider-Einträge erzeugen
• late: letzter Durchlauf nach anderen impliziten Providern

• discovery funktioniert weiterhin als Legacy-Alias, gibt jedoch eine Veraltungswarnung aus
• wenn sowohl catalog als auch discovery registriert sind, verwendet OpenClaw catalog und gibt eine Warnung aus
• augmentModelCatalog ist veraltet; gebündelte Provider sollten ergänzende Zeilen über registerModelCatalogProvider veröffentlichen

​

Schreibgeschützte Kanalprüfung

• resolveAccount(...) ist der Laufzeitpfad. Er darf davon ausgehen, dass Anmeldedaten vollständig materialisiert sind, und kann schnell fehlschlagen, wenn erforderliche Geheimnisse fehlen.
• Schreibgeschützte Befehlspfade wie openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve sowie Reparaturabläufe für Doctor und Konfiguration sollten Laufzeitanmeldedaten nicht materialisieren müssen, nur um die Konfiguration zu beschreiben.

• Geben Sie nur einen beschreibenden Kontostatus zurück.
• Behalten Sie enabled und configured bei.
• Fügen Sie gegebenenfalls Felder für Quelle und Status der Anmeldedaten hinzu, beispielsweise:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Sie müssen keine Rohwerte von Tokens zurückgeben, nur um die schreibgeschützte Verfügbarkeit zu melden. Die Rückgabe von tokenStatus: "available" (und des zugehörigen Quellenfelds) reicht für statusorientierte Befehle aus.
• Verwenden Sie configured_unavailable, wenn Anmeldedaten über SecretRef konfiguriert, im aktuellen Befehlspfad jedoch nicht verfügbar sind.

​

Paket-Packs

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• die Kanalregistrierung selbst
• alle HTTP-Routen, die verfügbar sein müssen, bevor das Gateway zu lauschen beginnt
• alle Gateway-Methoden, Werkzeuge oder Dienste, die während desselben Zeitfensters vorhanden sein müssen

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

Metadaten des Kanalkatalogs

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (selbst gehostet)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Selbst gehosteter Chat über Nextcloud-Talk-Webhook-Bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: sekundäre Bezeichnung für umfangreichere Katalog-/Statusoberflächen
• docsLabel: Linktext für den Dokumentationslink überschreiben
• preferOver: Plugin-/Kanal-IDs mit niedrigerer Priorität, die dieser Katalogeintrag übertreffen soll
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: Steuerung der Texte auf Auswahloberflächen
• markdownCapable: kennzeichnet den Kanal für Entscheidungen zur ausgehenden Formatierung als Markdown-fähig
• exposure.configured: blendet den Kanal auf Listenoberflächen für konfigurierte Kanäle aus, wenn auf false gesetzt
• exposure.setup: blendet den Kanal in interaktiven Auswahlfeldern für Einrichtung/Konfiguration aus, wenn auf false gesetzt
• exposure.docs: kennzeichnet den Kanal für Dokumentationsnavigationsoberflächen als intern/privat
• quickstartAllowFrom: nimmt den Kanal in den standardmäßigen Schnellstartablauf allowFrom auf
• forceAccountBinding: erfordert eine explizite Kontobindung, selbst wenn nur ein Konto vorhanden ist
• preferSessionLookupForAnnounceTarget: bevorzugt bei der Auflösung von Ankündigungszielen die Sitzungssuche

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

Plugins für die Kontext-Engine

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

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Neue Capability hinzufügen

1. Definieren Sie den Core-Vertrag. Legen Sie fest, welches gemeinsame Verhalten der Core verwalten soll: Richtlinie, Fallback, Konfigurationszusammenführung, Lebenszyklus, kanalbezogene Semantik und Form der Runtime-Hilfsfunktion.
2. Fügen Sie typisierte Oberflächen für Plugin-Registrierung und Runtime hinzu. Erweitern Sie OpenClawPluginApi und/oder api.runtime um die kleinste zweckmäßige typisierte Capability-Oberfläche.
3. Binden Sie Core- sowie Kanal-/Feature-Consumer an. Kanäle und Feature-Plugins sollten die neue Capability über den Core nutzen, statt die Implementierung eines Providers direkt zu importieren.
4. Registrieren Sie Provider-Implementierungen. Provider-Plugins registrieren anschließend ihre Backends für die Capability.
5. Fügen Sie Vertragsabdeckung hinzu. Fügen Sie Tests hinzu, damit Eigentümerschaft und Registrierungsform dauerhaft explizit bleiben.

​

Capability-Checkliste

• Core-Vertragstypen in src/<capability>/types.ts
• Core-Runner/-Runtime-Hilfsfunktion in src/<capability>/runtime.ts
• Registrierungsoberfläche der Plugin-API in src/plugins/types.ts
• Verdrahtung der Plugin-Registry in src/plugins/registry.ts
• Runtime-Bereitstellung des Plugins in src/plugins/runtime/*, wenn Feature-/Kanal- Plugins sie nutzen müssen
• Erfassungs-/Testhilfen in src/test-utils/plugin-registration.ts
• Eigentümerschafts-/Vertragszusicherungen in src/plugins/contracts/registry.ts
• Dokumentation für Betreiber/Plugins in docs/

​

Capability-Vorlage

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(pluginManifest.contracts?.videoGenerationProviders).toEqual(["openai"]);

• Der Core verwaltet den Capability-Vertrag und die Orchestrierung
• Provider-Plugins verwalten die Provider-Implementierungen
• Feature-/Kanal-Plugins nutzen Runtime-Hilfsfunktionen
• Vertragstests halten die Eigentümerschaft explizit fest

​

Verwandte Themen

• Plugin-Architektur — öffentliches Capability-Modell und Formen
• Unterpfade des Plugin SDK
• Einrichtung des Plugin SDK
• Plugins erstellen