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.

​

Laadpipeline

1. kandidaat-Plugin-roots ontdekken
2. native of compatibele bundelmanifesten en pakketmetadata lezen
3. onveilige kandidaten afwijzen
4. Plugin-config normaliseren (plugins.enabled, allow, deny, entries, slots, load.paths)
5. enablement voor elke kandidaat bepalen
6. ingeschakelde native modules laden: gebouwde gebundelde modules gebruiken een native loader; lokale TypeScript-broncode van derden gebruikt de noodfallback Jiti
7. native register(api) hooks aanroepen en registraties verzamelen in de Plugin registry
8. de registry beschikbaar maken voor commands/runtime-oppervlakken

​

Manifest-first gedrag

• de Plugin te identificeren
• gedeclareerde channels/skills/config-schema of bundelcapabilities te ontdekken
• plugins.entries.<id>.config te valideren
• labels/placeholders in de Control UI aan te vullen
• install-/catalogusmetadata te tonen
• goedkope activation- en setupdescriptors te behouden zonder de Plugin-runtime te laden

• CLI-laden wordt beperkt tot Plugins die eigenaar zijn van de gevraagde primaire command
• channel-setup/Plugin-resolutie wordt beperkt tot Plugins die eigenaar zijn van de gevraagde channel-id
• expliciete provider-setup/runtime-resolutie wordt beperkt tot Plugins die eigenaar zijn van de gevraagde provider-id
• Gateway-opstartplanning gebruikt activation.onStartup voor expliciete opstartimports en opt-outs bij opstarten; Plugins zonder opstartmetadata laden alleen via smallere activation-triggers

​

Plugin-cachegrens

• PluginLoaderCacheState en compatibele actieve runtime registries
• jiti/module-caches en loadercaches voor public surfaces die worden gebruikt om te voorkomen dat hetzelfde runtime surface herhaaldelijk wordt geïmporteerd
• filesystemcaches voor geïnstalleerde Plugin-artifacts
• kortlevende per-call maps voor padnormalisatie of duplicaatresolutie

• discoveryresultaten
• directe manifest registries
• manifest registries die uit de geïnstalleerde Plugin-index zijn gereconstrueerd
• provider owner lookup, model suppression, provider policy of public-artifact- metadata
• elk ander manifest-afgeleid antwoord waarbij een gewijzigd manifest, geïnstalleerde index of laadpad zichtbaar moet zijn bij de volgende metadataread

​

Registrymodel

• Plugin-records (identiteit, bron, herkomst, status, diagnostiek)
• tools
• legacy hooks en typed hooks
• channels
• providers
• Gateway RPC-handlers
• HTTP-routes
• CLI-registrars
• achtergrondservices
• Plugin-eigen commands

• Plugin-module -> registry-registratie
• core-runtime -> registry-consumptie

​

Callbacks voor gespreksbinding

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 requests
• request: de oorspronkelijke requestsamenvatting, detach-hint, sender-id en gespreksmetadata

​

Provider runtime hooks

• Manifestmetadata voor goedkope pre-runtime lookup: setup.providers[].envVars, verouderde compatibiliteit providerAuthEnvVars, providerAuthAliases, providerAuthChoices en channelEnvVars.
• Config-time hooks: catalog (legacy discovery) plus applyConfigDefaults.
• Runtime hooks: meer dan 40 optionele hooks voor auth, modelresolutie, streamwrapping, thinking levels, replay policy en usage endpoints. Zie de volledige lijst onder Hookvolgorde en gebruik.

​

Hookvolgorde en gebruik

​

Providervoorbeeld

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

​

Runtimehelpers

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-outputpayload voor bestands-/spraaknotitieoppervlakken.
• Gebruikt coreconfiguratie messages.tts en providerselectie.
• Retourneert PCM-audiobuffer + samplefrequentie. Plugins moeten resamplen/encoderen voor providers.
• listVoices is optioneel per provider. Gebruik dit voor leveranciersspecifieke stemkiezers of installatieflows.
• Stemlijsten kunnen rijkere metadata bevatten, zoals locale-, gender- en persoonlijkheidstags voor providerbewuste kiezers.
• OpenAI en ElevenLabs ondersteunen vandaag 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 antwoordaflevering in core.
• Gebruik spraakproviders voor leveranciersspecifiek synthese-gedrag.
• Legacy Microsoft-edge-input wordt genormaliseerd naar de microsoft provider-id.
• Het voorkeursmodel voor eigenaarschap is bedrijfsgericht: één leveranciersplugin kan tekst-, spraak-, beeld- en toekomstige mediaproviders bezitten terwijl OpenClaw die capaciteitscontracten toevoegt.

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

