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 multimediów, generowanie obrazów, generowanie wideo, pobieranie z sieci, wyszukiwanie w sieci, narzędzia agenta lub dowolną kombinację. Nie musisz dodawać swojego pluginu do repozytorium OpenClaw. Opublikuj go w ClawHub lub npm, a użytkownicy zainstalują go przez openclaw plugins install <package-name>. OpenClaw najpierw próbuje ClawHub i automatycznie przechodzi do npm jako fallback.

Wymagania wstępne

Node >= 22 i menedżer pakietów (npm lub pnpm)
Znajomość TypeScript (ESM)
Dla pluginów w repozytorium: sklonowane repozytorium i wykonane pnpm install

Jaki rodzaj pluginu?

Plugin kanału

Połącz OpenClaw z platformą komunikacyjną (Discord, IRC itp.)

Plugin dostawcy

Dodaj dostawcę modeli (LLM, proxy lub niestandardowy endpoint)

Plugin narzędzia / hooka

Zarejestruj narzędzia agenta, hooki zdarzeń lub usługi — przejdź dalej poniżej

Jeśli plugin kanału jest opcjonalny i może nie być zainstalowany, gdy działa onboarding/konfiguracja, użyj createOptionalChannelSetupSurface(...) z openclaw/plugin-sdk/channel-setup. Tworzy on parę adapter konfiguracji + kreator, która informuje o wymaganiu instalacji i blokuje rzeczywiste zapisy konfiguracji, dopóki plugin nie zostanie zainstalowany.

Szybki start: plugin narzędzia

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

Utwórz pakiet i 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"
    }
  }
}

Każdy plugin potrzebuje manifestu, nawet jeśli nie ma konfiguracji. Pełny schemat znajdziesz w Manifest. Kanoniczne fragmenty publikowania do ClawHub znajdują się w docs/snippets/plugin-publish/.

Napisz punkt wejścia

// 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 służy do pluginów innych niż kanały. Dla kanałów użyj defineChannelPluginEntry — zobacz Channel Plugins. Pełne opcje punktów wejścia znajdziesz w Entry Points.

Przetestuj i opublikuj

Pluginy zewnętrzne: zweryfikuj i opublikuj w ClawHub, a następnie zainstaluj:

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 sprawdza też ClawHub przed npm dla prostych specyfikacji pakietów, takich jak @myorg/openclaw-my-plugin.Pluginy w repozytorium: umieść je w drzewie workspace dołączonych pluginów — zostaną wykryte automatycznie.

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:

Możliwość	Metoda rejestracji	Szczegółowy przewodnik
Wnioskowanie tekstowe (LLM)	`api.registerProvider(...)`	Provider Plugins
Backend wnioskowania CLI	`api.registerCliBackend(...)`	CLI Backends
Kanał / komunikacja	`api.registerChannel(...)`	Channel Plugins
Mowa (TTS/STT)	`api.registerSpeechProvider(...)`	Provider Plugins
Transkrypcja w czasie rzeczywistym	`api.registerRealtimeTranscriptionProvider(...)`	Provider Plugins
Głos w czasie rzeczywistym	`api.registerRealtimeVoiceProvider(...)`	Provider Plugins
Rozumienie multimediów	`api.registerMediaUnderstandingProvider(...)`	Provider Plugins
Generowanie obrazów	`api.registerImageGenerationProvider(...)`	Provider Plugins
Generowanie muzyki	`api.registerMusicGenerationProvider(...)`	Provider Plugins
Generowanie wideo	`api.registerVideoGenerationProvider(...)`	Provider Plugins
Pobieranie z sieci	`api.registerWebFetchProvider(...)`	Provider Plugins
Wyszukiwanie w sieci	`api.registerWebSearchProvider(...)`	Provider Plugins
Narzędzia agenta	`api.registerTool(...)`	Poniżej
Polecenia niestandardowe	`api.registerCommand(...)`	Entry Points
Hooki zdarzeń	`api.registerHook(...)`	Entry Points
Trasy HTTP	`api.registerHttpRoute(...)`	Internals
Podpolecenia CLI	`api.registerCli(...)`	Entry Points

