Przejdź do głównej treści
To jest szczegółowe odniesienie architektoniczne dla systemu Plugin OpenClaw. Aby skorzystać z praktycznych przewodników, zacznij od jednej z poniższych stron tematycznych.

Instalowanie i używanie Plugin

Przewodnik dla użytkownika końcowego dotyczący dodawania, włączania i rozwiązywania problemów z pluginami.

Budowanie pluginów

Samouczek pierwszego Plugin z najmniejszym działającym manifestem.

Pluginy kanałów

Zbuduj Plugin kanału wiadomości.

Pluginy dostawców

Zbuduj Plugin dostawcy modeli.

Omówienie SDK

Odniesienie do mapy importów i API rejestracji.

​
Publiczny model możliwości

Możliwości są publicznym modelem natywnego Plugin wewnątrz OpenClaw. Każdy natywny Plugin OpenClaw rejestruje się względem jednego lub większej liczby typów możliwości:
MożliwośćMetoda rejestracjiPrzykładowe pluginy
Inferencja tekstuapi.registerProvider(...)openai, anthropic
Backend inferencji CLIapi.registerCliBackend(...)openai, anthropic
Osadzeniaapi.registerEmbeddingProvider(...)Pluginy wektorowe należące do dostawcy
Mowaapi.registerSpeechProvider(...)elevenlabs, microsoft
Transkrypcja w czasie rzeczywistymapi.registerRealtimeTranscriptionProvider(...)openai
Głos w czasie rzeczywistymapi.registerRealtimeVoiceProvider(...)openai
Rozumienie mediówapi.registerMediaUnderstandingProvider(...)openai, google
Źródło transkryptówapi.registerTranscriptSourceProvider(...)discord
Generowanie obrazówapi.registerImageGenerationProvider(...)openai, google, fal, minimax
Generowanie muzykiapi.registerMusicGenerationProvider(...)google, minimax
Generowanie wideoapi.registerVideoGenerationProvider(...)qwen
Pobieranie z sieciapi.registerWebFetchProvider(...)firecrawl
Wyszukiwanie w sieciapi.registerWebSearchProvider(...)google
Kanał / wiadomościapi.registerChannel(...)msteams, matrix
Wykrywanie Gatewayapi.registerGatewayDiscoveryService(...)bonjour
Plugin, który rejestruje zero możliwości, ale udostępnia haki, narzędzia, usługi wykrywania lub usługi działające w tle, jest starszym Plugin tylko z hakami. Ten wzorzec jest nadal w pełni obsługiwany.

​
Stanowisko dotyczące zgodności zewnętrznej

Model możliwości jest wdrożony w rdzeniu i używany obecnie przez dołączone/natywne pluginy, ale zgodność zewnętrznych pluginów nadal wymaga wyższego progu niż „jest eksportowane, więc jest zamrożone”.
Sytuacja PluginWskazówki
Istniejące zewnętrzne pluginyUtrzymuj działanie integracji opartych na hakach; to jest baza zgodności.
Nowe dołączone/natywne pluginyPreferuj jawną rejestrację możliwości zamiast sięgania do elementów specyficznych dla dostawcy lub nowych projektów tylko z hakami.
Zewnętrzne pluginy przyjmujące rejestrację możliwościDozwolone, ale traktuj powierzchnie pomocnicze specyficzne dla możliwości jako ewoluujące, chyba że dokumentacja oznacza je jako stabilne.
Rejestracja możliwości jest zamierzonym kierunkiem. Starsze haki pozostają najbezpieczniejszą ścieżką bez ryzyka przerwania działania dla zewnętrznych pluginów podczas przejścia. Eksportowane podścieżki pomocnicze nie są sobie równe — preferuj wąskie, udokumentowane kontrakty zamiast przypadkowych eksportów pomocniczych.

​
Kształty Plugin

OpenClaw klasyfikuje każdy załadowany Plugin do kształtu na podstawie jego rzeczywistego zachowania rejestracyjnego (nie tylko statycznych metadanych):
Rejestruje dokładnie jeden typ możliwości (na przykład Plugin wyłącznie dostawcy, taki jak mistral).
Rejestruje wiele typów możliwości (na przykład openai odpowiada za inferencję tekstu, mowę, rozumienie mediów i generowanie obrazów).
Rejestruje tylko haki (typowane lub niestandardowe), bez możliwości, narzędzi, poleceń ani usług.
Rejestruje narzędzia, polecenia, usługi lub trasy, ale bez możliwości.
Użyj openclaw plugins inspect <id>, aby zobaczyć kształt Plugin i rozbicie możliwości. Szczegóły znajdziesz w odniesieniu CLI.

​
Starsze haki

Hak before_agent_start pozostaje obsługiwany jako ścieżka zgodności dla pluginów tylko z hakami. Starsze pluginy używane w praktyce nadal od niego zależą. Kierunek:
  • utrzymać jego działanie
  • udokumentować go jako starszy
  • preferować before_model_resolve do pracy nad nadpisywaniem modelu/dostawcy
  • preferować before_prompt_build do pracy nad mutacją promptu
  • usuwać dopiero po spadku rzeczywistego użycia i gdy pokrycie fiksturami potwierdzi bezpieczeństwo migracji

​
Sygnały zgodności

Gdy uruchomisz openclaw doctor lub openclaw plugins inspect <id>, możesz zobaczyć jedną z tych etykiet:
SygnałZnaczenie
config validKonfiguracja parsuje się poprawnie, a pluginy się rozwiązują
compatibility advisoryPlugin używa obsługiwanego, ale starszego wzorca (np. hook-only)
legacy warningPlugin używa before_agent_start, który jest przestarzały
hard errorKonfiguracja jest nieprawidłowa albo Plugin nie załadował się
Ani hook-only, ani before_agent_start nie przerwą dziś działania Twojego Plugin: hook-only jest informacyjne, a before_agent_start wywołuje tylko ostrzeżenie. Te sygnały pojawiają się także w openclaw status --all i openclaw plugins doctor.

​
Omówienie architektury

System Plugin OpenClaw ma cztery warstwy:
1

Manifest + wykrywanie

OpenClaw znajduje kandydackie pluginy ze skonfigurowanych ścieżek, katalogów głównych obszarów roboczych, globalnych katalogów głównych pluginów oraz dołączonych pluginów. Wykrywanie najpierw odczytuje natywne manifesty openclaw.plugin.json oraz obsługiwane manifesty pakietów.
2

Włączanie + walidacja

Rdzeń decyduje, czy wykryty Plugin jest włączony, wyłączony, zablokowany albo wybrany dla wyłącznego slotu, takiego jak pamięć.
3

Ładowanie w czasie działania

Natywne pluginy OpenClaw są ładowane w procesie i rejestrują możliwości w centralnym rejestrze. Spakowany JavaScript ładuje się przez natywne require; lokalne źródło TypeScript firm trzecich jest awaryjną ścieżką zastępczą Jiti. Zgodne pakiety są normalizowane do rekordów rejestru bez importowania kodu wykonywanego w czasie działania.
4

Konsumowanie powierzchni

Reszta OpenClaw odczytuje rejestr, aby udostępniać narzędzia, kanały, konfigurację dostawców, haki, trasy HTTP, polecenia CLI i usługi.
W przypadku samego CLI Plugin wykrywanie poleceń głównych jest podzielone na dwie fazy:
  • metadane czasu parsowania pochodzą z registerCli(..., { descriptors: [...] })
  • rzeczywisty moduł CLI Plugin może pozostać leniwy i zarejestrować się przy pierwszym wywołaniu
Dzięki temu kod CLI należący do Plugin pozostaje wewnątrz Plugin, a OpenClaw nadal może zarezerwować nazwy poleceń głównych przed parsowaniem. Ważna granica projektowa:
  • walidacja manifestu/konfiguracji powinna działać na podstawie metadanych manifestu/schematu bez wykonywania kodu Plugin
  • natywne wykrywanie możliwości może załadować zaufany kod wejściowy Plugin, aby zbudować nieaktywującą migawkę rejestru
  • natywne zachowanie w czasie działania pochodzi ze ścieżki register(api) modułu Plugin z api.registrationMode === "full"
Ten podział pozwala OpenClaw walidować konfigurację, wyjaśniać brakujące/wyłączone pluginy oraz budować podpowiedzi UI/schematu, zanim pełne środowisko wykonawcze będzie aktywne.

​
Migawka metadanych Plugin i tabela wyszukiwania

Podczas startu Gateway buduje jeden PluginMetadataSnapshot dla bieżącej migawki konfiguracji. Migawka zawiera tylko metadane: przechowuje indeks zainstalowanych pluginów, rejestr manifestów, diagnostykę manifestów, mapy właścicieli, normalizator identyfikatorów Plugin oraz rekordy manifestów. Nie przechowuje załadowanych modułów Plugin, SDK dostawców, zawartości pakietów ani eksportów czasu działania. Walidacja konfiguracji świadoma pluginów, automatyczne włączanie przy starcie oraz bootstrap Plugin Gateway korzystają z tej migawki zamiast niezależnie odbudowywać metadane manifestu/indeksu. PluginLookUpTable jest wyprowadzana z tej samej migawki i dodaje plan pluginów startowych dla bieżącej konfiguracji czasu działania. Po starcie Gateway utrzymuje bieżącą migawkę metadanych jako wymienny produkt czasu działania. Powtarzane wykrywanie dostawców w czasie działania może wypożyczyć tę migawkę zamiast rekonstruować zainstalowany indeks i rejestr manifestów dla każdego przebiegu katalogu dostawców. Migawka jest czyszczona lub zastępowana przy zamknięciu Gateway, zmianach konfiguracji/inwentarza pluginów oraz zapisach zainstalowanego indeksu; wywołujący wracają do zimnej ścieżki manifestu/indeksu, gdy nie istnieje zgodna bieżąca migawka. Kontrole zgodności muszą obejmować katalogi główne wykrywania pluginów, takie jak plugins.load.paths i domyślny obszar roboczy agenta, ponieważ pluginy obszaru roboczego są częścią zakresu metadanych. Migawka i tabela wyszukiwania utrzymują powtarzane decyzje startowe na szybkiej ścieżce:
  • własność kanału
  • odroczony start kanału
  • identyfikatory pluginów startowych
  • własność dostawcy i backendu CLI
  • własność konfiguracji dostawcy, aliasu polecenia, dostawcy katalogu modeli i kontraktu manifestu
  • walidacja schematu konfiguracji Plugin i schematu konfiguracji kanału
  • decyzje o automatycznym włączaniu przy starcie
Granicą bezpieczeństwa jest zastąpienie migawki, nie mutacja. Odbuduj migawkę, gdy zmieni się konfiguracja, inwentarz pluginów, rekordy instalacji lub utrwalona polityka indeksu. Nie traktuj jej jako szerokiego, mutowalnego globalnego rejestru i nie przechowuj nieograniczonych historycznych migawek. Ładowanie Plugin w czasie działania pozostaje oddzielone od migawek metadanych, aby przestarzały stan czasu działania nie mógł zostać ukryty za cache metadanych. Reguła cache jest udokumentowana w wewnętrznej architekturze Plugin: metadane manifestu i wykrywania są świeże, chyba że wywołujący posiada jawną migawkę, tabelę wyszukiwania lub rejestr manifestów dla bieżącego przepływu. Ukryte cache metadanych i TTL oparte na zegarze ściennym nie są częścią ładowania Plugin. Tylko cache loadera czasu działania, modułów i artefaktów zależności mogą utrzymywać się po faktycznym załadowaniu kodu lub zainstalowanych artefaktów. Niektórzy wywołujący ze ścieżki zimnej nadal rekonstruują rejestry manifestów bezpośrednio z utrwalonego indeksu zainstalowanych pluginów zamiast otrzymywać PluginLookUpTable Gateway. Ta ścieżka teraz rekonstruuje rejestr na żądanie; preferuj przekazywanie bieżącej tabeli wyszukiwania lub jawnego rejestru manifestów przez przepływy czasu działania, gdy wywołujący już go ma.

​
Planowanie aktywacji

Planowanie aktywacji jest częścią płaszczyzny sterowania. Wywołujący mogą zapytać, które pluginy są istotne dla konkretnego polecenia, dostawcy, kanału, trasy, uprzęży agenta lub możliwości, zanim załadują szersze rejestry czasu działania. Planer zachowuje zgodność z bieżącym zachowaniem manifestu:
  • pola activation.* są jawnymi wskazówkami dla planisty
  • providers, channels, commandAliases, setup.providers, contracts.tools i hooki pozostają awaryjnym mechanizmem własności z manifestu
  • API planisty oparte wyłącznie na identyfikatorach pozostaje dostępne dla istniejących wywołujących
  • API planu raportuje etykiety powodów, aby diagnostyka mogła odróżniać jawne wskazówki od awaryjnego mechanizmu własności
