Plugins bouwen

Plugins breiden OpenClaw uit met nieuwe mogelijkheden: kanalen, modelproviders, spraak, realtime transcriptie, realtime stem, mediabegrip, afbeeldinggeneratie, videogeneratie, web fetch, web search, agenttools, of elke combinatie. Je hoeft je plugin niet aan de OpenClaw-repository toe te voegen. Publiceer naar ClawHub en gebruikers installeren met openclaw plugins install <package-name>. OpenClaw probeert eerst ClawHub en valt automatisch terug op npm voor pakketten die nog npm-distributie gebruiken.

Vereisten

Node >= 22 en een pakketbeheerder (npm of pnpm)
Vertrouwdheid met TypeScript (ESM)
Voor plugins in de repo: repository gekloond en pnpm install uitgevoerd

Wat voor soort plugin?

Kanaalplugin

Verbind OpenClaw met een berichtenplatform (Discord, IRC, enz.)

Providerplugin

Voeg een modelprovider toe (LLM, proxy of aangepast endpoint)

Tool- / hookplugin

Registreer agenttools, eventhooks of services — ga hieronder verder

Gebruik voor een kanaalplugin waarvan niet gegarandeerd is dat die is geïnstalleerd wanneer onboarding/setup wordt uitgevoerd createOptionalChannelSetupSurface(...) uit openclaw/plugin-sdk/channel-setup. Dit maakt een setupadapter + wizardpaar dat de installatievereiste vermeldt en echt schrijven naar configuratie gesloten laat falen totdat de plugin is geïnstalleerd.

Snel starten: toolplugin

Deze walkthrough maakt een minimale plugin die een agenttool registreert. Kanaal- en providerplugins hebben eigen handleidingen waar hierboven naar wordt gelinkt.

Maak het pakket en het manifest

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "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"
    }
  }
}

Elke plugin heeft een manifest nodig, zelfs zonder configuratie, en elke plugin hoort activation.onStartup bewust te declareren. Runtime-geregistreerde tools hebben startup-import nodig, dus dit voorbeeld stelt dit in op true. Zie Manifest voor het volledige schema. De canonieke ClawHub- publicatiesnippets staan in docs/snippets/plugin-publish/.

Schrijf het entrypoint

// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds a custom tool to OpenClaw",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "Do a thing",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: `Got: ${params.input}` }] };
      },
    });
  },
});

definePluginEntry is voor niet-kanaalplugins. Gebruik voor kanalen defineChannelPluginEntry — zie Kanaalplugins. Zie Entrypoints voor alle entrypointopties.

Test en publiceer

Externe plugins: valideer en publiceer met ClawHub, installeer daarna:

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin

OpenClaw controleert ook ClawHub vóór npm voor kale pakketspecificaties zoals @myorg/openclaw-my-plugin; npm blijft een fallback voor pakketten die nog niet naar ClawHub zijn gemigreerd.Plugins in de repo: plaats ze onder de gebundelde plugin-workspaceboom — automatisch ontdekt.

pnpm test -- <bundled-plugin-root>/my-plugin/

Pluginmogelijkheden

Eén plugin kan een willekeurig aantal mogelijkheden registreren via het api-object:

Mogelijkheid	Registratiemethode	Gedetailleerde handleiding
Tekstinferentie (LLM)	`api.registerProvider(...)`	Providerplugins
CLI-inferentiebackend	`api.registerCliBackend(...)`	CLI-backends
Kanaal / berichten	`api.registerChannel(...)`	Kanaalplugins
Spraak (TTS/STT)	`api.registerSpeechProvider(...)`	Providerplugins
Realtime transcriptie	`api.registerRealtimeTranscriptionProvider(...)`	Providerplugins
Realtime stem	`api.registerRealtimeVoiceProvider(...)`	Providerplugins
Mediabegrip	`api.registerMediaUnderstandingProvider(...)`	Providerplugins
Afbeeldinggeneratie	`api.registerImageGenerationProvider(...)`	Providerplugins
Muziekgeneratie	`api.registerMusicGenerationProvider(...)`	Providerplugins
Videogeneratie	`api.registerVideoGenerationProvider(...)`	Providerplugins
Web fetch	`api.registerWebFetchProvider(...)`	Providerplugins
Web search	`api.registerWebSearchProvider(...)`	Providerplugins
Toolresultaatmiddleware	`api.registerAgentToolResultMiddleware(...)`	SDK-overzicht
Agenttools	`api.registerTool(...)`	Hieronder
Aangepaste opdrachten	`api.registerCommand(...)`	Entrypoints
Pluginhooks	`api.on(...)`	Pluginhooks
Interne eventhooks	`api.registerHook(...)`	Entrypoints
HTTP-routes	`api.registerHttpRoute(...)`	Internals
CLI-subopdrachten	`api.registerCli(...)`	Entrypoints