Pełne API rejestracji znajdziesz w SDK Overview. Jeśli twój plugin rejestruje niestandardowe metody RPC gateway, trzymaj je pod prefiksem specyficznym dla pluginu. Podstawowe przestrzenie nazw administracyjnych (config.*, exec.approvals.*, wizard.*, update.*) pozostają zarezerwowane i zawsze rozwiązują się do operator.admin, nawet jeśli plugin żąda węższego zakresu. Semantyka strażników hooków, o której warto pamiętać:

before_tool_call: { block: true } jest rozstrzygające i zatrzymuje handlery o niższym priorytecie.
before_tool_call: { block: false } jest traktowane jak 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 na dowolnym kanale.
before_install: { block: true } jest rozstrzygające i zatrzymuje handlery o niższym priorytecie.
before_install: { block: false } jest traktowane jak brak decyzji.
message_sending: { cancel: true } jest rozstrzygające i zatrzymuje handlery o niższym priorytecie.
message_sending: { cancel: false } jest traktowane jak brak decyzji.

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ę z tym samym identyfikatorem w zatwierdzeniach pluginów. Przekazywanie zatwierdzeń pluginów można konfigurować niezależnie przez approvals.plugin w konfiguracji. Jeśli niestandardowa logika zatwierdzania musi wykrywać ten sam przypadek ograniczonego fallbacku, użyj isApprovalNotFoundError z openclaw/plugin-sdk/error-runtime zamiast ręcznie dopasowywać ciągi wygaśnięcia zatwierdzenia. Szczegóły znajdziesz w semantyce decyzji hooków SDK Overview.

Rejestrowanie narzędzi agenta

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

register(api) {
  // Narzędzie wymagane — zawsze dostępne
  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 }] };
    },
  });

  // Narzędzie opcjonalne — użytkownik musi dodać je do listy dozwolonych
  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 },
  );
}

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

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

Nazwy narzędzi nie mogą kolidować z podstawowymi narzędziami (konflikty są pomijane)
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

Konwencje importu

Zawsze importuj z wyspecjalizowanych ścieżek openclaw/plugin-sdk/<subpath>:

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

// Błędnie: monolityczny root (przestarzałe, zostanie usunięte)
import { ... } from "openclaw/plugin-sdk";

Pełne odniesienie do subpath znajdziesz w SDK Overview. Wewnątrz swojego pluginu używaj lokalnych plików barrel (api.ts, runtime-api.ts) do importów wewnętrznych — nigdy nie importuj własnego pluginu przez jego ścieżkę SDK. Dla pluginów dostawców trzymaj helpery specyficzne dla dostawcy w tych barrelach na poziomie root pakietu, chyba że dany interfejs jest naprawdę ogólny. Aktualne dołączone przykłady:

Anthropic: wrappery strumieni Claude oraz helpery service_tier / beta
OpenAI: buildery dostawców, helpery modeli domyślnych, dostawcy realtime
OpenRouter: builder dostawcy oraz helpery onboardingu/konfiguracji

Jeśli helper jest użyteczny tylko w jednym dołączonym pakiecie dostawcy, trzymaj go w interfejsie tego pakietu na poziomie root zamiast przenosić go do openclaw/plugin-sdk/*. Niektóre generowane interfejsy helperów openclaw/plugin-sdk/<bundled-id> nadal istnieją dla utrzymania i zgodności dołączonych pluginów, na przykład plugin-sdk/feishu-setup lub plugin-sdk/zalo-setup. Traktuj je jako zarezerwowane powierzchnie, a nie domyślny wzorzec dla nowych pluginów zewnętrznych.

Lista kontrolna przed zgłoszeniem

package.json ma poprawne metadane openclaw

Manifest openclaw.plugin.json jest obecny i prawidłowy

Punkt wejścia używa defineChannelPluginEntry lub definePluginEntry

Wszystkie importy używają wyspecjalizowanych ścieżek plugin-sdk/<subpath>

Importy wewnętrzne używają modułów lokalnych, a nie samoodwołań SDK

Testy przechodzą (pnpm test -- <bundled-plugin-root>/my-plugin/)

pnpm check przechodzi (pluginy w repozytorium)

Testowanie wydań beta

Obserwuj tagi wydań GitHub w openclaw/openclaw i zasubskrybuj przez Watch > Releases. Tagi beta wyglądają jak v2026.3.N-beta.1. Możesz też włączyć powiadomienia dla oficjalnego konta OpenClaw X @openclaw, aby otrzymywać ogłoszenia o wydaniach.
Przetestuj swój plugin z tagiem beta, gdy tylko się pojawi. Okno przed wydaniem stabilnym zwykle trwa tylko kilka godzin.
Po testach napisz w wątku swojego pluginu na kanale Discord plugin-forum, czy all good, czy co się zepsuło. Jeśli nie masz jeszcze wątku, utwórz go.
Jeśli coś się zepsuje, otwórz lub zaktualizuj issue zatytułowane Beta blocker: <plugin-name> - <summary> i dodaj etykietę beta-blocker. Umieść link do issue w swoim wątku.
Otwórz PR do main zatytułowany fix(<plugin-id>): beta blocker - <summary> i podlinkuj issue zarówno w PR, jak i w swoim wątku na Discordzie. Współtwórcy nie mogą etykietować PR, więc tytuł jest sygnałem po stronie PR dla maintainerów i automatyzacji. Blokery z PR są scalane; blokery bez niego mogą mimo to zostać wydane. Maintainerzy obserwują te wątki podczas testów beta.
Cisza oznacza zielono. Jeśli przegapisz okno, twoja poprawka prawdopodobnie trafi do następnego cyklu.

Następne kroki

Pluginy kanałów

Zbuduj plugin kanału komunikacyjnego

Pluginy dostawców

Zbuduj plugin dostawcy modeli

SDK Overview

Referencja mapy importów i API rejestracji

Runtime Helpers

TTS, search, subagent przez api.runtime

Testing

Narzędzia i wzorce testowania

Plugin Manifest

Pełna referencja schematu manifestu

Powiązane

Plugin Architecture — szczegółowe omówienie architektury wewnętrznej
SDK Overview — referencja Plugin SDK
Manifest — format manifestu pluginu
Channel Plugins — tworzenie pluginów kanałów
Provider Plugins — tworzenie pluginów dostawców

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Tworzenie pluginów

Tworzenie pluginów

Wymagania wstępne

Jaki rodzaj pluginu?

Plugin kanału

Plugin dostawcy

Plugin narzędzia / hooka

Szybki start: plugin narzędzia

Możliwości pluginów

Rejestrowanie narzędzi agenta

Konwencje importu

Lista kontrolna przed zgłoszeniem

Testowanie wydań beta

Następne kroki

Pluginy kanałów

Pluginy dostawców

SDK Overview

Runtime Helpers

Testing

Plugin Manifest

Powiązane

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

​Tworzenie pluginów

​Wymagania wstępne

​Jaki rodzaj pluginu?

Plugin kanału

Plugin dostawcy

Plugin narzędzia / hooka

​Szybki start: plugin narzędzia

​Możliwości pluginów

​Rejestrowanie narzędzi agenta

​Konwencje importu

​Lista kontrolna przed zgłoszeniem

​Testowanie wydań beta

​Następne kroki

Pluginy kanałów

Pluginy dostawców

SDK Overview

Runtime Helpers

Testing

Plugin Manifest

​Powiązane

Tworzenie pluginów

Wymagania wstępne

Jaki rodzaj pluginu?

Szybki start: plugin narzędzia

Możliwości pluginów

Rejestrowanie narzędzi agenta

Konwencje importu

Lista kontrolna przed zgłoszeniem

Testowanie wydań beta

Następne kroki

Powiązane