Tworzenie pluginów

Pluginy rozszerzają OpenClaw bez zmieniania rdzenia. Plugin może dodać kanał komunikacyjny, dostawcę modelu, lokalny backend CLI, narzędzie agenta, hook, dostawcę multimediów lub inną funkcję należącą do pluginu.

Nie trzeba dodawać zewnętrznego pluginu do repozytorium OpenClaw. Należy opublikować pakiet w ClawHub, a użytkownicy zainstalują go za pomocą:

openclaw plugins install clawhub:<package-name>

Podczas przejścia związanego z uruchomieniem specyfikacje pakietów bez prefiksu nadal są instalowane z npm. Należy użyć prefiksu clawhub:, aby skorzystać z rozwiązywania przez ClawHub.

Wymagania

• Node 22.22.3+, Node 24.15+ lub Node 25.9+ oraz npm albo pnpm.
• Moduły TypeScript ESM.
• W przypadku pracy nad dołączonym do repozytorium pluginem należy sklonować repozytorium i uruchomić pnpm install. Rozwój pluginów w kopii kodu źródłowego wymaga wyłącznie pnpm, ponieważ OpenClaw wykrywa dołączone pluginy w pakietach przestrzeni roboczej extensions/*.

Wybór postaci pluginu

Szybki start

Minimalny plugin narzędzi można utworzyć, rejestrując jedno wymagane narzędzie agenta. Jest to najkrótsza użyteczna postać pluginu, obejmująca pakiet, manifest, punkt wejścia i lokalną weryfikację.

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

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}` }],        };      },    });  },});

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

pnpm test extensions/my-plugin/pnpm check

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

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

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

Rejestrowanie narzędzi

Narzędzia mogą być wymagane lub opcjonalne. Wymagane narzędzia są zawsze dostępne, gdy plugin jest włączony. Opcjonalne narzędzia wymagają jawnej zgody użytkownika, zanim OpenClaw załaduje środowisko uruchomieniowe pluginu będącego ich właścicielem.

Fabryki narzędzi otrzymują zaufany kontekst środowiska uruchomieniowego, w tym deliveryContext, nativeChannelId dla aktywnej konwersacji na platformie, jeśli jest dostępna, oraz requesterSenderId.

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 },  );}

Każde narzędzie zarejestrowane za pomocą api.registerTool(...) musi być również zadeklarowane w manifeście pluginu:

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

Użytkownicy włączają je za pomocą tools.allow:

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

Narzędzia opcjonalne określają, czy narzędzie jest udostępniane modelowi. Należy użyć żądań uprawnień pluginu, gdy narzędzie lub hook powinien poprosić o zatwierdzenie po wybraniu go przez model, ale przed wykonaniem działania.

Narzędzi opcjonalnych należy używać w przypadku skutków ubocznych, nietypowych plików binarnych lub funkcji, które nie powinny być domyślnie udostępniane. Nazwy narzędzi nie mogą kolidować z nazwami narzędzi rdzenia; konflikty są pomijane i zgłaszane w diagnostyce pluginów. Nieprawidłowe rejestracje są pomijane i zgłaszane w ten sam sposób: brak niepustej wartości name, wartość execute, która nie jest funkcją, lub deskryptor narzędzia bez obiektu parameters.

Fabryki narzędzi otrzymują obiekt kontekstu dostarczany przez środowisko uruchomieniowe. Należy użyć ctx.activeModel, gdy narzędzie musi rejestrować, wyświetlać lub dostosowywać się do aktywnego modelu dla bieżącej tury; może on zawierać provider, modelId i modelRef. Należy traktować go jako informacyjne metadane środowiska uruchomieniowego, a nie granicę bezpieczeństwa chroniącą przed lokalnym operatorem, kodem zainstalowanego pluginu lub zmodyfikowanym środowiskiem uruchomieniowym OpenClaw. Wrażliwe narzędzia lokalne powinny nadal wymagać jawnego włączenia przez plugin lub operatora i odmawiać działania, gdy metadane aktywnego modelu są niedostępne lub nieodpowiednie.

Manifest deklaruje własność i wykrywanie; wykonanie nadal wywołuje aktywną zarejestrowaną implementację narzędzia. Należy zachować zgodność toolMetadata.<tool>.optional: true z api.registerTool(..., { optional: true }), aby OpenClaw mógł uniknąć ładowania środowiska uruchomieniowego tego pluginu, dopóki narzędzie nie zostanie jawnie dodane do listy dozwolonych.

Konwencje importowania

Należy importować z wyspecjalizowanych podścieżek SDK:

Nie należy importować z przestarzałego głównego pliku zbiorczego:

W pakiecie pluginu należy używać lokalnych plików zbiorczych, takich jak api.ts i runtime-api.ts, do importów wewnętrznych. Nie należy importować własnego pluginu za pośrednictwem ścieżki SDK. Pomocnicze funkcje specyficzne dla dostawcy powinny pozostać w jego pakiecie, chyba że punkt integracji jest rzeczywiście ogólny.

Niestandardowe metody RPC Gateway są zaawansowanym punktem wejścia. Należy umieścić je pod prefiksem właściwym dla pluginu; administracyjne przestrzenie nazw rdzenia, takie jak config.*, exec.approvals.*, operator.admin.*, wizard.* i update.*, pozostają zastrzeżone i są rozwiązywane do operator.admin. Most openclaw/plugin-sdk/gateway-method-runtime jest zastrzeżony dla tras HTTP pluginu, które deklarują contracts.gatewayMethodDispatch: ["authenticated-request"].

Pełną mapę importów zawiera Omówienie SDK pluginów.

Lista kontrolna przed przesłaniem

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Plik package.json zawiera prawidłowe metadane openclaw OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Manifest openclaw.plugin.json jest obecny i prawidłowy OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Punkt wejścia używa defineChannelPluginEntry lub definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Wszystkie importy używają wyspecjalizowanych ścieżek plugin-sdk/<subpath> OPENCLAW_DOCS_MARKER:calloutClose: