Pluginy

Pluginy rozszerzają OmeniaClaw o nowe możliwości: kanały, dostawców modeli, środowiska agentów, narzędzia, Skills, mowę, transkrypcję w czasie rzeczywistym, głos w czasie rzeczywistym, rozumienie mediów, generowanie obrazów, generowanie wideo, pobieranie z sieci, wyszukiwanie w sieci i nie tylko. Niektóre pluginy są core (dostarczane z OmeniaClaw), inne są zewnętrzne. Większość zewnętrznych pluginów jest publikowana i odkrywana przez ClawHub. Npm pozostaje obsługiwane do bezpośrednich instalacji oraz dla tymczasowego zestawu pakietów pluginów należących do OmeniaClaw, dopóki ta migracja się nie zakończy.

Szybki start

Przykłady instalacji, wyświetlania listy, odinstalowywania, aktualizacji i publikowania do skopiowania znajdziesz w Zarządzanie pluginami.

OmeniaClaw plugins list

# Search ClawHub pluginsOmeniaClaw plugins search "calendar" # From ClawHubOmeniaClaw plugins install clawhub:OmeniaClaw-codex-app-server # From npmOmeniaClaw plugins install npm:@acme/OmeniaClaw-pluginOmeniaClaw plugins install npm-pack:./OmeniaClaw-plugin-1.2.3.tgz # From gitOmeniaClaw plugins install git:github.com/acme/[email protected] # From a local directory or archiveOmeniaClaw plugins install ./my-pluginOmeniaClaw plugins install ./my-plugin.tgz

OmeniaClaw gateway restart

OmeniaClaw plugins inspect <plugin-id> --runtime --json # If the plugin registered a CLI root, run one command from that root.OmeniaClaw <plugin-command> --help

Jeśli wolisz sterowanie natywne dla czatu, włącz commands.plugins: true i użyj:

/plugin install clawhub:<package>/plugin show <plugin-id>/plugin enable <plugin-id>

Ścieżka instalacji używa tego samego resolvera co CLI: lokalna ścieżka/archiwum, jawne clawhub:<pkg>, jawne npm:<pkg>, jawne npm-pack:<path.tgz>, jawne git:<repo> albo zwykła specyfikacja pakietu przez npm.

Jeśli konfiguracja jest nieprawidłowa, instalacja zwykle kończy się w trybie fail-closed i wskazuje OmeniaClaw doctor --fix. Jedynym wyjątkiem odzyskiwania jest wąska ścieżka ponownej instalacji bundlowanego pluginu dla pluginów, które włączają OmeniaClaw.install.allowInvalidConfigRecovery. Podczas uruchamiania Gateway nieprawidłowa konfiguracja pluginu kończy się w trybie fail-closed jak każda inna nieprawidłowa konfiguracja. Uruchom OmeniaClaw doctor --fix, aby poddać kwarantannie błędną konfigurację pluginu przez wyłączenie tego wpisu pluginu i usunięcie jego nieprawidłowego ładunku konfiguracji; zwykła kopia zapasowa konfiguracji zachowuje poprzednie wartości. Gdy konfiguracja kanału odwołuje się do pluginu, którego nie da się już odkryć, ale ten sam nieaktualny identyfikator pluginu pozostaje w konfiguracji pluginu lub rekordach instalacji, uruchamianie Gateway zapisuje ostrzeżenia i pomija ten kanał zamiast blokować każdy inny kanał. Uruchom OmeniaClaw doctor --fix, aby usunąć nieaktualne wpisy kanału/pluginu; nieznane klucze kanałów bez dowodów na nieaktualny plugin nadal nie przechodzą walidacji, aby literówki pozostały widoczne. Jeśli ustawiono plugins.enabled: false, nieaktualne odwołania do pluginów są traktowane jako bezczynne: uruchamianie Gateway pomija odkrywanie/ładowanie pluginów, a OmeniaClaw doctor zachowuje wyłączoną konfigurację pluginów zamiast usuwać ją automatycznie. Włącz ponownie pluginy przed uruchomieniem czyszczenia przez doctor, jeśli chcesz usunąć nieaktualne identyfikatory pluginów.

