Skip to main content
Dokumentacja pakowania Pluginów (metadane package.json), manifestów (openclaw.plugin.json), punktów konfiguracji i schematów konfiguracji.
Szukasz przewodnika krok po kroku? Przewodniki praktyczne omawiają pakowanie w kontekście: Pluginy kanałów i Pluginy dostawców.

Metadane pakietu

Plik package.json musi zawierać pole openclaw, które informuje system Pluginów, co udostępnia Twój Plugin:
Publikowanie zewnętrzne w ClawHub wymaga pól compat i build. Kanoniczne fragmenty dotyczące publikowania znajdują się w docs/snippets/plugin-publish/.

Pola openclaw

string[]
Pliki punktów wejścia (względem katalogu głównego pakietu). Prawidłowe źródłowe punkty wejścia do programowania w obszarze roboczym i kopii roboczej git.
string[]
Skompilowane odpowiedniki JavaScript dla extensions, preferowane, gdy OpenClaw ładuje zainstalowany pakiet npm. Kolejność rozwiązywania wersji źródłowych i skompilowanych opisano w sekcji Punkty wejścia SDK.
string
Lekki punkt wejścia używany wyłącznie podczas konfiguracji (opcjonalny).
string
Skompilowany odpowiednik JavaScript dla setupEntry. Wymaga również ustawienia setupEntry.
object
Zastępcza tożsamość Pluginu { id, label }, używana, gdy Plugin nie zawiera metadanych kanału ani dostawcy, z których można wyznaczyć identyfikator lub etykietę.
object
Metadane katalogowe kanału używane w interfejsach konfiguracji, wyboru, szybkiego startu i stanu.
object
Wskazówki instalacyjne: npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery, requiredPlatformPackages.
object
Flagi zachowania podczas uruchamiania.
object
Zakres wersji pluginApi obsługiwany przez ten Plugin. Wymagany przy publikowaniu zewnętrznym w ClawHub.
Identyfikatory dostawców (providers: string[]) są metadanymi manifestu, a nie pakietu. Zadeklaruj je w openclaw.plugin.json, a nie tutaj — zobacz Manifest Pluginu.

openclaw.channel

openclaw.channel to lekkie metadane pakietu służące do wykrywania kanałów oraz wyświetlania interfejsów konfiguracji przed załadowaniem środowiska wykonawczego. Przykład:
exposure obsługuje:
  • configured: uwzględnia kanał w widokach list skonfigurowanych kanałów i widokach stanu
  • setup: uwzględnia kanał w interaktywnych selektorach konfiguracji
  • docs: oznacza kanał jako publicznie widoczny w dokumentacji i nawigacji
showConfigured i showInSetup pozostają obsługiwane jako starsze aliasy. Preferuj exposure.

openclaw.install

openclaw.install to metadane pakietu, a nie manifestu.
Interaktywne wdrażanie używa openclaw.install w interfejsach instalacji na żądanie: jeśli Plugin udostępnia opcje uwierzytelniania dostawcy albo metadane konfiguracji lub katalogu kanałów przed załadowaniem środowiska wykonawczego, proces wdrażania może poprosić o instalację z ClawHub, npm lub lokalnego źródła, zainstalować lub włączyć Plugin, a następnie kontynuować wybrany proces. Opcje ClawHub używają clawhubSpec i są preferowane, gdy to pole jest obecne; opcje npm wymagają zaufanych metadanych katalogu ze specyfikacją rejestru npmSpec (dokładne wersje i expectedIntegrity są opcjonalnymi przypięciami, wymuszanymi podczas instalacji lub aktualizacji, jeśli je ustawiono). Informacje „co wyświetlić” przechowuj w openclaw.plugin.json, a „jak to zainstalować” — w package.json.
Jeśli ustawiono minHostVersion, wymaganie to jest egzekwowane zarówno podczas instalacji, jak i ładowania niedołączonych Pluginów z rejestru manifestów. Starsze hosty pomijają zewnętrzne Pluginy; nieprawidłowe ciągi wersji są odrzucane. Zakłada się, że dołączone źródłowe Pluginy mają tę samą wersję co kopia robocza hosta.
W przypadku instalacji npm przypiętych do wersji zachowaj dokładną wersję w npmSpec i dodaj oczekiwaną integralność artefaktu:
allowInvalidConfigRecovery nie jest ogólnym sposobem obchodzenia uszkodzonych konfiguracji. Służy wyłącznie do wąsko określonego odzyskiwania dołączonych Pluginów, umożliwiając ponownej instalacji lub konfiguracji naprawę znanych pozostałości po aktualizacji, takich jak brakująca ścieżka dołączonego Pluginu albo nieaktualny wpis channels.<id> dotyczący tego samego Pluginu. Jeśli konfiguracja jest uszkodzona z innych powodów, instalacja nadal kończy się bezpiecznym błędem i informuje operatora o konieczności uruchomienia openclaw doctor --fix.

