package.json), manifestów (openclaw.plugin.json), wpisów konfiguracji początkowej i schematów konfiguracji.
Metadane pakietu
Twójpackage.json wymaga pola openclaw, które informuje system Pluginów, co zapewnia Twój Plugin:
- Plugin kanału
- Plugin dostawcy / punkt odniesienia ClawHub
Jeśli publikujesz Plugin zewnętrznie w ClawHub, te pola
compat i build są wymagane. Kanoniczne fragmenty publikowania znajdują się w docs/snippets/plugin-publish/.Pola openclaw
Pliki punktów wejścia (względem katalogu głównego pakietu).
Lekki wpis używany tylko do konfiguracji początkowej (opcjonalny).
Metadane katalogu kanału dla powierzchni konfiguracji początkowej, selektora, szybkiego startu i statusu.
Identyfikatory dostawców rejestrowane przez ten Plugin.
Wskazówki instalacji:
npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.Flagi zachowania przy uruchamianiu.
openclaw.channel
openclaw.channel to lekkie metadane pakietu służące do wykrywania kanałów i powierzchni konfiguracji początkowej przed załadowaniem środowiska wykonawczego.
| Pole | Typ | Znaczenie |
|---|---|---|
id | string | Kanoniczny identyfikator kanału. |
label | string | Główna etykieta kanału. |
selectionLabel | string | Etykieta selektora/konfiguracji początkowej, gdy powinna różnić się od label. |
detailLabel | string | Dodatkowa etykieta szczegółów dla bogatszych katalogów kanałów i powierzchni statusu. |
docsPath | string | Ścieżka dokumentacji dla linków konfiguracji początkowej i wyboru. |
docsLabel | string | Zastępcza etykieta używana dla linków dokumentacji, gdy powinna różnić się od identyfikatora kanału. |
blurb | string | Krótki opis do onboardingu/katalogu. |
order | number | Kolejność sortowania w katalogach kanałów. |
aliases | string[] | Dodatkowe aliasy wyszukiwania dla wyboru kanału. |
preferOver | string[] | Identyfikatory Pluginów/kanałów o niższym priorytecie, które ten kanał powinien wyprzedzać. |
systemImage | string | Opcjonalna nazwa ikony/obrazu systemowego dla katalogów interfejsu kanałów. |
selectionDocsPrefix | string | Tekst prefiksu przed linkami dokumentacji w powierzchniach wyboru. |
selectionDocsOmitLabel | boolean | Pokazuj ścieżkę dokumentacji bezpośrednio zamiast etykietowanego linku dokumentacji w tekście wyboru. |
selectionExtras | string[] | Dodatkowe krótkie ciągi dołączane w tekście wyboru. |
markdownCapable | boolean | Oznacza kanał jako obsługujący Markdown na potrzeby decyzji o formatowaniu wychodzącym. |
exposure | object | Kontrolki widoczności kanału dla konfiguracji początkowej, list skonfigurowanych i powierzchni dokumentacji. |
quickstartAllowFrom | boolean | Włącza ten kanał do standardowego przepływu konfiguracji początkowej szybkiego startu allowFrom. |
forceAccountBinding | boolean | Wymaga jawnego powiązania konta nawet wtedy, gdy istnieje tylko jedno konto. |
preferSessionLookupForAnnounceTarget | boolean | Preferuj wyszukiwanie sesji podczas rozwiązywania celów ogłoszeń dla tego kanału. |
exposure obsługuje:
configured: uwzględnij kanał w powierzchniach list skonfigurowanych/statusowychsetup: uwzględnij kanał w interaktywnych selektorach konfiguracji początkowej/konfiguracjidocs: oznacz kanał jako publiczny w powierzchniach dokumentacji/nawigacji
showConfigured i showInSetup pozostają obsługiwane jako starsze aliasy. Preferuj exposure.openclaw.install
openclaw.install to metadane pakietu, a nie metadane manifestu.
| Pole | Typ | Znaczenie |
|---|---|---|
clawhubSpec | string | Kanoniczna specyfikacja ClawHub dla instalacji/aktualizacji i przepływów instalacji na żądanie podczas onboardingu. |
npmSpec | string | Kanoniczna specyfikacja npm dla awaryjnych przepływów instalacji/aktualizacji. |
localPath | string | Lokalna ścieżka deweloperska lub ścieżka instalacji w pakiecie. |
defaultChoice | "clawhub" | "npm" | "local" | Preferowane źródło instalacji, gdy dostępnych jest wiele źródeł. |
minHostVersion | string | Minimalna obsługiwana wersja OpenClaw w formie >=x.y.z lub >=x.y.z-prerelease. |
expectedIntegrity | string | Oczekiwany ciąg integralności dystrybucji npm, zwykle sha512-..., dla przypiętych instalacji. |
allowInvalidConfigRecovery | boolean | Pozwala przepływom ponownej instalacji wbudowanych Pluginów odzyskać działanie po określonych awariach przestarzałej konfiguracji. |
requiredPlatformPackages | string[] | Wymagane specyficzne dla platformy aliasy npm weryfikowane podczas instalacji npm. |
Zachowanie onboardingu
Zachowanie onboardingu
Interaktywny onboarding używa także
openclaw.install dla powierzchni instalacji na żądanie. Jeśli Twój Plugin udostępnia wybory uwierzytelniania dostawcy lub metadane konfiguracji początkowej/katalogu kanału przed załadowaniem środowiska wykonawczego, onboarding może pokazać ten wybór, poprosić o instalację z ClawHub, npm lub lokalnego źródła, zainstalować albo włączyć Plugin, a następnie kontynuować wybrany przepływ. Wybory onboardingu ClawHub używają clawhubSpec i są preferowane, gdy są obecne; wybory npm wymagają zaufanych metadanych katalogu ze specyfikacją rejestru npmSpec; dokładne wersje i expectedIntegrity są opcjonalnymi przypięciami npm. Jeśli expectedIntegrity jest obecne, przepływy instalacji/aktualizacji wymuszają je dla npm. Przechowuj metadane „co pokazać” w openclaw.plugin.json, a metadane „jak to zainstalować” w package.json.Wymuszanie minHostVersion
Wymuszanie minHostVersion
Jeśli ustawiono
minHostVersion, wymuszają je zarówno instalacja, jak i ładowanie rejestru manifestów niewbudowanych Pluginów. Starsze hosty pomijają zewnętrzne Pluginy; nieprawidłowe ciągi wersji są odrzucane. Zakłada się, że wbudowane Pluginy źródłowe mają tę samą wersję co checkout hosta.Przypięte instalacje npm
Przypięte instalacje npm
W przypadku przypiętych instalacji npm zachowaj dokładną wersję w
npmSpec i dodaj oczekiwaną integralność artefaktu:Zakres allowInvalidConfigRecovery
Zakres allowInvalidConfigRecovery
allowInvalidConfigRecovery nie jest ogólnym obejściem uszkodzonych konfiguracji. Służy wyłącznie do wąskiego odzyskiwania wbudowanych Pluginów, aby ponowna instalacja/konfiguracja początkowa mogła naprawić znane pozostałości po aktualizacji, takie jak brakująca ścieżka wbudowanego Pluginu lub przestarzały wpis channels.<id> dla tego samego Pluginu. Jeśli konfiguracja jest uszkodzona z niezwiązanych powodów, instalacja nadal kończy się w trybie fail-closed i informuje operatora, aby uruchomił openclaw doctor --fix.Odroczone pełne ładowanie
Pluginy kanałów mogą włączyć odroczone ładowanie za pomocą:setupEntry podczas fazy uruchamiania przed rozpoczęciem nasłuchiwania, nawet dla już skonfigurowanych kanałów. Pełny wpis ładuje się po tym, jak Gateway zacznie nasłuchiwać.
Jeśli Twój wpis konfiguracji początkowej/pełny wpis rejestruje metody RPC Gateway, utrzymuj je pod prefiksem specyficznym dla Pluginu. Zarezerwowane główne przestrzenie nazw administracyjnych (config.*, exec.approvals.*, wizard.*, update.*) pozostają własnością rdzenia i zawsze rozwiązują się do operator.admin.
Manifest Pluginu
Każdy natywny Plugin musi dostarczaćopenclaw.plugin.json w katalogu głównym pakietu. OpenClaw używa go do walidacji konfiguracji bez wykonywania kodu Pluginu.
kind i channels:
Publikowanie w ClawHub
Dla pakietów Pluginów użyj polecenia ClawHub właściwego dla pakietu:Starszy alias publikowania tylko dla umiejętności jest przeznaczony dla Skills. Pakiety Pluginów powinny zawsze używać
clawhub package publish.Wpis konfiguracji
Pliksetup-entry.ts jest lekką alternatywą dla index.ts, którą OpenClaw ładuje, gdy potrzebuje tylko powierzchni konfiguracji (wdrażania, naprawy konfiguracji, inspekcji wyłączonego kanału).
defineBundledChannelSetupEntry(...) z openclaw/plugin-sdk/channel-entry-contract zamiast defineSetupPluginEntry(...). Ten wbudowany kontrakt obsługuje także opcjonalny eksport runtime, dzięki czemu okablowanie uruchomieniowe w czasie konfiguracji może pozostać lekkie i jawne.
Kiedy OpenClaw używa setupEntry zamiast pełnego wpisu
Kiedy OpenClaw używa setupEntry zamiast pełnego wpisu
- Kanał jest wyłączony, ale potrzebuje powierzchni konfiguracji/wdrażania.
- Kanał jest włączony, ale nieskonfigurowany.
- Włączone jest odroczone ładowanie (
deferConfiguredChannelFullLoadUntilAfterListen).
Co musi zarejestrować setupEntry
Co musi zarejestrować setupEntry
- Obiekt Pluginu kanału (przez
defineSetupPluginEntry). - Wszystkie trasy HTTP wymagane przed nasłuchem Gateway.
- Wszystkie metody Gateway potrzebne podczas uruchamiania.
config.* lub update.*.Czego setupEntry NIE powinien zawierać
Czego setupEntry NIE powinien zawierać
- Rejestracji CLI.
- Usług działających w tle.
- Ciężkich importów uruchomieniowych (kryptografia, SDK).
- Metod Gateway potrzebnych dopiero po uruchomieniu.
Wąskie importy pomocników konfiguracji
Dla gorących ścieżek przeznaczonych tylko do konfiguracji preferuj wąskie szwy pomocników konfiguracji zamiast szerszego parasolaplugin-sdk/setup, gdy potrzebujesz tylko części powierzchni konfiguracji:
| Ścieżka importu | Do czego jej używać | Kluczowe eksporty |
|---|---|---|
plugin-sdk/setup-runtime | pomocniki uruchomieniowe czasu konfiguracji, które pozostają dostępne w setupEntry / odroczonym uruchamianiu kanału | createSetupTranslator, createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime | przestarzały alias zgodności; użyj plugin-sdk/setup-runtime | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools | pomocniki CLI/archiwum/dokumentacji dla konfiguracji/instalacji | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
plugin-sdk/setup, gdy chcesz pełny współdzielony zestaw narzędzi konfiguracji, w tym pomocniki łatek konfiguracji, takie jak moveSingleAccountChannelSectionToDefaultAccount(...).
Użyj createSetupTranslator(...) dla stałych tekstów kreatora konfiguracji. Podąża on za ustawieniami regionalnymi kreatora CLI (OPENCLAW_LOCALE, następnie zmiennymi ustawień regionalnych systemu) i wraca do angielskiego. Tekst konfiguracji specyficzny dla Pluginu trzymaj w kodzie należącym do Pluginu, a współdzielonych kluczy katalogu używaj tylko dla wspólnych etykiet konfiguracji, tekstu statusu i oficjalnych tekstów konfiguracji wbudowanych Pluginów.
Adaptery łatek konfiguracji pozostają bezpieczne na gorącej ścieżce podczas importu. Ich wyszukiwanie powierzchni kontraktu wbudowanej promocji pojedynczego konta jest leniwe, więc zaimportowanie plugin-sdk/setup-runtime nie ładuje z wyprzedzeniem odkrywania powierzchni kontraktu wbudowanego, zanim adapter zostanie faktycznie użyty.
Promocja pojedynczego konta należąca do kanału
Gdy kanał przechodzi z jednokontowej konfiguracji najwyższego poziomu nachannels.<id>.accounts.*, domyślne współdzielone zachowanie polega na przeniesieniu promowanych wartości zakresu konta do accounts.default.
Kanały wbudowane mogą zawęzić lub zastąpić tę promocję przez swoją powierzchnię kontraktu konfiguracji:
singleAccountKeysToMove: dodatkowe klucze najwyższego poziomu, które powinny zostać przeniesione do promowanego kontanamedAccountPromotionKeys: gdy nazwane konta już istnieją, tylko te klucze przenoszą się do promowanego konta; współdzielone klucze polityki/dostarczania pozostają w korzeniu kanałuresolveSingleAccountPromotionTarget(...): wybiera, które istniejące konto otrzymuje promowane wartości
Matrix jest obecnym wbudowanym przykładem. Jeśli istnieje dokładnie jedno nazwane konto Matrix albo jeśli
defaultAccount wskazuje istniejący niekanoniczny klucz, taki jak Ops, promocja zachowuje to konto zamiast tworzyć nowy wpis accounts.default.Schemat konfiguracji
Konfiguracja Pluginu jest sprawdzana względem JSON Schema w manifeście. Użytkownicy konfigurują Pluginy przez:api.pluginConfig podczas rejestracji.
Dla konfiguracji specyficznej dla kanału użyj zamiast tego sekcji konfiguracji kanału:
Tworzenie schematów konfiguracji kanałów
UżyjbuildChannelConfigSchema, aby przekonwertować schemat Zod na opakowanie ChannelConfigSchema używane przez artefakty konfiguracji należące do Pluginu:
openclaw.plugin.json#channelConfigs, aby schemat konfiguracji, konfiguracja i powierzchnie UI mogły sprawdzać channels.<id> bez ładowania kodu uruchomieniowego.
Kreatory konfiguracji
Pluginy kanałów mogą dostarczać interaktywne kreatory konfiguracji dlaopenclaw onboard. Kreator jest obiektem ChannelSetupWizard w ChannelPlugin:
ChannelSetupWizard obsługuje credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize i więcej. Pełne przykłady znajdziesz w pakietach wbudowanych Pluginów (na przykład w Pluginie Discord src/channel.setup.ts).
Współdzielone monity allowFrom
Współdzielone monity allowFrom
Dla monitów listy dozwolonych DM, które potrzebują tylko standardowego przepływu
note -> prompt -> parse -> merge -> patch, preferuj współdzielone pomocniki konfiguracji z openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) i createNestedChannelParsedAllowFromPrompt(...).Standardowy status konfiguracji kanału
Standardowy status konfiguracji kanału
Dla bloków statusu konfiguracji kanału, które różnią się tylko etykietami, wynikami i opcjonalnymi dodatkowymi liniami, preferuj
createStandardChannelSetupStatus(...) z openclaw/plugin-sdk/setup zamiast ręcznego tworzenia tego samego obiektu status w każdym Pluginie.Opcjonalna powierzchnia konfiguracji kanału
Opcjonalna powierzchnia konfiguracji kanału
Dla 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 także niższego poziomu konstruktory createOptionalChannelSetupAdapter(...) i createOptionalChannelSetupWizard(...), gdy potrzebujesz tylko jednej połowy tej opcjonalnej powierzchni instalacji.Wygenerowany opcjonalny adapter/kreator zamyka się bezpiecznie przy rzeczywistych zapisach konfiguracji. Ponownie używa jednego komunikatu o wymaganej instalacji w validateInput, applyAccountConfig i finalize, a także dołącza link do dokumentacji, gdy ustawiono docsPath.Pomocniki konfiguracji oparte na pliku binarnym
Pomocniki konfiguracji oparte na pliku binarnym
Dla interfejsów konfiguracji opartych na pliku binarnym preferuj współdzielone delegowane pomocniki zamiast kopiować to samo powiązanie pliku binarnego/statusu do każdego kanału:
createDetectedBinaryStatus(...)dla bloków stanu, które różnią się tylko etykietami, wskazówkami, ocenami i wykrywaniem binarnymcreateCliPathTextInput(...)dla pól tekstowych opartych na ścieżcecreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)icreateDelegatedResolveConfigured(...), gdysetupEntrymusi leniwie przekazać obsługę do cięższego pełnego kreatoracreateDelegatedTextInputShouldPrompt(...), gdysetupEntrymusi tylko delegować decyzjętextInputs[*].shouldPrompt
Publikowanie i instalowanie
Zewnętrzne Pluginy: opublikuj w ClawHub, a następnie zainstaluj:- npm
- Tylko ClawHub
- Specyfikacja pakietu npm
W przypadku instalacji pochodzących z npm
openclaw plugins install instaluje pakiet w projekcie dla danego Pluginu pod ~/.openclaw/npm/projects z wyłączonymi skryptami cyklu życia. Utrzymuj drzewa zależności Pluginów jako czysty JS/TS i unikaj pakietów wymagających kompilacji postinstall.Uruchamianie Gateway nie instaluje zależności Pluginów. Przepływy instalacji npm/git/ClawHub odpowiadają za zbieżność zależności; lokalne Pluginy muszą mieć już zainstalowane swoje zależności.
Powiązane
- Tworzenie Pluginów — przewodnik krok po kroku na początek
- Manifest Pluginu — pełna referencja schematu manifestu
- Punkty wejścia SDK —
definePluginEntryidefineChannelPluginEntry