OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Building plugins

Plugins bouwen

Plugins breiden OpenClaw uit zonder de kern te wijzigen. Een plugin kan een berichtenkanaal, modelprovider, lokale CLI-backend, agenttool, hook, mediaprovider of een andere door de plugin beheerde mogelijkheid toevoegen.

Je hoeft geen externe plugin aan de OpenClaw-repository toe te voegen. Publiceer het pakket op ClawHub, waarna gebruikers het installeren met:

bash
openclaw plugins install clawhub:<package-name>

Tijdens de overgang bij de lancering worden kale pakketspecificaties nog steeds vanuit npm geïnstalleerd. Gebruik het voorvoegsel clawhub: als je ClawHub-resolutie wilt.

Vereisten

  • Node 22.22.3+, Node 24.15+ of Node 25.9+, en npm of pnpm.
  • TypeScript ESM-modules.
  • Kloon voor werk aan in de repository gebundelde plugins de repository en voer pnpm install uit. Pluginontwikkeling vanuit een broncheckout werkt alleen met pnpm, omdat OpenClaw gebundelde plugins detecteert vanuit extensions/*-workspacepakketten.

Kies de pluginvorm

Kanaalplugin

Verbind OpenClaw met een berichtenplatform.
Providerplugin

Voeg een provider voor modellen, media, zoeken, ophalen, spraak of realtimegebruik toe.
CLI-backendplugin

Voer een lokale AI-CLI uit via de modelfallback van OpenClaw.
Toolplugin

Registreer agenttools.

Snelstart

Bouw een minimale toolplugin door één verplichte agenttool te registreren. Dit is de kortste bruikbare pluginvorm en omvat het pakket, het manifest, het toegangspunt en lokale verificatie.

  • Pakketmetadata maken

    package.json
    {"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"openclaw": {"extensions": ["./index.ts"],"compat": {"pluginApi": ">=2026.3.24-beta.2","minGatewayVersion": "2026.3.24-beta.2"},"build": {"openclawVersion": "2026.3.24-beta.2","pluginSdkVersion": "2026.3.24-beta.2"}}}
    openclaw.plugin.json
    {"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

    Gepubliceerde externe plugins moeten runtime-toegangspunten naar gebouwde JavaScript- bestanden laten verwijzen. Zie SDK-toegangspunten voor het volledige contract voor toegangspunten.

    Elke plugin heeft een manifest nodig, zelfs zonder configuratie. Runtimetools moeten in contracts.tools staan, zodat OpenClaw het eigenaarschap kan detecteren zonder elke pluginruntime voortijdig te laden. Stel activation.onStartup bewust in; dit voorbeeld wordt geladen wanneer de Gateway start.

    Door de host vertrouwde pluginoppervlakken worden ook door het manifest afgeschermd en vereisen voor geïnstalleerde plugins een expliciete declaratie: api.registerAgentToolResultMiddleware(...) vereist dat elke doelruntime in contracts.agentToolResultMiddleware wordt vermeld, en api.registerTrustedToolPolicy(...) vereist elke beleids-id in contracts.trustedToolPolicies. Deze declaraties houden de inspectie tijdens installatie en de runtimeregistratie op elkaar afgestemd.

    Zie Pluginmanifest voor elk manifestveld.

  • De tool registreren

    index.ts
    import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

    Gebruik definePluginEntry voor plugins die geen kanaalplugin zijn. Kanaalplugins gebruiken in plaats daarvan defineChannelPluginEntry uit openclaw/plugin-sdk/core.

  • De runtime testen

    Inspecteer voor een geïnstalleerde of externe plugin de geladen runtime:

    bash
    openclaw plugins inspect my-plugin --runtime --json

    Als de plugin een CLI-opdracht registreert, voer je die opdracht ook uit en controleer je de uitvoer, bijvoorbeeld openclaw demo-plugin ping.

    Voor een in deze repository gebundelde plugin detecteert OpenClaw pluginpakketten uit een broncheckout via de extensions/*-workspace. Voer de meest gerichte test uit:

    bash
    pnpm test extensions/my-plugin/pnpm check

  • De pakketinstallatie testen

    Test voordat je een publicatieklaar pluginpakket publiceert dezelfde installatievorm die gebruikers zullen krijgen. Voeg eerst een bouwstap toe, laat runtime-toegangspunten zoals openclaw.extensions naar gebouwde JavaScript-bestanden zoals ./dist/index.js verwijzen en zorg dat npm pack die dist/-uitvoer bevat. TypeScript-brontoegangspunten zijn alleen bedoeld voor broncheckouts en lokale ontwikkelpaden.

    Pak daarna de plugin in en installeer het tar-bestand met npm-pack::

    bash
    npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

    npm-pack: gebruikt het door OpenClaw beheerde npm-project per plugin en detecteert daardoor fouten in runtimeafhankelijkheden die tests vanuit een broncheckout kunnen verbergen. Het verifieert de pakket- en afhankelijkheidsvorm, niet de officiële vertrouwensstatus die aan de catalogus is gekoppeld. Runtime-imports moeten in dependencies of optionalDependencies staan; afhankelijkheden die alleen in devDependencies staan, worden niet geïnstalleerd voor het beheerde runtimeproject.

    Gebruik geen onbewerkte archief-/padinstallatie als definitieve verificatie voor officieel of bevoorrecht plugingedrag. Onbewerkte bronnen zijn nuttig voor lokale foutopsporing, maar bewijzen niet hetzelfde afhankelijkheidspad als installaties via npm of ClawHub. Als je plugin afhankelijk is van de vertrouwde status van een officiële plugin, voeg dan een tweede verificatie toe via een door de catalogus ondersteunde officiële installatie of een gepubliceerd pakketpad dat het officiële vertrouwen vastlegt. Zie Resolutie van pluginafhankelijkheden voor details over de installatieroot en het eigenaarschap van afhankelijkheden.

  • Publiceren

    Valideer het pakket voordat je het publiceert:

    bash
    clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

    Canonieke ClawHub-pakketfragmenten staan in docs/snippets/plugin-publish/.

  • Installeren

    Installeer het gepubliceerde pakket via ClawHub:

    bash
    openclaw plugins install clawhub:your-org/your-plugin

    • Tools registreren

    Tools kunnen verplicht of optioneel zijn. Verplichte tools zijn altijd beschikbaar wanneer de plugin is ingeschakeld. Voor optionele tools moet de gebruiker expliciet toestemming geven voordat OpenClaw de runtime van de eigenaarplugin laadt.

    Toolfactories ontvangen vertrouwde runtimecontext, waaronder deliveryContext, nativeChannelId voor het actieve platformgesprek indien beschikbaar, en requesterSenderId.

    typescript
    register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "Run a workflow",      parameters: Type.Object({ pipeline: Type.String() }),      async execute(_id, params) {        return { content: [{ type: "text", text: params.pipeline }] };      },    },    { optional: true },  );}

    Elke tool die met api.registerTool(...) wordt geregistreerd, moet ook in het pluginmanifest worden gedeclareerd:

    json
    {  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

    Gebruikers geven toestemming met tools.allow:

    json5
    {  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin}

    Optionele tools bepalen of een tool aan het model wordt aangeboden. Gebruik verzoeken om pluginmachtigingen wanneer een tool of hook om goedkeuring moet vragen nadat het model deze heeft geselecteerd en voordat de actie wordt uitgevoerd.

    Gebruik optionele tools voor neveneffecten, ongebruikelijke binaire bestanden of mogelijkheden die niet standaard beschikbaar mogen zijn. Toolnamen mogen niet conflicteren met namen van kerntools; conflicten worden overgeslagen en gemeld in de plugindiagnostiek. Ongeldige registraties worden overgeslagen en op dezelfde manier gemeld: een ontbrekende, niet-lege name, een execute die geen functie is, of een tooldescriptor zonder een parameters- object.

    Toolfactories ontvangen een door de runtime geleverd contextobject. Gebruik ctx.activeModel wanneer een tool voor de huidige beurt moet loggen, weergeven of zich moet aanpassen aan het actieve model; dit kan provider, modelId en modelRef bevatten. Beschouw dit als informatieve runtimemetadata, niet als een beveiligingsgrens tegen de lokale operator, geïnstalleerde plugincode of een aangepaste OpenClaw-runtime. Gevoelige lokale tools moeten nog steeds expliciete toestemming van de plugin of operator vereisen en gesloten falen wanneer metadata van het actieve model ontbreekt of ongeschikt is.

    Het manifest declareert eigenaarschap en detectie; voor de uitvoering wordt nog steeds de actieve geregistreerde toolimplementatie aangeroepen. Houd toolMetadata.<tool>.optional: true afgestemd op api.registerTool(..., { optional: true }), zodat OpenClaw het laden van die pluginruntime kan uitstellen totdat de tool expliciet op de toelatingslijst staat.

    Importconventies

    Importeer vanuit gerichte SDK-subpaden:

    typescript

    Importeer niet vanuit de verouderde root-barrel:

    typescript

    Gebruik binnen je pluginpakket lokale barrel-bestanden zoals api.ts en runtime-api.ts voor interne imports. Importeer je eigen plugin niet via een SDK-pad. Providerspecifieke helpers moeten in het providerpakket blijven, tenzij de koppeling werkelijk generiek is.

    Aangepaste Gateway-RPC-methoden zijn een geavanceerd toegangspunt. Plaats ze onder een pluginspecifiek voorvoegsel; beheernamespaces van de kern, zoals config.*, exec.approvals.*, operator.admin.*, wizard.* en update.*, blijven gereserveerd en worden omgezet in operator.admin. De openclaw/plugin-sdk/gateway-method-runtime-bridge is gereserveerd voor HTTP-routes van plugins die contracts.gatewayMethodDispatch: ["authenticated-request"] declareren.

    Zie Overzicht van de Plugin-SDK voor de volledige importkaart.

    Checklist vóór indiening

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json bevat correcte openclaw-metadata OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Het manifest openclaw.plugin.json is aanwezig en geldig OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Het toegangspunt gebruikt defineChannelPluginEntry of definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Alle imports gebruiken gerichte plugin-sdk/<subpath>-paden OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page