Interna der Plugin-Architektur

​

Lade-Pipeline

1. Kandidaten für Plugin-Roots 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 entscheiden
6. aktivierte native Module laden: gebaute gebündelte Module verwenden einen nativen Loader; lokaler TypeScript-Quellcode von Drittanbietern verwendet den Notfall-Fallback Jiti
7. native register(api)-Hooks aufrufen und Registrierungen in der Plugin-Registry sammeln
8. die Registry für Befehle/Runtime-Oberflächen bereitstellen

​

Manifest-zuerst-Verhalten

• das Plugin zu identifizieren
• deklarierte Channels/Skills/Konfigurationsschemas oder Bundle-Capabilities zu ermitteln
• plugins.entries.<id>.config zu validieren
• Control-UI-Labels/Platzhalter zu ergänzen
• Installations-/Katalogmetadaten anzuzeigen
• günstige Aktivierungs- und Einrichtungsdeskriptoren zu erhalten, ohne die Plugin-Runtime zu laden

• CLI-Laden wird auf Plugins eingegrenzt, denen der angeforderte primäre Befehl gehört
• Channel-Einrichtung/Plugin-Auflösung wird auf Plugins eingegrenzt, denen die angeforderte Channel-ID gehört
• explizite Provider-Einrichtung/Runtime-Auflösung wird auf Plugins eingegrenzt, denen die angeforderte Provider-ID gehört
• Gateway-Startplanung verwendet activation.onStartup für explizite Startimporte und Start-Opt-outs; Plugins ohne Startmetadaten laden nur über engere Aktivierungsauslöser

​

Plugin-Cache-Grenze

• PluginLoaderCacheState und kompatible aktive Runtime-Registries
• jiti-/Modul-Caches und Public-Surface-Loader-Caches, die verwendet werden, um zu vermeiden, dieselbe Runtime-Oberfläche wiederholt zu importieren
• Dateisystem-Caches für installierte Plugin-Artefakte
• kurzlebige Maps pro Aufruf für Pfadnormalisierung oder Duplikatauflösung

• Erkennungsergebnisse
• direkte Manifest-Registries
• Manifest-Registries, die aus dem installierten Plugin-Index rekonstruiert wurden
• Provider-Eigentümer-Lookup, Modellunterdrückung, Provider-Policy oder Metadaten zu öffentlichen Artefakten
• jede andere aus dem Manifest abgeleitete Antwort, bei der ein geändertes Manifest, ein installierter Index oder ein Ladepfad beim nächsten Metadatenlesen sichtbar sein sollte

​

Registry-Modell

• Plugin-Datensätze (Identität, Quelle, Ursprung, Status, Diagnosen)
• Tools
• Legacy-Hooks und typisierte Hooks
• Channels
• Provider
• Gateway-RPC-Handler
• HTTP-Routen
• CLI-Registrare
• Hintergrunddienste
• Plugin-eigene Befehle

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

​

Callbacks für Conversation Bindings

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" oder "denied"
• decision: "allow-once", "allow-always" oder "deny"
• binding: das aufgelöste Binding für genehmigte Anforderungen
• request: die ursprüngliche Anforderungszusammenfassung, der Detach-Hinweis, die Sender-ID und Conversation-Metadaten

​

Provider-Runtime-Hooks

• Manifest-Metadaten für günstige Pre-Runtime-Lookups: setup.providers[].envVars, veraltete Kompatibilität providerAuthEnvVars, providerAuthAliases, providerAuthChoices und channelEnvVars.
• Konfigurationszeit-Hooks: catalog (Legacy-discovery) plus applyConfigDefaults.
• Runtime-Hooks: mehr als 40 optionale Hooks für Authentifizierung, Modellauflösung, Stream-Wrapping, Thinking Levels, Replay-Policy und Nutzungsendpunkte. Siehe die vollständige Liste unter Hook-Reihenfolge und Nutzung.

​

Hook-Reihenfolge und Nutzung

​

Provider-Beispiel

api.registerProvider({
  id: "example-proxy",
  label: "Example 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: "Auto" }],
        },
      };
    },
  },
  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-Helfer

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

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

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

• textToSpeech gibt die normale Core-TTS-Ausgabe-Payload für Datei-/Sprachnotiz-Oberflächen zurück.
• Verwendet Core-Konfiguration messages.tts und Provider-Auswahl.
• Gibt PCM-Audiopuffer + Abtastrate zurück. Plugins müssen für Provider resamplen/encodieren.
• listVoices ist pro Provider optional. Verwenden Sie es für anbieter-eigene Sprachauswahlen oder Setup-Flows.
• Sprachlisten können reichere Metadaten wie Locale, Geschlecht und Persönlichkeits-Tags für provider-bewusste Auswahlen enthalten.
• OpenAI und ElevenLabs unterstützen heute Telefonie. Microsoft nicht.

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

