Interne werking van de Plugin-architectuur

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.

​

Laadpijplijn

1. kandidaat-Plugin-roots ontdekken
2. native of compatibele bundlemanifests en pakketmetadata lezen
3. onveilige kandidaten weigeren
4. Plugin-configuratie normaliseren (plugins.enabled, allow, deny, entries, slots, load.paths)
5. inschakeling voor elke kandidaat bepalen
6. ingeschakelde native modules laden: gebouwde gebundelde modules gebruiken een native loader; niet-gebouwde native Plugins gebruiken jiti
7. native register(api)-hooks aanroepen en registraties verzamelen in het Plugin-register
8. het register beschikbaar maken voor opdrachten/runtime-oppervlakken

​

Manifest-eerst-gedrag

• de Plugin te identificeren
• gedeclareerde kanalen/Skills/configuratieschema’s of bundlecapaciteiten te ontdekken
• plugins.entries.<id>.config te valideren
• Control UI-labels/placeholders aan te vullen
• installatie-/catalogusmetadata te tonen
• goedkope activatie- en setupbeschrijvingen te bewaren zonder de Plugin-runtime te laden

• CLI-laden beperkt zich tot Plugins die eigenaar zijn van de gevraagde primaire opdracht
• kanaalsetup/Plugin-resolutie beperkt zich tot Plugins die eigenaar zijn van de gevraagde kanaal-id
• expliciete provider-setup/runtime-resolutie beperkt zich tot Plugins die eigenaar zijn van de gevraagde provider-id
• Gateway-opstartplanning gebruikt activation.onStartup voor expliciete opstartimports en opstart-opt-outs; elke Plugin zou dit moeten declareren naarmate OpenClaw afstapt van impliciete opstartimports, terwijl Plugins zonder statische capaciteitsmetadata en zonder activation.onStartup nog steeds de verouderde impliciete opstart-sidecar-fallback gebruiken voor compatibiliteit

​

Plugin-cachegrens

• PluginLoaderCacheState en compatibele actieve runtimeregisters
• jiti/modulecaches en public-surface-loadercaches die worden gebruikt om te voorkomen dat hetzelfde runtime-oppervlak herhaaldelijk wordt geïmporteerd
• runtime-afhankelijkheidsspiegels en bestandssysteemcaches voor geïnstalleerde Plugin- artefacten
• kortlevende per-aanroep-maps voor padnormalisatie of dubbele resolutie

• ontdekkingsresultaten
• directe manifestregisters
• manifestregisters die zijn gereconstrueerd uit de geïnstalleerde Plugin-index
• lookup van providereigenaar, modelonderdrukking, providerbeleid of metadata voor publieke artefacten
• enig ander manifest-afgeleid antwoord waarbij een gewijzigd manifest, geïnstalleerde index of laadpad zichtbaar zou moeten zijn bij de volgende metadatalezing

​

Registermodel

• Plugin-records (identiteit, bron, oorsprong, status, diagnostiek)
• tools
• legacy hooks en getypeerde hooks
• kanalen
• providers
• Gateway RPC-handlers
• HTTP-routes
• CLI-registrars
• achtergrondservices
• Plugin-eigen opdrachten

• Plugin-module -> registerregistratie
• core-runtime -> registerconsumptie

​

Conversatiebindingscallbacks

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" of "denied"
• decision: "allow-once", "allow-always" of "deny"
• binding: de opgeloste binding voor goedgekeurde verzoeken
• request: de oorspronkelijke verzoeksamenvatting, detach-hint, afzender-id en conversatiemetadata

​

Provider-runtimehooks

• Manifestmetadata voor goedkope pre-runtime lookup: setup.providers[].envVars, verouderde compatibiliteit providerAuthEnvVars, providerAuthAliases, providerAuthChoices en channelEnvVars.
• Config-time hooks: catalog (legacy discovery) plus applyConfigDefaults.
• Runtimehooks: meer dan 40 optionele hooks voor auth, modelresolutie, stream-wrapping, denkniveaus, replaybeleid en gebruiksendpoints. Zie de volledige lijst onder Hookvolgorde en gebruik.

​

Hookvolgorde en gebruik

​

Provider-voorbeeld

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);
  },
});

​

Ingebouwde voorbeelden

​