Instalacja zależności pluginów odbywa się tylko podczas jawnych przepływów instalacji/aktualizacji lub naprawy przez doctor. Uruchamianie Gateway, przeładowanie konfiguracji i inspekcja środowiska uruchomieniowego nie uruchamiają menedżerów pakietów ani nie naprawiają drzew zależności. Lokalne pluginy muszą już mieć zainstalowane swoje zależności, natomiast pluginy npm, git i ClawHub są instalowane w zarządzanych katalogach głównych pluginów OmeniaClaw. Zależności npm mogą być hoistowane w zarządzanym katalogu głównym npm OmeniaClaw; instalacja/aktualizacja skanuje ten zarządzany katalog główny przed zaufaniem, a odinstalowanie usuwa pakiety zarządzane przez npm przez npm. Zewnętrzne pluginy i niestandardowe ścieżki ładowania nadal muszą być instalowane przez OmeniaClaw plugins install. Użyj OmeniaClaw plugins list --json, aby zobaczyć statyczny dependencyStatus dla każdego widocznego pluginu bez importowania kodu uruchomieniowego ani naprawiania zależności. Zobacz Rozwiązywanie zależności pluginów, aby poznać cykl życia w czasie instalacji.

Zablokowana własność ścieżki pluginu

Jeśli diagnostyka pluginu mówi blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) a walidacja konfiguracji następuje z plugin present but blocked, OmeniaClaw znalazł pliki pluginu należące do innego użytkownika Unix niż proces, który je ładuje. Pozostaw konfigurację pluginu na miejscu; napraw własność w systemie plików albo uruchom OmeniaClaw jako ten sam użytkownik, do którego należy katalog stanu.

W przypadku instalacji Docker oficjalny obraz działa jako node (uid 1000), więc hostowe katalogi konfiguracji i przestrzeni roboczej OmeniaClaw montowane przez bind powinny zwykle należeć do uid 1000:

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

Jeśli celowo uruchamiasz OmeniaClaw jako root, napraw zarządzany katalog główny pluginów tak, aby należał do root:

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

Po naprawieniu własności uruchom ponownie OmeniaClaw doctor --fix albo OmeniaClaw plugins registry --refresh, aby utrwalony rejestr pluginów odpowiadał naprawionym plikom.

W przypadku instalacji npm zmienne selektory, takie jak latest lub dist-tag, są rozwiązywane przed instalacją, a potem przypinane do dokładnej zweryfikowanej wersji w zarządzanym katalogu głównym npm OmeniaClaw. Po zakończeniu działania npm OmeniaClaw weryfikuje, czy zainstalowany wpis package-lock.json nadal pasuje do rozwiązanej wersji i integralności. Jeśli npm zapisze inne metadane pakietu, instalacja kończy się niepowodzeniem, a zarządzany pakiet jest wycofywany zamiast zaakceptować inny artefakt pluginu. Zarządzane katalogi główne npm dziedziczą także pakietowe overrides npm OmeniaClaw, więc przypięcia bezpieczeństwa chroniące spakowanego hosta mają też zastosowanie do hoistowanych zewnętrznych zależności pluginów.

Checkouty źródłowe są obszarami roboczymi pnpm. Jeśli klonujesz OmeniaClaw, aby pracować nad bundlowanymi pluginami, uruchom pnpm install; OmeniaClaw ładuje wtedy bundlowane pluginy z extensions/<id>, więc edycje i zależności lokalne dla pakietu są używane bezpośrednio. Zwykłe instalacje główne npm są przeznaczone dla spakowanego OmeniaClaw, a nie dla rozwoju z checkoutu źródłowego.

Typy pluginów

OmeniaClaw rozpoznaje dwa formaty pluginów:

Oba pojawiają się w OmeniaClaw plugins list. Szczegóły dotyczące bundle znajdziesz w Bundle pluginów.

Jeśli piszesz natywny plugin, zacznij od Budowania pluginów i Przeglądu Plugin SDK.

Punkty wejścia pakietu

Natywne pakiety npm pluginów muszą deklarować OmeniaClaw.extensions w package.json. Każdy wpis musi pozostać w katalogu pakietu i rozwiązywać się do czytelnego pliku uruchomieniowego albo do pliku źródłowego TypeScript z wywnioskowanym zbudowanym odpowiednikiem JavaScript, takim jak src/index.ts do dist/index.js. Spakowane instalacje muszą dostarczać ten wynik uruchomieniowy JavaScript. Awaryjne użycie źródła TypeScript jest przeznaczone dla checkoutów źródłowych i lokalnych ścieżek deweloperskich, a nie dla pakietów npm instalowanych w zarządzanym katalogu głównym pluginów OmeniaClaw.