Nie traktuj activation jako hooka cyklu życia ani zamiennika register(...). To metadane używane do zawężania ładowania. Preferuj pola własności, gdy już opisują relację; używaj activation tylko jako dodatkowych wskazówek dla planisty.

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

Pluginy kanałów nie muszą rejestrować osobnego narzędzia wysyłania/edycji/reakcji dla zwykłych akcji czatu. OpenClaw utrzymuje jedno współdzielone narzędzie message w rdzeniu, a pluginy kanałów odpowiadają za specyficzne dla kanału wykrywanie i wykonywanie za nim. Obecna granica wygląda tak:
  • rdzeń odpowiada za host współdzielonego narzędzia message, okablowanie promptów, księgowanie sesji/wątków oraz przekazywanie wykonania
  • pluginy kanałów odpowiadają za wykrywanie akcji w zakresie, wykrywanie możliwości i wszystkie specyficzne dla kanału fragmenty schematu
  • pluginy kanałów odpowiadają za gramatykę konwersacji sesji specyficzną dla dostawcy, na przykład za to, jak identyfikatory konwersacji kodują identyfikatory wątków albo dziedziczą z konwersacji nadrzędnych
  • pluginy kanałów wykonują końcową akcję przez swój adapter akcji
Dla pluginów kanałów powierzchnią SDK jest ChannelMessageActionAdapter.describeMessageTool(...). To ujednolicone wywołanie wykrywania pozwala pluginowi zwrócić widoczne akcje, możliwości i wkłady do schematu razem, aby te elementy nie rozjeżdżały się względem siebie. Gdy specyficzny dla kanału parametr narzędzia wiadomości przenosi źródło multimediów, takie jak lokalna ścieżka albo zdalny URL multimediów, plugin powinien także zwrócić mediaSourceParams z describeMessageTool(...). Rdzeń używa tej jawnej listy do stosowania normalizacji ścieżek sandboxa i wskazówek dostępu do multimediów wychodzących bez hardkodowania nazw parametrów należących do pluginu. Preferuj tam mapy ograniczone do akcji, a nie jedną płaską listę dla całego kanału, aby parametr multimediów tylko dla profilu nie był normalizowany przy niepowiązanych akcjach takich jak send. Rdzeń przekazuje zakres runtime do tego kroku wykrywania. Ważne pola obejmują:
  • accountId
  • currentChannelId
  • currentThreadTs
  • currentMessageId
  • sessionKey
  • sessionId
  • agentId
  • zaufany przychodzący requesterSenderId