Odroczone pełne ładowanie

Pluginy kanałów mogą włączyć odroczone ładowanie za pomocą:
Po włączeniu OpenClaw ładuje tylko setupEntry w fazie uruchamiania przed rozpoczęciem nasłuchiwania, nawet w przypadku już skonfigurowanych kanałów. Pełny punkt wejścia jest ładowany po rozpoczęciu nasłuchiwania przez Gateway.
Włączaj odroczone ładowanie tylko wtedy, gdy setupEntry rejestruje wszystko, czego Gateway potrzebuje przed rozpoczęciem nasłuchiwania: rejestrację kanału, trasy HTTP i metody Gateway. Jeśli pełny punkt wejścia odpowiada za wymagane funkcje startowe, zachowaj zachowanie domyślne.
Jeśli punkty wejścia konfiguracji lub pełnego ładowania rejestrują metody RPC Gateway, umieść je pod prefiksem właściwym dla danego Pluginu. Zastrzeżone przestrzenie nazw administracyjnych rdzenia (config.*, exec.approvals.*, wizard.*, update.*) pozostają własnością rdzenia i są zawsze normalizowane do operator.admin.

Manifest Pluginu

Każdy natywny Plugin musi zawierać plik openclaw.plugin.json w katalogu głównym pakietu. OpenClaw używa go do walidowania konfiguracji bez wykonywania kodu Pluginu.
W przypadku Pluginów kanałów dodaj channels (a w przypadku Pluginów dostawców dodaj providers):
Nawet Pluginy bez konfiguracji muszą zawierać schemat. Pusty schemat jest prawidłowy:
Pełną dokumentację schematu zawiera strona Manifest Pluginu.

Publikowanie w ClawHub

Pakiety Skills i Pluginów korzystają z oddzielnych poleceń publikowania w ClawHub. W przypadku pakietów Pluginów użyj polecenia przeznaczonego dla pakietów:
clawhub skill publish <path> to inne polecenie, służące do publikowania folderu Skills, a nie pakietu Pluginu. Zobacz Publikowanie w ClawHub.

Punkt wejścia konfiguracji

setup-entry.ts to lekka alternatywa dla index.ts, którą OpenClaw ładuje, gdy potrzebuje tylko powierzchni konfiguracji (wdrażania, naprawy konfiguracji, inspekcji wyłączonego kanału):
Pozwala to uniknąć ładowania ciężkiego kodu środowiska wykonawczego (bibliotek kryptograficznych, rejestracji CLI, usług działających w tle) podczas procesów konfiguracji. Kanały dołączone do obszaru roboczego, które przechowują bezpieczne dla konfiguracji eksporty w modułach pomocniczych, mogą używać defineBundledChannelSetupEntry(...) z openclaw/plugin-sdk/channel-entry-contract zamiast defineSetupPluginEntry(...). Ten kontrakt dołączonego kanału obsługuje również opcjonalny eksport runtime, dzięki czemu powiązania środowiska wykonawczego na etapie konfiguracji mogą pozostać lekkie i jawne.
  • Kanał jest wyłączony, ale wymaga powierzchni konfiguracji lub wdrażania.
  • Kanał jest włączony, ale nieskonfigurowany.
  • Włączono odroczone ładowanie (deferConfiguredChannelFullLoadUntilAfterListen).
  • Obiekt Pluginu kanału (za pośrednictwem defineSetupPluginEntry).
  • Wszystkie trasy HTTP wymagane przed rozpoczęciem nasłuchiwania przez Gateway.
  • Wszystkie metody Gateway potrzebne podczas uruchamiania.