Runtime-helpers

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 retourneert de normale core-TTS-uitvoerpayload voor bestands-/spraaknotitie-oppervlakken.
• Gebruikt core-messages.tts-configuratie en providerselectie.
• Retourneert PCM-audiobuffer + samplefrequentie. Plugins moeten resamplen/encoden voor providers.
• listVoices is optioneel per provider. Gebruik dit voor vendor-owned stemkiezers of setupflows.
• Stemlijsten kunnen rijkere metadata bevatten, zoals locale, gender en persoonlijkheidstags voor provider-aware kiezers.
• OpenAI en ElevenLabs ondersteunen momenteel telefonie. Microsoft niet.

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,
    };
  },
});

• Houd TTS-beleid, fallback en antwoordlevering in core.
• Gebruik spraakproviders voor vendor-owned synthese-gedrag.
• Legacy Microsoft edge-invoer wordt genormaliseerd naar de provider-id microsoft.
• Het voorkeursmodel voor ownership is bedrijfsgericht: een vendor-plugin kan tekst-, spraak-, beeld- en toekomstige mediaproviders bezitten naarmate OpenClaw die capability-contracten toevoegt.

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

• Houd orkestratie, fallback, configuratie en channel-wiring in core.
• Houd vendor-gedrag in de provider-plugin.
• Additieve uitbreiding moet getypt blijven: nieuwe optionele methoden, nieuwe optionele resultaatvelden, nieuwe optionele capabilities.
• Videogeneratie volgt al hetzelfde patroon:
  • core bezit het capability-contract en de runtime-helper
  • vendor-plugins registreren api.registerVideoGenerationProvider(...)
  • feature-/channel-plugins consumeren 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 { 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.* is het gedeelde voorkeursoppervlak voor begrip van afbeelding/audio/video.
• Gebruikt core media-understanding audioconfiguratie (tools.media.audio) en provider-fallbackvolgorde.
• Retourneert { text: undefined } wanneer er geen transcriptie-uitvoer wordt geproduceerd (bijvoorbeeld overgeslagen/niet-ondersteunde invoer).
• api.runtime.stt.transcribeAudioFile(...) blijft beschikbaar als compatibiliteitsalias.

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 en model zijn optionele per-run overrides, geen persistente sessiewijzigingen.
• OpenClaw honoreert die override-velden alleen voor vertrouwde callers.
• Voor plugin-owned fallback-runs moeten operators expliciet intekenen met plugins.entries.<id>.subagent.allowModelOverride: true.
• Gebruik plugins.entries.<id>.subagent.allowedModels om vertrouwde plugins te beperken tot specifieke canonieke provider/model-doelen, of "*" om elk doel expliciet toe te staan.
• Subagent-runs van niet-vertrouwde plugins werken nog steeds, maar override-verzoeken worden geweigerd in plaats van stil terug te vallen.
• Door plugins aangemaakte subagent-sessies worden getagd met de id van de aanmakende plugin. Fallback api.runtime.subagent.deleteSession(...) mag alleen die owned sessies verwijderen; willekeurige sessieverwijdering vereist nog steeds een admin-scoped Gateway-request.

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,
  },
});

• Houd providerselectie, credential-resolutie en gedeelde requestsemantiek in core.
• Gebruik webzoekproviders voor vendor-specifieke zoektransports.
• api.runtime.webSearch.* is het gedeelde voorkeursoppervlak voor feature-/channel-plugins die zoekgedrag nodig hebben zonder afhankelijk te zijn van de agent-tool-wrapper.

​

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(...): genereer een afbeelding met de geconfigureerde image-generation providerketen.
• listProviders(...): vermeld beschikbare image-generation providers en hun capabilities.

​

Gateway HTTP-routes

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

• path: routepad onder de Gateway HTTP-server.
• auth: vereist. Gebruik "gateway" om normale Gateway-auth te vereisen, of "plugin" voor plugin-managed auth/Webhook-verificatie.
• match: optioneel. "exact" (standaard) of "prefix".
• replaceExisting: optioneel. Staat dezelfde plugin toe om zijn eigen bestaande routeregistratie te vervangen.
• handler: retourneer true wanneer de route de request heeft afgehandeld.

