Wewnętrzne mechanizmy Pluginu

To jest szczegółowa dokumentacja architektury systemu pluginów OpenClaw. Praktyczne informacje znajdziesz na jednej z poniższych stron tematycznych.

Publiczny model możliwości

Możliwości stanowią publiczny model natywnych pluginów w OpenClaw. Każdy natywny plugin OpenClaw rejestruje co najmniej jeden typ możliwości:

Podejście do zgodności zewnętrznej

Model możliwości został wdrożony w rdzeniu i jest obecnie używany przez dołączone i natywne pluginy, ale zgodność zewnętrznych pluginów wymaga bardziej rygorystycznego kryterium niż „jest eksportowany, więc jest niezmienny”.

Rejestracja możliwości jest docelowym kierunkiem. Starsze haki pozostają najbezpieczniejszą ścieżką bez ryzyka zakłóceń dla zewnętrznych pluginów w okresie przejściowym. Nie wszystkie eksportowane podścieżki pomocnicze są równoważne — preferuj wąskie, udokumentowane kontrakty zamiast przypadkowo eksportowanych funkcji pomocniczych.

Formy pluginów

OpenClaw klasyfikuje każdy załadowany plugin według formy na podstawie jego rzeczywistego zachowania podczas rejestracji, a nie tylko statycznych metadanych:

Użyj openclaw plugins inspect <id>, aby zobaczyć formę pluginu i zestawienie jego możliwości. Szczegółowe informacje zawiera dokumentacja CLI.

Starsze haki

Hak before_agent_start pozostaje obsługiwany jako ścieżka zgodności dla pluginów opartych wyłącznie na hakach. Nadal zależą od niego starsze pluginy używane w praktyce.

Kierunek rozwoju:

• utrzymanie jego działania
• udokumentowanie go jako starszego rozwiązania
• preferowanie before_model_resolve do nadpisywania modelu lub dostawcy
• preferowanie before_prompt_build do modyfikowania promptu
• usunięcie dopiero po spadku rzeczywistego użycia i potwierdzeniu bezpieczeństwa migracji przez testy z użyciem danych wzorcowych

Sygnały zgodności

Polecenia openclaw doctor, openclaw plugins inspect <id>, openclaw status --all oraz openclaw plugins doctor wyświetlają następujące powiadomienia dotyczące zgodności:

Żaden z sygnałów informacyjnych ani ostrzeżeń nie zakłóca obecnie działania pluginu. Sygnały te pojawiają się również w wynikach poleceń openclaw status --all i openclaw plugins doctor.

Omówienie architektury

System pluginów OpenClaw składa się z czterech warstw:

W szczególności wykrywanie głównych poleceń CLI pluginów jest podzielone na dwie fazy:

• metadane dostępne podczas analizowania pochodzą z registerCli(..., { descriptors: [...] })
• właściwy moduł CLI pluginu może pozostać ładowany leniwie i rejestrować się przy pierwszym wywołaniu

Dzięki temu kod CLI należący do pluginu pozostaje w pluginie, a OpenClaw może zarezerwować nazwy głównych poleceń przed rozpoczęciem analizy.

Ważna granica projektowa:

• walidacja manifestu i konfiguracji powinna działać na podstawie metadanych manifestu i schematu bez wykonywania kodu pluginu
• wykrywanie natywnych możliwości może ładować zaufany kod wejściowy pluginu w celu utworzenia nieaktywującego obrazu rejestru
• natywne zachowanie w czasie działania pochodzi ze ścieżki register(api) modułu pluginu, gdy api.registrationMode === "full"

Ten podział pozwala OpenClaw sprawdzać poprawność konfiguracji, wyjaśniać brakujące lub wyłączone pluginy oraz tworzyć wskazówki dla interfejsu użytkownika i schematu przed uruchomieniem pełnego środowiska wykonawczego.

Obraz metadanych pluginów i tabela wyszukiwania

