Pluginy

Pluginy rozszerzają OpenClaw o kanały, dostawców modeli, środowiska wykonawcze agentów, narzędzia, Skills, syntezę mowy, transkrypcję w czasie rzeczywistym, obsługę głosu, analizę multimediów, generowanie, pobieranie treści z sieci, wyszukiwanie w sieci i inne możliwości środowiska wykonawczego.

Na tej stronie opisano, jak zainstalować plugin, ponownie uruchomić Gateway, sprawdzić, czy środowisko wykonawcze go załadowało, oraz rozwiązać typowe problemy z konfiguracją. Przykłady obejmujące wyłącznie polecenia zawiera strona Zarządzanie pluginami. Wygenerowany wykaz pluginów wbudowanych, oficjalnych zewnętrznych i dostępnych wyłącznie jako kod źródłowy zawiera Wykaz pluginów.

Wymagania

• kopia robocza lub instalacja OpenClaw z dostępnym CLI openclaw
• dostęp sieciowy do wybranego źródła (ClawHub, npm lub host Git)
• wszelkie poświadczenia, klucze konfiguracji lub narzędzia systemu operacyjnego wymagane przez dokumentację konfiguracji danego pluginu
• uprawnienia umożliwiające przeładowanie lub ponowne uruchomienie Gateway obsługującego Twoje kanały

Szybki start

openclaw plugins search "calendar"

# From ClawHub.openclaw plugins install clawhub:<package> # From npm.openclaw plugins install npm:<package> # From git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # From a local development checkout.openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json

Konfiguracja

Wybór źródła instalacji