• Houd orkestratie, fallback, config en kanaalbedrading in core.
• Houd leveranciersgedrag in de providerplugin.
• Additieve uitbreiding moet getypeerd blijven: nieuwe optionele methoden, nieuwe optionele resultaatvelden, nieuwe optionele capaciteiten.
• Videogeneratie volgt al hetzelfde patroon:
  • core bezit het capaciteitscontract en de runtimehelper
  • leveranciersplugins registreren api.registerVideoGenerationProvider(...)
  • feature-/kanaalplugins gebruiken 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 voorkeurs-gedeelde oppervlak voor begrip van beeld/audio/video.
• Gebruikt core media-understanding-audioconfiguratie (tools.media.audio) en providerfallbackvolgorde.
• Retourneert { text: undefined } wanneer er geen transcriptie-output wordt geproduceerd (bijvoorbeeld overgeslagen/niet-ondersteunde input).
• api.runtime.stt.transcribeAudioFile(...) blijft bestaan 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 overrides per run, geen persistente sessiewijzigingen.
• OpenClaw honoreert die overridevelden alleen voor vertrouwde aanroepers.
• Voor fallbackruns die eigendom zijn van plugins moeten operators zich aanmelden 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.
• Subagentruns van niet-vertrouwde plugins blijven werken, maar overrideverzoeken worden afgewezen in plaats van stilzwijgend terug te vallen.
• Door plugins gemaakte subagentsessies worden getagd met de makende plugin-id. Fallback api.runtime.subagent.deleteSession(...) mag alleen die sessies in eigendom verwijderen; willekeurige sessieverwijdering vereist nog steeds een Gateway-request met admin-scope.

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, credentialresolutie en gedeelde requestsemantiek in core.
• Gebruik webzoekproviders voor leveranciersspecifieke zoektransporten.
• api.runtime.webSearch.* is het voorkeurs-gedeelde oppervlak voor feature-/kanaalplugins die zoekgedrag nodig hebben zonder afhankelijk te zijn van de agenttoolwrapper.

​

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 capaciteiten.

​

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 door plugins beheerde auth/webhook-verificatie.
• match: optioneel. "exact" (standaard) of "prefix".
• replaceExisting: optioneel. Staat dezelfde plugin toe zijn eigen bestaande routeregistratie te vervangen.
• handler: retourneer true wanneer de route het request heeft afgehandeld.

• api.registerHttpHandler(...) is verwijderd en veroorzaakt een laadfout voor een plugin. Gebruik in plaats daarvan api.registerHttpRoute(...).
• Plugin-routes moeten auth expliciet declareren.
• Exacte path + match-conflicten worden geweigerd tenzij replaceExisting: true, en één plugin kan de route van een andere plugin niet vervangen.
• Overlappende routes met verschillende auth-niveaus worden geweigerd. Houd exact/prefix-fallthrough-ketens alleen op hetzelfde auth-niveau.
• auth: "plugin"-routes ontvangen niet automatisch runtime-scopes van de operator. Ze zijn bedoeld voor door plugins beheerde webhooks/handtekeningverificatie, niet voor bevoorrechte Gateway-helperaanroepen.
• auth: "gateway"-routes draaien binnen een runtime-scope van een Gateway-verzoek, maar die scope is bewust conservatief:
  • shared-secret bearer auth (gateway.auth.mode = "token" / "password") houdt runtime-scopes van plugin-routes vastgezet 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) honoreren x-openclaw-scopes alleen wanneer de header expliciet aanwezig is
  • als x-openclaw-scopes ontbreekt op die plugin-routeverzoeken met identiteit, valt de runtime-scope terug op operator.write
• Praktische regel: ga er niet van uit dat een gateway-auth-pluginroute impliciet een beheeroppervlak is. Als je route gedrag vereist dat alleen voor beheerders 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 — runtime-only barrel
• setup-entry.js — entry van setup-plugin

​

Schema’s voor berichttools

• presentation voor semantische presentatieblokken (text, context, divider, buttons, select)
• delivery-pin voor verzoeken om vastgezette aflevering

​

Oplossen van kanaaldoelen