Podczas uruchamiania Gateway tworzony jest jeden obiekt PluginMetadataSnapshot dla bieżącego obrazu konfiguracji. Obraz zawiera wyłącznie metadane: przechowuje indeks zainstalowanych pluginów, rejestr manifestów, diagnostykę manifestów, mapy właścicieli, mechanizm normalizacji identyfikatorów pluginów oraz rekordy manifestów. Nie zawiera załadowanych modułów pluginów, zestawów SDK dostawców, zawartości pakietów ani eksportowanych elementów środowiska wykonawczego.

Walidacja konfiguracji uwzględniająca pluginy, automatyczne włączanie podczas uruchamiania oraz inicjalizacja pluginów Gateway korzystają z tego obrazu zamiast niezależnie przebudowywać metadane manifestów i indeksu. Obiekt PluginLookUpTable jest tworzony na podstawie tego samego obrazu i dodaje plan uruchamiania pluginów dla bieżącej konfiguracji środowiska wykonawczego.

Po uruchomieniu Gateway zachowuje bieżący obraz metadanych jako wymienialny produkt środowiska wykonawczego. Powtarzane wykrywanie dostawców w czasie działania może korzystać z tego obrazu zamiast odtwarzać indeks instalacji i rejestr manifestów przy każdym przebiegu katalogu dostawców. Obraz jest czyszczony lub zastępowany przy zamykaniu Gateway, zmianach konfiguracji lub spisu pluginów oraz zapisach indeksu instalacji; jeśli nie istnieje zgodny bieżący obraz, kod wywołujący powraca do zimnej ścieżki manifestu i indeksu. Kontrole zgodności muszą uwzględniać katalogi główne wykrywania pluginów, takie jak plugins.load.paths, oraz domyślną przestrzeń roboczą agenta, ponieważ pluginy przestrzeni roboczej należą do zakresu metadanych.

Obraz i tabela wyszukiwania utrzymują powtarzane decyzje podczas uruchamiania na szybkiej ścieżce:

• własność kanałów
• odroczone uruchamianie kanałów
• identyfikatory pluginów uruchamianych podczas startu
• własność dostawców i mechanizmów CLI
• własność dostawcy konfiguracji, aliasów poleceń, dostawcy katalogu modeli oraz kontraktu manifestu
• walidacja schematu konfiguracji pluginów i schematu konfiguracji kanałów
• decyzje o automatycznym włączaniu podczas uruchamiania

Granicę bezpieczeństwa stanowi zastępowanie obrazu, a nie jego modyfikowanie. Przebuduj obraz po zmianie konfiguracji, spisu pluginów, rekordów instalacji lub utrwalonych zasad indeksu. Nie traktuj go jako ogólnego, modyfikowalnego rejestru globalnego i nie przechowuj nieograniczonej liczby obrazów historycznych. Ładowanie pluginów w czasie działania pozostaje oddzielone od obrazów metadanych, dzięki czemu nieaktualny stan środowiska wykonawczego nie może zostać ukryty za pamięcią podręczną metadanych.

Regułę pamięci podręcznej opisano w dokumencie Wewnętrzna architektura pluginów: metadane manifestu i wykrywania są aktualne, chyba że kod wywołujący przechowuje jawny obraz, tabelę wyszukiwania lub rejestr manifestów dla bieżącego przepływu. Ukryte pamięci podręczne metadanych i czasy TTL oparte na zegarze nie są częścią ładowania pluginów. Po faktycznym załadowaniu kodu lub zainstalowanych artefaktów mogą być zachowywane wyłącznie pamięci podręczne modułu ładującego środowiska wykonawczego, modułów i artefaktów zależności.

Niektóre wywołania zimnej ścieżki nadal odtwarzają rejestry manifestów bezpośrednio z utrwalonego indeksu zainstalowanych pluginów zamiast otrzymywać obiekt PluginLookUpTable z Gateway. Ta ścieżka odtwarza teraz rejestr na żądanie; jeśli kod wywołujący już go posiada, preferuj przekazywanie bieżącej tabeli wyszukiwania lub jawnego rejestru manifestów przez przepływy środowiska wykonawczego.