• api.registerHttpHandler(...) is verwijderd en veroorzaakt een Plugin-laadfout. Gebruik in plaats daarvan api.registerHttpRoute(...).
• Plugin-routes moeten auth expliciet declareren.
• Exacte path + match-conflicten worden geweigerd tenzij replaceExisting: true, en een Plugin kan de route van een andere Plugin niet vervangen.
• Overlappende routes met verschillende auth-niveaus worden geweigerd. Houd exact/prefix-fallthroughketens alleen op hetzelfde auth-niveau.
• auth: "plugin"-routes ontvangen niet automatisch operator-runtime-scopes. Ze zijn bedoeld voor door Plugins beheerde webhooks/handtekeningverificatie, niet voor bevoorrechte Gateway-helperaanroepen.
• auth: "gateway"-routes draaien binnen een Gateway-aanvraag-runtime-scope, maar die scope is bewust conservatief:
  • shared-secret bearer-auth (gateway.auth.mode = "token" / "password") houdt Plugin-route-runtime-scopes vast op operator.write, zelfs als de aanroeper x-openclaw-scopes meestuurt
  • vertrouwde HTTP-modi met identiteit (bijvoorbeeld trusted-proxy of gateway.auth.mode = "none" op een private ingress) respecteren x-openclaw-scopes alleen wanneer de header expliciet aanwezig is
  • als x-openclaw-scopes ontbreekt op die Plugin-route-aanvragen met identiteit, valt de runtime-scope terug op operator.write
• Praktische regel: ga er niet van uit dat een gateway-auth Plugin-route een impliciet admin-oppervlak is. Als je route gedrag vereist dat alleen voor admins is, vereis dan een auth-modus met identiteit en documenteer het expliciete x-openclaw-scopes-headercontract.

​

Plugin SDK-importpaden

• index.js — entry van gebundelde Plugin
• api.js — helper/types-barrel
• runtime-api.js — barrel alleen voor runtime
• setup-entry.js — setup-Plugin-entry

​

Schema’s voor berichttools

• presentation voor semantische presentatieblokken (text, context, divider, buttons, select)
• delivery-pin voor pinned-delivery-aanvragen

​

Resolutie van kanaaldoelen

• messaging.inferTargetChatType({ to }) beslist of een genormaliseerd doel moet worden behandeld als direct, group of channel vóór directory-lookup.
• messaging.targetResolver.looksLikeId(raw, normalized) vertelt core of een invoer direct naar id-achtige resolutie moet gaan in plaats van directory-zoekopdracht.
• messaging.targetResolver.resolveTarget(...) is de Plugin-fallback wanneer core een definitieve provider-eigen resolutie nodig heeft na normalisatie of na een directory-misser.
• messaging.resolveOutboundSessionRoute(...) beheert providerspecifieke sessie- routeconstructie zodra een doel is opgelost.

• Gebruik inferTargetChatType voor categoriebeslissingen die moeten plaatsvinden vóór het zoeken naar peers/groepen.
• Gebruik looksLikeId voor controles op “behandel dit als een expliciete/native target id”.
• Gebruik resolveTarget voor providerspecifieke normalisatie-fallback, niet voor brede directory-zoekopdracht.
• Houd provider-native ids zoals chat-ids, thread-ids, JID’s, handles en room- ids binnen target-waarden of providerspecifieke params, niet in generieke SDK- velden.

​

Door configuratie ondersteunde directories

• door allowlist gestuurde DM-peers
• geconfigureerde kanaal-/groepsmappen
• account-scoped statische directory-fallbacks

• query-filtering
• limiettoepassing
• deduplicatie-/normalisatiehelpers
• ChannelDirectoryEntry[] bouwen

​

Providercatalogi

• { provider } voor één providervermelding
• { providers } voor meerdere providervermeldingen

• simple: eenvoudige providers op basis van API-sleutels of env
• profile: providers die verschijnen wanneer auth-profielen bestaan
• paired: providers die meerdere gerelateerde providervermeldingen synthetiseren
• late: laatste pass, na andere impliciete providers

• discovery werkt nog steeds als legacy-alias
• als zowel catalog als discovery zijn geregistreerd, gebruikt OpenClaw catalog

​

Alleen-lezen kanaalinspectie

• resolveAccount(...) is het runtimepad. Het mag ervan uitgaan dat credentials volledig gematerialiseerd zijn en kan snel falen wanneer vereiste secrets ontbreken.
• Alleen-lezen commandopaden zoals openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve en doctor-/configuratie- reparatiestromen zouden geen runtime-credentials hoeven te materialiseren alleen om configuratie te beschrijven.