Specyfikacje pakietów bez prefiksu mają szczególne zasady zgodności: nazwa bez prefiksu, która pasuje do identyfikatora wbudowanego pluginu, używa tego wbudowanego źródła; nazwa bez prefiksu, która pasuje do identyfikatora oficjalnego zewnętrznego pluginu, używa oficjalnego katalogu pakietów; każda inna specyfikacja bez prefiksu jest instalowana przez npm w okresie przejściowym po uruchomieniu. Surowe specyfikacje @openclaw/*, które pasują do wbudowanych pluginów, również wskazują wbudowaną kopię przed użyciem npm jako rozwiązania rezerwowego. Użyj npm:@openclaw/<plugin>@<version>, aby celowo zainstalować zewnętrzny pakiet npm zamiast wbudowanej kopii. Użyj clawhub:, npm:, git: lub npm-pack:, aby deterministycznie wybrać źródło. Pełny kontrakt polecenia opisano na stronie openclaw plugins.

W przypadku instalacji z npm specyfikacje bez przypiętej wersji oraz @latest wybierają najnowszy stabilny pakiet, który deklaruje zgodność z tą wersją OpenClaw. Jeśli bieżące najnowsze wydanie npm deklaruje nowszą wartość openclaw.compat.pluginApi lub openclaw.install.minHostVersion, niż obsługuje ta kompilacja, OpenClaw przeszukuje starsze stabilne wersje i instaluje najnowszą zgodną wersję. Dokładne wersje i jawne znaczniki kanałów, takie jak @beta, pozostają przypięte do wybranego pakietu i powodują błąd w przypadku niezgodności.

Zasady instalacji operatora

Skonfiguruj security.installPolicy, aby przed instalacją lub aktualizacją pluginu uruchamiać zaufane lokalne polecenie zasad. Zasady otrzymują metadane oraz ścieżkę do przygotowanego źródła i mogą zezwolić na instalację lub ją zablokować. Obejmują zarówno ścieżki instalacji i aktualizacji przez CLI, jak i przez Gateway. Hooki before_install pluginu są uruchamiane później i tylko w procesach OpenClaw, w których załadowano hooki pluginów, dlatego do decyzji instalacyjnych należących do operatora używaj zamiast nich security.installPolicy. Przestarzała flaga --dangerously-force-unsafe-install jest akceptowana ze względu na zgodność, ale niczego nie robi: nie omija zasad instalacji ani wbudowanej w OpenClaw listy zabronionych zależności pluginów.

Wspólny schemat wykonywania security.installPolicy, używany zarówno przez Skills, jak i pluginy, opisano na stronie Konfiguracja Skills.

Konfiguracja zasad pluginów

Typowa struktura konfiguracji pluginów wygląda następująco:

{  plugins: {    enabled: true,    allow: ["voice-call"],    deny: ["untrusted-plugin"],    load: { paths: ["~/Projects/oss/voice-call-plugin"] },    slots: { memory: "memory-core" },    entries: {      "voice-call": { enabled: true, config: { provider: "twilio" } },    },  },}

Najważniejsze reguły zasad:

• plugins.enabled: false wyłącza wszystkie pluginy i pomija ich wykrywanie oraz ładowanie. Nieaktualne odwołania do pluginów pozostają nieaktywne, dopóki to ustawienie obowiązuje; jeśli chcesz usunąć nieaktualne identyfikatory, ponownie włącz pluginy przed uruchomieniem czyszczenia przez doctor.
• plugins.deny ma pierwszeństwo przed listą dozwolonych pluginów i ustawieniami włączenia poszczególnych pluginów.
• plugins.allow jest wyłączną listą dozwolonych pluginów. Narzędzia należące do pluginów spoza tej listy pozostają niedostępne, nawet jeśli tools.allow zawiera "*".
• plugins.entries.<id>.enabled: false wyłącza jeden plugin, zachowując jego konfigurację.
• plugins.load.paths dodaje jawne lokalne pliki lub katalogi pluginów. Lokalne ścieżki zarządzane przez plugins install muszą wskazywać katalogi pluginów lub archiwa; dla samodzielnych plików pluginów używaj plugins.load.paths.
• Pluginy pochodzące z obszaru roboczego są domyślnie wyłączone; przed użyciem lokalnego kodu z obszaru roboczego jawnie je włącz lub dodaj do listy dozwolonych pluginów.
• Wbudowane pluginy działają zgodnie ze swoimi wbudowanymi metadanymi określającymi domyślne włączenie lub wyłączenie, chyba że konfiguracja jawnie je nadpisuje.
• plugins.slots.<slot> (memory lub contextEngine) wybiera jeden plugin dla wyłącznej kategorii. Wybór gniazda jest traktowany jako jawna aktywacja i wymusza włączenie wybranego pluginu dla tego gniazda, nawet jeśli w innym przypadku wymagałby jawnego włączenia. plugins.deny i plugins.entries.<id>.enabled: false nadal go blokują.
• Wbudowane pluginy wymagające jawnego włączenia mogą aktywować się automatycznie, gdy konfiguracja wskazuje jedną z należących do nich powierzchni, takich jak odwołanie do dostawcy lub modelu, konfiguracja kanału, backend CLI albo środowisko wykonawcze agenta.
• Trasowanie Codex z rodziny OpenAI zachowuje oddzielne granice dostawcy i pluginu środowiska wykonawczego: starsze odwołania do modeli Codex są starszą konfiguracją naprawianą przez doctor, natomiast wbudowany plugin codex jest właścicielem środowiska wykonawczego serwera aplikacji Codex dla kanonicznych odwołań agentów openai/*, jawnego agentRuntime.id: "codex" oraz starszych odwołań codex/*.

Gdy plugins.allow nie jest ustawione, a niewbudowane pluginy są automatycznie wykrywane w obszarze roboczym lub globalnych katalogach głównych pluginów, dzienniki uruchamiania zawierają komunikat plugins.allow is empty; discovered non-bundled plugins may auto-load: ... z identyfikatorami wykrytych pluginów oraz, w przypadku krótkich list, minimalnym fragmentem plugins.allow. Przed skopiowaniem zaufanych pluginów do openclaw.json uruchom openclaw plugins list --enabled --verbose lub openclaw plugins inspect <id> dla podanego identyfikatora pluginu. To samo przypięcie zaufania obowiązuje, gdy diagnostyka informuje, że plugin został załadowany without install/load-path provenance: sprawdź ten identyfikator pluginu, a następnie przypnij go w plugins.allow lub zainstaluj ponownie z zaufanego źródła, aby OpenClaw zarejestrował pochodzenie instalacji.

Uruchom openclaw doctor lub openclaw doctor --fix, gdy walidacja konfiguracji zgłasza nieaktualne identyfikatory pluginów, niezgodności list dozwolonych pluginów i narzędzi albo starsze ścieżki wbudowanych pluginów.

Formaty pluginów

OpenClaw rozpoznaje dwa formaty pluginów:

Oba formaty są widoczne w openclaw plugins list, openclaw plugins inspect, openclaw plugins enable i openclaw plugins disable. Granicę zgodności pakietów opisano na stronie Pakiety pluginów, a tworzenie natywnych pluginów — na stronie Tworzenie pluginów.

Hooki pluginów

Pluginy mogą rejestrować hooki w czasie działania za pomocą dwóch różnych interfejsów API:

• Typowane hooki api.on(...) dla zdarzeń cyklu życia środowiska wykonawczego. Jest to preferowana powierzchnia dla oprogramowania pośredniczącego, zasad, przepisywania wiadomości, kształtowania promptów i sterowania narzędziami.
• api.registerHook(...) dla wewnętrznego systemu hooków opisanego na stronie Hooki. Służy głównie do ogólnych efektów ubocznych poleceń i cyklu życia oraz zachowania zgodności z istniejącą automatyzacją w stylu HOOK.

Prosta zasada: jeśli procedura obsługi wymaga priorytetu, semantyki scalania albo możliwości blokowania lub anulowania, użyj typowanych hooków. Jeśli jedynie reaguje na command:new, command:reset, message:sent lub podobne ogólne zdarzenia, odpowiedni będzie api.registerHook.

Wewnętrzne hooki zarządzane przez plugin są widoczne w openclaw hooks list jako plugin:<id>. Nie można ich włączać ani wyłączać za pomocą openclaw hooks; zamiast tego włącz lub wyłącz plugin.

Sprawdzanie aktywnego Gateway

Polecenia openclaw plugins list i zwykłe openclaw plugins inspect odczytują konfigurację, manifest i stan rejestru w stanie zimnym. Nie potwierdzają, że już działający Gateway zaimportował ten sam kod pluginu.

Gdy plugin wygląda na zainstalowany, ale aktywny ruch czatu go nie używa:

openclaw gateway status --deep --require-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

Zarządzane instancje Gateway są automatycznie uruchamiane ponownie po instalacji, aktualizacji i odinstalowaniu pluginu, jeśli zmiany modyfikują jego kod źródłowy. W instalacjach na VPS-ie lub w kontenerze upewnij się, że każde ręczne ponowne uruchomienie obejmuje właściwy proces podrzędny openclaw gateway run, który obsługuje Twoje kanały, a nie tylko proces opakowujący lub nadzorujący.

Rozwiązywanie problemów

Jeśli nieaktualna konfiguracja pluginu nadal wskazuje plugin kanału, którego nie można już wykryć, walidacja konfiguracji zmienia błąd tego klucza kanału w ostrzeżenie zamiast błędu krytycznego, dzięki czemu uruchomiona instancja Gateway może nadal obsługiwać wszystkie pozostałe kanały. Uruchom openclaw doctor --fix, aby usunąć nieaktualne wpisy pluginów i kanałów. Nieznane klucze kanałów bez dowodów na istnienie nieaktualnego pluginu nadal powodują błąd walidacji, aby literówki pozostawały widoczne.

W przypadku celowego zastąpienia kanału preferowany plugin powinien deklarować channelConfigs.<channel-id>.preferOver z identyfikatorem starszego pluginu lub pluginu o niższym priorytecie. Jeśli oba pluginy są jawnie włączone, OpenClaw zachowuje to żądanie i zgłasza komunikaty diagnostyczne o powielonej własności kanału/narzędzia zamiast bezgłośnie wybierać jednego właściciela.

Jeśli zainstalowany pakiet zgłasza, że requires compiled runtime output for TypeScript entry ..., oznacza to, że został opublikowany bez plików JavaScript wymaganych przez OpenClaw w czasie działania. Zaktualizuj go lub zainstaluj ponownie, gdy wydawca udostępni skompilowany JavaScript, albo do tego czasu wyłącz/odinstaluj plugin.

Zablokowana własność ścieżki pluginu

Jeśli komunikaty diagnostyczne zawierają blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root), a walidacja następnie zgłasza plugin present but blocked, OpenClaw znalazł pliki pluginu należące do innego użytkownika systemu Unix niż proces, który je wczytuje. Pozostaw konfigurację pluginu bez zmian; popraw własność plików w systemie plików lub uruchom OpenClaw jako ten sam użytkownik, do którego należy katalog stanu.

W instalacjach Docker oficjalny obraz działa jako node (uid 1000), dlatego katalogi konfiguracji i przestrzeni roboczej OpenClaw zamontowane z hosta powinny zwykle należeć do uid 1000:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

Jeśli celowo uruchamiasz OpenClaw jako root, ustaw zamiast tego własność zarządzanego katalogu głównego pluginów na root:

sudo chown -R root:root /path/to/openclaw-config/npm

Po poprawieniu własności ponownie uruchom openclaw doctor --fix lub openclaw plugins registry --refresh, aby zapisany rejestr pluginów odpowiadał naprawionym plikom.

Powolne przygotowywanie narzędzi pluginów

Jeśli przebiegi agenta zdają się zatrzymywać podczas przygotowywania narzędzi, włącz rejestrowanie na poziomie śledzenia i sprawdź wpisy dotyczące czasu działania fabryk narzędzi pluginów:

openclaw config set logging.level traceopenclaw logs --follow

Szukaj wpisów:

[trace:plugin-tools] factory timings ...

Podsumowanie zawiera łączny czas działania fabryk oraz najwolniejsze fabryki narzędzi pluginów, w tym identyfikator pluginu, zadeklarowane nazwy narzędzi, strukturę wyniku oraz informację, czy narzędzie jest opcjonalne. Powolne wpisy są podnoszone do poziomu ostrzeżeń, gdy pojedyncza fabryka działa co najmniej 1 s lub łączne przygotowanie fabryk narzędzi pluginów trwa co najmniej 5 s.

OpenClaw buforuje pomyślne wyniki fabryk narzędzi pluginów na potrzeby wielokrotnych rozstrzygnięć z tym samym efektywnym kontekstem żądania. Klucz pamięci podręcznej obejmuje efektywną konfigurację środowiska uruchomieniowego, przestrzeń roboczą i identyfikator agenta, zasady piaskownicy, ustawienia przeglądarki, kontekst dostarczenia, tożsamość żądającego oraz stan własności, dzięki czemu fabryki zależne od tych zaufanych pól uruchamiają się ponownie po zmianie kontekstu. Jeśli czasy pozostają wysokie, plugin może wykonywać kosztowne operacje przed zwróceniem definicji swoich narzędzi.

Jeśli jeden plugin odpowiada za większość czasu, sprawdź jego rejestracje środowiska uruchomieniowego:

openclaw plugins inspect <plugin-id> --runtime --json

Następnie zaktualizuj, zainstaluj ponownie lub wyłącz ten plugin. Autorzy pluginów powinni przenieść kosztowne wczytywanie zależności do ścieżki wykonywania narzędzia zamiast wykonywać je wewnątrz fabryki narzędzia.

Informacje o katalogach głównych zależności, walidacji metadanych pakietów, rekordach rejestru, zachowaniu ponownego wczytywania podczas uruchamiania oraz czyszczeniu starszych danych zawiera sekcja Rozwiązywanie zależności pluginów.

Powiązane materiały

• Zarządzanie pluginami — przykłady poleceń wyświetlania, instalowania, aktualizowania, odinstalowywania i publikowania
• openclaw plugins — pełna dokumentacja CLI
• Wykaz pluginów — wygenerowana lista dołączonych i zewnętrznych pluginów
• Dokumentacja pluginów — wygenerowane strony dokumentacji poszczególnych pluginów
• Pluginy społeczności — wyszukiwanie w ClawHub i zasady dotyczące PR-ów dokumentacji
• Rozwiązywanie zależności pluginów — katalogi główne instalacji, rekordy rejestru i granice środowiska uruchomieniowego
• Tworzenie pluginów — przewodnik tworzenia natywnych pluginów
• Omówienie zestawu SDK pluginów — rejestracja środowiska uruchomieniowego, hooki i pola API
• Manifest pluginu — manifest i metadane pakietu