Planowanie aktywacji

Planowanie aktywacji jest częścią płaszczyzny sterowania. Kod wywołujący może przed załadowaniem szerszych rejestrów środowiska uruchomieniowego sprawdzić, które pluginy są istotne dla konkretnego polecenia, dostawcy, kanału, trasy, środowiska agenta lub możliwości.

Planista zachowuje zgodność z bieżącym działaniem manifestu:

• pola activation.* są jawnymi wskazówkami dla planisty
• providers, channels, commandAliases, setup.providers, contracts.tools oraz punkty zaczepienia pozostają mechanizmem rezerwowym opartym na własności określonej w manifeście
• interfejs API planisty zwracający wyłącznie identyfikatory pozostaje dostępny dla istniejącego kodu wywołującego
• interfejs API planu zgłasza etykiety przyczyn, dzięki czemu diagnostyka może odróżnić jawne wskazówki od mechanizmu rezerwowego opartego na własności

Pluginy kanałów i współdzielone narzędzie wiadomości

Pluginy kanałów nie muszą rejestrować osobnego narzędzia do wysyłania, edytowania ani reagowania w przypadku zwykłych działań na czacie. OpenClaw utrzymuje jedno współdzielone narzędzie message w rdzeniu, a pluginy kanałów odpowiadają za właściwe dla kanału wykrywanie i wykonywanie działań.

Obecny podział odpowiedzialności wygląda następująco:

• rdzeń odpowiada za hosta współdzielonego narzędzia message, integrację z promptem, ewidencję sesji i wątków oraz przekazywanie wykonania
• pluginy kanałów odpowiadają za wykrywanie działań w danym zakresie, wykrywanie możliwości oraz wszelkie fragmenty schematu właściwe dla kanału
• pluginy kanałów odpowiadają za gramatykę konwersacji sesji właściwą dla dostawcy, na przykład sposób kodowania identyfikatorów wątków w identyfikatorach konwersacji lub ich dziedziczenia z konwersacji nadrzędnych
• pluginy kanałów wykonują końcowe działanie za pośrednictwem własnego adaptera działań

W przypadku pluginów kanałów powierzchnią SDK jest ChannelMessageActionAdapter.describeMessageTool(...). To ujednolicone wywołanie wykrywania pozwala pluginowi zwrócić jednocześnie widoczne działania, możliwości i wkład w schemat, aby elementy te nie ulegały wzajemnemu rozjechaniu.

Gdy parametr narzędzia wiadomości właściwy dla kanału zawiera źródło multimediów, takie jak ścieżka lokalna lub zdalny adres URL multimediów, plugin powinien również zwrócić mediaSourceParams z describeMessageTool(...). Rdzeń używa tej jawnej listy do normalizacji ścieżek piaskownicy oraz stosowania wskazówek dotyczących dostępu do wychodzących multimediów bez wpisywania na stałe nazw parametrów należących do pluginu. Preferuj w tym miejscu mapy ograniczone do konkretnych działań zamiast jednej płaskiej listy dla całego kanału, aby parametr multimediów używany tylko przez profil nie był normalizowany w niepowiązanych działaniach, takich jak send.

Rdzeń przekazuje zakres środowiska uruchomieniowego do tego etapu wykrywania. Ważne pola obejmują:

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• zaufany przychodzący requesterSenderId

Ma to znaczenie w przypadku pluginów zależnych od kontekstu. Kanał może ukrywać lub udostępniać działania dotyczące wiadomości zależnie od aktywnego konta, bieżącego pokoju, wątku lub wiadomości albo zaufanej tożsamości zgłaszającego, bez wpisywania na stałe w rdzeniowym narzędziu message rozgałęzień właściwych dla kanałów.

Dlatego zmiany routingu osadzonego modułu uruchamiającego nadal należą do zadań pluginu: moduł uruchamiający odpowiada za przekazanie bieżącej tożsamości czatu lub sesji do granicy wykrywania pluginu, aby współdzielone narzędzie message udostępniało w bieżącej turze właściwą powierzchnię należącą do kanału.