Nieśledzone katalogi umieszczone w globalnym katalogu głównym rozszerzeń są traktowane jako lokalne checkouty źródłowe i mogą bezpośrednio ładować wpisy TypeScript. Katalogi nadal wskazane przez rekord instalacji, w tym installPath lub sourcePath, pozostają zarządzane i utrzymują wymóg skompilowanego wyjścia nawet wtedy, gdy globalne skanowanie je widzi. Jeśli celowo konwertujesz zarządzaną instalację w nieśledzony lokalny checkout, najpierw usuń nieaktualny rekord instalacji przez odinstalowanie lub czyszczenie doctor.

Jeśli ostrzeżenie zarządzanego pakietu mówi, że requires compiled runtime output for TypeScript entry ..., pakiet został opublikowany bez plików JavaScript, których OmeniaClaw potrzebuje w czasie uruchomienia. To problem pakowania pluginu, a nie lokalnej konfiguracji. Zaktualizuj albo zainstaluj ponownie plugin po ponownym opublikowaniu skompilowanego JavaScript przez wydawcę albo wyłącz/odinstaluj ten plugin, dopóki poprawiony pakiet nie będzie dostępny.

Użyj OmeniaClaw.runtimeExtensions, gdy opublikowane pliki uruchomieniowe nie znajdują się w tych samych ścieżkach co wpisy źródłowe. Gdy runtimeExtensions jest obecne, musi zawierać dokładnie jeden wpis dla każdego wpisu extensions. Niedopasowane listy powodują niepowodzenie instalacji i odkrywania pluginów zamiast cichego powrotu do ścieżek źródłowych. Jeśli publikujesz też OmeniaClaw.setupEntry, użyj OmeniaClaw.runtimeSetupEntry dla jego zbudowanego odpowiednika JavaScript; ten plik jest wymagany, gdy został zadeklarowany.

{  "name": "@acme/OmeniaClaw-plugin",  "OmeniaClaw": {    "extensions": ["./src/index.ts"],    "runtimeExtensions": ["./dist/index.js"]  }}

Oficjalne pluginy

Pakiety npm należące do OmeniaClaw podczas migracji

