Przejdź do głównej treści

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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?

Plugin kanału

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

Plugin dostawcy

Dodaj dostawcę modelu (LLM, proxy lub niestandardowy punkt końcowy)

Plugin backendu CLI

Zamapuj lokalne AI CLI do tekstowego runnera awaryjnego OpenClaw

Plugin narzędzi / hooków

Zarejestruj narzędzia agenta, hooki zdarzeń lub usługi - kontynuuj poniżej
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.
1

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 bez konfiguracji. Narzędzia rejestrowane w runtime muszą być wymienione w contracts.tools, aby OpenClaw mógł wykryć plugin właścicielski bez ładowania runtime każdego pluginu. Pluginy powinny też świadomie deklarować activation.onStartup. Ten przykład ustawia ją na true. Pełny schemat znajdziesz w Manifest. Kanoniczne fragmenty publikowania w ClawHub znajdują się w docs/snippets/plugin-publish/.
2

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. W przypadku kanałów użyj defineChannelPluginEntry - zobacz Pluginy kanałów. Pełne opcje punktu wejścia znajdziesz w Punkty wejścia.
3

Przetestuj i opublikuj

Pluginy zewnętrzne: zweryfikuj i opublikuj z 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
Gołe specyfikacje pakietów, takie jak @myorg/openclaw-my-plugin, instalują się z npm podczas przejścia uruchomieniowego. Użyj clawhub:, gdy chcesz rozwiązywania przez ClawHub.Pluginy w repozytorium: umieść pod drzewem 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 rejestracjiSzczegółowy przewodnik
Wnioskowanie tekstowe (LLM)api.registerProvider(...)Pluginy dostawców
Backend wnioskowania CLIapi.registerCliBackend(...)Pluginy backendu CLI
Kanał / komunikacjaapi.registerChannel(...)Pluginy kanałów
Mowa (TTS/STT)api.registerSpeechProvider(...)Pluginy dostawców
Transkrypcja w czasie rzeczywistymapi.registerRealtimeTranscriptionProvider(...)Pluginy dostawców
Głos w czasie rzeczywistymapi.registerRealtimeVoiceProvider(...)Pluginy dostawców
Rozumienie mediówapi.registerMediaUnderstandingProvider(...)Pluginy dostawców
Generowanie obrazówapi.registerImageGenerationProvider(...)Pluginy dostawców
Generowanie muzykiapi.registerMusicGenerationProvider(...)Pluginy dostawców
Generowanie wideoapi.registerVideoGenerationProvider(...)Pluginy dostawców
Pobieranie z sieciapi.registerWebFetchProvider(...)Pluginy dostawców
Wyszukiwanie w sieciapi.registerWebSearchProvider(...)Pluginy dostawców
Middleware wyników narzędziapi.registerAgentToolResultMiddleware(...)Omówienie SDK
Narzędzia agentaapi.registerTool(...)Poniżej
Niestandardowe poleceniaapi.registerCommand(...)Punkty wejścia
Hooki pluginówapi.on(...)Hooki pluginów
Wewnętrzne hooki zdarzeńapi.registerHook(...)Punkty wejścia
Trasy HTTPapi.registerHttpRoute(...)Internals
Podpolecenia CLIapi.registerCli(...)Punkty wejścia
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 --json
openclaw demo-plugin ping

​
Konwencje importu

Zawsze importuj ze skoncentrowanych ścieżek openclaw/plugin-sdk/<subpath>: 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";
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

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ą skoncentrowanych ścieżek plugin-sdk/<subpath>
Importy wewnętrzne używają modułów lokalnych, nie autoimportów SDK
Testy przechodzą (pnpm test -- <bundled-plugin-root>/my-plugin/)
pnpm check przechodzi (Pluginy w repozytorium)

​
Testowanie wydań beta

  1. Obserwuj tagi wydań GitHub w openclaw/openclaw i zasubskrybuj je przez Watch > Releases. Tagi beta wyglądają jak v2026.3.N-beta.1. Możesz też włączyć powiadomienia dla oficjalnego konta OpenClaw na X @openclaw, aby otrzymywać ogłoszenia o wydaniach.
  2. Przetestuj swój Plugin względem tagu beta, gdy tylko się pojawi. Okno przed wydaniem stabilnym zwykle trwa tylko kilka godzin.
  3. Opublikuj wiadomość w wątku swojego Pluginu na kanale Discord plugin-forum po testach, wpisując all good albo opisując, co się zepsuło. Jeśli nie masz jeszcze wątku, utwórz go.
  4. Jeśli coś się zepsuje, otwórz lub zaktualizuj issue zatytułowane Beta blocker: <plugin-name> - <summary> i zastosuj etykietę beta-blocker. Umieść link do issue w swoim wątku.
  5. Otwórz PR do main zatytułowany fix(<plugin-id>): beta blocker - <summary> i połącz issue zarówno w PR, jak i w swoim wątku Discord. Kontrybutorzy nie mogą etykietować PR-ów, więc tytuł jest sygnałem po stronie PR dla maintainerów i automatyzacji. Blokery z PR zostaną scalone; blokery bez PR mogą mimo to zostać wydane. Maintainerzy obserwują te wątki podczas testów beta.
  6. Cisza oznacza zielone światło. Jeśli przegapisz okno, Twoja poprawka prawdopodobnie trafi do następnego cyklu.

​
Następne kroki

Pluginy kanałów

Zbuduj Plugin kanału komunikacji

Pluginy dostawców

Zbuduj Plugin dostawcy modelu

Pluginy backendu CLI

Zarejestruj lokalny backend CLI AI

Przegląd SDK

Mapa importów i referencja API rejestracji

Helpery runtime

TTS, wyszukiwanie, podagent przez api.runtime

Testowanie

Narzędzia i wzorce testowe

Manifest Pluginu

Pełna referencja schematu manifestu

​
Powiązane