W przypadku pomocniczych mechanizmów wykonawczych należących do kanału wbudowane pluginy powinny przechowywać środowisko wykonawcze we własnych modułach. Rdzeń nie odpowiada już za środowiska uruchomieniowe działań na wiadomościach Discord, Slack, Telegram ani WhatsApp w src/agents/tools. Nie publikujemy osobnych podścieżek plugin-sdk/*-action-runtime, a wbudowane pluginy powinny importować własny lokalny kod środowiska uruchomieniowego bezpośrednio z należących do nich modułów.

Ta sama granica ma ogólne zastosowanie do elementów SDK nazwanych według dostawcy: rdzeń nie powinien importować charakterystycznych dla kanałów zbiorczych modułów pomocniczych dla Discord, Signal, Slack, WhatsApp ani podobnych pluginów. Jeśli rdzeń potrzebuje określonego zachowania, powinien korzystać z należącego do wbudowanego pluginu modułu zbiorczego api.ts / runtime-api.ts albo przekształcić tę potrzebę w wąską, ogólną możliwość we współdzielonym SDK.

Wbudowane pluginy podlegają tej samej zasadzie. Plik runtime-api.ts wbudowanego pluginu nie powinien ponownie eksportować jego własnej, markowej fasady openclaw/plugin-sdk/<plugin-id>. Takie markowe fasady pozostają warstwami zgodności dla zewnętrznych pluginów i starszych odbiorców, lecz wbudowane pluginy powinny używać lokalnych eksportów oraz wąskich, ogólnych podścieżek SDK, takich jak openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store lub openclaw/plugin-sdk/webhook-ingress. Nowy kod nie powinien dodawać fasad SDK właściwych dla identyfikatora pluginu, chyba że wymaga tego granica zgodności istniejącego zewnętrznego ekosystemu.

W przypadku ankiet istnieją konkretnie dwie ścieżki wykonania:

• outbound.sendPoll jest współdzieloną ścieżką bazową dla kanałów pasujących do wspólnego modelu ankiet
• actions.handleAction("poll") jest preferowaną ścieżką dla właściwej dla kanału semantyki ankiet lub dodatkowych parametrów ankiety

Rdzeń odkłada teraz współdzielone analizowanie ankiety do momentu, gdy przekazanie ankiety do pluginu odrzuci działanie, dzięki czemu należące do pluginów procedury obsługi ankiet mogą przyjmować pola ankiety właściwe dla kanału bez wcześniejszego blokowania przez ogólny parser ankiet.

Pełną sekwencję uruchamiania opisano w dokumencie Wewnętrzna architektura pluginów.

Model własności możliwości

OpenClaw traktuje natywny plugin jako granicę własności firmy lub funkcji, a nie jako zbiór niepowiązanych integracji.

Oznacza to, że:

• plugin firmy powinien zwykle odpowiadać za wszystkie powierzchnie tej firmy dostępne w OpenClaw
• plugin funkcji powinien zwykle odpowiadać za całą wprowadzaną przez siebie powierzchnię funkcji
• kanały powinny korzystać ze współdzielonych możliwości rdzenia zamiast doraźnie ponownie implementować zachowanie dostawcy

Docelowy stan wygląda następująco:

• powierzchnia dostawcy dostępna w OpenClaw znajduje się w jednym pluginie, nawet jeśli obejmuje modele tekstowe, mowę, obrazy i wideo
• inni dostawcy mogą zrobić to samo dla własnego zakresu powierzchni
• kanałów nie interesuje, który plugin dostawcy odpowiada za danego dostawcę; korzystają ze współdzielonego kontraktu możliwości udostępnianego przez rdzeń

Kluczowe rozróżnienie jest następujące:

• plugin = granica własności
• możliwość = kontrakt rdzenia, który może być implementowany lub używany przez wiele pluginów

Jeśli więc OpenClaw dodaje nową dziedzinę, taką jak wideo, pierwsze pytanie nie brzmi „który dostawca powinien mieć na stałe zakodowaną obsługę wideo?”. Pierwsze pytanie brzmi „jaki jest kontrakt podstawowej możliwości wideo?”. Po utworzeniu tego kontraktu pluginy dostawców mogą się względem niego rejestrować, a pluginy kanałów i funkcji mogą z niego korzystać.

Jeśli dana możliwość jeszcze nie istnieje, właściwy sposób działania zwykle wygląda następująco:

Pozwala to zachować jawną własność, unikając jednocześnie zachowania rdzenia zależnego od jednego dostawcy lub jednorazowej ścieżki kodu właściwej dla pluginu.

Warstwy możliwości

Przy podejmowaniu decyzji o umiejscowieniu kodu używaj następującego modelu myślowego:

Na przykład TTS działa według tego modelu:

• rdzeń odpowiada za zasady TTS podczas generowania odpowiedzi, kolejność mechanizmów rezerwowych, preferencje i dostarczanie do kanałów
• elevenlabs, google, microsoft i openai odpowiadają za implementacje syntezy
• voice-call korzysta z pomocniczego środowiska uruchomieniowego TTS dla telefonii

Ten sam wzorzec powinien być preferowany w przypadku przyszłych możliwości.

Przykład firmowego pluginu obsługującego wiele możliwości

Plugin firmy powinien z zewnątrz tworzyć spójną całość. Jeśli OpenClaw ma współdzielone kontrakty dla modeli, mowy, transkrypcji w czasie rzeczywistym, głosu w czasie rzeczywistym, rozumienia multimediów, generowania obrazów, generowania wideo, pobierania treści z internetu i wyszukiwania w internecie, dostawca może odpowiadać za wszystkie swoje powierzchnie w jednym miejscu:

    describeImageWithModel,  transcribeOpenAiCompatibleAudio,} from "openclaw/plugin-sdk/media-understanding"; const plugin: OpenClawPluginDefinition = {  id: "exampleai",  name: "ExampleAI",  register(api) {    api.registerProvider({      id: "exampleai",      // auth/model catalog/runtime hooks    });     api.registerSpeechProvider({      id: "exampleai",      // vendor speech config — implement the SpeechProviderPlugin interface directly    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      async describeImage(req) {        return describeImageWithModel({          ...req,          provider: "exampleai",        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          ...req,          provider: "exampleai",        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // credential + fetch logic      }),    );  },}; export default plugin;

Nie są istotne dokładne nazwy funkcji pomocniczych. Istotna jest struktura:

• jeden plugin odpowiada za powierzchnię dostawcy
• rdzeń nadal odpowiada za kontrakty możliwości
• kanały i pluginy funkcji korzystają z funkcji pomocniczych api.runtime.*, a nie z kodu dostawcy
• testy kontraktowe mogą potwierdzać, że plugin zarejestrował możliwości, za które deklaruje odpowiedzialność

Przykład możliwości: rozumienie wideo

OpenClaw już traktuje rozumienie obrazów, dźwięku i wideo jako jedną współdzieloną możliwość. Obowiązuje tam ten sam model własności:

Pozwala to uniknąć wbudowywania założeń jednego dostawcy dotyczących wideo w rdzeń. Plugin odpowiada za powierzchnię dostawcy, a rdzeń za kontrakt możliwości i zachowanie mechanizmu rezerwowego.

Generowanie wideo korzysta już z tej samej sekwencji: rdzeń odpowiada za typowany kontrakt możliwości i pomocniczy mechanizm środowiska uruchomieniowego, a pluginy dostawców rejestrują względem niego implementacje api.registerVideoGenerationProvider(...).

Potrzebujesz konkretnej listy kontrolnej wdrożenia? Zobacz Przewodnik po możliwościach.

Kontrakty i ich egzekwowanie

Powierzchnia API pluginów jest celowo typowana i scentralizowana w OpenClawPluginApi. Ten kontrakt definiuje obsługiwane punkty rejestracji oraz pomocnicze funkcje środowiska wykonawczego, na których plugin może polegać.

Dlaczego ma to znaczenie:

• autorzy pluginów otrzymują jeden stabilny standard wewnętrzny
• rdzeń może odrzucać zduplikowane prawa własności, na przykład gdy dwa pluginy rejestrują ten sam identyfikator dostawcy
• podczas uruchamiania mogą być wyświetlane praktyczne informacje diagnostyczne dotyczące nieprawidłowej rejestracji
• testy kontraktowe mogą egzekwować prawa własności wbudowanych pluginów i zapobiegać niezauważalnym rozbieżnościom

Egzekwowanie odbywa się na dwóch poziomach:

W praktyce OpenClaw z góry wie, który plugin jest właścicielem danej powierzchni. Dzięki temu rdzeń i kanały mogą płynnie ze sobą współdziałać, ponieważ prawa własności są deklarowane, typowane i testowalne, a nie niejawne.

Co powinien obejmować kontrakt

W razie wątpliwości należy podnieść poziom abstrakcji: najpierw zdefiniować możliwość, a następnie pozwolić pluginom się z nią integrować.

Model wykonywania

Natywne pluginy OpenClaw działają w procesie wraz z Gateway. Nie są izolowane. Załadowany natywny plugin ma tę samą granicę zaufania na poziomie procesu co kod rdzenia.

Zgodne pakiety są domyślnie bezpieczniejsze, ponieważ OpenClaw obecnie traktuje je jako pakiety metadanych lub treści. W bieżących wydaniach oznacza to głównie dołączone Skills.

W przypadku pluginów, które nie są wbudowane, należy używać list dozwolonych elementów oraz jawnych ścieżek instalacji i ładowania. Pluginy przestrzeni roboczej należy traktować jako kod używany podczas programowania, a nie jako domyślny kod produkcyjny.

W przypadku nazw wbudowanych pakietów przestrzeni roboczej identyfikator pluginu powinien być zakotwiczony w nazwie npm: domyślnie @openclaw/<id> albo z zatwierdzonym, typowanym sufiksem, takim jak -provider, -plugin, -speech, -sandbox lub -media-understanding, gdy pakiet celowo udostępnia węższą rolę pluginu.

Granica eksportu

OpenClaw eksportuje możliwości, a nie udogodnienia implementacyjne.

Rejestracja możliwości powinna pozostać publiczna. Należy ograniczyć eksport pomocniczych elementów, które nie stanowią kontraktu:

• podścieżki funkcji pomocniczych właściwych dla wbudowanych pluginów
• podścieżki infrastruktury środowiska wykonawczego, które nie są przeznaczone jako publiczne API
• funkcje pomocnicze właściwe dla dostawcy
• funkcje pomocnicze konfiguracji i wdrażania początkowego, które są szczegółami implementacyjnymi

Zarezerwowane podścieżki funkcji pomocniczych wbudowanych pluginów zostały wycofane z wygenerowanej mapy eksportu SDK. Funkcje pomocnicze właściwe dla właściciela należy przechowywać w pakiecie pluginu należącym do tego właściciela; tylko zachowania hosta wielokrotnego użytku należy przenosić do ogólnych kontraktów SDK, takich jak plugin-sdk/gateway-runtime, plugin-sdk/security-runtime i plugin-sdk/plugin-config-runtime.

Szczegóły wewnętrzne i materiały referencyjne

Informacje o potoku ładowania, modelu rejestru, punktach zaczepienia środowiska wykonawczego dostawców, trasach HTTP Gateway, schematach narzędzi wiadomości, rozpoznawaniu elementów docelowych kanałów, katalogach dostawców, pluginach mechanizmu kontekstu oraz przewodnik dotyczący dodawania nowej możliwości zawiera strona Szczegóły wewnętrzne architektury pluginów.

Powiązane materiały

• Tworzenie pluginów
• Manifest pluginu
• Konfiguracja SDK pluginów