• Retourneer alleen beschrijvende accountstatus.
• Behoud enabled en configured.
• Neem credentialbron-/statusvelden op wanneer relevant, zoals:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Je hoeft geen ruwe tokenwaarden te retourneren alleen om alleen-lezen beschikbaarheid te rapporteren. tokenStatus: "available" retourneren (en het bijbehorende bronveld) is genoeg voor statusachtige commando’s.
• Gebruik configured_unavailable wanneer een credential via SecretRef is geconfigureerd maar niet beschikbaar is in het huidige commandopad.

​

Pakketpacks

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

• kanaalregistratie zelf
• alle HTTP-routes die beschikbaar moeten zijn voordat de Gateway begint te luisteren
• alle Gateway-methoden, tools of services die tijdens datzelfde venster moeten bestaan

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

Metagegevens van kanaalcatalogus

{
  "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: secundair label voor rijkere catalogus-/statusoppervlakken
• docsLabel: overschrijf de linktekst voor de documentatielink
• preferOver: Plugin-/kanaal-id’s met lagere prioriteit die dit catalogusitem moet overtreffen
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: tekstinstellingen voor selectieoppervlakken
• markdownCapable: markeert het kanaal als markdown-geschikt voor beslissingen over uitgaande opmaak
• exposure.configured: verberg het kanaal in oppervlakken voor lijsten met geconfigureerde kanalen wanneer ingesteld op false
• exposure.setup: verberg het kanaal in interactieve setup-/configuratiekeuzes wanneer ingesteld op false
• exposure.docs: markeer het kanaal als intern/privé voor documentatienavigatieoppervlakken
• showConfigured / showInSetup: verouderde aliassen die nog steeds voor compatibiliteit worden geaccepteerd; geef de voorkeur aan exposure
• quickstartAllowFrom: laat het kanaal deelnemen aan de standaard quickstart-allowFrom-flow
• forceAccountBinding: vereis expliciete accountbinding, zelfs wanneer er maar één account bestaat
• preferSessionLookupForAnnounceTarget: geef de voorkeur aan sessiezoekopdrachten bij het herleiden van aankondigingsdoelen

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

​

Context-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);
    },
  }));
}

​

Een nieuwe capability toevoegen

1. definieer het corecontract Bepaal welk gedeeld gedrag core moet beheren: beleid, fallback, configuratiesamenvoeging, lifecycle, kanaalgerichte semantiek en de vorm van runtimehelpers.
2. voeg getypeerde Plugin-registratie-/runtimeoppervlakken toe Breid OpenClawPluginApi en/of api.runtime uit met het kleinste nuttige getypeerde capability-oppervlak.
3. koppel core + consumers van kanalen/functies Kanalen en functie-Plugins moeten de nieuwe capability via core gebruiken, niet door rechtstreeks een vendorimplementatie te importeren.
4. registreer vendorimplementaties Vendor-Plugins registreren vervolgens hun backends tegen de capability.
5. voeg contractdekking toe Voeg tests toe zodat eigenaarschap en registratiestructuur in de loop van de tijd expliciet blijven.

​

Capability-checklist

• corecontracttypen in src/<capability>/types.ts
• corerunner/runtimehelper in src/<capability>/runtime.ts
• Plugin-API-registratieoppervlak in src/plugins/types.ts
• Plugin-registerkoppeling in src/plugins/registry.ts
• Plugin-runtimeblootstelling in src/plugins/runtime/* wanneer functie-/kanaal-Plugins deze moeten gebruiken
• capture-/testhelpers in src/test-utils/plugin-registration.ts
• eigenaarschaps-/contractasserties in src/plugins/contracts/registry.ts
• operator-/Plugin-documentatie in docs/

​

Capability-template

// 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 beheert het capability-contract + de orkestratie
• vendor-Plugins beheren vendorimplementaties
• functie-/kanaal-Plugins gebruiken runtimehelpers
• contracttests houden eigenaarschap expliciet

​

Gerelateerd

• Plugin-architectuur — publiek capabilitymodel en vormen
• Plugin SDK-subpaden
• Plugin SDK-setup
• Plugins bouwen