CLI commands
Pluginy
Zarządzaj Plugin Gateway, pakietami hooków i zgodnymi pakietami.
Przewodnik dla użytkownika końcowego dotyczący instalowania, włączania i rozwiązywania problemów z pluginami.
Szybkie przykłady instalowania, wyświetlania listy, aktualizowania, odinstalowywania i publikowania.
Model zgodności pakietów.
Pola manifestu i schemat konfiguracji.
Wzmacnianie zabezpieczeń instalacji pluginów.
Polecenia
openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --jsonopenclaw plugins search <query>openclaw plugins search <query> --limit 20openclaw plugins search <query> --jsonopenclaw plugins install <path-or-spec>openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --jsonopenclaw plugins inspect --allopenclaw plugins info <id>openclaw plugins enable <id>openclaw plugins disable <id>openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins uninstall <id>openclaw plugins doctoropenclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins marketplace entriesopenclaw plugins marketplace entries --offlineopenclaw plugins marketplace entries --jsonopenclaw plugins marketplace list <marketplace>openclaw plugins marketplace list <marketplace> --jsonopenclaw plugins marketplace refreshopenclaw plugins marketplace refresh --feed-profile clawhub-public --jsonopenclaw plugins marketplace refresh --feed-url https://clawhub.ai/v1/feeds/plugins --expected-sha256 <sha256>openclaw plugins init my-tool --name "My Tool"openclaw plugins init my-provider --name "My Provider" --type provideropenclaw plugins init my-provider --name "My Provider" --type provider --directory ./my-provideropenclaw plugins build --entry ./dist/index.jsopenclaw plugins build --entry ./dist/index.js --checkopenclaw plugins validate --entry ./dist/index.jsAby zbadać powolną instalację, inspekcję, odinstalowanie lub odświeżanie rejestru, uruchom
polecenie z OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1. Ślad zapisuje czasy faz
do stderr i zachowuje możliwość parsowania wyjścia JSON. Zobacz Debugowanie.
Autor
openclaw plugins init stock-quotes --name "Stock Quotes"cd stock-quotesnpm run plugin:buildnpm run plugin:validateplugins init domyślnie tworzy minimalny plugin narzędzia w TypeScript. Pierwszy
argument to id pluginu; przekaż --name, aby ustawić nazwę wyświetlaną. OpenClaw używa
id jako domyślnego katalogu wyjściowego i nazwy pakietu. Szkielety narzędzi używają
defineToolPlugin.
plugins build importuje zbudowany punkt wejścia, odczytuje jego statyczne metadane narzędzia, zapisuje
openclaw.plugin.json i utrzymuje package.json openclaw.extensions w zgodności.
plugins validate sprawdza, czy wygenerowany manifest, metadane pakietu i
bieżący eksport punktu wejścia nadal są zgodne. Zobacz Pluginy narzędzi, aby poznać
pełny proces tworzenia narzędzi.
Szkielet zapisuje źródła TypeScript, ale generuje metadane z zbudowanego
punktu wejścia ./dist/index.js, więc przepływ działa także z opublikowanym CLI. Użyj
--entry <path>, gdy punkt wejścia nie jest domyślnym punktem wejścia pakietu. Użyj
plugins build --check w CI, aby zakończyć niepowodzeniem, gdy wygenerowane metadane są nieaktualne, bez
ponownego zapisywania plików.
Szkielet dostawcy
openclaw plugins init acme-models --name "Acme Models" --type providercd acme-modelsnpm installnpm run buildnpm testnpm run validateSzkielety dostawców tworzą generyczny plugin dostawcy tekstu/modelu z zgodną z OpenAI
obsługą kluczy API, wbudowanym skryptem npm run validate dla clawhub package validate, metadanymi pakietu ClawHub oraz ręcznie uruchamianym przepływem GitHub
do przyszłego zaufanego publikowania przez GitHub Actions OIDC. Szkielety dostawców nie
generują Skills i nie używają openclaw plugins build ani
openclaw plugins validate; te polecenia są przeznaczone dla ścieżki wygenerowanych metadanych
szkieletu narzędzia.
Przed publikacją zastąp zastępczy bazowy URL API, katalog modeli, trasę dokumentacji, tekst poświadczeń i treść README rzeczywistymi szczegółami dostawcy. Użyj wygenerowanego README do pierwszej publikacji w ClawHub i konfiguracji zaufanego wydawcy.
Instalacja
openclaw plugins search "calendar" # search ClawHub pluginsopenclaw plugins install <package> # source auto-detectionopenclaw plugins install clawhub:<package> # ClawHub onlyopenclaw plugins install npm:<package> # npm onlyopenclaw plugins install npm-pack:<path.tgz> # local npm pack through npm install semanticsopenclaw plugins install git:github.com/<owner>/<repo> # git repoopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <package> --force # overwrite existing installopenclaw plugins install <package> --pin # pin versionopenclaw plugins install clawhub:<package> --acknowledge-clawhub-riskopenclaw plugins install <package> --dangerously-force-unsafe-installopenclaw plugins install <path> # local pathopenclaw plugins install <plugin>@<marketplace> # marketplaceopenclaw plugins install <plugin> --marketplace <name> # marketplace (explicit)openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>Opiekunowie testujący instalacje wykonywane podczas konfiguracji mogą nadpisać automatyczne źródła instalacji pluginów za pomocą chronionych zmiennych środowiskowych. Zobacz Nadpisania instalacji pluginów.
plugins search odpytuje ClawHub o możliwe do zainstalowania pakiety pluginów i wypisuje
gotowe do instalacji nazwy pakietów. Wyszukuje pakiety code-plugin i bundle-plugin,
a nie Skills. Użyj openclaw skills search dla Skills z ClawHub.
Config includes and invalid-config repair
Jeśli sekcja plugins jest wspierana przez jednoplikowe $include, plugins install/update/enable/disable/uninstall zapisuje do tego dołączonego pliku i pozostawia openclaw.json bez zmian. Dołączenia główne, tablice dołączeń i dołączenia z sąsiednimi nadpisaniami kończą się zamknięciem z błędem zamiast spłaszczania. Zobacz Dołączenia konfiguracji, aby poznać obsługiwane kształty.
Jeśli konfiguracja jest nieprawidłowa podczas instalacji, plugins install zwykle kończy się zamknięciem z błędem i informuje, aby najpierw uruchomić openclaw doctor --fix. Podczas uruchamiania Gateway i gorącego przeładowania nieprawidłowa konfiguracja pluginu kończy się zamknięciem z błędem tak jak każda inna nieprawidłowa konfiguracja; openclaw doctor --fix może poddać kwarantannie nieprawidłowy wpis pluginu. Jedynym udokumentowanym wyjątkiem w czasie instalacji jest wąska ścieżka odzyskiwania dołączonego pluginu dla pluginów, które jawnie wybierają openclaw.install.allowInvalidConfigRecovery.
--force and reinstall vs update
--force ponownie używa istniejącego celu instalacji i nadpisuje już zainstalowany plugin lub pakiet hooków w miejscu. Użyj tego, gdy celowo ponownie instalujesz ten sam id z nowej ścieżki lokalnej, archiwum, pakietu ClawHub lub artefaktu npm. Do rutynowych aktualizacji już śledzonego pluginu npm preferuj openclaw plugins update <id-or-npm-spec>.
Jeśli uruchomisz plugins install dla id pluginu, który jest już zainstalowany, OpenClaw zatrzyma się i wskaże plugins update <id-or-npm-spec> dla zwykłej aktualizacji albo plugins install <package> --force, gdy naprawdę chcesz nadpisać bieżącą instalację z innego źródła.
--pin scope
--pin dotyczy tylko instalacji npm. Nie jest obsługiwane z instalacjami git:; użyj jawnego odwołania git, takiego jak git:github.com/acme/plugin@v1.2.3, gdy chcesz przypięte źródło. Nie jest obsługiwane z --marketplace, ponieważ instalacje z marketplace utrwalają metadane źródła marketplace zamiast specyfikacji npm.
--dangerously-force-unsafe-install
--dangerously-force-unsafe-install jest przestarzałe i teraz nie wykonuje żadnej operacji. OpenClaw nie uruchamia już wbudowanego blokowania niebezpiecznego kodu w czasie instalacji dla instalacji pluginów.
Użyj współdzielonej, należącej do operatora powierzchni security.installPolicy, gdy wymagana jest specyficzna dla hosta polityka instalacji. Hooki pluginu before_install są hookami cyklu życia środowiska uruchomieniowego pluginu i nie są podstawową granicą polityki dla instalacji CLI.
Jeśli plugin opublikowany przez Ciebie w ClawHub jest ukryty lub zablokowany przez skan rejestru, użyj kroków wydawcy w Publikowanie w ClawHub. --dangerously-force-unsafe-install nie prosi ClawHub o ponowne przeskanowanie pluginu ani o upublicznienie zablokowanego wydania.
--acknowledge-clawhub-risk
Społecznościowe instalacje ClawHub sprawdzają rekord zaufania wybranego wydania przed pobraniem pakietu. Jeśli ClawHub wyłączy pobieranie dla wydania, zgłosi złośliwe wyniki skanowania albo umieści wydanie w blokującym stanie moderacji, takim jak kwarantanna, OpenClaw odrzuci wydanie. W przypadku nieblokujących ryzykownych statusów skanowania, ryzykownych stanów moderacji lub powodów rejestru OpenClaw pokazuje szczegóły zaufania i prosi o potwierdzenie przed kontynuowaniem.
Użyj --acknowledge-clawhub-risk tylko po przejrzeniu ostrzeżenia ClawHub i podjęciu decyzji o kontynuowaniu bez interaktywnego monitu. Oczekujące lub nieaktualne czyste rekordy zaufania ostrzegają, ale nie wymagają potwierdzenia. Oficjalne pakiety ClawHub i dołączone źródła pluginów OpenClaw pomijają ten monit zaufania wydania.
Hook packs and npm specs
plugins install jest także powierzchnią instalacji dla pakietów hooków, które udostępniają openclaw.hooks w package.json. Użyj openclaw hooks do filtrowanej widoczności hooków i włączania poszczególnych hooków, a nie do instalacji pakietów.
Specyfikacje Npm są wyłącznie rejestrowe (nazwa pakietu + opcjonalna dokładna wersja lub dist-tag). Specyfikacje Git/URL/file oraz zakresy semver są odrzucane. Instalacje zależności działają w jednym zarządzanym projekcie npm na plugin z --ignore-scripts dla bezpieczeństwa, nawet gdy Twoja powłoka ma globalne ustawienia instalacji npm. Zarządzane projekty npm pluginów dziedziczą pakietowe overrides npm OpenClaw, więc piny bezpieczeństwa hosta obejmują też wyniesione zależności pluginów.
Użyj npm:<package>, gdy chcesz jawnie wskazać rozwiązywanie przez npm. Gołe specyfikacje pakietów także instalują bezpośrednio z npm podczas przejścia startowego, chyba że pasują do oficjalnego identyfikatora pluginu.
Surowe specyfikacje pakietów @openclaw/*, które pasują do dołączonych pluginów, są rozwiązywane do kopii dołączonej i należącej do obrazu przed awaryjnym przejściem do npm. Na przykład openclaw plugins install @openclaw/discord@2026.5.20 --pin używa dołączonego pluginu Discord z bieżącej kompilacji OpenClaw zamiast tworzyć zarządzane nadpisanie npm. Aby wymusić zewnętrzny pakiet npm, użyj openclaw plugins install npm:@openclaw/discord@2026.5.20 --pin.
Gołe specyfikacje i @latest pozostają na stabilnej ścieżce. Wersje poprawek OpenClaw oznaczone datą, takie jak 2026.5.3-1, są stabilnymi wydaniami dla tego sprawdzenia. Jeśli npm rozwiąże którąkolwiek z nich do wersji przedwydaniowej, OpenClaw zatrzyma się i poprosi o jawne wyrażenie zgody przy użyciu tagu przedwydaniowego, takiego jak @beta/@rc, albo dokładnej wersji przedwydaniowej, takiej jak @1.2.3-beta.4.
W przypadku instalacji npm bez dokładnej wersji (npm:<package> lub npm:<package>@latest) OpenClaw sprawdza rozwiązaną metadane pakietu przed instalacją. Jeśli najnowszy stabilny pakiet wymaga nowszego API pluginów OpenClaw albo minimalnej wersji hosta, OpenClaw sprawdza starsze stabilne wersje i instaluje zamiast tego najnowsze zgodne wydanie. Dokładne wersje i jawne dist-tagi, takie jak @beta, pozostają rygorystyczne: jeśli wybrany pakiet jest niezgodny, polecenie kończy się niepowodzeniem i prosi o uaktualnienie OpenClaw albo wybranie zgodnej wersji.
Jeśli goła specyfikacja instalacji pasuje do oficjalnego identyfikatora pluginu (na przykład diffs), OpenClaw instaluje bezpośrednio wpis katalogu. Aby zainstalować pakiet npm o tej samej nazwie, użyj jawnej specyfikacji z zakresem (na przykład @scope/diffs).
Repozytoria Git
Użyj git:<repo>, aby instalować bezpośrednio z repozytorium git. Obsługiwane formy obejmują git:github.com/owner/repo, git:owner/repo, pełne adresy klonowania https://, ssh://, git://, file:// oraz git@host:owner/repo.git. Dodaj @<ref> lub #<ref>, aby przed instalacją przełączyć się na gałąź, tag albo commit.
Instalacje Git klonują do katalogu tymczasowego, przełączają się na żądaną referencję, jeśli jest podana, a następnie używają zwykłego instalatora katalogu pluginu. Oznacza to, że walidacja manifestu, polityka instalacji operatora, praca instalacyjna menedżera pakietów i rekordy instalacji zachowują się tak jak przy instalacjach npm. Zarejestrowane instalacje git zawierają źródłowy URL/ref oraz rozwiązywany commit, aby openclaw plugins update mogło później ponownie rozwiązać źródło.
Po instalacji z git użyj openclaw plugins inspect <id> --runtime --json, aby zweryfikować rejestracje runtime, takie jak metody Gateway i polecenia CLI. Jeśli plugin zarejestrował korzeń CLI za pomocą api.registerCli, wykonaj to polecenie bezpośrednio przez główny CLI OpenClaw, na przykład openclaw demo-plugin ping.
Archiwa
Obsługiwane archiwa: .zip, .tgz, .tar.gz, .tar. Natywne archiwa pluginów OpenClaw muszą zawierać poprawny openclaw.plugin.json w wyodrębnionym katalogu głównym pluginu; archiwa zawierające tylko package.json są odrzucane, zanim OpenClaw zapisze rekordy instalacji.
Użyj npm-pack:<path.tgz>, gdy plik jest archiwum tarball npm-pack i chcesz
przetestować tę samą ścieżkę zarządzanego projektu npm na plugin, której używają
instalacje z rejestru, w tym weryfikację package-lock.json, skanowanie wyniesionych
zależności i rekordy instalacji npm. Zwykłe ścieżki archiwów nadal instalują się jako lokalne
archiwa pod katalogiem głównym rozszerzeń pluginów.
Obsługiwane są także instalacje z marketplace Claude.
Instalacje ClawHub używają jawnego lokatora clawhub:<package>:
openclaw plugins install clawhub:openclaw-codex-app-serveropenclaw plugins install clawhub:openclaw-codex-app-server@1.2.3Gołe specyfikacje pluginów bezpieczne dla npm domyślnie instalują z npm podczas przejścia startowego, chyba że pasują do oficjalnego identyfikatora pluginu:
openclaw plugins install openclaw-codex-app-serverUżyj npm:, aby jawnie wskazać rozwiązywanie tylko przez npm:
openclaw plugins install npm:openclaw-codex-app-serveropenclaw plugins install npm:@openclaw/discord@2026.5.20openclaw plugins install npm:@scope/plugin-name@1.0.1OpenClaw sprawdza deklarowaną zgodność API pluginu / minimalną zgodność Gateway przed instalacją. Gdy wybrana wersja ClawHub publikuje artefakt ClawPack, OpenClaw pobiera wersjonowany npm-pack .tgz, weryfikuje nagłówek skrótu ClawHub i skrót artefaktu, a następnie instaluje go przez zwykłą ścieżkę archiwum. Starsze wersje ClawHub bez metadanych ClawPack nadal instalują się przez starszą ścieżkę weryfikacji archiwum pakietu. Zarejestrowane instalacje przechowują metadane źródła ClawHub, rodzaj artefaktu, integralność npm, shasum npm, nazwę tarballa i fakty skrótu ClawPack na potrzeby późniejszych aktualizacji.
Niewersjonowane instalacje ClawHub zachowują niewersjonowaną zarejestrowaną specyfikację, aby openclaw plugins update mogło śledzić nowsze wydania ClawHub; jawne selektory wersji lub tagów, takie jak clawhub:pkg@1.2.3 i clawhub:pkg@beta, pozostają przypięte do tego selektora.
Skrót marketplace
Użyj skrótu plugin@marketplace, gdy nazwa marketplace istnieje w lokalnej pamięci podręcznej rejestru Claude pod ~/.claude/plugins/known_marketplaces.json:
openclaw plugins marketplace list <marketplace-name>openclaw plugins install <plugin-name>@<marketplace-name>Użyj --marketplace, gdy chcesz jawnie przekazać źródło marketplace:
openclaw plugins install <plugin-name> --marketplace <marketplace-name>openclaw plugins install <plugin-name> --marketplace <owner/repo>openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>openclaw plugins install <plugin-name> --marketplace ./my-marketplaceŹródła marketplace
- znana nazwa marketplace Claude z
~/.claude/plugins/known_marketplaces.json - lokalny katalog główny marketplace albo ścieżka
marketplace.json - skrót repozytorium GitHub, taki jak
owner/repo - URL repozytorium GitHub, taki jak
https://github.com/owner/repo - URL git
Reguły zdalnego marketplace
W przypadku zdalnych marketplace ładowanych z GitHub albo git wpisy pluginów muszą pozostać wewnątrz sklonowanego repozytorium marketplace. OpenClaw akceptuje względne źródła ścieżek z tego repozytorium i odrzuca HTTP(S), ścieżki bezwzględne, git, GitHub oraz inne nieścieżkowe źródła pluginów ze zdalnych manifestów.
Dla lokalnych ścieżek i archiwów OpenClaw wykrywa automatycznie:
- natywne pluginy OpenClaw (
openclaw.plugin.json) - pakiety zgodne z Codex (
.codex-plugin/plugin.json) - pakiety zgodne z Claude (
.claude-plugin/plugin.jsonalbo domyślny układ komponentów Claude) - pakiety zgodne z Cursor (
.cursor-plugin/plugin.json)
Zarządzane instalacje lokalne muszą być katalogami pluginów albo archiwami. Samodzielne pliki pluginów .js,
.mjs, .cjs i .ts nie są kopiowane do zarządzanego katalogu głównego pluginów
przez plugins install; zamiast tego wymień je jawnie w plugins.load.paths.
Lista
openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --jsonopenclaw plugins search <query>openclaw plugins search <query> --limit 20openclaw plugins search <query> --json--enabledbooleanPokaż tylko włączone pluginy.
--verbosebooleanPrzełącz z widoku tabeli na wiersze szczegółów dla każdego pluginu z metadanymi źródła/pochodzenia/wersji/aktywacji.
--jsonbooleanInwentarz czytelny maszynowo oraz diagnostyka rejestru i stan instalacji zależności pakietów.
Jeśli log startowy pokazuje plugins.allow is empty; discovered non-bundled plugins may auto-load: ...,
uruchom openclaw plugins list --enabled --verbose albo
openclaw plugins inspect <id> z wymienionym identyfikatorem pluginu, aby potwierdzić
identyfikatory pluginów i skopiować zaufane identyfikatory do plugins.allow w openclaw.json. Gdy
ostrzeżenie może wymienić każdy wykryty plugin, wypisuje gotowy do wklejenia
fragment plugins.allow, który już zawiera te identyfikatory. Jeśli plugin ładuje się
bez pochodzenia z instalacji/ścieżki ładowania, sprawdź ten identyfikator pluginu, a następnie albo przypnij
zaufany identyfikator w plugins.allow, albo zainstaluj plugin ponownie z zaufanego źródła,
aby OpenClaw zapisał pochodzenie instalacji.
plugins search to zdalne wyszukiwanie katalogu ClawHub. Nie sprawdza lokalnego
stanu, nie modyfikuje konfiguracji, nie instaluje pakietów ani nie ładuje kodu runtime pluginu. Wyniki
wyszukiwania zawierają nazwę pakietu ClawHub, rodzinę, kanał, wersję, podsumowanie oraz
wskazówkę instalacji, taką jak openclaw plugins install clawhub:<package>.
Podczas pracy nad dołączonym pluginem wewnątrz spakowanego obrazu Docker zamontuj bindem katalog
źródłowy pluginu na pasującą spakowaną ścieżkę źródłową, taką jak
/app/extensions/synology-chat. OpenClaw wykryje tę zamontowaną nakładkę źródeł
przed /app/dist/extensions/synology-chat; zwykły skopiowany katalog źródłowy
pozostaje nieaktywny, więc normalne spakowane instalacje nadal używają skompilowanego dist.
Do debugowania hooków runtime:
openclaw plugins inspect <id> --runtime --jsonpokazuje zarejestrowane hooki i diagnostykę z przebiegu inspekcji z załadowaniem modułu. Inspekcja runtime nigdy nie instaluje zależności; użyjopenclaw doctor --fix, aby wyczyścić starszy stan zależności albo odzyskać brakujące pobieralne pluginy, do których odwołuje się konfiguracja.openclaw gateway status --deep --require-rpcpotwierdza osiągalny URL/profil Gateway, wskazówki usługi/procesu, ścieżkę konfiguracji i kondycję RPC.- Niedowiązane hooki konwersacji (
llm_input,llm_output,before_model_resolve,before_agent_reply,before_agent_run,before_agent_finalize,agent_end) wymagająplugins.entries.<id>.hooks.allowConversationAccess=true.
Użyj --link, aby uniknąć kopiowania lokalnego katalogu pluginu (dodaje do plugins.load.paths):
openclaw plugins install -l ./my-pluginSamodzielne pliki pluginów muszą być wymienione w plugins.load.paths, a nie
instalowane przez plugins install ani umieszczane bezpośrednio w ~/.openclaw/extensions
lub <workspace>/.openclaw/extensions. Te automatycznie wykrywane katalogi główne ładują katalogi
pakietów albo pakietów pluginów, natomiast pliki skryptów najwyższego poziomu są traktowane jako lokalne
pomocnicze pliki i pomijane.
Indeks pluginów
Metadane instalacji pluginów są stanem zarządzanym maszynowo, a nie konfiguracją użytkownika. Instalacje i aktualizacje zapisują je we współdzielonej bazie stanu SQLite w aktywnym katalogu stanu OpenClaw. Wiersz installed_plugin_index przechowuje trwałe metadane installRecords, w tym rekordy uszkodzonych lub brakujących manifestów pluginów, oraz zimną pamięć podręczną rejestru wyprowadzoną z manifestu, używaną przez openclaw plugins update, odinstalowanie, diagnostykę i zimny rejestr pluginów.
Gdy OpenClaw widzi w konfiguracji dostarczone starsze rekordy plugins.installs, odczyty wykonywane w runtime traktują je jako dane zgodności bez przepisywania openclaw.json. Jawne zapisy pluginów i openclaw doctor --fix przenoszą te rekordy do indeksu pluginów i usuwają klucz konfiguracji, gdy zapisy konfiguracji są dozwolone; jeśli którykolwiek zapis się nie powiedzie, rekordy konfiguracji zostają zachowane, aby metadane instalacji nie zostały utracone.
Odinstalowanie
openclaw plugins uninstall <id>openclaw plugins uninstall <id> --dry-runopenclaw plugins uninstall <id> --keep-filesuninstall usuwa rekordy pluginów z plugins.entries, utrwalonego indeksu pluginów, wpisów list dozwolonych/zabronionych pluginów oraz linkowanych wpisów plugins.load.paths, gdy ma to zastosowanie. O ile nie ustawiono --keep-files, odinstalowanie usuwa także śledzony zarządzany katalog instalacji, gdy znajduje się on w głównym katalogu rozszerzeń pluginów OpenClaw. W przypadku pluginów Active Memory slot pamięci resetuje się do memory-core.
Aktualizacja
openclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins update <id-or-npm-spec> --dry-runopenclaw plugins update @openclaw/voice-callopenclaw plugins update openclaw-codex-app-server --acknowledge-clawhub-riskopenclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-installAktualizacje dotyczą śledzonych instalacji pluginów w zarządzanym indeksie pluginów oraz śledzonych instalacji pakietów hooków w hooks.internal.installs.
Resolving plugin id vs npm spec
Gdy przekazujesz identyfikator pluginu, OpenClaw ponownie używa zapisanej specyfikacji instalacji dla tego pluginu. Oznacza to, że wcześniej zapisane dist-tagi, takie jak @beta, oraz dokładne przypięte wersje będą nadal używane przy późniejszych uruchomieniach update <id>.
Podczas update <id> --dry-run dokładnie przypięte instalacje npm pozostają przypięte. Jeśli OpenClaw może również rozwiązać domyślną linię rejestru pakietu i ta domyślna linia jest nowsza niż zainstalowana przypięta wersja, przebieg próbny zgłasza przypięcie i wypisuje jawne polecenie aktualizacji pakietu @latest, aby przejść na domyślną linię rejestru.
Ta reguła aktualizacji celowanej różni się od zbiorczej ścieżki konserwacyjnej openclaw plugins update --all. Aktualizacje zbiorcze nadal respektują zwykłe śledzone specyfikacje instalacji, ale zaufane oficjalne rekordy pluginów OpenClaw mogą synchronizować się z bieżącym celem oficjalnego katalogu zamiast pozostawać na nieaktualnym dokładnym oficjalnym pakiecie. Użyj celowanego update <id>, gdy celowo chcesz pozostawić dokładną lub otagowaną oficjalną specyfikację bez zmian.
W przypadku instalacji npm możesz także przekazać jawną specyfikację pakietu npm z dist-tagiem lub dokładną wersją. OpenClaw rozwiązuje tę nazwę pakietu z powrotem do śledzonego rekordu pluginu, aktualizuje ten zainstalowany plugin i zapisuje nową specyfikację npm dla przyszłych aktualizacji opartych na identyfikatorze.
Przekazanie nazwy pakietu npm bez wersji lub tagu również rozwiązuje się z powrotem do śledzonego rekordu pluginu. Użyj tego, gdy plugin został przypięty do dokładnej wersji i chcesz przenieść go z powrotem na domyślną linię wydań rejestru.
Beta channel updates
Celowane openclaw plugins update <id-or-npm-spec> ponownie używa śledzonej specyfikacji pluginu, chyba że przekażesz nową specyfikację. Zbiorcze openclaw plugins update --all używa skonfigurowanego update.channel, gdy synchronizuje zaufane oficjalne rekordy pluginów z celem oficjalnego katalogu, dzięki czemu instalacje z kanału beta mogą pozostać na linii wydań beta zamiast zostać po cichu znormalizowane do stable/latest.
openclaw update zna także aktywny kanał aktualizacji OpenClaw: na kanale beta rekordy pluginów npm z domyślnej linii oraz ClawHub najpierw próbują @beta. Wracają do zapisanej specyfikacji default/latest, jeśli wydanie beta pluginu nie istnieje; pluginy npm wracają także wtedy, gdy pakiet beta istnieje, ale nie przechodzi walidacji instalacji. Ten fallback jest zgłaszany jako ostrzeżenie i nie powoduje niepowodzenia aktualizacji core. Dokładne wersje i jawne tagi pozostają przypięte do tego selektora dla aktualizacji celowanych.
Version checks and integrity drift
Przed aktualizacją npm na żywo OpenClaw sprawdza zainstalowaną wersję pakietu względem metadanych rejestru npm. Jeśli zainstalowana wersja i zapisana tożsamość artefaktu już odpowiadają rozwiązanemu celowi, aktualizacja jest pomijana bez pobierania, ponownej instalacji ani przepisywania openclaw.json.
Gdy istnieje zapisany skrót integralności, a skrót pobranego artefaktu się zmienia, OpenClaw traktuje to jako dryf artefaktu npm. Interaktywne polecenie openclaw plugins update wypisuje oczekiwany i rzeczywisty skrót oraz prosi o potwierdzenie przed kontynuacją. Nieinteraktywne pomocniki aktualizacji stosują fail-closed, chyba że wywołujący poda jawną politykę kontynuacji.
--dangerously-force-unsafe-install on update
--dangerously-force-unsafe-install jest również akceptowane w plugins update dla zgodności, ale jest przestarzałe i nie zmienia już zachowania aktualizacji pluginów. Operator security.installPolicy nadal może blokować aktualizacje; hooki pluginów before_install mają zastosowanie tylko w procesach, w których hooki pluginów są załadowane.
--acknowledge-clawhub-risk on update
Aktualizacje pluginów społecznościowych opartych na ClawHub wykonują tę samą kontrolę zaufania dokładnego wydania co instalacje przed pobraniem pakietu zastępczego. Użyj --acknowledge-clawhub-risk dla sprawdzonej automatyzacji, która powinna kontynuować, gdy wybrane wydanie ClawHub ma ryzykowne ostrzeżenie dotyczące zaufania. Oficjalne pakiety ClawHub i dołączone źródła pluginów OpenClaw omijają ten monit zaufania wydania.
Inspekcja
openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --jsonInspekcja pokazuje tożsamość, status ładowania, źródło, możliwości manifestu, flagi polityki, diagnostykę, metadane instalacji, możliwości pakietu oraz wszelkie wykryte wsparcie serwerów MCP lub LSP bez domyślnego importowania runtime pluginu. Wyjście JSON obejmuje kontrakty manifestu pluginu, takie jak contracts.agentToolResultMiddleware i contracts.trustedToolPolicies, aby operatorzy mogli audytować deklaracje zaufanej powierzchni przed włączeniem lub ponownym uruchomieniem pluginu. Dodaj --runtime, aby załadować moduł pluginu i uwzględnić zarejestrowane hooki, narzędzia, polecenia, usługi, metody Gateway oraz trasy HTTP. Inspekcja runtime zgłasza brakujące zależności pluginu bezpośrednio; instalacje i naprawy pozostają w openclaw plugins install, openclaw plugins update i openclaw doctor --fix.
Polecenia CLI należące do pluginów są zwykle instalowane jako główne grupy poleceń openclaw, ale pluginy mogą także rejestrować polecenia zagnieżdżone pod nadrzędnym poleceniem core, takim jak openclaw nodes. Gdy inspect --runtime pokaże polecenie pod cliCommands, uruchom je pod wymienioną ścieżką; na przykład plugin rejestrujący demo-git można zweryfikować za pomocą openclaw demo-git ping.
Każdy plugin jest klasyfikowany według tego, co faktycznie rejestruje w runtime:
- plain-capability — jeden typ możliwości (np. plugin wyłącznie dostawcy)
- hybrid-capability — wiele typów możliwości (np. tekst + mowa + obrazy)
- hook-only — tylko hooki, bez możliwości ani powierzchni
- non-capability — narzędzia/polecenia/usługi, ale bez możliwości
Zobacz Kształty pluginów, aby dowiedzieć się więcej o modelu możliwości.
Doctor
openclaw plugins doctordoctor zgłasza błędy ładowania pluginów, diagnostykę manifestu/odkrywania, powiadomienia o zgodności oraz przestarzałe odwołania w konfiguracji pluginów, takie jak brakujące sloty pluginów. Gdy drzewo instalacji i konfiguracja pluginów są czyste, wypisuje No plugin issues detected. Jeśli przestarzała konfiguracja pozostaje, ale drzewo instalacji jest poza tym zdrowe, podsumowanie informuje o tym zamiast sugerować pełne zdrowie pluginów.
Jeśli skonfigurowany plugin jest obecny na dysku, ale blokowany przez kontrole bezpieczeństwa ścieżki loadera, walidacja konfiguracji zachowuje wpis pluginu i zgłasza go jako present but blocked. Napraw poprzedzającą diagnostykę zablokowanego pluginu, taką jak własność ścieżki lub uprawnienia zapisu dla wszystkich, zamiast usuwać konfigurację plugins.entries.<id> albo plugins.allow.
W przypadku błędów kształtu modułu, takich jak brak eksportów register/activate, uruchom ponownie z OPENCLAW_PLUGIN_LOAD_DEBUG=1, aby uwzględnić zwięzłe podsumowanie kształtu eksportów w wyjściu diagnostycznym.
Rejestr
openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins registry --jsonLokalny rejestr pluginów to utrwalony zimny model odczytu OpenClaw dla tożsamości zainstalowanych pluginów, ich włączenia, metadanych źródła i własności kontrybucji. Zwykłe uruchamianie, wyszukiwanie właściciela dostawcy, klasyfikacja konfiguracji kanału i inwentarz pluginów mogą go odczytywać bez importowania modułów runtime pluginów.
Użyj plugins registry, aby sprawdzić, czy utrwalony rejestr jest obecny, aktualny lub przestarzały. Użyj --refresh, aby przebudować go z utrwalonego indeksu pluginów, polityki konfiguracji oraz metadanych manifestu/pakietu. To jest ścieżka naprawy, a nie ścieżka aktywacji runtime.
openclaw doctor --fix naprawia także powiązany z rejestrem dryf zarządzanego npm: jeśli osierocony lub odzyskany pakiet @openclaw/* w zarządzanym projekcie npm pluginu albo starszy płaski zarządzany katalog główny npm przysłania dołączony plugin, doctor usuwa ten przestarzały pakiet i przebudowuje rejestr, aby uruchamianie walidowało względem dołączonego manifestu. Doctor ponownie linkuje także pakiet hosta openclaw do zarządzanych pluginów npm, które deklarują peerDependencies.openclaw, dzięki czemu lokalne dla pakietu importy runtime, takie jak openclaw/plugin-sdk/*, rozwiązują się po aktualizacjach lub naprawach npm.
Marketplace
openclaw plugins marketplace entriesopenclaw plugins marketplace entries --offlineopenclaw plugins marketplace entries --jsonopenclaw plugins marketplace entries --feed-profile <name>openclaw plugins marketplace entries --feed-url <url>openclaw plugins marketplace list <source>openclaw plugins marketplace list <source> --jsonopenclaw plugins marketplace refreshopenclaw plugins marketplace refresh --feed-profile <name>openclaw plugins marketplace refresh --feed-url <url>openclaw plugins marketplace refresh --expected-sha256 <sha256> --jsonplugins marketplace entries wyświetla wpisy ze skonfigurowanego kanału marketplace OpenClaw. Domyślnie próbuje użyć hostowanego kanału i wraca do najnowszej zaakceptowanej migawki albo danych dołączonych do pakietu. Użyj --feed-profile <name>, aby odczytać konkretny skonfigurowany profil, --feed-url <url>, aby odczytać jawny URL hostowanego kanału, oraz --offline, aby odczytać najnowszą zaakceptowaną migawkę bez pobierania kanału.
plugins marketplace refresh odświeża skonfigurowaną migawkę hostowanego kanału i zgłasza, czy OpenClaw zaakceptował dane hostowane, hostowaną migawkę, czy dane awaryjne dołączone do pakietu. Użyj --expected-sha256, gdy wywołujący potrzebuje, aby polecenie zakończyło się niepowodzeniem, chyba że świeży hostowany ładunek będzie zgodny z przypiętą sumą kontrolną.
Marketplace list akceptuje lokalną ścieżkę marketplace, ścieżkę marketplace.json, skrót GitHub w rodzaju owner/repo, URL repozytorium GitHub albo URL git. --json wypisuje rozpoznaną etykietę źródła oraz przeanalizowany manifest marketplace i wpisy Pluginów.
Odświeżanie marketplace wczytuje hostowany kanał marketplace OpenClaw i zapisuje
zweryfikowaną odpowiedź jako lokalną migawkę hostowanego kanału. Bez opcji używa
skonfigurowanego domyślnego profilu kanału. Użyj --feed-profile <name>, aby odświeżyć
konkretny skonfigurowany profil, --feed-url <url>, aby odświeżyć jawny URL hostowanego
kanału, --expected-sha256 <sha256>, aby wymagać zgodnej sumy kontrolnej ładunku
(sha256:<hex> albo sam 64-znakowy skrót szesnastkowy), oraz --json dla
wyniku czytelnego maszynowo. Jawne URL-e hostowanych kanałów nie mogą zawierać
danych uwierzytelniających, ciągów zapytania ani fragmentów. Odświeżenia bez przypięcia mogą zgłosić
wynik hostowanej migawki albo dołączonego fallbacku bez niepowodzenia polecenia. Odświeżenia
z przypięciem kończą się niepowodzeniem, chyba że zaakceptują świeży hostowany ładunek, a udane hostowane
odświeżenia kończą się niepowodzeniem, jeśli OpenClaw nie może zapisać zweryfikowanej migawki.