Zie SDK-overzicht voor de volledige registratie-API. Gebundelde plugins kunnen api.registerAgentToolResultMiddleware(...) gebruiken wanneer ze asynchrone herschrijving van toolresultaten nodig hebben voordat het model de output ziet. Declareer de gerichte runtimes in contracts.agentToolResultMiddleware, bijvoorbeeld ["pi", "codex"]. Dit is een vertrouwde seam voor gebundelde plugins; externe plugins horen reguliere OpenClaw-pluginhooks te gebruiken tenzij OpenClaw een expliciet vertrouwensbeleid voor deze mogelijkheid krijgt. Als je plugin aangepaste Gateway-RPC-methoden registreert, houd ze dan op een plugin-specifiek prefix. Core-adminnamespaces (config.*, exec.approvals.*, wizard.*, update.*) blijven gereserveerd en worden altijd opgelost naar operator.admin, zelfs als een plugin om een smallere scope vraagt. Hook-guardsemantiek om rekening mee te houden:

before_tool_call: { block: true } is terminaal en stopt handlers met lagere prioriteit.
before_tool_call: { block: false } wordt behandeld als geen beslissing.
before_tool_call: { requireApproval: true } pauzeert agentuitvoering en vraagt de gebruiker om goedkeuring via de exec-goedkeuringsoverlay, Telegram-knoppen, Discord-interacties of de opdracht /approve op elk kanaal.
before_install: { block: true } is terminaal en stopt handlers met lagere prioriteit.
before_install: { block: false } wordt behandeld als geen beslissing.
message_sending: { cancel: true } is terminaal en stopt handlers met lagere prioriteit.
message_sending: { cancel: false } wordt behandeld als geen beslissing.
message_received: geef de voorkeur aan het getypeerde veld threadId wanneer je inkomende thread-/topicrouting nodig hebt. Bewaar metadata voor kanaalspecifieke extra’s.
message_sending: geef de voorkeur aan getypeerde routingvelden replyToId / threadId boven kanaalspecifieke metadatasleutels.

De opdracht /approve verwerkt zowel exec- als plugingoedkeuringen met begrensde fallback: wanneer een exec-goedkeurings-id niet wordt gevonden, probeert OpenClaw hetzelfde id opnieuw via plugingoedkeuringen. Doorsturen van plugingoedkeuringen kan onafhankelijk worden geconfigureerd via approvals.plugin in config. Als aangepaste goedkeuringsplumbing hetzelfde begrensde fallbackgeval moet detecteren, gebruik dan bij voorkeur isApprovalNotFoundError uit openclaw/plugin-sdk/error-runtime in plaats van handmatig approval-expiry-strings te matchen. Zie Pluginhooks voor voorbeelden en de hookreferentie.

Agenttools registreren

Tools zijn getypeerde functies die de LLM kan aanroepen. Ze kunnen vereist zijn (altijd beschikbaar) of optioneel (opt-in door gebruiker):

register(api) {
  // Required tool — always available
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // Optional tool — user must add to allowlist
  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 },
  );
}

Gebruikers schakelen optionele tools in config in:

{
  tools: { allow: ["workflow_tool"] },
}

Toolnamen mogen niet botsen met coretools (conflicten worden overgeslagen)
Tools met misvormde registratieobjecten, inclusief ontbrekende parameters, worden overgeslagen en gemeld in plugindiagnostiek in plaats van agentruns te breken
Gebruik optional: true voor tools met side effects of extra binaire vereisten
Gebruikers kunnen alle tools van een plugin inschakelen door de plugin-id toe te voegen aan tools.allow

Importconventies

Importeer altijd uit gerichte paden openclaw/plugin-sdk/<subpath>:

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";

Zie SDK-overzicht voor de volledige subpadreferentie. Gebruik binnen je plugin lokale barrel-bestanden (api.ts, runtime-api.ts) voor interne imports — importeer je eigen plugin nooit via het SDK-pad. Houd voor providerplugins providerspecifieke helpers in die package-root barrels, tenzij de seam echt generiek is. Huidige gebundelde voorbeelden:

Anthropic: Claude-streamwrappers en service_tier / betahelpers
OpenAI: providerbouwers, helpers voor standaardmodellen, realtimeproviders
OpenRouter: providerbouwer plus onboarding-/configuratiehelpers

Als een helper alleen nuttig is binnen één gebundeld providerpackage, houd deze dan op die package-root seam in plaats van deze te promoveren naar openclaw/plugin-sdk/*. Sommige gegenereerde helper-seams voor openclaw/plugin-sdk/<bundled-id> bestaan nog steeds voor onderhoud van gebundelde plugins wanneer ze gevolgd eigenaarsgebruik hebben. Behandel die als gereserveerde surfaces, niet als het standaardpatroon voor nieuwe plugins van derden.

Checklist vóór indiening

package.json heeft correcte openclaw-metadata

openclaw.plugin.json-manifest is aanwezig en geldig

Entry point gebruikt defineChannelPluginEntry of definePluginEntry

Alle imports gebruiken gerichte plugin-sdk/<subpath>-paden

Interne imports gebruiken lokale modules, geen SDK-self-imports

Tests slagen (pnpm test -- <bundled-plugin-root>/my-plugin/)

pnpm check slaagt (plugins in de repo)

Testen van betareleases

Let op GitHub-releasetags op openclaw/openclaw en abonneer je via Watch > Releases. Betatags zien eruit als v2026.3.N-beta.1. Je kunt ook meldingen inschakelen voor het officiële OpenClaw X-account @openclaw voor releaseaankondigingen.
Test je plugin tegen de betatag zodra die verschijnt. De periode vóór stable is meestal maar een paar uur.
Plaats na het testen een bericht in de thread van je plugin in het Discord-kanaal plugin-forum met all good of wat er kapot ging. Als je nog geen thread hebt, maak er dan een.
Als er iets kapotgaat, open of update dan een issue met de titel Beta blocker: <plugin-name> - <summary> en pas het label beta-blocker toe. Zet de issuelink in je thread.
Open een PR naar main met de titel fix(<plugin-id>): beta blocker - <summary> en link het issue in zowel de PR als je Discord-thread. Contributors kunnen PR’s niet labelen, dus de titel is het PR-signaal voor maintainers en automatisering. Blockers met een PR worden gemerged; blockers zonder PR kunnen toch worden uitgebracht. Maintainers volgen deze threads tijdens bètatests.
Stilte betekent groen. Als je de periode mist, landt je fix waarschijnlijk in de volgende cyclus.

Volgende stappen

Kanaalplugins

Bouw een messagingkanaalplugin

Providerplugins

Bouw een modelproviderplugin

SDK-overzicht

Importmap en referentie voor de registratie-API

Runtimehelpers

TTS, zoeken, subagent via api.runtime

Testen

Testhulpmiddelen en patronen

Pluginmanifest

Volledige schemareferentie voor het manifest

Gerelateerd

Pluginarchitectuur — diepgaande uitleg van de interne architectuur
SDK-overzicht — referentie voor de Plugin-SDK
Manifest — manifestindeling voor plugins
Kanaalplugins — kanaalplugins bouwen
Providerplugins — providerplugins bouwen

Overview

Plugins

Skills

Automation and tasks

Tools

Agent coordination

Vereisten

Wat voor soort plugin?

Kanaalplugin

Providerplugin

Tool- / hookplugin

Snel starten: toolplugin

Pluginmogelijkheden

Agenttools registreren

Importconventies

Checklist vóór indiening

Testen van betareleases

Volgende stappen

Kanaalplugins

Providerplugins

SDK-overzicht

Runtimehelpers

Testen

Pluginmanifest

Gerelateerd

Overview

Plugins

Skills

Automation and tasks

Tools

Agent coordination

Documentation Index

​Vereisten

​Wat voor soort plugin?

Kanaalplugin

Providerplugin

Tool- / hookplugin

​Snel starten: toolplugin

​Pluginmogelijkheden

​Agenttools registreren

​Importconventies

​Checklist vóór indiening

​Testen van betareleases

​Volgende stappen

Kanaalplugins

Providerplugins

SDK-overzicht

Runtimehelpers

Testen

Pluginmanifest

​Gerelateerd

Vereisten

Wat voor soort plugin?

Snel starten: toolplugin

Pluginmogelijkheden

Agenttools registreren

Importconventies

Checklist vóór indiening

Testen van betareleases

Volgende stappen

Gerelateerd