ClawHub jest główną ścieżką dystrybucji dla większości pluginów. Obecne spakowane wydania OmeniaClaw już zawierają wiele oficjalnych pluginów, więc zwykle nie wymagają one oddzielnych instalacji npm w standardowych konfiguracjach. Dopóki każdy plugin należący do OmeniaClaw nie zmigruje do ClawHub, OmeniaClaw nadal publikuje niektóre pakiety pluginów @OmeniaClaw/* w npm dla starszych/niestandardowych instalacji i bezpośrednich przepływów npm.

Jeśli npm zgłasza pakiet pluginu @OmeniaClaw/* jako przestarzały, ta wersja pakietu pochodzi ze starszej zewnętrznej serii pakietów. Użyj bundlowanego pluginu z obecnego OmeniaClaw albo lokalnego checkoutu, dopóki nowszy pakiet npm nie zostanie opublikowany.

Core (dostarczane z OmeniaClaw)

Szukasz pluginów innych firm? Zobacz ClawHub.

Konfiguracja

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

plugins.allow jest wyłączne. Gdy nie jest puste, tylko wymienione pluginy mogą być ładowane lub udostępniać narzędzia, nawet jeśli tools.allow zawiera "*" albo konkretną nazwę narzędzia należącego do pluginu. Jeśli lista dozwolonych narzędzi odwołuje się do narzędzi pluginu, dodaj identyfikatory właścicielskich pluginów do plugins.allow albo usuń plugins.allow; OmeniaClaw doctor ostrzega o takim kształcie konfiguracji.

plugins.bundledDiscovery domyślnie ma wartość "allowlist" dla nowych konfiguracji, więc restrykcyjna lista plugins.allow blokuje też pominięte wbudowane pluginy dostawców, w tym wykrywanie dostawcy wyszukiwania w sieci w czasie działania. Doctor oznacza starsze restrykcyjne konfiguracje listy dozwolonych wartością "compat" podczas migracji, aby aktualizacje zachowały starsze zachowanie wbudowanych dostawców, dopóki operator nie wybierze bardziej restrykcyjnego trybu. Puste plugins.allow nadal jest traktowane jako nieustawione/otwarte.

Zmiany konfiguracji wykonane przez /plugins enable lub /plugins disable wyzwalają przeładowanie pluginów Gateway w ramach tego samego procesu. Nowe tury agenta odbudowują listę narzędzi z odświeżonego rejestru pluginów. Operacje zmieniające źródła, takie jak instalacja, aktualizacja i odinstalowanie, nadal restartują proces Gateway, ponieważ już zaimportowanych modułów pluginów nie da się bezpiecznie zastąpić w miejscu.

OmeniaClaw plugins list to lokalna migawka rejestru/konfiguracji pluginów. Plugin enabled oznacza tam, że utrwalony rejestr i bieżąca konfiguracja pozwalają pluginowi uczestniczyć. Nie dowodzi to, że już działający zdalny Gateway przeładował się lub zrestartował z tym samym kodem pluginu. W konfiguracjach VPS/kontenerowych z procesami opakowującymi wysyłaj restarty lub zapisy wyzwalające przeładowanie do właściwego procesu OmeniaClaw gateway run albo użyj OmeniaClaw gateway restart wobec działającego Gateway, gdy przeładowanie zgłosi błąd.

Wykrywanie i kolejność pierwszeństwa

OmeniaClaw skanuje pluginy w tej kolejności (pierwsze dopasowanie wygrywa):

Instalacje pakietowe i obrazy Docker zwykle rozwiązują wbudowane pluginy z skompilowanego drzewa dist/extensions. Jeśli katalog źródłowy wbudowanego pluginu jest zamontowany przez bind mount nad odpowiadającą mu spakowaną ścieżką źródłową, na przykład /app/extensions/synology-chat, OmeniaClaw traktuje ten zamontowany katalog źródłowy jako nakładkę źródłową wbudowanego pluginu i wykrywa go przed spakowanym pakietem /app/dist/extensions/synology-chat. Dzięki temu pętle kontenerowe maintainerów działają bez przełączania każdego wbudowanego pluginu z powrotem na źródła TypeScript. Ustaw OmeniaClaw_DISABLE_BUNDLED_SOURCE_OVERLAYS=1, aby wymusić spakowane pakiety dist nawet wtedy, gdy obecne są montowania nakładek źródłowych.

Reguły włączania

• plugins.enabled: false wyłącza wszystkie pluginy i pomija wykrywanie/ładowanie pluginów
• plugins.deny zawsze ma pierwszeństwo przed listą dozwolonych
• plugins.entries.\<id\>.enabled: false wyłącza ten plugin
• Pluginy pochodzące z obszaru roboczego są domyślnie wyłączone (muszą być jawnie włączone)
• Wbudowane pluginy korzystają z wbudowanego zestawu domyślnie włączonych, chyba że zostanie to nadpisane
• Wyłączne sloty mogą wymusić włączenie wybranego pluginu dla danego slotu
• Niektóre wbudowane pluginy opcjonalne są włączane automatycznie, gdy konfiguracja nazywa powierzchnię należącą do pluginu, taką jak referencja modelu dostawcy, konfiguracja kanału lub środowisko uruchomieniowe harness
• Nieaktualna konfiguracja pluginu jest zachowywana, gdy plugins.enabled: false jest aktywne; włącz ponownie pluginy przed uruchomieniem czyszczenia przez doctor, jeśli chcesz usunąć nieaktualne identyfikatory
• Trasy OpenAI-family Codex zachowują oddzielne granice pluginów: openai-codex/* należy do pluginu OpenAI, natomiast wbudowany plugin serwera aplikacji Codex jest wybierany przez kanoniczne referencje agenta openai/*, jawne agentRuntime.id: "codex" dostawcy/modelu albo starsze referencje modeli codex/*

Rozwiązywanie problemów z hookami środowiska uruchomieniowego

Jeśli plugin pojawia się w plugins list, ale efekty uboczne register(api) lub hooki nie uruchamiają się w ruchu czatu na żywo, sprawdź najpierw te elementy:

• Uruchom OmeniaClaw gateway status --deep --require-rpc i potwierdź, że aktywny URL Gateway, profil, ścieżka konfiguracji i proces są tymi, które edytujesz.
• Zrestartuj działający Gateway po zmianach instalacji/konfiguracji/kodu pluginu. W kontenerach opakowujących PID 1 może być tylko nadzorcą; zrestartuj albo zasygnalizuj proces potomny OmeniaClaw gateway run.
• Użyj OmeniaClaw plugins inspect <id> --runtime --json, aby potwierdzić rejestracje hooków i diagnostykę. Niewbudowane hooki konwersacji, takie jak before_model_resolve, before_agent_reply, before_agent_run, llm_input, llm_output, before_agent_finalize i agent_end, wymagają plugins.entries.<id>.hooks.allowConversationAccess=true.
• Do przełączania modeli preferuj before_model_resolve. Uruchamia się przed rozwiązywaniem modelu dla tur agenta; llm_output uruchamia się dopiero po tym, jak próba modelu wygeneruje odpowiedź asystenta.
• Aby udowodnić skuteczny model sesji, użyj OmeniaClaw sessions albo powierzchni sesji/statusu Gateway, a podczas debugowania ładunków dostawcy uruchom Gateway z --raw-stream --raw-stream-path <path>.

Powolne przygotowywanie narzędzi pluginu

Jeśli tury agenta wyglądają na zablokowane podczas przygotowywania narzędzi, włącz logowanie trace i sprawdź wiersze czasu fabryk narzędzi pluginów:

OmeniaClaw config set logging.level traceOmeniaClaw logs --follow

Szukaj:

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

Podsumowanie wyświetla łączny czas fabryk i najwolniejsze fabryki narzędzi pluginów, w tym identyfikator pluginu, zadeklarowane nazwy narzędzi, kształt wyniku oraz to, czy narzędzie jest opcjonalne. Wolne wiersze są promowane do ostrzeżeń, gdy pojedyncza fabryka trwa co najmniej 1 s albo łączne przygotowanie fabryk narzędzi pluginów trwa co najmniej 5 s.

OmeniaClaw buforuje pomyślne wyniki fabryk narzędzi pluginów dla powtarzanych rozwiązań z tym samym skutecznym kontekstem żądania. Klucz cache obejmuje skuteczną konfigurację środowiska uruchomieniowego, obszar roboczy, identyfikatory agenta/sesji, politykę sandboxa, ustawienia przeglądarki, kontekst dostarczania, tożsamość żądającego i stan własności, więc fabryki zależne od tych zaufanych pól są uruchamiane ponownie, gdy kontekst się zmienia.

Jeśli jeden plugin dominuje w czasie, sprawdź jego rejestracje środowiska uruchomieniowego:

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

Następnie zaktualizuj, zainstaluj ponownie albo wyłącz ten plugin. Autorzy pluginów powinni przenieść kosztowne ładowanie zależności za ścieżkę wykonywania narzędzia, zamiast robić to wewnątrz fabryki narzędzia.

Zduplikowana własność kanału lub narzędzia

Objawy:

• channel already registered: <channel-id> (<plugin-id>)
• channel setup already registered: <channel-id> (<plugin-id>)
• plugin tool name conflict (<plugin-id>): <tool-name>

Oznaczają one, że więcej niż jeden włączony plugin próbuje posiadać ten sam kanał, przepływ konfiguracji lub nazwę narzędzia. Najczęstszą przyczyną jest zewnętrzny plugin kanału zainstalowany obok wbudowanego pluginu, który teraz udostępnia ten sam identyfikator kanału.

Kroki debugowania:

• Uruchom OmeniaClaw plugins list --enabled --verbose, aby zobaczyć każdy włączony plugin i jego pochodzenie.
• Uruchom OmeniaClaw plugins inspect <id> --runtime --json dla każdego podejrzanego pluginu i porównaj channels, channelConfigs, tools oraz diagnostykę.
• Uruchom OmeniaClaw plugins registry --refresh po zainstalowaniu lub usunięciu pakietów pluginów, aby utrwalone metadane odzwierciedlały bieżącą instalację.
• Zrestartuj Gateway po zmianach instalacji, rejestru lub konfiguracji.

Opcje naprawy:

• Jeśli jeden plugin celowo zastępuje inny dla tego samego identyfikatora kanału, preferowany plugin powinien zadeklarować channelConfigs.<channel-id>.preferOver z identyfikatorem pluginu o niższym priorytecie. Zobacz /plugins/manifest#replacing-another-channel-plugin.
• Jeśli duplikat jest przypadkowy, wyłącz jedną stronę za pomocą plugins.entries.<plugin-id>.enabled: false albo usuń nieaktualną instalację pluginu.
• Jeśli jawnie włączono oba pluginy, OmeniaClaw zachowuje to żądanie i zgłasza konflikt. Wybierz jednego właściciela kanału albo zmień nazwy narzędzi należących do pluginu, aby powierzchnia środowiska uruchomieniowego była jednoznaczna.

Sloty pluginów (kategorie wyłączne)

Niektóre kategorie są wyłączne (aktywny może być tylko jeden naraz):

{  plugins: {    slots: {      memory: "memory-core", // or "none" to disable      contextEngine: "legacy", // or a plugin id    },  },}

Referencja CLI

OmeniaClaw plugins list                       # compact inventoryOmeniaClaw plugins list --enabled            # only enabled pluginsOmeniaClaw plugins list --verbose            # per-plugin detail linesOmeniaClaw plugins list --json               # machine-readable inventoryOmeniaClaw plugins search <query>            # search ClawHub plugin catalogOmeniaClaw plugins inspect <id>              # static detailOmeniaClaw plugins inspect <id> --runtime    # registered hooks/tools/CLI/gateway methodsOmeniaClaw plugins inspect <id> --json       # machine-readableOmeniaClaw plugins inspect --all             # fleet-wide tableOmeniaClaw plugins info <id>                 # inspect aliasOmeniaClaw plugins doctor                    # diagnosticsOmeniaClaw plugins registry                  # inspect persisted registry stateOmeniaClaw plugins registry --refresh        # rebuild persisted registryOmeniaClaw doctor --fix                      # repair plugin registry state OmeniaClaw plugins install <package>         # install from npm by defaultOmeniaClaw plugins install clawhub:<pkg>     # install from ClawHub onlyOmeniaClaw plugins install npm:<pkg>         # install from npm onlyOmeniaClaw plugins install git:<repo>        # install from gitOmeniaClaw plugins install git:<repo>@<ref>  # install from git refOmeniaClaw plugins install <spec> --force    # overwrite existing installOmeniaClaw plugins install <path>            # install from local pathOmeniaClaw plugins install -l <path>         # link (no copy) for devOmeniaClaw plugins install <plugin> --marketplace <source>OmeniaClaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>OmeniaClaw plugins install <spec> --pin      # record exact resolved npm specOmeniaClaw plugins install <spec> --dangerously-force-unsafe-installOmeniaClaw plugins update <id-or-npm-spec> # update one pluginOmeniaClaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-installOmeniaClaw plugins update --all            # update allOmeniaClaw plugins uninstall <id>          # remove config and plugin index recordsOmeniaClaw plugins uninstall <id> --keep-filesOmeniaClaw plugins marketplace list <source>OmeniaClaw plugins marketplace list <source> --json # Verify runtime registrations after install.OmeniaClaw plugins inspect <id> --runtime --json # Run plugin-owned CLI commands directly from the OmeniaClaw root CLI.OmeniaClaw <plugin-command> --help OmeniaClaw plugins enable <id>OmeniaClaw plugins disable <id>

Dołączone pluginy są dostarczane z OmeniaClaw. Wiele z nich jest domyślnie włączonych (na przykład dołączone dostawcy modeli, dołączeni dostawcy mowy oraz dołączony plugin przeglądarki). Inne dołączone pluginy nadal wymagają OmeniaClaw plugins enable <id>.

--force nadpisuje istniejący zainstalowany plugin lub pakiet hooków w miejscu. Użyj OmeniaClaw plugins update <id-or-npm-spec> do rutynowych aktualizacji śledzonych pluginów npm. Nie jest obsługiwane z --link, który ponownie używa ścieżki źródłowej zamiast kopiować do zarządzanego miejsca instalacji.

Gdy plugins.allow jest już ustawione, OmeniaClaw plugins install dodaje identyfikator zainstalowanego pluginu do tej listy dozwolonych przed jego włączeniem. Jeśli ten sam identyfikator pluginu znajduje się w plugins.deny, instalacja usuwa ten nieaktualny wpis odmowy, dzięki czemu jawna instalacja jest od razu możliwa do załadowania po ponownym uruchomieniu.

OmeniaClaw przechowuje utrwalony lokalny rejestr pluginów jako model odczytu na zimno dla inwentarza pluginów, własności wkładów i planowania uruchomienia. Przepływy instalowania, aktualizowania, odinstalowywania, włączania i wyłączania odświeżają ten rejestr po zmianie stanu pluginów. Ten sam plik plugins/installs.json przechowuje trwałe metadane instalacji w najwyższego poziomu installRecords oraz odtwarzalne metadane manifestu w plugins. Jeśli brakuje rejestru, jest on nieaktualny lub nieprawidłowy, OmeniaClaw plugins registry --refresh odbudowuje jego widok manifestu na podstawie rekordów instalacji, polityki konfiguracji oraz metadanych manifestu/pakietu bez ładowania modułów runtime pluginów.

W trybie Nix (OmeniaClaw_NIX_MODE=1) mutatory cyklu życia pluginów są wyłączone. Zarządzaj wyborem pakietów pluginów i konfiguracją przez źródło Nix dla instalacji; w przypadku nix-OmeniaClaw zacznij od agent-first Quick Start. OmeniaClaw plugins update <id-or-npm-spec> stosuje się do śledzonych instalacji. Przekazanie specyfikacji pakietu npm z dist-tag albo dokładną wersją rozwiązuje nazwę pakietu z powrotem do śledzonego rekordu pluginu i zapisuje nową specyfikację na potrzeby przyszłych aktualizacji. Przekazanie nazwy pakietu bez wersji przenosi dokładnie przypiętą instalację z powrotem do domyślnej linii wydań rejestru. Jeśli zainstalowany plugin npm już pasuje do rozwiązanej wersji i zapisanej tożsamości artefaktu, OmeniaClaw pomija aktualizację bez pobierania, ponownej instalacji ani przepisywania konfiguracji. Gdy OmeniaClaw update działa na kanale beta, rekordy pluginów npm i ClawHub z linii domyślnej próbują najpierw @beta, a następnie wracają do default/latest, gdy nie istnieje wydanie beta pluginu. Dokładne wersje i jawne tagi pozostają przypięte.

--pin dotyczy wyłącznie npm. Nie jest obsługiwane z --marketplace, ponieważ instalacje z marketplace utrwalają metadane źródła marketplace zamiast specyfikacji npm.

--dangerously-force-unsafe-install to awaryjne obejście dla fałszywych alarmów wbudowanego skanera niebezpiecznego kodu. Pozwala kontynuować instalacje pluginów i aktualizacje pluginów mimo wbudowanych ustaleń critical, ale nadal nie omija blokad polityki before_install pluginu ani blokowania po niepowodzeniu skanowania. Skanowanie instalacji ignoruje typowe pliki i katalogi testowe, takie jak tests/, __tests__/, *.test.* i *.spec.*, aby nie blokować spakowanych mocków testowych; zadeklarowane punkty wejścia runtime pluginu nadal są skanowane, nawet jeśli używają jednej z tych nazw.

Ta flaga CLI dotyczy tylko przepływów instalacji/aktualizacji pluginów. Instalacje zależności Skills wspierane przez Gateway używają zamiast tego odpowiadającego nadpisania żądania dangerouslyForceUnsafeInstall, podczas gdy OmeniaClaw skills install pozostaje oddzielnym przepływem pobierania/instalacji Skills z ClawHub.

Jeśli plugin opublikowany przez Ciebie w ClawHub jest ukryty albo zablokowany przez skanowanie, otwórz panel ClawHub albo uruchom clawhub package rescan <name>, aby poprosić ClawHub o ponowne sprawdzenie. --dangerously-force-unsafe-install wpływa tylko na instalacje na Twoim własnym komputerze; nie prosi ClawHub o ponowne przeskanowanie pluginu ani o upublicznienie zablokowanego wydania.

Zgodne pakiety uczestniczą w tym samym przepływie list/inspect/enable/disable pluginów. Obecna obsługa runtime obejmuje Skills z pakietów, command-skills Claude, domyślne ustawienia Claude settings.json, domyślne ustawienia Claude .lsp.json i zadeklarowane w manifeście lspServers, command-skills Cursor oraz zgodne katalogi hooków Codex.

OmeniaClaw plugins inspect <id> raportuje także wykryte możliwości pakietu oraz obsługiwane lub nieobsługiwane wpisy serwerów MCP i LSP dla pluginów opartych na pakietach.

Źródła marketplace mogą być znaną nazwą marketplace Claude z ~/.claude/plugins/known_marketplaces.json, lokalnym katalogiem głównym marketplace albo ścieżką marketplace.json, skrótem GitHub w stylu owner/repo, adresem URL repozytorium GitHub albo adresem URL git. W przypadku zdalnych marketplace wpisy pluginów muszą pozostać wewnątrz sklonowanego repozytorium marketplace i używać wyłącznie względnych źródeł ścieżek.

Pełne szczegóły znajdziesz w referencji CLI OmeniaClaw plugins.

Omówienie API Plugin

Natywne pluginy eksportują obiekt wejścia, który udostępnia register(api). Starsze pluginy mogą nadal używać activate(api) jako starszego aliasu, ale nowe pluginy powinny używać register.

export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  register(api) {    api.registerProvider({      /* ... */    });    api.registerTool({      /* ... */    });    api.registerChannel({      /* ... */    });  },});

