Przejdź do głównej treści
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

Plugin kanału

Połącz OpenClaw z platformą wiadomości.

Plugin dostawcy

Dodaj dostawcę modelu, mediów, wyszukiwania, pobierania, mowy albo czasu rzeczywistego.

Plugin backendu CLI

Uruchamiaj lokalne AI CLI przez fallback modelu OpenClaw.

Plugin narzędziowy

Zarejestruj narzędzia agenta.

​
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.
1

Utwórz metadane pakietu

{
  "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
  }
}
Opublikowane zewnętrzne pluginy powinny wskazywać wpisy runtime na zbudowane pliki JavaScript. Zobacz punkty wejścia SDK, aby poznać pełny kontrakt punktu wejścia.Każdy plugin potrzebuje manifestu, nawet gdy nie ma konfiguracji. Narzędzia runtime muszą znajdować się w contracts.tools, aby OpenClaw mógł wykryć własność bez zachłannego ładowania każdego runtime pluginu. Ustaw activation.onStartup celowo. Ten przykład uruchamia się przy starcie Gateway.Powierzchnie pluginów zaufane przez hosta są także bramkowane manifestem i wymagają jawnego włączenia dla zainstalowanych pluginów. Jeśli zainstalowany plugin rejestruje api.registerAgentToolResultMiddleware(...), zadeklaruj każdy docelowy runtime w contracts.agentToolResultMiddleware. Jeśli rejestruje api.registerTrustedToolPolicy(...), zadeklaruj każdy identyfikator polityki w contracts.trustedToolPolicies. Te deklaracje utrzymują zgodność kontroli podczas instalacji z rejestracją runtime.Każde pole manifestu opisuje manifest Pluginu.
2

Zarejestruj narzędzie

index.ts
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}` }],
        };
      },
    });
  },
});
Użyj definePluginEntry dla pluginów niebędących kanałami. Pluginy kanałów używają defineChannelPluginEntry.
3

Przetestuj runtime

Dla zainstalowanego lub zewnętrznego pluginu sprawdź załadowany runtime:
openclaw plugins inspect my-plugin --runtime --json
Jeśli plugin rejestruje polecenie CLI, uruchom również to polecenie. Na przykład polecenie demonstracyjne powinno mieć dowód wykonania, taki jak openclaw demo-plugin ping.Dla wbudowanego pluginu w tym repozytorium OpenClaw wykrywa pakiety pluginów w checkoutcie źródłowym z workspace extensions/*. Uruchom najbliższy test docelowy:
pnpm test -- extensions/my-plugin/
pnpm check
4

Przetestuj instalację pakietu

Przed opublikowaniem pluginu gotowego jako pakiet przetestuj ten sam kształt instalacji, który otrzymają użytkownicy. Najpierw dodaj krok budowania, wskaż wpisy runtime, takie jak openclaw.extensions, na zbudowany JavaScript, np. ./dist/index.js, i upewnij się, że npm pack obejmuje wynik dist/. Wpisy źródłowe TypeScript są tylko dla checkoutów źródłowych i lokalnych ścieżek programistycznych.Następnie spakuj plugin i zainstaluj tarball za pomocą npm-pack::
npm pack --pack-destination /tmp
openclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --force
openclaw plugins inspect my-plugin --runtime --json
npm-pack: używa zarządzanego przez OpenClaw projektu npm przypisanego do pluginu, więc wychwytuje błędy zależności runtime, które testowanie checkoutu źródłowego może ukryć. Dowodzi kształtu pakietu i zależności, a nie oficjalnego zaufania powiązanego z katalogiem. Importy runtime muszą znajdować się w dependencies albo optionalDependencies; zależności pozostawione tylko w devDependencies nie zostaną zainstalowane dla zarządzanego projektu runtime.Nie używaj surowej instalacji archiwum/ścieżki jako końcowego dowodu dla oficjalnego lub uprzywilejowanego zachowania pluginu. Surowe źródła są przydatne do lokalnego debugowania, ale nie dowodzą tej samej ścieżki zależności co instalacje npm albo ClawHub. Jeśli Twój plugin polega na statusie zaufanego oficjalnego pluginu, dodaj drugi dowód przez oficjalną instalację opartą na katalogu albo opublikowaną ścieżkę pakietu, która zapisuje oficjalne zaufanie. Zobacz rozwiązywanie zależności pluginów, aby poznać szczegóły katalogu głównego instalacji i własności zależności.
5

Opublikuj

Zweryfikuj pakiet przed opublikowaniem:
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
Kanoniczne fragmenty ClawHub znajdują się w docs/snippets/plugin-publish/.
6

Zainstaluj

Zainstaluj opublikowany pakiet przez ClawHub:
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: 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
Nie importuj z przestarzałego głównego barrela: 
import { definePluginEntry } from "openclaw/plugin-sdk";
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

package.json ma poprawne metadane openclaw
Manifest openclaw.plugin.json jest obecny i poprawny
Punkt wejścia używa defineChannelPluginEntry albo definePluginEntry
Wszystkie importy używają ukierunkowanych ścieżek plugin-sdk/<subpath>
Importy wewnętrzne używają modułów lokalnych, a nie samoimportów SDK
Testy przechodzą (pnpm test -- <bundled-plugin-root>/my-plugin/)
pnpm check przechodzi (pluginy w repozytorium)

​
Testowanie względem 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 taga beta, gdy tylko się pojawi. Okno przed wydaniem stabilnym zwykle trwa tylko kilka godzin.
  3. Po testach napisz w wątku swojego pluginu na kanale Discord plugin-forum: all good albo opisz, co się zepsuło. Jeśli nie masz jeszcze wątku, utwórz go.
  4. Jeśli coś się zepsuje, otwórz lub zaktualizuj zgłoszenie zatytułowane Beta blocker: <plugin-name> - <summary> i zastosuj etykietę beta-blocker. Umieść link do zgłoszenia w swoim wątku.
  5. Otwórz PR do main zatytułowany fix(<plugin-id>): beta blocker - <summary> i podlinkuj zgłoszenie zarówno w PR, jak i w swoim wątku na Discord. Współautorzy nie mogą nadawać PR etykiet, 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 trafić do wydania. Maintainerzy obserwują te wątki podczas testów beta.
  6. Cisza oznacza zielone światło. Jeśli przegapisz okno, poprawka prawdopodobnie trafi do następnego cyklu.

​
Następne kroki

Pluginy kanałów

Zbuduj plugin kanału wiadomości

Pluginy dostawców

Zbuduj plugin dostawcy modeli

Pluginy backendu CLI

Zarejestruj lokalny backend CLI AI

Omówienie SDK

Mapa importów i dokumentacja API rejestracji

Pomocniki środowiska uruchomieniowego

TTS, wyszukiwanie, subagent przez api.runtime

Testowanie

Narzędzia i wzorce testowe

Manifest pluginu

Pełna dokumentacja schematu manifestu

​
Powiązane