Naar hoofdinhoud gaan
Plugins breiden OpenClaw uit zonder core te wijzigen. Een plugin kan een messaging channel, modelprovider, lokale CLI-backend, agenttool, hook, mediaprovider, of een andere door de plugin beheerde capability toevoegen. Je hoeft geen externe plugin aan de OpenClaw-repository toe te voegen. Publiceer het package naar ClawHub en gebruikers installeren het met: 
openclaw plugins install clawhub:<package-name>
Bare package specs installeren tijdens de launch-cutover nog steeds vanaf npm. Gebruik de prefix clawhub: wanneer je ClawHub-resolutie wilt.

​
Vereisten

  • Gebruik Node 22.19+, Node 23.11+, of Node 24+ en een package manager zoals npm of pnpm.
  • Wees vertrouwd met TypeScript ESM-modules.
  • Voor in-repo gebundeld pluginwerk: clone de repository en voer pnpm install uit. Source-checkout pluginontwikkeling is alleen pnpm, omdat OpenClaw gebundelde plugins laadt vanuit extensions/* workspace-packages.

​
Kies de pluginvorm

Channel plugin

Verbind OpenClaw met een messagingplatform.

Provider plugin

Voeg een model-, media-, zoek-, fetch-, spraak- of realtimeprovider toe.

CLI backend plugin

Voer een lokale AI-CLI uit via OpenClaw-modelterugval.

Tool plugin

Registreer agenttools.

​
Snelstart

Bouw een minimale toolplugin door één vereiste agenttool te registreren. Dit is de kortste nuttige pluginvorm en toont het package, manifest, entrypoint en lokale bewijs.
1

Create package metadata

{
  "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"
    }
  }
}

{
  "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-entry’s naar gebouwde JavaScript- bestanden laten wijzen. Zie SDK-entrypoints voor het volledige entrypointcontract.Elke plugin heeft een manifest nodig, ook wanneer die geen config heeft. Runtimetools moeten in contracts.tools staan zodat OpenClaw ownership kan ontdekken zonder elke pluginruntime eager te laden. Stel activation.onStartup bewust in. Dit voorbeeld start bij het opstarten van de Gateway.Door de host vertrouwde pluginoppervlakken zijn ook manifest-gated en vereisen expliciete inschakeling voor geïnstalleerde plugins. Als een geïnstalleerde plugin api.registerAgentToolResultMiddleware(...) registreert, declareer dan elke doelruntime in contracts.agentToolResultMiddleware. Als die api.registerTrustedToolPolicy(...) registreert, declareer dan elke policy-id in contracts.trustedToolPolicies. Deze declaraties houden inspectie tijdens installatie en runtimeregistratie op elkaar afgestemd.Zie voor elk manifestveld Pluginmanifest.
2

Register the tool

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 niet-channelplugins. Channelplugins gebruiken defineChannelPluginEntry.
3

Test the runtime

Inspecteer voor een geïnstalleerde of externe plugin de geladen runtime:
openclaw plugins inspect my-plugin --runtime --json
Als de plugin een CLI-command registreert, voer dat command dan ook uit. Een demo-command moet bijvoorbeeld uitvoeringsbewijs hebben zoals openclaw demo-plugin ping.Voor een gebundelde plugin in deze repository ontdekt OpenClaw source-checkout pluginpackages vanuit de extensions/* workspace. Voer de dichtstbijzijnde gerichte test uit:
pnpm test -- extensions/my-plugin/
pnpm check
4

Test the package install

Test vóór het publiceren van een package-ready plugin dezelfde installatievorm die gebruikers krijgen. Voeg eerst een buildstap toe, laat runtime-entry’s zoals openclaw.extensions wijzen naar gebouwde JavaScript zoals ./dist/index.js, en zorg dat npm pack die dist/-output bevat. TypeScript-source-entry’s zijn alleen voor source-checkouts en lokale ontwikkelpaden.Pack daarna de plugin en installeer de tarball met npm-pack::
npm pack --pack-destination /tmp
openclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --force
openclaw plugins inspect my-plugin --runtime --json
npm-pack: gebruikt OpenClaw’s beheerde npm-project per plugin, dus het vangt runtimeafhankelijkheidsfouten die source-checkouttests kunnen verbergen. Het bewijst de package- en afhankelijkheidsvorm, niet catalogus-gekoppeld officieel vertrouwen. Runtime-imports moeten in dependencies of optionalDependencies staan; afhankelijkheden die alleen in devDependencies blijven staan, worden niet geïnstalleerd voor het beheerde runtimeproject.Gebruik geen raw archive/path-install als eindbewijs voor officieel of privileged plugingedrag. Raw sources zijn nuttig voor lokale debugging, maar ze bewijzen niet hetzelfde afhankelijkheidspad als npm- of ClawHub-installaties. Als je plugin vertrouwt op vertrouwde officiële pluginstatus, voeg dan een tweede bewijs toe via een catalog-backed officiële installatie of een gepubliceerd packagepad dat officieel vertrouwen vastlegt. Zie Plugin dependency resolution voor details over install-root en ownership van afhankelijkheden.
5

Publish

Valideer het package vóór publicatie:
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
De canonieke ClawHub-snippets staan in docs/snippets/plugin-publish/.
6

Install

Installeer het gepubliceerde package via ClawHub:
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. Optionele tools vereisen opt-in van de gebruiker. 
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 worden gedeclareerd in het pluginmanifest: 
{
  "contracts": {
    "tools": ["workflow_tool"]
  },
  "toolMetadata": {
    "workflow_tool": {
      "optional": true
    }
  }
}
Gebruikers kiezen ervoor met tools.allow: 
{
  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for all tools from one plugin
}
Optionele tools bepalen of een tool aan het model wordt blootgesteld. Gebruik plugin permission requests wanneer een tool of hook om goedkeuring moet vragen nadat het model die selecteert en voordat de actie wordt uitgevoerd. Gebruik optionele tools voor bijwerkingen, ongebruikelijke binaries of capabilities die niet standaard moeten worden blootgesteld. Toolnamen mogen niet conflicteren met coretools; conflicten worden overgeslagen en gerapporteerd in plugindiagnostics. Ongeldige registraties, inclusief tooldescriptors zonder parameters, worden overgeslagen en op dezelfde manier gerapporteerd. Geregistreerde tools zijn getypeerde functies die het model kan aanroepen nadat policy- en allowlist-controles slagen. Toolfactories ontvangen een door de runtime geleverd contextobject. Gebruik ctx.activeModel wanneer een tool moet loggen, weergeven of zich aanpassen aan het actieve model voor de huidige turn. Het object kan provider, modelId en modelRef bevatten. Behandel het als informatieve runtimemetadata, niet als een beveiligingsgrens tegen de lokale operator, geïnstalleerde plugincode of een gewijzigde OpenClaw-runtime. Gevoelige lokale tools moeten nog steeds een expliciete plugin- of operator-opt-in vereisen en fail-closed wanneer active-model-metadata ontbreekt of ongeschikt is. Het manifest declareert ownership en discovery; uitvoering roept nog steeds de live geregistreerde toolimplementatie aan. 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 allowlist staat.

​
Importconventies

Importeer vanuit gerichte SDK-subpaden: 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
Importeer niet vanuit de deprecated root barrel: 
import { definePluginEntry } from "openclaw/plugin-sdk";
Gebruik binnen je pluginpackage 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 providerpackage blijven, tenzij de seam echt generiek is. Custom Gateway RPC-methoden zijn een geavanceerd entrypoint. Houd ze op een pluginspecifieke prefix; core admin-namespaces zoals config.*, exec.approvals.*, operator.admin.*, wizard.* en update.* blijven gereserveerd en resolven naar operator.admin. De openclaw/plugin-sdk/gateway-method-runtime-bridge is gereserveerd voor plugin-HTTP routes die contracts.gatewayMethodDispatch: ["authenticated-request"] declareren. Zie voor de volledige importmap Plugin SDK-overzicht.

​
Checklist vóór indiening

package.json heeft correcte openclaw-metadata
openclaw.plugin.json-manifest is aanwezig en geldig
Entrypoint 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 (in-repo plugins)

​
Test tegen beta-releases

  1. Let op GitHub-release-tags op openclaw/openclaw en abonneer je via Watch > Releases. Beta-tags zien eruit als v2026.3.N-beta.1. Je kunt ook meldingen inschakelen voor het officiële OpenClaw X-account @openclaw voor release-aankondigingen.
  2. Test je Plugin tegen de beta-tag zodra die verschijnt. De periode vóór stable is meestal maar een paar uur.
  3. Plaats na het testen een bericht in de thread van je Plugin in het Discord-kanaal plugin-forum met all good of wat er kapotging. Als je nog geen thread hebt, maak er dan een aan.
  4. 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 issue-link in je thread.
  5. 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 alsnog worden uitgebracht. Maintainers volgen deze threads tijdens beta-tests.
  6. Stilte betekent groen. Als je de periode mist, landt je fix waarschijnlijk in de volgende cyclus.

​
Volgende stappen

Channel Plugins

Bouw een messaging-channel-Plugin

Provider Plugins

Bouw een modelprovider-Plugin

CLI Backend Plugins

Registreer een lokale AI CLI-backend

SDK Overview

Importmap en API-referentie voor registratie

Runtime Helpers

TTS, zoeken, subagent via api.runtime

Testing

Testhulpmiddelen en patronen

Plugin Manifest

Volledige manifest-schemareferentie

​
Gerelateerd