Te metody Gateway używane podczas uruchamiania nadal powinny unikać zastrzeżonych przestrzeni nazw administracyjnych rdzenia, takich jak config.* lub update.*.
  • Rejestracji CLI.
  • Usług działających w tle.
  • Ciężkich importów środowiska wykonawczego (kryptografia, zestawy SDK).
  • Metod Gateway potrzebnych dopiero po uruchomieniu.

Wąskie importy pomocnicze konfiguracji

W przypadku intensywnie używanych ścieżek przeznaczonych wyłącznie do konfiguracji preferuj wąskie interfejsy pomocnicze konfiguracji zamiast szerszego modułu zbiorczego plugin-sdk/setup, jeśli potrzebujesz tylko części powierzchni konfiguracji: Użyj szerszego interfejsu plugin-sdk/setup, jeśli potrzebujesz pełnego wspólnego zestawu narzędzi konfiguracyjnych, w tym funkcji pomocniczych do modyfikowania konfiguracji, takich jak moveSingleAccountChannelSectionToDefaultAccount(...). Używaj createSetupTranslator(...) do stałych tekstów kreatora konfiguracji. Funkcja ta stosuje ustawienia regionalne kreatora CLI (OPENCLAW_LOCALE, a następnie systemowe zmienne ustawień regionalnych) i w razie potrzeby używa języka angielskiego. Teksty konfiguracji właściwe dla Pluginu przechowuj w kodzie należącym do Pluginu, a współdzielonych kluczy katalogu używaj wyłącznie do wspólnych etykiet konfiguracji, tekstów stanu i tekstów konfiguracji oficjalnych dołączonych Pluginów. Adaptery modyfikowania konfiguracji pozostają bezpieczne dla intensywnie używanych ścieżek już podczas importu. Wyszukiwanie powierzchni kontraktu dołączonego kanału dotyczącej promowania pojedynczego konta jest leniwe, dlatego importowanie plugin-sdk/setup-runtime nie powoduje natychmiastowego ładowania mechanizmu wykrywania powierzchni kontraktów dołączonych kanałów, zanim adapter zostanie faktycznie użyty.

Promowanie pojedynczego konta należące do kanału

Gdy kanał przechodzi z konfiguracji pojedynczego konta najwyższego poziomu na channels.<id>.accounts.*, domyślne współdzielone zachowanie przenosi promowane wartości dotyczące konta do accounts.default. Dołączone kanały mogą zawęzić lub zastąpić to promowanie za pośrednictwem swojej powierzchni kontraktu konfiguracji:
  • singleAccountKeysToMove: dodatkowe klucze najwyższego poziomu, które należy przenieść do promowanego konta
  • namedAccountPromotionKeys: jeśli nazwane konta już istnieją, do promowanego konta przenoszone są tylko te klucze; współdzielone klucze zasad i dostarczania pozostają w katalogu głównym kanału
  • resolveSingleAccountPromotionTarget(...): wybiera istniejące konto, które otrzyma promowane wartości
Matrix jest obecnie przykładem dołączonego kanału. Jeśli istnieje dokładnie jedno nazwane konto Matrix albo jeśli defaultAccount wskazuje istniejący niekanoniczny klucz, taki jak Ops, promowanie zachowuje to konto zamiast tworzyć nowy wpis accounts.default.

Schemat konfiguracji

Konfiguracja Pluginu jest walidowana względem schematu JSON w manifeście. Użytkownicy konfigurują Pluginy za pomocą:
Podczas rejestracji Plugin otrzymuje tę konfigurację jako api.pluginConfig. W przypadku konfiguracji właściwej dla kanału użyj zamiast tego sekcji konfiguracji kanału:

Tworzenie schematów konfiguracji kanałów

Użyj buildChannelConfigSchema, aby przekształcić schemat Zod w opakowanie ChannelConfigSchema używane przez artefakty konfiguracji należące do Pluginu:
Jeśli kontrakt jest już tworzony jako schemat JSON lub TypeBox, użyj bezpośredniej funkcji pomocniczej, aby OpenClaw mógł pominąć konwersję ze schematu Zod do schematu JSON na ścieżkach metadanych:
W przypadku Pluginów innych firm kontraktem ścieżki nieaktywnej nadal jest manifest Pluginu: odwzoruj wygenerowany schemat JSON w openclaw.plugin.json#channelConfigs, aby powierzchnie schematu konfiguracji, konfiguracji początkowej i interfejsu użytkownika mogły analizować channels.<id> bez ładowania kodu środowiska wykonawczego.

