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 functionaliteit 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>

Kale pakketspecificaties worden tijdens de overgang bij de lancering nog steeds vanaf 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.
  • Voor werk aan een gebundelde plugin in de repository kloon je de repository en voer je pnpm install uit. Pluginontwikkeling vanuit een broncheckout werkt alleen met pnpm, omdat OpenClaw gebundelde plugins ontdekt via extensions/*-werkruimtepakketten.

Kies de pluginvorm

Kanaalplugin

Verbind OpenClaw met een berichtenplatform.
Providerplugin

Voeg een model-, media-, zoek-, ophaal-, spraak- of realtimeprovider 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": "Voegt een aangepaste tool toe aan 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, ook zonder configuratie. Runtimetools moeten voorkomen in contracts.tools, zodat OpenClaw het eigenaarschap kan ontdekken zonder elke pluginruntime voortijdig te laden. Stel activation.onStartup bewust in; dit voorbeeld wordt geladen wanneer de Gateway wordt gestart.

    Ook door de host vertrouwde pluginoppervlakken worden door het manifest afgeschermd en vereisen een expliciete declaratie voor geïnstalleerde plugins: api.registerAgentToolResultMiddleware(...) vereist dat elke doelruntime wordt vermeld in contracts.agentToolResultMiddleware, en api.registerTrustedToolPolicy(...) vereist elke beleids-id in contracts.trustedToolPolicies. Deze declaraties houden de inspectie tijdens installatie en 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: "Voegt een aangepaste tool toe aan OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Eén invoerwaarde teruggeven",      parameters: Type.Object({ input: Type.String() }),      outputSchema: Type.Object(        { input: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        const details = { input: params.input };        return {          content: [{ type: "text", text: `Ontvangen: ${params.input}` }],          details,        };      },    });  },});

    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 gebundelde plugin in deze repository ontdekt OpenClaw pluginpakketten uit een broncheckout via de werkruimte extensions/*. Voer de meest gerichte test uit:

    bash
    pnpm test extensions/my-plugin/pnpm check

  • De pakketinstallatie testen

    Voordat je een publicatieklare plugin publiceert, test je dezelfde installatievorm die gebruikers ontvangen. Voeg eerst een bouwstap toe, laat runtime-toegangspunten zoals openclaw.extensions verwijzen naar gebouwde JavaScript-bestanden zoals ./dist/index.js, 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 tarballbestand 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 zo fouten in runtime-afhankelijkheden die tests vanuit een broncheckout kunnen verbergen. Hiermee wordt de pakket- en afhankelijkheidsvorm aangetoond, niet officiële vertrouwensstatus via een catalogus. 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- of padinstallatie als definitieve verificatie voor officieel of bevoorrecht plugingedrag. Onbewerkte bronnen zijn nuttig voor lokale foutopsporing, maar tonen niet hetzelfde afhankelijkheidspad aan als installaties via npm of ClawHub. Als je plugin afhankelijk is van de vertrouwde status van een officiële plugin, voeg je een tweede verificatie toe via een officiële installatie op basis van een catalogus of een gepubliceerd pakketpad dat officiële vertrouwensstatus vastlegt. Zie Resolutie van plugin-afhankelijkheden 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 bijbehorende pluginruntime laadt.

    Toolfabrieken ontvangen vertrouwde runtimecontext, waaronder deliveryContext, nativeChannelId voor het actieve platformgesprek wanneer beschikbaar, en requesterSenderId.

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

    outputSchema is optioneel. Het beschrijft de gestructureerde details-waarde die wordt gebruikt door Codemodus en Toolzoekfunctie. Catalogus- aanroepen weigeren ongeldige schema's vóór uitvoering en valideren de uiteindelijke waarde na toolhooks. Laat het weg voor tools zonder een stabiel JSON-resultaat. Zie Toolplugins voor het volledige contract.

    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 melden zich aan met tools.allow:

    json5
    {  tools: { allow: ["workflow_tool"] }, // of ["my-plugin"] voor elke tool van één plugin}

    Optionele tools bepalen of een tool aan het model wordt aangeboden. Gebruik pluginmachtigingsverzoeken 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 functionaliteiten 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.

    Toolfabrieken 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 beveiligingsgrens tegen de lokale beheerder, geïnstalleerde plugincode of een gewijzigde OpenClaw-runtime. Gevoelige lokale tools moeten nog steeds expliciete toestemming op plugin- of beheerdersniveau vereisen en veilig weigeren wanneer metadata over het actieve model ontbreekt of ongeschikt is.

    Het manifest declareert eigenaarschap en ontdekking; bij de uitvoering wordt nog steeds de actieve, geregistreerde toolimplementatie aangeroepen. Houd toolMetadata.<tool>.optional: true afgestemd op api.registerTool(..., { optional: true }), zodat OpenClaw kan voorkomen dat die pluginruntime wordt geladen totdat de tool expliciet op de toelatingslijst staat.

    Importconventies

    Importeer vanuit gerichte SDK-subpaden:

    typescript

    Gebruik binnen je pluginpakket lokale barrelbestanden 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 het koppelvlak echt generiek is.

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

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

    Compatibiliteitsvelden van de OpenClaw-SDK bevatten TypeScript-annotaties van het type @deprecated, die editors als migratiewaarschuwingen tonen. Om ze tijdens het bouwen af te dwingen, schakel je een typebewuste regel in, zoals @typescript-eslint/no-deprecated. Oxlint is niet typebewust en kan deze annotaties daarom niet afdwingen.

    Controlelijst vóór indiening

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

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

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

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

    Was this useful?
    On this page

    On this page