OmeniaClaw ładuje obiekt wejścia i wywołuje register(api) podczas aktywacji pluginu. Loader nadal wraca do activate(api) dla starszych pluginów, ale dołączone pluginy i nowe pluginy zewnętrzne powinny traktować register jako publiczny kontrakt.

api.registrationMode informuje plugin, dlaczego jego wejście jest ładowane:

Wejścia pluginów, które otwierają gniazda, bazy danych, procesy robocze w tle albo długotrwałe klienty, powinny zabezpieczać te efekty uboczne warunkiem api.registrationMode === "full". Ładowania odkrywania są buforowane oddzielnie od ładowań aktywujących i nie zastępują działającego rejestru Gateway. Odkrywanie jest nieaktywujące, ale nie jest wolne od importów: OmeniaClaw może wykonać zaufane wejście pluginu albo moduł pluginu kanału, aby zbudować migawkę. Utrzymuj najwyższe poziomy modułów lekkie i bez efektów ubocznych, a klientów sieciowych, podprocesy, listenery, odczyty poświadczeń i uruchamianie usług przenieś za ścieżki pełnego runtime.

Typowe metody rejestracji:

Zachowanie strażników hooków dla typowanych hooków cyklu życia:

• before_tool_call: { block: true } jest końcowe; handlery o niższym priorytecie są pomijane.
• before_tool_call: { block: false } jest bez działania i nie usuwa wcześniejszej blokady.
• before_install: { block: true } jest końcowe; handlery o niższym priorytecie są pomijane.
• before_install: { block: false } jest bez działania i nie usuwa wcześniejszej blokady.
• message_sending: { cancel: true } jest końcowe; handlery o niższym priorytecie są pomijane.
• message_sending: { cancel: false } jest bez działania i nie usuwa wcześniejszego anulowania.

Natywny serwer aplikacji Codex przekazuje zdarzenia natywnych narzędzi Codex z powrotem do tej powierzchni haków. Pluginy mogą blokować natywne narzędzia Codex przez before_tool_call, obserwować wyniki przez after_tool_call i uczestniczyć w zatwierdzeniach PermissionRequest Codex. Most nie przepisuje jeszcze argumentów natywnych narzędzi Codex. Dokładna granica obsługi środowiska uruchomieniowego Codex znajduje się w dokumencie kontraktu obsługi Codex harness v1.

Pełne typowane zachowanie haków opisuje przegląd SDK.

Powiązane

• Budowanie pluginów - utwórz własny plugin
• Pakiety pluginów - zgodność pakietów Codex/Claude/Cursor
• Manifest pluginu - schemat manifestu
• Rejestrowanie narzędzi - dodaj narzędzia agenta w pluginie
• Wewnętrzne działanie pluginów - model możliwości i potok ładowania
• ClawHub - odkrywanie pluginów innych firm