• Belassen Sie TTS-Richtlinie, Fallback und Antwortzustellung im Core.
• Verwenden Sie Speech-Provider für anbieter-eigenes Syntheseverhalten.
• Legacy-Microsoft-edge-Eingabe wird auf die Provider-ID microsoft normalisiert.
• Das bevorzugte Besitzmodell ist unternehmensorientiert: Ein Anbieter-Plugin kann Text-, Speech-, Image- und künftige Media-Provider besitzen, während OpenClaw diese Capability-Verträ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 Channel-Verdrahtung im Core.
• Belassen Sie anbieter-spezifisches Verhalten im Provider-Plugin.
• Additive Erweiterungen sollten typisiert bleiben: neue optionale Methoden, neue optionale Ergebnisfelder, neue optionale Capabilities.
• Videoerzeugung folgt bereits demselben Muster:
  • Core besitzt den Capability-Vertrag und Runtime-Helfer
  • Anbieter-Plugins registrieren api.registerVideoGenerationProvider(...)
  • Feature-/Channel-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.5",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Use the printed fields as the source of truth." },
  ],
  instructions: "Return entities and searchable tags.",
  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 when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* ist die bevorzugte gemeinsame Oberfläche für Bild-/Audio-/Video-Verstehen.
• extractStructuredWithModel(...) ist die plugin-seitige Seam für begrenzte, provider-eigene, image-first Extraktion. Fügen Sie mindestens eine Bildeingabe hinzu; Texteingaben sind ergänzender Kontext. Produkt-Plugins besitzen ihre Routen und Schemas, während OpenClaw die Provider-/Runtime-Grenze besitzt.
• Verwendet Core-Media-Understanding-Audiokonfiguration (tools.media.audio) und Provider-Fallback-Reihenfolge.
• Gibt { text: undefined } zurück, wenn keine Transkriptionsausgabe erzeugt wird (zum Beispiel übersprungene/nicht unterstützte Eingabe).
• api.runtime.stt.transcribeAudioFile(...) bleibt als Kompatibilitätsalias erhalten.

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider und model sind optionale Overrides pro Lauf, keine persistenten Sitzungsänderungen.
• OpenClaw berücksichtigt diese Override-Felder nur für vertrauenswürdige Aufrufer.
• Für plugin-eigene Fallback-Läufe müssen Operatoren mit plugins.entries.<id>.subagent.allowModelOverride: true zustimmen.
• Verwenden Sie plugins.entries.<id>.subagent.allowedModels, um vertrauenswürdige Plugins auf bestimmte kanonische provider/model-Ziele zu beschränken, oder "*", um jedes Ziel ausdrücklich zu erlauben.
• Subagent-Läufe nicht vertrauenswürdiger Plugins funktionieren weiterhin, aber Override-Anfragen werden abgelehnt, statt stillschweigend zurückzufallen.
• Von Plugins erstellte Subagent-Sitzungen werden mit der ID des erstellenden Plugins getaggt. Fallback api.runtime.subagent.deleteSession(...) darf nur diese eigenen Sitzungen löschen; beliebiges Löschen von Sitzungen erfordert weiterhin eine admin-skopierte Gateway-Anfrage.

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

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• Belassen Sie Provider-Auswahl, Anmeldedatenauflösung und gemeinsame Request-Semantik im Core.
• Verwenden Sie Websuche-Provider für anbieter-spezifische Suchtransporte.
• api.runtime.webSearch.* ist die bevorzugte gemeinsame Oberfläche für Feature-/Channel-Plugins, die Suchverhalten benötigen, ohne vom Agent-Tool-Wrapper abzuhängen.

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

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

• generate(...): Erzeugt ein Bild mithilfe der konfigurierten Image-Generation-Provider-Kette.
• listProviders(...): Listet verfügbare Image-Generation-Provider und ihre Capabilities 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. Verwenden Sie "gateway", um normale Gateway-Authentifizierung zu verlangen, oder "plugin" für Plugin-verwaltete Authentifizierung/Webhook-Verifizierung.
• match: optional. "exact" (Standard) oder "prefix".
• replaceExisting: optional. Erlaubt demselben Plugin, seine eigene bestehende Routenregistrierung zu ersetzen.
• handler: gibt true zurück, wenn die Route die Anfrage verarbeitet hat.

