Tworzenie pluginów

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

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

openclaw plugins install clawhub:<package-name>

Gołe specyfikacje pakietów nadal instalują z npm podczas przełączenia uruchomieniowego. Użyj prefiksu clawhub:, gdy chcesz rozwiązywania przez ClawHub.

Wymagania

• Użyj Node 22.19+, Node 23.11+ albo Node 24+ oraz menedżera pakietów, takiego jak npm lub pnpm.
• Znajomość modułów TypeScript ESM.
• Przy pracy nad wbudowanym pluginem w repozytorium sklonuj repozytorium i uruchom pnpm install. Tworzenie pluginów w checkoutcie źródłowym obsługuje wyłącznie pnpm, ponieważ OpenClaw ładuje wbudowane pluginy z pakietów workspace extensions/*.

Wybierz kształt pluginu

Szybki start

Zbuduj minimalny plugin narzędziowy, rejestrując jedno wymagane narzędzie agenta. To najkrótszy użyteczny kształt pluginu i pokazuje pakiet, manifest, punkt wejścia oraz lokalny dowód.

{"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 albo opcjonalne. Wymagane narzędzia są zawsze dostępne, gdy plugin jest włączony. Opcjonalne narzędzia wymagają zgody użytkownika.

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 all tools from one plugin}

Opcjonalne narzędzia kontrolują, czy narzędzie jest udostępniane modelowi. Użyj żądań uprawnień pluginu, gdy narzędzie lub hook powinny poprosić o zatwierdzenie po tym, jak model je wybierze, a przed uruchomieniem akcji.

Używaj narzędzi opcjonalnych do skutków ubocznych, nietypowych binariów albo funkcji, które nie powinny być domyślnie udostępniane. Nazwy narzędzi nie mogą kolidować z narzędziami rdzenia; konflikty są pomijane i zgłaszane w diagnostyce pluginów. Nieprawidłowo sformułowane rejestracje, w tym deskryptory narzędzi bez parameters, są pomijane i zgłaszane w ten sam sposób. Zarejestrowane narzędzia to typowane funkcje, które model może wywołać po przejściu kontroli polityki i allowlisty.

Fabryki narzędzi otrzymują obiekt kontekstu dostarczony przez runtime. Użyj ctx.activeModel, gdy narzędzie musi logować, wyświetlać albo dostosowywać się do aktywnego modelu dla bieżącej tury. Obiekt może zawierać provider, modelId i modelRef. Traktuj go jako informacyjne metadane runtime, a nie jako granicę bezpieczeństwa wobec lokalnego operatora, kodu zainstalowanego pluginu albo zmodyfikowanego runtime OpenClaw. Wrażliwe narzędzia lokalne nadal powinny wymagać jawnej zgody pluginu albo operatora i domyślnie odmawiać działania, gdy metadane aktywnego modelu są brakujące albo nieodpowiednie.

Manifest deklaruje własność i wykrywanie; wykonanie nadal wywołuje działającą zarejestrowaną implementację narzędzia. Utrzymuj toolMetadata.<tool>.optional: true w zgodzie z api.registerTool(..., { optional: true }), aby OpenClaw mógł uniknąć ładowania runtime tego pluginu, dopóki narzędzie nie zostanie jawnie dodane do allowlisty.

Konwencje importu

Importuj z ukierunkowanych podścieżek SDK:

Nie importuj z przestarzałego głównego barrela:

W pakiecie pluginu używaj lokalnych plików barrel, takich jak api.ts i runtime-api.ts, do importów wewnętrznych. Nie importuj własnego pluginu przez ścieżkę SDK. Helpery specyficzne dla dostawcy powinny pozostać w pakiecie dostawcy, chyba że granica jest naprawdę generyczna.

Niestandardowe metody RPC Gateway to zaawansowany punkt wejścia. Utrzymuj je pod prefiksem specyficznym dla pluginu; przestrzenie nazw administracji rdzenia, takie jak config.*, exec.approvals.*, operator.admin.*, wizard.* i update.*, pozostają zarezerwowane i rozwiązują się do operator.admin. Most openclaw/plugin-sdk/gateway-method-runtime jest zarezerwowany dla tras HTTP pluginu, które deklarują contracts.gatewayMethodDispatch: ["authenticated-request"].

Pełną mapę importów znajdziesz w omówieniu SDK pluginów.

Lista kontrolna przed przesłaniem

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json ma poprawne metadane openclaw OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Manifest openclaw.plugin.json jest obecny i poprawny OPENCLAW_DOCS_MARKER:calloutClose:

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

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