​

Tworzenie wtyczek

​

Wymagania wstępne

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

​

Jaki rodzaj wtyczki?

​

Szybki start: wtyczka narzędzia

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

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

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

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

​

Możliwości wtyczek

• before_tool_call: { block: true } jest terminalne 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 wykonania, przyciski Telegram, interakcje Discord lub polecenie /approve na dowolnym kanale.
• before_install: { block: true } jest terminalne i zatrzymuje handlery o niższym priorytecie.
• before_install: { block: false } jest traktowane jak brak decyzji.
• message_sending: { cancel: true } jest terminalne i zatrzymuje handlery o niższym priorytecie.
• message_sending: { cancel: false } jest traktowane jak brak decyzji.

​

Rejestrowanie narzędzi agenta

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

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

• Nazwy narzędzi nie mogą kolidować z podstawowymi narzędziami (konflikty są pomijane)
• Użyj optional: true dla narzędzi z efektami ubocznymi lub dodatkowymi wymaganiami binarnymi
• Użytkownicy mogą włączyć wszystkie narzędzia z wtyczki, dodając identyfikator wtyczki do tools.allow

​

Konwencje importu

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";

• Anthropic: wrappery strumieni Claude oraz helpery service_tier / beta
• OpenAI: kreatory providerów, helpery modeli domyślnych, providery realtime
• OpenRouter: kreator providera oraz helpery onboardingu/konfiguracji

​

Lista kontrolna przed zgłoszeniem

​

Testowanie wydań beta

1. Obserwuj tagi wydań GitHub w openclaw/openclaw i subskrybuj przez Watch > Releases. Tagi beta mają postać v2026.3.N-beta.1. Możesz też włączyć powiadomienia dla oficjalnego konta OpenClaw na X @openclaw, aby otrzymywać informacje o wydaniach.
2. Przetestuj swoją wtyczkę z tagiem beta, gdy tylko się pojawi. Okno przed wydaniem stabilnym zwykle trwa tylko kilka godzin.
3. Po testach napisz w wątku swojej wtyczki na kanale Discord plugin-forum, 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 o tytule Beta blocker: <plugin-name> - <summary> i nadaj mu etykietę beta-blocker. Umieść link do issue w swoim wątku.
5. Otwórz PR do main o tytule fix(<plugin-id>): beta blocker - <summary> i dodaj link do issue zarówno w PR, jak i w swoim wątku na Discordzie. Współtwórcy nie mogą nadawać etykiet PR-om, więc tytuł jest sygnałem po stronie PR dla maintainerów i automatyzacji. Blokery z PR są scalane; 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, poprawka najpewniej trafi do następnego cyklu.

​

Następne kroki

​

Powiązane

• Architektura wtyczek — szczegółowe omówienie architektury wewnętrznej
• Przegląd SDK — dokumentacja Plugin SDK
• Manifest — format manifestu wtyczki
• Wtyczki kanałów — tworzenie wtyczek kanałów
• Wtyczki providerów — tworzenie wtyczek providerów