Przejdź do głównej treści

​
Punkty wejścia pluginów

Każdy plugin eksportuje domyślny obiekt entry. SDK udostępnia trzy pomocnicze funkcje do ich tworzenia.
Szukasz przewodnika krok po kroku? Zobacz Pluginy kanałów lub Pluginy providerów, aby zapoznać się z instrukcjami krok po kroku.

​
definePluginEntry

Import: openclaw/plugin-sdk/plugin-entry Dla pluginów providerów, pluginów narzędzi, pluginów hooków i wszystkiego, co nie jest kanałem wiadomości. 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
  },
});
PoleTypWymaganeDomyślnie
idstringTak—
namestringTak—
descriptionstringTak—
kindstringNie—
configSchemaOpenClawPluginConfigSchema | () => OpenClawPluginConfigSchemaNieSchemat pustego obiektu
register(api: OpenClawPluginApi) => voidTak—
  • id musi odpowiadać manifestowi openclaw.plugin.json.
  • kind służy do wyłącznych slotów: "memory" lub "context-engine".
  • configSchema może być funkcją do leniwej ewaluacji.
  • OpenClaw rozwiązuje i zapamiętuje ten schemat przy pierwszym dostępie, więc kosztowne konstruktory schematów uruchamiają się tylko raz.

​
defineChannelPluginEntry

Import: openclaw/plugin-sdk/channel-core Opakowuje definePluginEntry logiką specyficzną dla kanałów. Automatycznie wywołuje api.registerChannel({ plugin }), udostępnia opcjonalny seam metadanych CLI dla głównej pomocy i warunkuje registerFull trybem rejestracji. 
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});
PoleTypWymaganeDomyślnie
idstringTak—
namestringTak—
descriptionstringTak—
pluginChannelPluginTak—
configSchemaOpenClawPluginConfigSchema | () => OpenClawPluginConfigSchemaNieSchemat pustego obiektu
setRuntime(runtime: PluginRuntime) => voidNie—
registerCliMetadata(api: OpenClawPluginApi) => voidNie—
registerFull(api: OpenClawPluginApi) => voidNie—
  • setRuntime jest wywoływane podczas rejestracji, aby można było zapisać referencję runtime (zwykle przez createPluginRuntimeStore). Jest pomijane podczas przechwytywania metadanych CLI.
  • registerCliMetadata działa zarówno przy api.registrationMode === "cli-metadata", jak i api.registrationMode === "full". Używaj go jako kanonicznego miejsca dla deskryptorów CLI należących do kanału, aby główna pomoc pozostawała nieaktywująca, a jednocześnie normalna rejestracja poleceń CLI była zgodna z pełnym ładowaniem pluginów.
  • registerFull działa tylko wtedy, gdy api.registrationMode === "full". Jest pomijane podczas ładowania tylko do setupu.
  • Podobnie jak definePluginEntry, configSchema może być leniwą fabryką, a OpenClaw zapamiętuje rozwiązany schemat przy pierwszym dostępie.
  • Dla należących do pluginu głównych poleceń CLI preferuj api.registerCli(..., { descriptors: [...] }), gdy chcesz, aby polecenie pozostało ładowane leniwie, ale nie znikało z głównego drzewa parsowania CLI. W przypadku pluginów kanałów preferuj rejestrowanie tych deskryptorów z poziomu registerCliMetadata(...), a registerFull(...) pozostaw do pracy wyłącznie runtime.
  • Jeśli registerFull(...) rejestruje również metody Gateway RPC, trzymaj je pod prefiksem specyficznym dla pluginu. Zarezerwowane główne przestrzenie nazw administratora (config.*, exec.approvals.*, wizard.*, update.*) są zawsze wymuszane do operator.admin.

​
defineSetupPluginEntry

Import: openclaw/plugin-sdk/channel-core Dla lekkiego pliku setup-entry.ts. Zwraca tylko { plugin } bez logiki runtime ani CLI. 
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);
OpenClaw ładuje to zamiast pełnego entry, gdy kanał jest wyłączony, nieskonfigurowany albo gdy włączone jest odroczone ładowanie. Zobacz Setup i konfiguracja, aby dowiedzieć się, kiedy ma to znaczenie. W praktyce łącz defineSetupPluginEntry(...) z wąskimi rodzinami helperów setupu:
  • openclaw/plugin-sdk/setup-runtime dla bezpiecznych dla runtime helperów setupu, takich jak bezpieczne importowo adaptery poprawek setupu, wyjście lookup-note, promptResolvedAllowFrom, splitSetupEntries i delegowane proxy setupu
  • openclaw/plugin-sdk/channel-setup dla opcjonalnych powierzchni setupu instalacji
  • openclaw/plugin-sdk/setup-tools dla helperów CLI/archiwów/dokumentacji setupu i instalacji
Ciężkie SDK, rejestrację CLI i długowieczne usługi runtime trzymaj w pełnym entry.

​
Tryb rejestracji

api.registrationMode informuje plugin, jak został załadowany:
TrybKiedyCo rejestrować
"full"Normalny start GatewayWszystko
"setup-only"Wyłączony/nieskonfigurowany kanałTylko rejestrację kanału
"setup-runtime"Przepływ setupu z dostępnym runtimeRejestrację kanału oraz tylko lekki runtime potrzebny przed załadowaniem pełnego entry
"cli-metadata"Główna pomoc / przechwytywanie metadanych CLITylko deskryptory CLI
defineChannelPluginEntry obsługuje ten podział automatycznie. Jeśli używasz definePluginEntry bezpośrednio dla kanału, sprawdź tryb samodzielnie: 
register(api) {
  if (api.registrationMode === "cli-metadata" || api.registrationMode === "full") {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Ciężkie rejestracje wyłącznie runtime
  api.registerService(/* ... */);
}
Traktuj "setup-runtime" jako okno, w którym powierzchnie startowe tylko do setupu muszą istnieć bez ponownego wchodzenia do pełnego środowiska runtime zbundlowanego kanału. Dobrze pasują tu rejestracja kanału, bezpieczne dla setupu trasy HTTP, bezpieczne dla setupu metody Gateway oraz delegowane helpery setupu. Ciężkie usługi działające w tle, rejestratory CLI oraz bootstrapy SDK providerów/klientów nadal należą do "full". W szczególności dla rejestratorów CLI:
  • używaj descriptors, gdy rejestrator posiada jedno lub więcej głównych poleceń i chcesz, aby OpenClaw ładował właściwy moduł CLI leniwie przy pierwszym wywołaniu
  • upewnij się, że te deskryptory obejmują każdy główny korzeń polecenia udostępniany przez rejestrator
  • używaj samego commands tylko dla ścieżek zgodności eager

​
Kształty pluginów

OpenClaw klasyfikuje załadowane pluginy według ich zachowania rejestracyjnego:
KształtOpis
plain-capabilityJeden typ możliwości (np. tylko provider)
hybrid-capabilityWiele typów możliwości (np. provider + speech)
hook-onlyTylko hooki, bez możliwości
non-capabilityNarzędzia/polecenia/usługi, ale bez możliwości
Użyj openclaw plugins inspect <id>, aby zobaczyć kształt pluginu.

​
Powiązane