• api.registerHttpHandler(...) wurde entfernt und führt zu einem Plugin-Ladefehler. 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; ein Plugin kann die Route eines anderen Plugins nicht ersetzen.
• Überlappende Routen mit unterschiedlichen auth-Stufen werden abgelehnt. Behalten Sie exact/prefix-Fallthrough-Ketten nur auf derselben Authentifizierungsstufe.
• Routen mit auth: "plugin" erhalten nicht automatisch Operator-Laufzeitbereiche. Sie sind für Plugin-verwaltete Webhooks/Signaturverifizierung gedacht, nicht für privilegierte Gateway-Hilfsaufrufe.
• Routen mit auth: "gateway" laufen innerhalb eines Gateway-Anfrage-Laufzeitbereichs, aber dieser Bereich ist absichtlich konservativ:
  • Shared-Secret-Bearer-Authentifizierung (gateway.auth.mode = "token" / "password") hält Laufzeitbereiche von Plugin-Routen auf operator.write fixiert, selbst wenn der Aufrufer x-openclaw-scopes sendet
  • vertrauenswürdige identitätstragende HTTP-Modi (zum Beispiel trusted-proxy oder gateway.auth.mode = "none" auf einem privaten Ingress) berücksichtigen x-openclaw-scopes nur, wenn der Header ausdrücklich vorhanden ist
  • fehlt x-openclaw-scopes bei diesen identitätstragenden Plugin-Routen-Anfragen, fällt der Laufzeitbereich auf operator.write zurück
• Praktische Regel: Gehen Sie nicht davon aus, dass eine Gateway-authentifizierte Plugin-Route implizit eine Admin-Oberfläche ist. Wenn Ihre Route nur Admin-Verhalten benötigt, verlangen Sie einen identitätstragenden Authentifizierungsmodus und dokumentieren Sie den ausdrücklichen Header-Vertrag für x-openclaw-scopes.

​

Plugin-SDK-Importpfade

• index.js — Einstieg für gebündelte Plugins
• api.js — Barrel für Hilfen/Typen
• runtime-api.js — nur Laufzeit-Barrel
• setup-entry.js — Setup-Plugin-Einstieg

​

Nachrichtentool-Schemas

• presentation für semantische Präsentationsblöcke (text, context, divider, buttons, select)
• delivery-pin für Anfragen zu angehefteter Zustellung

​

Auflösung von Channel-Zielen

• 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 Core mit, ob eine Eingabe direkt zur ID-artigen Auflösung gehen soll, statt eine Verzeichnissuche zu verwenden.
• messaging.targetResolver.reservedLiterals listet einfache Wörter auf, die Channel-/Sitzungsreferenzen für diesen Provider sind. Die Auflösung bewahrt konfigurierte Verzeichniseinträge, bevor reservierte Literale abgelehnt werden, und schlägt dann bei einem Verzeichnisfehler geschlossen fehl.
• messaging.targetResolver.resolveTarget(...) ist der Plugin-Fallback, wenn Core nach der Normalisierung oder nach einem Verzeichnisfehler eine abschließende Provider-eigene Auflösung benötigt.
• messaging.resolveOutboundSessionRoute(...) besitzt die Provider-spezifische Konstruktion der Sitzungsroute, sobald ein Ziel aufgelöst ist.

• Verwenden Sie inferTargetChatType für Kategorieentscheidungen, die vor der Suche nach Peers/Gruppen stattfinden sollten.
• Verwenden Sie looksLikeId für Prüfungen nach dem Muster „dies als explizite/native Ziel-ID behandeln“.
• Verwenden Sie resolveTarget für Provider-spezifischen Normalisierungs-Fallback, nicht für breite Verzeichnissuche.
• Halten Sie Provider-native IDs wie Chat-IDs, Thread-IDs, JIDs, Handles und Raum-IDs innerhalb von target-Werten oder Provider-spezifischen Parametern, nicht in generischen SDK-Feldern.

​

Konfigurationsgestützte Verzeichnisse

• durch Allowlist gesteuerte DM-Peers
• konfigurierte Channel-/Gruppen-Zuordnungen
• kontobezogene statische Verzeichnis-Fallbacks

• Abfragefilterung
• Anwendung von Limits
• Hilfen für Deduplizierung/Normalisierung
• Erstellen von ChannelDirectoryEntry[]

​

Provider-Kataloge

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

• simple: einfache API-Key- oder env-gesteuerte Provider
• profile: Provider, die erscheinen, wenn Auth-Profile existieren
• paired: Provider, die mehrere zusammengehörige Provider-Einträge synthetisieren
• late: letzter Durchlauf, nach anderen impliziten Providern

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

​

Schreibgeschützte Channel-Prüfung

