Pluginy

Pluginy rozszerzają OpenClaw o kanały, dostawców modeli, środowiska wykonawcze agentów, narzędzia, Skills, mowę, transkrypcję w czasie rzeczywistym, głos, rozumienie multimediów, generowanie, pobieranie treści z internetu, wyszukiwanie w internecie i inne możliwości środowiska uruchomieniowego.

Na tej stronie opisano instalowanie pluginu, ponowne uruchamianie Gateway, sprawdzanie, czy środowisko uruchomieniowe go załadowało, oraz rozwiązywanie typowych problemów z konfiguracją. Przykłady obejmujące tylko polecenia zawiera strona Zarządzanie pluginami. Wygenerowany wykaz pluginów wbudowanych, oficjalnych zewnętrznych i dostępnych wyłącznie w kodzie źródłowym 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 dane uwierzytelniające, klucze konfiguracji lub narzędzia systemu operacyjnego wymagane w dokumentacji konfiguracji danego pluginu
• uprawnienie do przeładowania lub ponownego uruchomienia Gateway obsługującego kanały

Szybki start

openclaw plugins search "calendar"

# Z ClawHub.openclaw plugins install clawhub:<package> # Z npm.openclaw plugins install npm:<package> # Z git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # Z lokalnej kopii roboczej używanej do programowania.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ą specjalne zachowanie zgodności: nazwa bez prefiksu, która odpowiada identyfikatorowi pluginu wbudowanego, używa tego wbudowanego źródła; nazwa bez prefiksu, która odpowiada identyfikatorowi oficjalnego pluginu zewnętrznego, używa oficjalnego katalogu pakietów; każda inna specyfikacja bez prefiksu jest podczas migracji związanej z uruchomieniem instalowana przez npm. Surowe specyfikacje @openclaw/*, które odpowiadają pluginom wbudowanym, również wskazują wbudowaną kopię przed przejściem awaryjnym do npm. 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łną umowę polecenia opisano w openclaw plugins.

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

Zasady instalacji operatora

Skonfiguruj security.installPolicy, aby przed instalacją lub aktualizacją pluginu uruchamiać zaufane lokalne polecenie zasad. Zasada otrzymuje metadane oraz ścieżkę do przygotowanego źródła i może zezwolić na instalację lub ją zablokować. Obejmuje zarówno ścieżki instalowania i aktualizowania przez CLI, jak i przez Gateway. Hooki pluginu before_install 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 należy zamiast nich używać security.installPolicy. Przestarzała flaga --dangerously-force-unsafe-install jest akceptowana ze względu na zgodność, ale nie wykonuje żadnej operacji: 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 w sekcji Konfiguracja Skills.

