package.json), manifestów (openclaw.plugin.json), punktów konfiguracji i schematów konfiguracji.
Metadane pakietu
Plikpackage.json musi zawierać pole openclaw, które informuje system Pluginów, co udostępnia Twój Plugin:
- Plugin kanału
- Plugin dostawcy / konfiguracja bazowa ClawHub
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 stanusetup: uwzględnia kanał w interaktywnych selektorach konfiguracjidocs: 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.
Zachowanie podczas wdrażania
Zachowanie podczas wdrażania
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.Wymuszanie minHostVersion
Wymuszanie minHostVersion
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.Instalacje npm przypięte do wersji
Instalacje npm przypięte do wersji
W przypadku instalacji npm przypiętych do wersji zachowaj dokładną wersję w
npmSpec i dodaj oczekiwaną integralność artefaktu:Zakres allowInvalidConfigRecovery
Zakres allowInvalidConfigRecovery
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ą: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.
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ć plikopenclaw.plugin.json w katalogu głównym pakietu. OpenClaw używa go do walidowania konfiguracji bez wykonywania kodu Pluginu.
channels (a w przypadku Pluginów dostawców dodaj providers):
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):
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.
When OpenClaw uses setupEntry instead of the full entry
When OpenClaw uses setupEntry instead of the full entry
- Kanał jest wyłączony, ale wymaga powierzchni konfiguracji lub wdrażania.
- Kanał jest włączony, ale nieskonfigurowany.
- Włączono odroczone ładowanie (
deferConfiguredChannelFullLoadUntilAfterListen).
What setupEntry must register
What setupEntry must register
- 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.
config.* lub update.*.What setupEntry should NOT include
What setupEntry should NOT include
- 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 zbiorczegoplugin-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 nachannels.<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 kontanamedAccountPromotionKeys: 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łuresolveSingleAccountPromotionTarget(...): 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ą: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żyjbuildChannelConfigSchema, aby przekształcić schemat Zod w opakowanie ChannelConfigSchema używane przez artefakty konfiguracji należące do Pluginu:
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 dlaopenclaw 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.
Standard channel setup status
Standard channel setup status
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.Optional channel setup surface
Optional channel setup surface
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.Pomocnicze funkcje konfiguracji opartej na plikach binarnych
Pomocnicze funkcje konfiguracji opartej na plikach binarnych
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 binarnegocreateCliPathTextInput(...)dla pól tekstowych zawierających ścieżkicreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)icreateDelegatedResolveConfigured(...), gdysetupEntrymusi leniwie przekazywać obsługę do bardziej rozbudowanego, pełnego kreatoracreateDelegatedTextInputShouldPrompt(...), gdysetupEntrymusi jedynie delegować decyzjętextInputs[*].shouldPrompt
Publikowanie i instalowanie
Zewnętrzne pluginy: opublikuj w ClawHub, a następnie zainstaluj:- npm
- Tylko ClawHub
- Specyfikacja pakietu npm
clawhub:, npm:, git: lub npm-pack: — zobacz Zarządzanie pluginami.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.
Powiązane materiały
- Tworzenie pluginów — przewodnik wprowadzający krok po kroku
- Manifest pluginu — pełna dokumentacja schematu manifestu
- Punkty wejścia SDK —
definePluginEntryidefineChannelPluginEntry