Ma to znaczenie dla pluginów zależnych od kontekstu. Kanał może ukrywać lub ujawniać akcje wiadomości na podstawie aktywnego konta, bieżącego pokoju/wątku/wiadomości albo zaufanej tożsamości żądającego bez hardkodowania specyficznych dla kanału gałęzi w rdzeniowym narzędziu message. Dlatego zmiany routingu osadzonego runnera nadal są pracą pluginu: runner odpowiada za przekazanie bieżącej tożsamości czatu/sesji do granicy wykrywania pluginu, aby współdzielone narzędzie message ujawniało właściwą, należącą do kanału powierzchnię dla bieżącej tury. W przypadku należących do kanału helperów wykonywania pluginy wbudowane powinny utrzymywać runtime wykonywania wewnątrz własnych modułów rozszerzeń. Rdzeń nie jest już właścicielem runtime’ów akcji wiadomości Discord, Slack, Telegram ani WhatsApp pod src/agents/tools. Nie publikujemy osobnych podścieżek plugin-sdk/*-action-runtime, a pluginy wbudowane powinny importować swój własny lokalny kod runtime bezpośrednio z modułów należących do ich rozszerzeń. Ta sama granica dotyczy ogólnie nazwanych od dostawcy styków SDK: rdzeń nie powinien importować specyficznych dla kanału wygodnych barrelów dla Slack, Discord, Signal, WhatsApp ani podobnych rozszerzeń. Jeśli rdzeń potrzebuje zachowania, powinien albo użyć własnego barrela api.ts / runtime-api.ts wbudowanego pluginu, albo promować potrzebę do wąskiej, generycznej możliwości we współdzielonym SDK. Pluginy wbudowane stosują tę samą regułę. runtime-api.ts wbudowanego pluginu nie powinien reeksportować własnej markowej fasady openclaw/plugin-sdk/<plugin-id>. Te markowe fasady pozostają shimami zgodności dla zewnętrznych pluginów i starszych konsumentów, ale pluginy wbudowane powinny używać lokalnych eksportów oraz wąskich generycznych podścieżek SDK, takich jak openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store albo openclaw/plugin-sdk/webhook-ingress. Nowy kod nie powinien dodawać specyficznych dla identyfikatora pluginu fasad SDK, chyba że wymaga tego granica zgodności dla istniejącego zewnętrznego ekosystemu. W przypadku ankiet istnieją konkretnie dwie ścieżki wykonywania:
  • outbound.sendPoll to współdzielona podstawa dla kanałów pasujących do wspólnego modelu ankiety
  • actions.handleAction("poll") to preferowana ścieżka dla specyficznej semantyki ankiet kanału albo dodatkowych parametrów ankiety
Rdzeń odracza teraz współdzielone parsowanie ankiet do momentu, gdy dyspozycja ankiety przez plugin odrzuci akcję, dzięki czemu należące do pluginu handlery ankiet mogą akceptować specyficzne dla kanału pola ankiety bez wcześniejszego blokowania przez generyczny parser ankiet. Zobacz Wewnętrzne mechanizmy architektury pluginów, aby poznać pełną sekwencję startową.

​
Model własności możliwości

OpenClaw traktuje natywny plugin jako granicę własności dla firmy albo funkcji, a nie jako zbiór niepowiązanych integracji. Oznacza to, że:
  • plugin firmy powinien zwykle posiadać wszystkie powierzchnie tej firmy skierowane do OpenClaw
  • plugin funkcji powinien zwykle posiadać pełną powierzchnię funkcji, którą wprowadza
  • kanały powinny używać współdzielonych możliwości rdzenia zamiast ponownie implementować zachowanie dostawcy ad hoc
openai odpowiada za inferencję tekstu, mowę, głos realtime, rozumienie multimediów i generowanie obrazów. google odpowiada za inferencję tekstu oraz rozumienie multimediów, generowanie obrazów i wyszukiwanie w sieci. qwen odpowiada za inferencję tekstu oraz rozumienie multimediów i generowanie wideo.
elevenlabs i microsoft odpowiadają za mowę; firecrawl odpowiada za web-fetch; minimax / mistral / moonshot / zai odpowiadają za backendy rozumienia multimediów.
voice-call odpowiada za transport połączeń, narzędzia, CLI, trasy i mostkowanie strumieni multimediów Twilio, ale używa współdzielonych możliwości mowy, transkrypcji realtime i głosu realtime zamiast importować pluginy dostawców bezpośrednio.
Docelowy stan to:
  • OpenAI żyje w jednym pluginie, nawet jeśli obejmuje modele tekstowe, mowę, obrazy i przyszłe wideo
  • inny dostawca może zrobić to samo dla własnego obszaru powierzchni
  • kanałów nie obchodzi, który plugin dostawcy posiada dostawcę; używają współdzielonego kontraktu możliwości wystawionego przez rdzeń
To jest kluczowa różnica:
  • plugin = granica własności
  • możliwość = kontrakt rdzenia, który wiele pluginów może implementować albo używać
Jeśli więc OpenClaw dodaje nową domenę, taką jak wideo, pierwsze pytanie nie brzmi „który dostawca powinien hardkodować obsługę wideo?”. Pierwsze pytanie brzmi „jaki jest kontrakt rdzenia dla możliwości wideo?”. Gdy ten kontrakt istnieje, pluginy dostawców mogą rejestrować się względem niego, a pluginy kanałów/funkcji mogą go używać. Jeśli możliwość jeszcze nie istnieje, właściwym krokiem jest zwykle:
1

Define the capability

Zdefiniuj brakującą możliwość w rdzeniu.
2

Expose through the SDK

Wystaw ją przez API/runtime pluginu w typowany sposób.
3

Wire consumers

Podepnij kanały/funkcje do tej możliwości.
4

Vendor implementations

Pozwól pluginom dostawców rejestrować implementacje.
Dzięki temu własność pozostaje jawna, a jednocześnie unika się zachowania rdzenia zależnego od jednego dostawcy albo jednorazowej, specyficznej dla pluginu ścieżki kodu.

​
Warstwowanie możliwości

Używaj tego modelu myślowego, decydując, gdzie należy kod:
Współdzielona orkiestracja, polityka, fallback, reguły scalania konfiguracji, semantyka dostarczania i typowane kontrakty.
Na przykład TTS ma taki kształt:
  • rdzeń odpowiada za politykę TTS w czasie odpowiedzi, kolejność fallbacków, preferencje i dostarczanie kanałem
  • openai, elevenlabs i microsoft odpowiadają za implementacje syntezy
  • voice-call używa helpera runtime TTS dla telefonii
Ten sam wzorzec powinien być preferowany dla przyszłych możliwości.

​
Przykład wielomożliwościowego pluginu firmy

Plugin firmy powinien być spójny z zewnątrz. Jeśli OpenClaw ma współdzielone kontrakty dla modeli, mowy, transkrypcji realtime, głosu realtime, rozumienia multimediów, generowania obrazów, generowania wideo, pobierania z sieci i wyszukiwania w sieci, dostawca może posiadać wszystkie swoje powierzchnie w jednym miejscu: 
import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
import {
  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({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
    });

    api.registerWebSearchProvider(
      createPluginBackedWebSearchProvider({
        id: "exampleai-search",
        // credential + fetch logic
      }),
    );
  },
};

export default plugin;
Znaczenie mają nie dokładne nazwy helperów. Liczy się kształt:
  • jeden plugin posiada powierzchnię dostawcy
  • rdzeń nadal posiada kontrakty możliwości
  • kanały i pluginy funkcji używają helperów api.runtime.*, a nie kodu dostawcy
  • testy kontraktowe mogą potwierdzać, że plugin zarejestrował możliwości, których posiadanie deklaruje

​
Przykład możliwości: rozumienie wideo

OpenClaw już traktuje rozumienie obrazów/audio/wideo jako jedną współdzieloną możliwość. Ten sam model własności ma zastosowanie także tam:
1

Core defines the contract

Rdzeń definiuje kontrakt rozumienia multimediów.
2

Vendor plugins register

Pluginy dostawców rejestrują describeImage, transcribeAudio i describeVideo, gdy ma to zastosowanie.
3

Consumers use the shared behavior

Kanały i pluginy funkcji używają współdzielonego zachowania rdzenia zamiast podpinać się bezpośrednio do kodu dostawcy.
Pozwala to uniknąć wypalania założeń jednego dostawcy dotyczących wideo w rdzeniu. Plugin posiada powierzchnię dostawcy; rdzeń posiada kontrakt możliwości i zachowanie fallback. Generowanie wideo już używa tej samej sekwencji: rdzeń posiada typowany kontrakt możliwości i helper runtime, a pluginy dostawców rejestrują wobec niego implementacje api.registerVideoGenerationProvider(...). Potrzebujesz konkretnej listy kontrolnej wdrożenia? Zobacz Capability Cookbook.

​
Kontrakty i egzekwowanie

Powierzchnia API pluginu jest celowo typowana i scentralizowana w OpenClawPluginApi. Ten kontrakt definiuje obsługiwane punkty rejestracji i helpery runtime, na których plugin może polegać. Dlaczego to ma znaczenie:
  • autorzy pluginów otrzymują jeden stabilny standard wewnętrzny
  • rdzeń może odrzucać zduplikowaną własność, na przykład dwa pluginy rejestrujące ten sam identyfikator dostawcy
  • startup może pokazywać użyteczną diagnostykę dla nieprawidłowej rejestracji
  • testy kontraktowe mogą egzekwować własność wbudowanego pluginu i zapobiegać cichemu dryfowi
Istnieją dwie warstwy egzekwowania:
Rejestr pluginów weryfikuje rejestracje podczas ładowania pluginów. Przykłady: zduplikowane identyfikatory dostawców, zduplikowane identyfikatory dostawców mowy oraz nieprawidłowo sformułowane rejestracje generują diagnostykę pluginu zamiast niezdefiniowanego zachowania.
Dołączone pluginy są ujmowane w rejestrach kontraktów podczas uruchomień testowych, aby OpenClaw mógł jawnie potwierdzać własność. Obecnie jest to używane dla dostawców modeli, dostawców mowy, dostawców wyszukiwania w sieci oraz własności dołączonych rejestracji.
Praktyczny efekt jest taki, że OpenClaw z góry wie, który plugin jest właścicielem której powierzchni. Dzięki temu rdzeń i kanały mogą płynnie się komponować, ponieważ własność jest deklarowana, typowana i testowalna, a nie domyślna.

​
Co należy do kontraktu

  • typowane
  • małe
  • specyficzne dla możliwości
  • należące do rdzenia
  • wielokrotnego użytku przez wiele pluginów
  • możliwe do użycia przez kanały/funkcje bez wiedzy o dostawcy
W razie wątpliwości podnieś poziom abstrakcji: najpierw zdefiniuj możliwość, a następnie pozwól pluginom się do niej podłączać.

​
Model wykonywania

Natywne pluginy OpenClaw działają w tym samym procesie co Gateway. Nie są izolowane w piaskownicy. Załadowany natywny plugin ma tę samą granicę zaufania na poziomie procesu co kod rdzenia.
Konsekwencje natywnych pluginów: plugin może rejestrować narzędzia, obsługę sieci, haki i usługi; błąd pluginu może zawiesić lub zdestabilizować gateway; a złośliwy natywny plugin jest równoważny wykonaniu dowolnego kodu wewnątrz procesu OpenClaw.
Zgodne pakiety są domyślnie bezpieczniejsze, ponieważ OpenClaw obecnie traktuje je jako pakiety metadanych/treści. W bieżących wydaniach oznacza to głównie dołączone Skills. Używaj list dozwolonych i jawnych ścieżek instalacji/ładowania dla pluginów niedołączonych. Traktuj pluginy z obszaru roboczego jako kod czasu programowania, a nie domyślne ustawienia produkcyjne. W przypadku dołączonych nazw pakietów obszaru roboczego utrzymuj identyfikator pluginu zakotwiczony w nazwie npm: domyślnie @openclaw/<id> albo zatwierdzony typowany sufiks, taki jak -provider, -plugin, -speech, -sandbox lub -media-understanding, gdy pakiet celowo udostępnia węższą rolę pluginu.
Uwaga o zaufaniu: plugins.allow ufa identyfikatorom pluginów, a nie pochodzeniu źródła. Plugin obszaru roboczego z tym samym identyfikatorem co dołączony plugin celowo przesłania dołączoną kopię, gdy ten plugin obszaru roboczego jest włączony/dodany do listy dozwolonych. Jest to normalne i przydatne w lokalnym programowaniu, testowaniu poprawek i hotfixach. Zaufanie do dołączonego pluginu jest rozstrzygane na podstawie migawki źródła — manifestu i kodu na dysku w czasie ładowania — a nie metadanych instalacji. Uszkodzony lub podmieniony rekord instalacji nie może po cichu rozszerzyć powierzchni zaufania dołączonego pluginu poza to, co deklaruje rzeczywiste źródło.

​
Granica eksportu

OpenClaw eksportuje możliwości, a nie wygodę implementacji. Utrzymuj rejestrację możliwości jako publiczną. Przycinaj eksporty pomocnicze niebędące kontraktami:
  • podścieżki pomocnicze specyficzne dla dołączonych pluginów
  • podścieżki infrastruktury czasu wykonywania nieprzeznaczone jako publiczne API
  • pomocnicze funkcje wygody specyficzne dla dostawcy
  • funkcje pomocnicze konfiguracji/wdrażania, które są szczegółami implementacji
Zarezerwowane podścieżki pomocnicze dołączonych pluginów zostały wycofane z wygenerowanej mapy eksportów SDK. Trzymaj funkcje pomocnicze specyficzne dla właściciela wewnątrz pakietu pluginu będącego właścicielem; promuj tylko zachowania hosta wielokrotnego użytku do ogólnych kontraktów SDK, takich jak plugin-sdk/gateway-runtime, plugin-sdk/security-runtime i plugin-sdk/plugin-config-runtime.

​
Wnętrze i odniesienie

Informacje o potoku ładowania, modelu rejestru, hakach czasu wykonywania dostawców, trasach HTTP Gateway, schematach narzędzi wiadomości, rozwiązywaniu celów kanałów, katalogach dostawców, pluginach silnika kontekstu oraz przewodniku dodawania nowej możliwości znajdziesz w Wnętrze architektury pluginów.

​
Powiązane