• resolveAccount(...) ist der Laufzeitpfad. Er darf annehmen, dass Zugangsdaten vollständig materialisiert sind, und kann schnell fehlschlagen, wenn erforderliche Secrets fehlen.
• Schreibgeschützte Befehlspfade wie openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve sowie Doctor-/Konfigurations- Reparaturabläufe sollten keine Laufzeit-Zugangsdaten materialisieren müssen, nur um Konfiguration zu beschreiben.

• Geben Sie nur beschreibenden Kontostatus zurück.
• Bewahren Sie enabled und configured.
• Fügen Sie bei Bedarf Felder für Quelle/Status von Zugangsdaten hinzu, etwa:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Sie müssen keine rohen Token-Werte zurückgeben, nur um schreibgeschützte Verfügbarkeit zu melden. tokenStatus: "available" (und das passende Quellenfeld) reicht für Statusbefehle aus.
• Verwenden Sie configured_unavailable, wenn Zugangsdaten per SecretRef konfiguriert, aber im aktuellen Befehlspfad 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 der Gateway zu lauschen beginnt
• alle Gateway-Methoden, Tools oder Dienste, die in demselben Zeitfenster vorhanden sein müssen

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

Kanal-Katalogmetadaten

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: sekundäres Label für reichhaltigere Katalog-/Statusoberflächen
• docsLabel: Linktext für den Dokumentationslink überschreiben
• preferOver: niedriger priorisierte Plugin-/Kanal-IDs, die dieser Katalogeintrag übertreffen soll
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: Kopiersteuerungen für Auswahloberflächen
• markdownCapable: markiert den Kanal für ausgehende Formatierungsentscheidungen als Markdown-fähig
• exposure.configured: blendet den Kanal aus Oberflächen mit konfigurierten Kanallisten aus, wenn auf false gesetzt
• exposure.setup: blendet den Kanal aus interaktiven Einrichtungs-/Konfigurationsauswahlen aus, wenn auf false gesetzt
• exposure.docs: markiert den Kanal für Dokumentationsnavigationsoberflächen als intern/privat
• showConfigured / showInSetup: Legacy-Aliasse, die aus Kompatibilitätsgründen weiterhin akzeptiert werden; bevorzugen Sie exposure
• quickstartAllowFrom: nimmt den Kanal in den standardmäßigen Quickstart-allowFrom-Flow auf
• forceAccountBinding: erfordert eine explizite Kontobindung, auch wenn nur ein Konto existiert
• preferSessionLookupForAnnounceTarget: bevorzugt die Sitzungssuche beim Auflösen von Ankündigungszielen

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

​

Kontext-Engine-Plugins

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, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    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, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Eine neue Capability hinzufügen

1. Core-Vertrag definieren Entscheiden Sie, welches gemeinsame Verhalten Core besitzen soll: Policy, Fallback, Konfigurationszusammenführung, Lifecycle, kanalbezogene Semantik und Form von Laufzeit-Hilfsfunktionen.
2. typisierte Plugin-Registrierungs-/Laufzeitoberflächen hinzufügen Erweitern Sie OpenClawPluginApi und/oder api.runtime um die kleinste nützliche typisierte Capability-Oberfläche.
3. Core + Kanal-/Feature-Konsumenten verdrahten Kanäle und Feature-Plugins sollten die neue Capability über Core konsumieren, nicht durch direkten Import einer Vendor-Implementierung.
4. Vendor-Implementierungen registrieren Vendor-Plugins registrieren dann ihre Backends für die Capability.
5. Vertragsabdeckung hinzufügen Fügen Sie Tests hinzu, damit Besitz und Registrierungsform über die Zeit explizit bleiben.

​

Capability-Checkliste

• Core-Vertragstypen in src/<capability>/types.ts
• Core-Runner-/Laufzeit-Hilfsfunktion in src/<capability>/runtime.ts
• Plugin-API-Registrierungsoberfläche in src/plugins/types.ts
• Plugin-Registry-Verdrahtung in src/plugins/registry.ts
• Plugin-Laufzeit-Exponierung in src/plugins/runtime/*, wenn Feature-/Kanal- Plugins sie konsumieren müssen
• Erfassungs-/Test-Hilfsfunktionen in src/test-utils/plugin-registration.ts
• Besitz-/Vertragsassertionen in src/plugins/contracts/registry.ts
• Operator-/Plugin-Dokumentation 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(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• Core besitzt den Capability-Vertrag und die Orchestrierung
• Vendor-Plugins besitzen Vendor-Implementierungen
• Feature-/Kanal-Plugins nutzen Runtime-Hilfsfunktionen
• Vertragstests halten die Zuständigkeit explizit

​

Verwandt

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