Dokumentacja referencyjna dotycząca pakowania Plugin (Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
package.json metadata), 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, co udostępnia Twój Plugin:
- Plugin kanału
- Plugin dostawcy / bazowy 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 wyłącznie do konfiguracji początkowej (opcjonalny).
Metadane katalogowe 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 podczas uruchamiania.
openclaw.channel
openclaw.channel to lekkie metadane pakietu służące do wykrywania kanałów i powierzchni konfiguracji początkowej przed załadowaniem środowiska uruchomieniowego.
| 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ółowa 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 do dokumentacji, gdy powinna różnić się od identyfikatora kanału. |
blurb | string | Krótki opis onboardingowy/katalogowy. |
order | number | Kolejność sortowania w katalogach kanałów. |
aliases | string[] | Dodatkowe aliasy wyszukiwania dla wyboru kanału. |
preferOver | string[] | Identyfikatory Plugin/kanałów o niższym priorytecie, które ten kanał powinien wyprzedzać. |
systemImage | string | Opcjonalna nazwa ikony/obrazu systemowego dla katalogów UI kanałów. |
selectionDocsPrefix | string | Tekst prefiksu przed linkami do dokumentacji w powierzchniach wyboru. |
selectionDocsOmitLabel | boolean | Pokazuj ścieżkę dokumentacji bezpośrednio zamiast etykietowanego linku do 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 dla 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 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 skonfigurowanych powierzchniach listowania w stylu statususetup: 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 oraz przepływów onboardingowych instalacji na żądanie. |
npmSpec | string | Kanoniczna specyfikacja npm dla zapasowych przepływów instalacji/aktualizacji. |
localPath | string | Lokalna ścieżka deweloperska lub ścieżka instalacji dołączonej. |
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 npm dist, zwykle sha512-..., dla instalacji przypiętych. |
allowInvalidConfigRecovery | boolean | Pozwala przepływom ponownej instalacji dołączonego Plugin odzyskiwać się po określonych awariach nieaktualnej konfiguracji. |
Zachowanie onboardingu
Zachowanie onboardingu
Interaktywny onboarding używa również
openclaw.install dla powierzchni instalacji na żądanie. Jeśli Twój Plugin udostępnia opcje uwierzytelniania dostawcy lub metadane konfiguracji początkowej/katalogu kanału przed załadowaniem środowiska uruchomieniowego, onboarding może pokazać ten wybór, poprosić o instalację z ClawHub, npm lub lokalną, zainstalować albo włączyć Plugin, a następnie kontynuować wybrany przepływ. Opcje onboardingu ClawHub używają clawhubSpec i są preferowane, gdy są obecne; opcje 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 egzekwują je dla npm. Metadane „co pokazać” trzymaj w openclaw.plugin.json, a metadane „jak to zainstalować” w package.json.Egzekwowanie minHostVersion
Egzekwowanie minHostVersion
Jeśli ustawiono
minHostVersion, egzekwują je zarówno instalacja, jak i ładowanie rejestru manifestów dla niedołączonych Plugin. Starsze hosty pomijają zewnętrzne Plugin; nieprawidłowe ciągi wersji są odrzucane. Zakłada się, że dołączone źródłowe Plugin mają tę samą wersję co checkout hosta.Przypięte instalacje npm
Przypięte instalacje npm
Dla 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 dla uszkodzonych konfiguracji. Służy wyłącznie do wąskiego odzyskiwania dołączonego Plugin, aby ponowna instalacja/konfiguracja początkowa mogła naprawić znane pozostałości po aktualizacji, takie jak brakująca ścieżka dołączonego Plugin lub nieaktualny wpis channels.<id> dla tego samego Plugin. Jeśli konfiguracja jest uszkodzona z niezwiązanych powodów, instalacja nadal kończy się niepowodzeniem w trybie zamkniętym i informuje operatora, aby uruchomił openclaw doctor --fix.Odroczone pełne ładowanie
Plugin kanału mogą włączyć odroczone ładowanie za pomocą:setupEntry w fazie uruchamiania przed nasłuchiwaniem, nawet dla już skonfigurowanych kanałów. Pełny wpis ładuje się po rozpoczęciu nasłuchiwania przez Gateway.
Jeśli Twój wpis konfiguracji początkowej/pełny wpis rejestruje metody RPC Gateway, trzymaj je pod prefiksem specyficznym dla Plugin. Zarezerwowane podstawowe przestrzenie nazw administracyjnych (config.*, exec.approvals.*, wizard.*, update.*) pozostają własnością core i zawsze rozwiązują się do operator.admin.
Manifest Plugin
Każdy natywny Plugin musi dostarczaćopenclaw.plugin.json w katalogu głównym pakietu. OpenClaw używa go do walidacji konfiguracji bez wykonywania kodu Plugin.
kind i channels:
Publikowanie w ClawHub
Dla pakietów Plugin użyj polecenia ClawHub specyficznego dla pakietu:Starszy alias publikowania tylko dla Skills jest przeznaczony dla Skills. Pakiety Plugin 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 (onboarding, naprawa konfiguracji, inspekcja wyłączonego kanału).
defineBundledChannelSetupEntry(...) z openclaw/plugin-sdk/channel-entry-contract zamiast defineSetupPluginEntry(...). Ten dołączony kontrakt obsługuje również opcjonalny eksport runtime, dzięki czemu okablowanie runtime podczas konfiguracji może 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 potrzebuje powierzchni konfiguracji/onboardingu.
- Kanał jest włączony, ale nieskonfigurowany.
- Włączone jest odroczone ładowanie (
deferConfiguredChannelFullLoadUntilAfterListen).
What setupEntry must register
What setupEntry must register
- Obiekt Plugin kanału (przez
defineSetupPluginEntry). - Wszelkie trasy HTTP wymagane przed nasłuchem Gateway.
- Wszelkie metody Gateway potrzebne podczas uruchamiania.
config.* lub update.*.What setupEntry should NOT include
What setupEntry should NOT include
- Rejestracje CLI.
- Usługi działające w tle.
- Ciężkie importy runtime (kryptografia, SDK).
- Metody Gateway potrzebne dopiero po uruchomieniu.
Wąskie importy pomocników konfiguracji
Dla gorących ścieżek przeznaczonych tylko do konfiguracji preferuj wąskie seams pomocników konfiguracji zamiast szerszego parasolaplugin-sdk/setup, gdy potrzebujesz tylko części powierzchni konfiguracji:
| Ścieżka importu | Do czego służy | Kluczowe eksporty |
|---|---|---|
plugin-sdk/setup-runtime | pomocnicy runtime czasu konfiguracji, którzy pozostają dostępni w setupEntry / odroczonym uruchamianiu kanału | 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 | pomocnicy konfiguracji/instalacji CLI/archiwów/dokumentacji | 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(...).
Adaptery łatek konfiguracji pozostają bezpieczne dla gorącej ścieżki przy imporcie. Ich dołączone wyszukiwanie powierzchni kontraktu promocji pojedynczego konta jest leniwe, więc importowanie plugin-sdk/setup-runtime nie ładuje z wyprzedzeniem wykrywania dołączonej powierzchni kontraktu, zanim adapter zostanie faktycznie użyty.
Promocja pojedynczego konta zarządzana przez kanał
Gdy kanał aktualizuje się z konfiguracji najwyższego poziomu dla pojedynczego konta dochannels.<id>.accounts.*, domyślne współdzielone zachowanie polega na przeniesieniu promowanych wartości o zakresie konta do accounts.default.
Dołączone kanały mogą zawęzić lub nadpisać tę promocję przez swoją powierzchnię kontraktu konfiguracji:
singleAccountKeysToMove: dodatkowe klucze najwyższego poziomu, które powinny zostać przeniesione do promowanego kontanamedAccountPromotionKeys: gdy konta nazwane już istnieją, tylko te klucze trafiają do promowanego konta; współdzielone klucze polityki/dostarczania pozostają w katalogu głównym kanałuresolveSingleAccountPromotionTarget(...): wybiera, które istniejące konto otrzyma promowane wartości
Matrix jest bieżącym dołączonym przykładem. Jeśli istnieje dokładnie jedno nazwane konto Matrix albo jeśli
defaultAccount wskazuje na istniejący klucz niekanoniczny, taki jak Ops, promocja zachowuje to konto zamiast tworzyć nowy wpis accounts.default.Schemat konfiguracji
Konfiguracja Plugin jest walidowana 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:
Budowanie schematów konfiguracji kanału
UżyjbuildChannelConfigSchema, aby przekonwertować schemat Zod na opakowanie ChannelConfigSchema używane przez artefakty konfiguracji należące do Plugin:
openclaw.plugin.json#channelConfigs, aby schemat konfiguracji, konfiguracja i powierzchnie UI mogły sprawdzać channels.<id> bez ładowania kodu runtime.
Kreatory konfiguracji
Pluginy kanałów mogą udostępniać 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 dołączonych Pluginów (na przykład Plugin Discord src/channel.setup.ts).
Shared allowFrom prompts
Shared allowFrom prompts
Standard channel setup status
Standard channel setup status
W przypadku bloków statusu konfiguracji kanału, które różnią się tylko etykietami, wynikami i opcjonalnymi dodatkowymi wierszami, preferuj
createStandardChannelSetupStatus(...) z openclaw/plugin-sdk/setup zamiast ręcznie tworzyć ten sam obiekt status w każdym Plugin.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ż niższopoziomowe konstruktory createOptionalChannelSetupAdapter(...) i createOptionalChannelSetupWizard(...), gdy potrzebujesz tylko jednej połowy tej opcjonalnej powierzchni instalacji.Wygenerowany opcjonalny adapter/kreator bezpiecznie odmawia rzeczywistych zapisów konfiguracji. Ponownie używa jednego komunikatu o wymaganej instalacji w validateInput, applyAccountConfig i finalize oraz dołącza link do dokumentacji, gdy ustawione jest docsPath.Binary-backed setup helpers
Binary-backed setup helpers
W przypadku UI konfiguracji wspieranych przez pliki binarne preferuj współdzielone delegowane pomocniki zamiast kopiować to samo połączenie binarne/statusu do każdego kanału:
createDetectedBinaryStatus(...)dla bloków statusu, które różnią się tylko etykietami, wskazówkami, wynikami i wykrywaniem pliku binarnegocreateCliPathTextInput(...)dla wejść 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
- ClawHub only
- npm package spec
W przypadku instalacji ze źródeł npm
openclaw plugins install instaluje pakiet w ~/.openclaw/npm z wyłączonymi skryptami cyklu życia. Utrzymuj drzewa zależności Pluginów jako czyste JS/TS i unikaj pakietów wymagających kompilacji przez postinstall.Uruchomienie Gateway nie instaluje zależności Pluginów. Przepływy instalacji npm/git/ClawHub odpowiadają za uzgodnienie zależności; lokalne Pluginy muszą mieć już zainstalowane swoje zależności.
Powiązane
- Tworzenie Pluginów — przewodnik krok po kroku ułatwiający rozpoczęcie pracy
- Manifest Pluginu — pełna dokumentacja schematu manifestu
- Punkty wejścia SDK —
definePluginEntryidefineChannelPluginEntry