Kreatory konfiguracji

Pluginy kanałów mogą udostępniać interaktywne kreatory konfiguracji dla openclaw onboard. Kreator jest obiektem ChannelSetupWizard w ChannelPlugin:
ChannelSetupWizard obsługuje również textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize i inne elementy. Pełny przykład dołączonego Pluginu znajduje się w pliku src/setup-core.ts Pluginu Discord.
W przypadku monitów listy dozwolonych nadawców wiadomości bezpośrednich, które wymagają tylko standardowego przepływu note -> prompt -> parse -> merge -> patch, preferuj współdzielone funkcje pomocnicze konfiguracji z openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) i createNestedChannelParsedAllowFromPrompt(...).
W przypadku bloków stanu konfiguracji kanału, które różnią się tylko etykietami, ocenami i opcjonalnymi dodatkowymi wierszami, preferuj createStandardChannelSetupStatus(...) z openclaw/plugin-sdk/setup zamiast ręcznego tworzenia tego samego obiektu status w każdym Pluginie.
W przypadku opcjonalnych powierzchni konfiguracji, które powinny pojawiać się tylko w określonych kontekstach, użyj createOptionalChannelSetupSurface z openclaw/plugin-sdk/channel-setup:
plugin-sdk/channel-setup udostępnia również konstruktory niższego poziomu createOptionalChannelSetupAdapter(...) i createOptionalChannelSetupWizard(...), jeśli potrzebujesz tylko jednej części tej opcjonalnej powierzchni instalacyjnej.Wygenerowany opcjonalny adapter/kreator działa w trybie fail-closed podczas rzeczywistych zapisów konfiguracji. Ponownie wykorzystuje jeden komunikat o wymaganej instalacji w validateInput, applyAccountConfig i finalize, a gdy ustawiono docsPath, dołącza odnośnik do dokumentacji.
W przypadku interfejsów konfiguracji opartych na plikach binarnych preferuj współdzielone, delegujące funkcje pomocnicze zamiast kopiowania tej samej logiki obsługi pliku binarnego i stanu do każdego kanału:
  • createDetectedBinaryStatus(...) dla bloków stanu różniących się tylko etykietami, wskazówkami, punktacją i wykrywaniem pliku binarnego
  • createCliPathTextInput(...) dla pól tekstowych zawierających ścieżki
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...) i createDelegatedResolveConfigured(...), gdy setupEntry musi leniwie przekazywać obsługę do bardziej rozbudowanego, pełnego kreatora
  • createDelegatedTextInputShouldPrompt(...), gdy setupEntry musi jedynie delegować decyzję textInputs[*].shouldPrompt

Publikowanie i instalowanie

Zewnętrzne pluginy: opublikuj w ClawHub, a następnie zainstaluj:
Same specyfikacje pakietów są instalowane z npm podczas przełączenia przy uruchamianiu, chyba że nazwa odpowiada identyfikatorowi dołączonego lub oficjalnego pluginu — w takim przypadku OpenClaw używa zamiast tego kopii lokalnej/oficjalnej. Aby deterministycznie wybrać źródło, użyj clawhub:, npm:, git: lub npm-pack: — zobacz Zarządzanie pluginami.
Pluginy w repozytorium: umieść je w drzewie przestrzeni roboczej dołączonych pluginów; zostaną automatycznie wykryte podczas kompilacji.
W przypadku instalacji ze źródła npm polecenie openclaw plugins install instaluje pakiet w osobnym projekcie pluginu w katalogu ~/.openclaw/npm/projects, z wyłączonymi skryptami cyklu życia (--ignore-scripts). Utrzymuj drzewa zależności pluginów wyłącznie w JS/TS i unikaj pakietów wymagających kompilacji przez postinstall.
Uruchomienie Gateway nie instaluje zależności pluginów. Za ujednolicenie zależności odpowiadają procesy instalacji z npm/git/ClawHub; zależności lokalnych pluginów muszą być już zainstalowane.
Metadane dołączonych pakietów są jawne, a nie wywnioskowane ze skompilowanego kodu JavaScript podczas uruchamiania Gateway. Zależności środowiska uruchomieniowego należą do pakietu pluginu, który jest ich właścicielem; uruchamianie spakowanego OpenClaw nigdy nie naprawia ani nie powiela zależności pluginów.

Powiązane materiały