Building plugins

Mogelijkheden toevoegen (gids voor bijdragers)

Gebruik dit wanneer OpenClaw een nieuw gedeeld domein nodig heeft, zoals embeddings, het genereren van afbeeldingen, het genereren van video's of een toekomstig functiegebied dat door leveranciers wordt ondersteund.

De regel:

plugin = eigenaarschapsgrens
capability = gedeeld kerncontract

Koppel een leverancier niet rechtstreeks aan een kanaal of tool. Definieer eerst de capability.

Wanneer je een capability maakt

Maak alleen een nieuwe capability wanneer al het volgende waar is:

Meer dan één leverancier zou deze redelijkerwijs kunnen implementeren.
Kanalen, tools of functieplugins moeten deze kunnen gebruiken zonder rekening te houden met de leverancier.
De kern moet verantwoordelijk zijn voor fallback-, beleids-, configuratie- of afleveringsgedrag.

Als het werk alleen voor een leverancier is en er nog geen gedeeld contract bestaat, definieer dan eerst het contract.

De standaardvolgorde

Definieer het getypeerde kerncontract.
Voeg pluginregistratie voor dat contract toe.
Voeg een gedeelde runtimehelper toe.
Koppel als bewijs één echte leveranciersplugin.
Zet verbruikers in functies en kanalen over op de runtimehelper.
Voeg contracttests toe.
Documenteer de configuratie voor operators en het eigenaarschapsmodel.

Wat waar thuishoort

Laag	Verantwoordelijk voor
Kern	Aanvraag-/antwoordtypen; providerregister en -resolutie; fallbackgedrag; configuratieschema met doorgegeven `title`-/`description`-documentatiemetadata op geneste object-, jokerteken-, array-item- en compositieknooppunten; runtimehelperoppervlak.
Leveranciersplugin	API-aanroepen naar de leverancier, afhandeling van leveranciersauthenticatie, leveranciersspecifieke normalisatie van aanvragen en registratie van de capability-implementatie.
Functie-/kanaalplugin	Roept `api.runtime.` of de overeenkomstige `plugin-sdk/-runtime`-helper aan. Roept nooit rechtstreeks een leveranciersimplementatie aan.

Koppelvlakken voor providers en harnesses

Gebruik providerhooks wanneer het gedrag bij het modelprovidercontract hoort in plaats van bij de generieke agentlus. Voorbeelden zijn providerspecifieke aanvraagparameters na transportselectie, voorkeuren voor authenticatieprofielen, promptoverlays en vervolgroutering voor fallback nadat een model of profiel is uitgevallen.

Gebruik agent-harnesshooks wanneer het gedrag hoort bij de runtime die een beurt uitvoert. Harnesses kunnen expliciete protocoluitkomsten classificeren, zoals lege uitvoer, redenering zonder zichtbare uitvoer of een gestructureerd plan zonder definitief antwoord, zodat het fallbackbeleid van het buitenste model de beslissing over opnieuw proberen kan nemen.

Houd beide koppelvlakken beperkt:

De kern is verantwoordelijk voor het beleid voor opnieuw proberen en fallback.
Providerplugins zijn verantwoordelijk voor providerspecifieke hints voor aanvragen, authenticatie en routering.
Harnessplugins zijn verantwoordelijk voor runtimespecifieke classificatie van pogingen.
Plugins van derden retourneren hints en wijzigen de kernstatus niet rechtstreeks.

Bestandschecklist

Voor een nieuwe capability moet je waarschijnlijk deze gebieden aanpassen:

src/<capability>/types.ts
src/<capability>/...registry/runtime.ts
src/plugins/types.ts
src/plugins/registry.ts
src/plugins/captured-registration.ts
src/plugins/contracts/registry.ts
src/plugins/runtime/types-core.ts
src/plugins/runtime/index.ts
src/plugin-sdk/<capability>.ts
src/plugin-sdk/<capability>-runtime.ts
Een of meer gebundelde pluginpakketten.
Configuratie, documentatie, tests.

Uitgewerkt voorbeeld: afbeeldingen genereren

Het genereren van afbeeldingen volgt de standaardstructuur:

De kern definieert ImageGenerationProvider.
De kern stelt registerImageGenerationProvider(...) beschikbaar.
De kern stelt api.runtime.imageGeneration.generate(...) en .listProviders(...) beschikbaar.
Leveranciersplugins (comfy, deepinfra, fal, google, litellm, microsoft-foundry, minimax, openai, openrouter, vydra, xai) registreren door leveranciers ondersteunde implementaties.
Toekomstige leveranciers registreren hetzelfde contract zonder kanalen of tools te wijzigen.

De configuratiesleutel is bewust gescheiden van routering voor beeldanalyse:

agents.defaults.imageModel analyseert afbeeldingen.
agents.defaults.mediaModels.image genereert afbeeldingen.

Houd deze gescheiden, zodat fallback en beleid expliciet blijven.

Embeddingproviders

Gebruik registerEmbeddingProvider(...) / contract embeddingProviders voor herbruikbare providers van vectorembeddings. Dit contract is bewust breder dan geheugen: tools, zoekfuncties, retrieval, importers of toekomstige functieplugins kunnen embeddings gebruiken zonder afhankelijk te zijn van de geheugenengine. Zoeken in het geheugen gebruikt ook de generieke embeddingProviders.

De oudere geheugenspecifieke registratie-API en het contract memoryEmbeddingProviders zijn verouderd. Gebruik registerEmbeddingProvider en embeddingProviders voor alle nieuwe embeddingproviders.

Reviewchecklist

Controleer het volgende voordat je een nieuwe capability uitbrengt:

Geen enkel kanaal of tool importeert rechtstreeks leverancierscode.
De runtimehelper is het gedeelde pad.
Ten minste één contracttest controleert gebundeld eigenaarschap.
De configuratiedocumentatie vermeldt de nieuwe model-/configuratiesleutel.
De plugindocumentatie legt de eigenaarschapsgrens uit.

Als een PR de capability-laag overslaat en leveranciersgedrag hardcodeert in een kanaal of tool, stuur deze dan terug en definieer eerst het contract.

Gerelateerd

Interne werking van plugins — capability-model, eigenaarschap, laadpijplijn, runtimehelpers.
Plugins bouwen — tutorial voor de eerste plugin.
SDK-overzicht — referentie voor de importstructuur en registratie-API.
Skills maken — aanvullend oppervlak voor bijdragers.

Was this useful?