• messaging.inferTargetChatType({ to }) bepaalt of een genormaliseerd doel vóór directory-lookup moet worden behandeld als direct, group of channel.
• messaging.targetResolver.looksLikeId(raw, normalized) vertelt core of een invoer direct naar id-achtige resolutie moet gaan in plaats van directory search.
• messaging.targetResolver.resolveTarget(...) is de pluginfallback wanneer core een uiteindelijke provider-eigen resolutie nodig heeft na normalisatie of na een directory-miss.
• messaging.resolveOutboundSessionRoute(...) bezit 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 doel-id”.
• Gebruik resolveTarget voor providerspecifieke normalisatiefallback, niet voor brede directory search.
• Houd provider-native ids zoals chat-id’s, thread-id’s, JID’s, handles en room- id’s binnen target-waarden of providerspecifieke parameters, niet in generieke SDK- velden.

​

Configuratiegestuurde directories

• allowlist-gestuurde DM-peers
• geconfigureerde kanaal-/groepsmaps
• account-scoped statische directoryfallbacks

• queryfiltering
• toepassing van limieten
• dedupe-/normalisatiehelpers
• bouwen van ChannelDirectoryEntry[]

​

Providercatalogi

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

• simple: eenvoudige API-key- of env-gestuurde providers
• 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

​

Read-only kanaalinspectie

• resolveAccount(...) is het runtime-pad. Het mag ervan uitgaan dat credentials volledig gematerialiseerd zijn en kan snel falen wanneer vereiste secrets ontbreken.
• Read-only opdrachtpaden 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 velden voor credentialbron/status op wanneer relevant, zoals:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Je hoeft geen ruwe tokenwaarden te retourneren alleen om read-only beschikbaarheid te rapporteren. tokenStatus: "available" retourneren (en het overeenkomende bron- veld) is genoeg voor statusachtige opdrachten.
• Gebruik configured_unavailable wanneer een credential via SecretRef is geconfigureerd maar niet beschikbaar is in het huidige opdrachtpad.

​

Pakketpacks

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

• kanaalregistratie zelf
• HTTP-routes die beschikbaar moeten zijn voordat de Gateway begint te luisteren
• 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
    }
  }
}

​

Metadata 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 docs-link
• preferOver: Plugin-/kanaal-id’s met lagere prioriteit die deze catalogusentry moet overtreffen
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: tekstbesturing voor selectieoppervlakken
• markdownCapable: markeert het kanaal als markdown-geschikt voor beslissingen over uitgaande opmaak
• exposure.configured: verberg het kanaal uit listingoppervlakken voor geconfigureerde kanalen wanneer ingesteld op false
• exposure.setup: verberg het kanaal uit interactieve setup-/configuratiekeuzes wanneer ingesteld op false
• exposure.docs: markeer het kanaal als intern/privé voor docs-navigatieoppervlakken
• showConfigured / showInSetup: verouderde aliassen die nog steeds worden geaccepteerd voor compatibiliteit; 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 Core-contract Bepaal welk gedeeld gedrag Core moet beheren: beleid, fallback, config-merge, 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. verbind Core + kanaal-/feature-consumers Kanalen en feature-Plugins moeten de nieuwe capability via Core consumeren, niet door rechtstreeks een vendorimplementatie te importeren.
4. registreer vendorimplementaties Vendor-Plugins registreren daarna hun backends tegen de capability.
5. voeg contractdekking toe Voeg tests toe zodat eigenaarschap en registratievorm in de loop van de tijd expliciet blijven.

​

Capability-checklist

• Core-contracttypes in src/<capability>/types.ts
• Core-runner/runtimehelper in src/<capability>/runtime.ts
• Plugin-API-registratieoppervlak in src/plugins/types.ts
• Plugin-registerbedrading in src/plugins/registry.ts
• Plugin-runtimeblootstelling in src/plugins/runtime/* wanneer feature-/kanaal-Plugins die moeten consumeren
• capture-/testhelpers in src/test-utils/plugin-registration.ts
• eigenaarschap-/contractasserties in src/plugins/contracts/registry.ts
• operator-/Plugin-docs 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 orchestratie
• vendor-Plugins beheren vendorimplementaties
• feature-/kanaal-Plugins consumeren runtimehelpers
• contracttests houden eigenaarschap expliciet

​

Gerelateerd

• Plugin-architectuur — openbaar capability-model en vormen
• Plugin-SDK-subpaden
• Plugin-SDK-setup
• Plugins bouwen