Konfigurowanie 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 oraz pomija ich wykrywanie i ładowanie. Nieaktualne odwołania do pluginów pozostają nieaktywne podczas obowiązywania tego ustawienia; przed uruchomieniem czyszczenia przez doctor należy ponownie włączyć pluginy, jeśli nieaktualne identyfikatory mają zostać usunięte.
• plugins.deny ma pierwszeństwo przed listą dozwolonych i ustawieniem włączenia poszczególnych pluginów.
• plugins.allow jest wyłączną listą dozwolonych. Narzędzia należące do pluginów spoza listy dozwolonych 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. Zarządzane ścieżki lokalne plugins install muszą wskazywać katalogi pluginów lub archiwa; w przypadku samodzielnych plików pluginów należy użyć plugins.load.paths.
• Pluginy pochodzące z obszaru roboczego są domyślnie wyłączone; przed użyciem lokalnego kodu z obszaru roboczego należy je jawnie włączyć lub dodać do listy dozwolonych.
• Pluginy wbudowane przestrzegają własnych metadanych określających domyślne włączenie lub wyłączenie, chyba że konfiguracja jawnie je zastąpi.
• plugins.slots.<slot> (memory lub contextEngine) wybiera jeden plugin dla wyłącznej kategorii. Wybór slotu jest traktowany jako jawna aktywacja i wymusza włączenie wybranego pluginu dla tego slotu, nawet jeśli w przeciwnym razie wymagałby zgody na włączenie. plugins.deny i plugins.entries.<id>.enabled: false nadal go blokują.
• Wbudowane pluginy wymagające zgody na włączenie mogą aktywować się automatycznie, gdy konfiguracja wskazuje jedną z należących do nich powierzchni, taką jak odwołanie do dostawcy lub modelu, konfiguracja kanału, backend CLI albo środowisko uruchomieniowe agenta.
• Routing Codex z rodziny OpenAI zachowuje oddzielne granice dostawcy i pluginu środowiska uruchomieniowego: starsze odwołania do modeli Codex stanowią starszą konfigurację naprawianą przez doctor, natomiast wbudowany plugin codex jest właścicielem środowiska uruchomieniowego serwera aplikacji Codex dla kanonicznych odwołań agentów openai/*, jawnych 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, podczas uruchamiania rejestrowany jest 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 wymienionego identyfikatora pluginu. To samo przypinanie 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 zapisał pochodzenie instalacji.

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

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 w sekcji Pakiety pluginów, a tworzenie natywnych pluginów — w sekcji Tworzenie pluginów.

Hooki pluginów

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

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

Prosta reguła: jeśli procedura obsługi wymaga priorytetu, semantyki scalania albo możliwości blokowania lub anulowania, należy użyć typowanych hooków. Jeśli tylko reaguje na command:new, command:reset, message:sent lub podobne zdarzenia ogólne, api.registerHook jest odpowiednie.

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

Sprawdzanie aktywnego Gateway

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

Gdy plugin wydaje się zainstalowany, ale ruch czatu na żywo go nie używa:

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

Zarządzane Gatewaye automatycznie uruchamiają się ponownie po instalacji, aktualizacji i odinstalowaniu, jeśli zmiany modyfikują kod źródłowy pluginu. W instalacjach na VPS-ie lub w kontenerze należy dopilnować, aby ręczne ponowne uruchomienie obejmowało właściwy proces podrzędny openclaw gateway run, który obsługuje kanały, a nie tylko proces opakowujący lub nadzorujący.

Rozwiązywanie problemów

Gdy nieaktualna konfiguracja pluginu nadal wskazuje niewykrywalny już plugin kanału, walidacja konfiguracji obniża błąd tego klucza kanału do ostrzeżenia zamiast błędu krytycznego, dzięki czemu Gateway może się uruchomić i nadal obsługiwać wszystkie pozostałe kanały. Uruchom openclaw doctor --fix, aby usunąć nieaktualne wpisy pluginu i kanału. Nieznane klucze kanałów bez dowodów na nieaktualny plugin nadal powodują niepowodzenie 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 zduplikowanej własności kanału/narzędzia, zamiast niejawnie wybierać jednego właściciela.

Jeśli zainstalowany pakiet zgłasza, że requires compiled runtime output for TypeScript entry ..., pakiet opublikowano bez plików JavaScript potrzebnych OpenClaw w środowisku uruchomieniowym. Zaktualizuj lub zainstaluj go ponownie, gdy wydawca udostępni skompilowany kod JavaScript, albo do tego czasu wyłącz/odinstaluj plugin.

Zablokowana własność ścieżki pluginu

Jeśli komunikaty diagnostyczne podają blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root), a następnie walidacja zgłasza plugin present but blocked, oznacza to, że OpenClaw znalazł pliki pluginu należące do innego użytkownika systemu Unix niż proces, który je ładuje. Pozostaw konfigurację pluginu bez zmian; popraw własność 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), więc montowane z hosta katalogi konfiguracji i przestrzeni roboczej OpenClaw powinny zwykle należeć do uid 1000:

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

Jeśli OpenClaw jest celowo uruchamiany jako root, zamiast tego ustaw właściciela 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 konfigurowanie narzędzi pluginu

Jeśli przebiegi agenta zdają się zatrzymywać podczas przygotowywania narzędzi, włącz rejestrowanie na poziomie śledzenia i sprawdź wiersze czasów fabryk narzędzi pluginów:

openclaw config set logging.level traceopenclaw logs --follow

Poszukaj:

[trace:plugin-tools] czasy fabryk ...

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

OpenClaw buforuje pomyślne wyniki fabryk narzędzi pluginów na potrzeby wielokrotnego rozstrzygania w tym samym efektywnym kontekście żądania. Klucz pamięci podręcznej obejmuje efektywną konfigurację środowiska uruchomieniowego, przestrzeń roboczą i identyfikator agenta, zasady piaskownicy, ustawienia przeglądarki, kontekst dostarczania, tożsamość żądającego oraz stan własności, więc 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 w środowisku uruchomieniowym:

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

Następnie zaktualizuj, ponownie zainstaluj lub wyłącz ten plugin. Autorzy pluginów powinni przenieść kosztowne ładowanie 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 pakietu, rekordach rejestru, przeładowywaniu przy uruchamianiu i usuwaniu starszych danych zawiera Rozwiązywanie zależności pluginów.

Powiązane

• Zarządzanie pluginami - przykłady poleceń do wyświetlania listy, instalowania, aktualizowania, odinstalowywania i publikowania
• openclaw plugins - pełna dokumentacja CLI
• Wykaz pluginów - wygenerowana lista pluginów wbudowanych i zewnętrznych
• Dokumentacja pluginów - wygenerowane strony dokumentacji poszczególnych pluginów
• Pluginy społeczności - wyszukiwanie w ClawHub i zasady PR-ów dotyczących 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 SDK pluginów - rejestracja w środowisku uruchomieniowym, hooki i pola API
• Manifest pluginu - manifest i metadane pakietu