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 mogelijkheid onder beheer van de plugin toevoegen.

U 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: wanneer u ClawHub-resolutie wilt.

Vereisten

  • Node 22.19+, Node 23.11+ of Node 24+, en npm of pnpm.
  • TypeScript-ESM-modules.
  • Voor werk aan een gebundelde plugin binnen de repository kloont u de repository en voert u pnpm install uit. Pluginontwikkeling vanuit een broncodecheckout werkt uitsluitend met pnpm, omdat OpenClaw gebundelde plugins ontdekt via workspace-pakketten in extensions/*.

Kies de pluginvorm

Kanaalplugin

Verbind OpenClaw met een berichtenplatform.
Providerplugin

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

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

Registreer agenttools.

Snel aan de slag

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 de lokale verificatie.

  • Pakketmetagegevens 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 bepalen zonder elke pluginruntime direct te laden. Stel activation.onStartup bewust in; dit voorbeeld wordt geladen wanneer de Gateway opstart.

    Door de host vertrouwde Plugin-oppervlakken worden eveneens door het manifest afgeschermd en vereisen een expliciete declaratie voor geïnstalleerde Plugins: 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 de installatie en de registratie tijdens runtime op elkaar afgestemd.

    Zie Plugin-manifest 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 kanaal-Plugins zijn. Kanaal-Plugins 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 die opdracht dan ook uit en controleer de uitvoer, bijvoorbeeld openclaw demo-plugin ping.

    Voor een gebundelde Plugin in deze repository ontdekt OpenClaw Plugin-pakketten uit de broncheckout via de extensions/*-werkruimte. Voer de meest gerichte test uit:

    bash
    pnpm test extensions/my-plugin/pnpm check

  • De pakketinstallatie testen

    Test vóór publicatie van een pakketklare Plugin dezelfde installatievorm die gebruikers krijgen. Voeg eerst een bouwstap toe, laat runtime-ingangen zoals openclaw.extensions verwijzen naar gebouwde JavaScript, zoals ./dist/index.js, en zorg ervoor dat npm pack die dist/-uitvoer bevat. TypeScript-broningangen zijn uitsluitend bedoeld voor broncheckouts en lokale ontwikkelpaden.

    Pak vervolgens de Plugin in en installeer het tar-archief 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 runtime-afhankelijkheden die tests vanuit een broncheckout kunnen verhullen. Hiermee wordt de pakket- en afhankelijkheidsstructuur aangetoond, niet het aan een catalogus gekoppelde officiële vertrouwen. Runtime-imports moeten in dependencies of optionalDependencies staan; afhankelijkheden die uitsluitend in devDependencies staan, worden niet geïnstalleerd voor het beheerde runtimeproject.

    Gebruik een onbewerkte archief-/padinstallatie niet als definitief bewijs voor officieel of geprivilegieerd plugingedrag. Onbewerkte bronbestanden zijn nuttig voor lokaal debuggen, maar ze 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 bewijs toe via een officiële installatie op basis van een catalogus of een gepubliceerd pakketpad dat officieel vertrouwen registreert. Zie Afhankelijkheidsresolutie voor plugins voor details over de installatiehoofdmap en het eigenaarschap van afhankelijkheden.

  • Publiceren

    Valideer het pakket vóór publicatie:

    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 vereist of optioneel zijn. Vereiste tools zijn altijd beschikbaar wanneer de plugin is ingeschakeld. Voor optionele tools moet de gebruiker zich expliciet aanmelden voordat OpenClaw de runtime van de bijbehorende plugin 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 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 blootgesteld. 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 mogelijkheden die niet standaard moeten worden blootgesteld. Toolnamen mogen niet conflicteren met namen van kerntools; conflicten worden overgeslagen en gemeld in de plugindiagnostiek. Ongeldige registraties worden op dezelfde manier overgeslagen en 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 aangeleverd contextobject. Gebruik ctx.activeModel wanneer een tool informatie over het actieve model voor de huidige beurt moet loggen, weergeven of zich eraan moet aanpassen; dit kan provider, modelId en modelRef bevatten. Beschouw dit als informatieve runtimemetadata, niet als een beveiligingsgrens tegen de lokale beheerder, geïnstalleerde plugincode of een aangepaste OpenClaw-runtime. Gevoelige lokale tools moeten nog steeds expliciete aanmelding door de plugin of beheerder vereisen en veilig weigeren wanneer metadata van het actieve model ontbreekt of ongeschikt is.

    Het manifest declareert eigenaarschap en detectie; bij uitvoering wordt nog steeds de actuele geregistreerde toolimplementatie aangeroepen. Houd toolMetadata.<tool>.optional: true in overeenstemming met 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

    Importeer niet vanuit de verouderde hoofdbarrel:

    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 de koppeling werkelijk generiek is.

    Aangepaste Gateway-RPC-methoden zijn een geavanceerd toegangspunt. Houd ze onder een pluginspecifiek voorvoegsel; kernbeheerdersnaamruimten 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 plugin-HTTP- routes die contracts.gatewayMethodDispatch: ["authenticated-request"] declareren.

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

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