Building plugins

Mogelijkheden toevoegen (gids voor bijdragers)

Gebruik dit wanneer OpenClaw een nieuw gedeeld domein nodig heeft, zoals embeddings, beeldgeneratie, videogeneratie of een toekomstig functiegebied dat door leveranciers wordt ondersteund.

De regel:

Plugin = eigendomsgrens
capabiliteit = gedeeld kerncontract

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

Wanneer u een capabiliteit maakt

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

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

Als het werk uitsluitend voor een leverancier is en er nog geen gedeeld contract bestaat, definieert u eerst het contract.

De standaardvolgorde

Definieer het getypeerde kerncontract.
Voeg Plugin-registratie voor dat contract toe.
Voeg een gedeelde runtimehelper toe.
Koppel ter bevestiging één echte leveranciers-Plugin.
Laat functie- en kanaalgebruikers de runtimehelper gebruiken.
Voeg contracttests toe.
Documenteer de configuratie voor beheerders en het eigendomsmodel.

Wat hoort waar

Laag	Is eigenaar van
Kern	Aanvraag-/antwoordtypen; providerregister en -resolutie; fallbackgedrag; configuratieschema met doorgegeven documentatiemetagegevens voor `title`/`description` op geneste object-, jokerteken-, array-item- en compositieknooppunten; runtimehelperoppervlak.
Leveranciers-Plugin	API-aanroepen naar de leverancier, afhandeling van leveranciersauthenticatie, leveranciersspecifieke normalisatie van aanvragen en registratie van de capabiliteitsimplementatie.
Functie-/kanaal-Plugin	Roept `api.runtime.` of de bijbehorende helper `plugin-sdk/-runtime` aan. Roept nooit rechtstreeks een leveranciersimplementatie aan.

Koppelpunten voor providers en harnassen

Gebruik providerhooks wanneer het gedrag bij het modelprovidercontract hoort in plaats van bij de algemene agentlus. Voorbeelden zijn providerspecifieke aanvraagparameters na transportselectie, voorkeuren voor authenticatieprofielen, promptoverlays en vervolgfallbackroutering na een failover van model of profiel.

Gebruik agentharnashooks wanneer het gedrag bij de runtime hoort die een beurt uitvoert. Harnassen kunnen expliciete protocolresultaten classificeren, zoals lege uitvoer, redeneringen zonder zichtbare uitvoer of een gestructureerd plan zonder definitief antwoord, zodat het buitenste fallbackbeleid voor modellen kan beslissen of opnieuw moet worden geprobeerd.

Houd beide koppelpunten beperkt:

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

Bestandscontrolelijst

Voor een nieuwe capabiliteit zult u naar verwachting 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 Plugin-pakketten.
Configuratie, documentatie en tests.

Uitgewerkt voorbeeld: beeldgeneratie

Beeldgeneratie volgt de standaardstructuur:

De kern definieert ImageGenerationProvider.
De kern stelt registerImageGenerationProvider(...) beschikbaar.
De kern stelt api.runtime.imageGeneration.generate(...) en .listProviders(...) beschikbaar.
Leveranciers-Plugins (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.imageGenerationModel 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, informatieophaling, importeurs of toekomstige functie-Plugins kunnen embeddings gebruiken zonder afhankelijk te zijn van de geheugenengine. Zoeken in het geheugen gebruikt ook algemene embeddingProviders.

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

Controlelijst voor beoordeling

Controleer voordat u een nieuwe capabiliteit uitbrengt:

Geen enkel kanaal of tool importeert leverancierscode rechtstreeks.
De runtimehelper is het gedeelde pad.
Ten minste één contracttest bevestigt het gebundelde eigenaarschap.
De configuratiedocumentatie noemt de nieuwe model- of configuratiesleutel.
De Plugin-documentatie legt de eigendomsgrens uit.

Als een PR de capabiliteitslaag overslaat en leveranciersgedrag rechtstreeks in een kanaal of tool vastlegt, stuurt u deze terug en definieert u eerst het contract.

Gerelateerd

Interne werking van Plugins — capabiliteitsmodel, eigenaarschap, laadpijplijn en runtimehelpers.
Plugins bouwen — zelfstudie voor de eerste Plugin.
SDK-overzicht — referentie voor de importtoewijzing en registratie-API.
Skills maken — aanvullend oppervlak voor bijdragers.

Was this useful?