Tworzenie Pluginów

Pluginy rozszerzają OpenClaw o nowe możliwości: kanały, dostawców modeli, mowę, transkrypcję w czasie rzeczywistym, głos w czasie rzeczywistym, rozumienie mediów, generowanie obrazów, generowanie wideo, pobieranie z sieci, wyszukiwanie w sieci, narzędzia agenta lub dowolne połączenie tych funkcji.

Nie musisz dodawać swojego pluginu do repozytorium OpenClaw. Opublikuj go w ClawHub, a użytkownicy zainstalują go poleceniem openclaw plugins install clawhub:<package-name>. Podczas przejścia uruchomieniowego gołe specyfikacje pakietów nadal instalują się z npm.

Wymagania wstępne

• Node >= 22 i menedżer pakietów (npm lub pnpm)
• Znajomość TypeScript (ESM)
• W przypadku pluginów w repozytorium: sklonowane repozytorium i wykonane pnpm install. Rozwój pluginów z checkoutu źródeł obsługuje wyłącznie pnpm, ponieważ OpenClaw ładuje dołączone pluginy z pakietów workspace extensions/*.

Jaki rodzaj pluginu?

W przypadku pluginu kanału, który nie musi być zainstalowany, gdy uruchamia się onboarding/konfiguracja, użyj createOptionalChannelSetupSurface(...) z openclaw/plugin-sdk/channel-setup. Tworzy parę adaptera konfiguracji i kreatora, która informuje o wymaganiu instalacji i bezpiecznie odmawia rzeczywistych zapisów konfiguracji, dopóki plugin nie zostanie zainstalowany.

Szybki start: plugin narzędziowy

Ten przewodnik tworzy minimalny plugin, który rejestruje narzędzie agenta. Pluginy kanałów i dostawców mają osobne przewodniki podlinkowane powyżej.

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

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

// index.tsimport { 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}` }] };      },    });  },});

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

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

Możliwości pluginów

Pojedynczy plugin może zarejestrować dowolną liczbę możliwości przez obiekt api:

Pełne API rejestracji znajdziesz w Omówienie SDK.

Dołączone pluginy mogą używać api.registerAgentToolResultMiddleware(...), gdy potrzebują asynchronicznego przepisywania wyniku narzędzia, zanim model zobaczy dane wyjściowe. Zadeklaruj docelowe runtime w contracts.agentToolResultMiddleware, na przykład ["pi", "codex"]. To zaufany interfejs dla dołączonych pluginów; zewnętrzne pluginy powinny preferować zwykłe hooki pluginów OpenClaw, chyba że OpenClaw wprowadzi jawną politykę zaufania dla tej możliwości.

Jeśli Twój plugin rejestruje niestandardowe metody RPC Gateway, trzymaj je pod prefiksem specyficznym dla pluginu. Przestrzenie nazw administracyjnych core (config.*, exec.approvals.*, wizard.*, update.*) pozostają zarezerwowane i zawsze rozwiązują się do operator.admin, nawet jeśli plugin zażąda węższego zakresu.

Semantyka guardów hooków, o której warto pamiętać:

• before_tool_call: { block: true } jest końcowe i zatrzymuje handlery o niższym priorytecie.
• before_tool_call: { block: false } jest traktowane jako brak decyzji.
• before_tool_call: { requireApproval: true } wstrzymuje wykonanie agenta i prosi użytkownika o zatwierdzenie przez nakładkę zatwierdzania exec, przyciski Telegram, interakcje Discord lub polecenie /approve w dowolnym kanale.
• before_install: { block: true } jest końcowe i zatrzymuje handlery o niższym priorytecie.
• before_install: { block: false } jest traktowane jako brak decyzji.
• message_sending: { cancel: true } jest końcowe i zatrzymuje handlery o niższym priorytecie.
• message_sending: { cancel: false } jest traktowane jako brak decyzji.
• message_received: preferuj typowane pole threadId, gdy potrzebujesz routingu wątków/tematów przychodzących. Zachowaj metadata dla dodatków specyficznych dla kanału.
• message_sending: preferuj typowane pola routingu replyToId / threadId zamiast kluczy metadanych specyficznych dla kanału.

Polecenie /approve obsługuje zarówno zatwierdzenia exec, jak i pluginów z ograniczonym fallbackiem: gdy identyfikator zatwierdzenia exec nie zostanie znaleziony, OpenClaw ponawia próbę użycia tego samego identyfikatora przez zatwierdzenia pluginów. Przekazywanie zatwierdzeń pluginów można skonfigurować niezależnie przez approvals.plugin w konfiguracji.

Jeśli niestandardowe mechanizmy zatwierdzania muszą wykryć ten sam przypadek ograniczonego fallbacku, preferuj isApprovalNotFoundError z openclaw/plugin-sdk/error-runtime zamiast ręcznego dopasowywania ciągów wygaśnięcia zatwierdzenia.

Przykłady i referencję hooków znajdziesz w Hooki pluginów.

Rejestrowanie narzędzi agenta

Narzędzia to typowane funkcje, które LLM może wywoływać. Mogą być wymagane (zawsze dostępne) lub opcjonalne (włączane przez użytkownika):

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

Fabryki narzędzi otrzymują obiekt kontekstu dostarczany przez runtime. Używaj ctx.activeModel, gdy narzędzie musi rejestrować, wyświetlać lub 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, zainstalowanego kodu Pluginu lub zmodyfikowanego runtime OpenClaw. W przypadku wrażliwych narzędzi lokalnych zachowaj jawne wymaganie zgody Pluginu lub operatora i odmawiaj działania, gdy metadane aktywnego modelu są brakujące albo nieodpowiednie.

Każde narzędzie zarejestrowane przez api.registerTool(...) musi być także zadeklarowane w manifeście Pluginu:

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

OpenClaw przechwytuje i buforuje zweryfikowany deskryptor z zarejestrowanego narzędzia, więc Pluginy nie duplikują description ani danych schematu w manifeście. Kontrakt manifestu deklaruje tylko własność i wykrywanie; wykonanie nadal wywołuje aktywną implementację zarejestrowanego narzędzia. Ustaw toolMetadata.<tool>.optional: true dla narzędzi zarejestrowanych za pomocą api.registerTool(..., { optional: true }), aby OpenClaw mógł uniknąć ładowania tego runtime Pluginu, dopóki narzędzie nie zostanie jawnie dodane do listy dozwolonych.

Użytkownicy włączają opcjonalne narzędzia w konfiguracji:

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

• Nazwy narzędzi nie mogą kolidować z narzędziami rdzenia (konflikty są pomijane)
• Narzędzia z nieprawidłowymi obiektami rejestracji, w tym bez parameters, są pomijane i zgłaszane w diagnostyce Pluginu zamiast przerywać uruchomienia agenta
• Używaj optional: true dla narzędzi z efektami ubocznymi lub dodatkowymi wymaganiami binarnymi
• Użytkownicy mogą włączyć wszystkie narzędzia z Pluginu, dodając identyfikator Pluginu do tools.allow

Rejestrowanie poleceń CLI

Pluginy mogą dodawać główne grupy poleceń openclaw za pomocą api.registerCli. Podaj descriptors dla każdego najwyższego poziomu korzenia polecenia, aby OpenClaw mógł wyświetlić i przekierować polecenie bez zachłannego ładowania każdego runtime Pluginu.

register(api) {  api.registerCli(    ({ program }) => {      const demo = program        .command("demo-plugin")        .description("Run demo plugin commands");       demo        .command("ping")        .description("Check that the plugin CLI is executable")        .action(() => {          console.log("demo-plugin:pong");        });    },    {      descriptors: [        {          name: "demo-plugin",          description: "Run demo plugin commands",          hasSubcommands: true,        },      ],    },  );}

Po instalacji zweryfikuj rejestrację runtime i wykonaj polecenie:

openclaw plugins inspect demo-plugin --runtime --jsonopenclaw demo-plugin ping

Konwencje importu

Zawsze importuj ze skoncentrowanych ścieżek openclaw/plugin-sdk/<subpath>:

  // Wrong: monolithic root (deprecated, will be removed) 

Pełną referencję podścieżek znajdziesz w Przeglądzie SDK.

W obrębie swojego Pluginu używaj lokalnych plików baryłkowych (api.ts, runtime-api.ts) do importów wewnętrznych - nigdy nie importuj własnego Pluginu przez jego ścieżkę SDK.

W przypadku Pluginów dostawców trzymaj helpery specyficzne dla dostawcy w tych baryłkach katalogu głównego pakietu, chyba że granica jest naprawdę generyczna. Obecne dołączone przykłady:

• Anthropic: wrappery strumienia Claude oraz helpery service_tier / beta
• OpenAI: konstruktory dostawcy, helpery modeli domyślnych, dostawcy realtime
• OpenRouter: konstruktor dostawcy oraz helpery onboardingu/konfiguracji

Jeśli helper jest użyteczny tylko wewnątrz jednego dołączonego pakietu dostawcy, zostaw go na tej granicy katalogu głównego pakietu zamiast promować go do openclaw/plugin-sdk/*.

Niektóre wygenerowane granice helperów openclaw/plugin-sdk/<bundled-id> nadal istnieją na potrzeby utrzymania dołączonych Pluginów, gdy mają śledzone użycie właściciela. Traktuj je jako powierzchnie zarezerwowane, a nie jako domyślny wzorzec dla nowych Pluginów firm trzecich.

Lista kontrolna przed zgłoszeniem

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 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ą skoncentrowanych ścieżek plugin-sdk/<subpath> OPENCLAW_DOCS_MARKER:calloutClose: