Omówienie Plugin SDK

SDK pluginów jest typowanym kontraktem między pluginami a rdzeniem. Ta strona jest odniesieniem dla tego, co importować i co można rejestrować.

Konwencja importu

Zawsze importuj z konkretnej podścieżki:

Każda podścieżka jest małym, samodzielnym modułem. Dzięki temu uruchamianie pozostaje szybkie i zapobiega problemom z zależnościami cyklicznymi. W przypadku pomocników wejścia/budowania specyficznych dla kanału preferuj openclaw/plugin-sdk/channel-core; zachowaj openclaw/plugin-sdk/core dla szerszej powierzchni zbiorczej i współdzielonych pomocników, takich jak buildChannelConfigSchema.

Dla konfiguracji kanału publikuj należący do kanału JSON Schema przez openclaw.plugin.json#channelConfigs. Podścieżka plugin-sdk/channel-config-schema jest przeznaczona dla współdzielonych prymitywów schematu i ogólnego konstruktora. Dołączone do OpenClaw pluginy używają plugin-sdk/bundled-channel-config-schema dla zachowanych schematów dołączonych kanałów. Przestarzałe eksporty zgodności pozostają w plugin-sdk/channel-config-schema-legacy; żadna z podścieżek schematów dołączonych nie jest wzorcem dla nowych pluginów.

Odniesienie podścieżek

SDK pluginów jest udostępniany jako zestaw wąskich podścieżek pogrupowanych według obszaru (wejście pluginu, kanał, dostawca, uwierzytelnianie, środowisko wykonawcze, capability, pamięć oraz zarezerwowane pomocniki dołączonych pluginów). Pełny katalog — pogrupowany i podlinkowany — zobacz w Podścieżki SDK pluginów.

Inwentarz punktów wejścia kompilatora znajduje się w scripts/lib/plugin-sdk-entrypoints.json; eksporty pakietu są generowane z publicznego podzbioru po odjęciu lokalnych dla repozytorium podścieżek testowych/wewnętrznych wymienionych w scripts/lib/plugin-sdk-private-local-only-subpaths.json. Uruchom pnpm plugin-sdk:surface, aby skontrolować liczbę publicznych eksportów. Przestarzałe publiczne podścieżki, które są wystarczająco stare i nieużywane przez kod produkcyjny dołączonych rozszerzeń, są śledzone w scripts/lib/plugin-sdk-deprecated-public-subpaths.json; szerokie przestarzałe baryłki reeksportów są śledzone w scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

API rejestracji

Callback register(api) otrzymuje obiekt OpenClawPluginApi z tymi metodami:

Rejestracja capability

Narzędzia i polecenia

Polecenia pluginów mogą ustawić agentPromptGuidance, gdy agent potrzebuje krótkiej, należącej do polecenia wskazówki routingu. Niech ten tekst dotyczy samego polecenia; nie dodawaj polityki specyficznej dla dostawcy lub pluginu do konstruktorów promptów rdzenia.

Infrastruktura

Hooki hosta dla pluginów przepływu pracy

Hooki hosta są połączeniami SDK dla pluginów, które muszą uczestniczyć w cyklu życia hosta, a nie tylko dodawać dostawcę, kanał lub narzędzie. Są to kontrakty ogólne; Plan Mode może ich używać, ale mogą też przepływy zatwierdzania, bramki polityki obszaru roboczego, monitory w tle, kreatory konfiguracji i pluginy towarzyszące UI.

Używaj pogrupowanych przestrzeni nazw dla nowego kodu pluginów:

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

Równoważne płaskie metody pozostają dostępne jako przestarzałe aliasy zgodności dla istniejących pluginów. Nie dodawaj nowego kodu pluginu, który wywołuje api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn ani api.unscheduleSessionTurnsByTag bezpośrednio.

scheduleSessionTurn(...) to wygodne API o zakresie sesji nad harmonogramem Gateway Cron. Cron odpowiada za czas wykonywania i tworzy rekord zadania w tle, gdy turn jest uruchamiany; Plugin SDK ogranicza tylko sesję docelową, nazewnictwo własne pluginu i czyszczenie. Użyj api.runtime.tasks.managedFlows wewnątrz zaplanowanego turn, gdy sama praca wymaga trwałego, wieloetapowego stanu Task Flow.

Kontrakty celowo rozdzielają uprawnienia:

• Zewnętrzne pluginy mogą być właścicielami rozszerzeń sesji, deskryptorów UI, poleceń, metadanych narzędzi, wstrzyknięć do następnego turn i zwykłych hooków.
• Zaufane polityki narzędzi uruchamiają się przed zwykłymi hookami before_tool_call i są dostępne tylko dla elementów dołączonych w pakiecie, ponieważ uczestniczą w polityce bezpieczeństwa hosta.
• Zastrzeżona własność poleceń jest dostępna tylko dla elementów dołączonych w pakiecie. Zewnętrzne pluginy powinny używać własnych nazw poleceń lub aliasów.
• allowPromptInjection=false wyłącza hooki modyfikujące prompt, w tym agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, pola promptu ze starszego before_agent_start oraz enqueueNextTurnInjection.

Przykłady konsumentów innych niż Plan:

Rejestracja odkrywania Gateway

api.registerGatewayDiscoveryService(...) pozwala pluginowi ogłaszać aktywny Gateway w lokalnym transporcie odkrywania, takim jak mDNS/Bonjour. OpenClaw wywołuje usługę podczas uruchamiania Gateway, gdy lokalne odkrywanie jest włączone, przekazuje bieżące porty Gateway i niesekretne dane podpowiedzi TXT oraz wywołuje zwrócony handler stop podczas zamykania Gateway.

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

Pluginy odkrywania Gateway nie mogą traktować ogłaszanych wartości TXT jako sekretów ani uwierzytelniania. Odkrywanie jest podpowiedzią routingu; uwierzytelnianie Gateway i przypinanie TLS nadal odpowiadają za zaufanie.

Metadane rejestracji CLI

api.registerCli(registrar, opts?) akceptuje dwa rodzaje metadanych poleceń:

• commands: jawne nazwy poleceń będących własnością rejestratora
• descriptors: deskryptory poleceń używane podczas parsowania dla pomocy CLI, routingu i leniwej rejestracji CLI pluginu
• parentPath: opcjonalna ścieżka polecenia nadrzędnego dla zagnieżdżonych grup poleceń, takich jak ["nodes"]

Dla funkcji sparowanych węzłów preferuj api.registerNodeCliFeature(registrar, opts?). To mały wrapper wokół api.registerCli(..., { parentPath: ["nodes"] }), który sprawia, że polecenia takie jak openclaw nodes canvas są jawnymi funkcjami węzłów będącymi własnością pluginu.

Jeśli chcesz, aby polecenie pluginu pozostało leniwie ładowane w zwykłej ścieżce głównej CLI, podaj descriptors, które obejmują każdy główny korzeń poleceń najwyższego poziomu udostępniany przez ten rejestrator.

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Manage Matrix accounts, verification, devices, and profile state",        hasSubcommands: true,      },    ],  },);

Zagnieżdżone polecenia otrzymują rozwiązane polecenie nadrzędne jako program:

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Capture or render canvas content from a paired node",        hasSubcommands: true,      },    ],  },);

Używaj samego commands tylko wtedy, gdy nie potrzebujesz leniwej rejestracji głównego CLI. Ta gorliwa ścieżka zgodności pozostaje obsługiwana, ale nie instaluje symboli zastępczych opartych na deskryptorach dla leniwego ładowania podczas parsowania.

Rejestracja backendu CLI

api.registerCliBackend(...) pozwala pluginowi posiadać domyślną konfigurację dla lokalnego backendu CLI AI, takiego jak codex-cli.

• id backendu staje się prefiksem dostawcy w referencjach modeli, takich jak codex-cli/gpt-5.
• config backendu używa tego samego kształtu co agents.defaults.cliBackends.<id>.
• Konfiguracja użytkownika nadal wygrywa. OpenClaw scala agents.defaults.cliBackends.<id> nad domyślną konfiguracją pluginu przed uruchomieniem CLI.
• Użyj normalizeConfig, gdy backend wymaga przepisania zgodności po scaleniu (na przykład normalizacji starych kształtów flag).
• Użyj resolveExecutionArgs dla przepisania argv o zakresie żądania, które należy do dialektu CLI, takiego jak mapowanie poziomów myślenia OpenClaw na natywną flagę effort.

Pełny przewodnik tworzenia znajdziesz w Pluginy backendu CLI.

Wyłączne sloty

Adaptery embeddingów pamięci

• registerMemoryCapability jest preferowanym, wyłącznym API pluginu pamięci.
• registerMemoryCapability może także udostępniać publicArtifacts.listArtifacts(...), aby pluginy towarzyszące mogły konsumować wyeksportowane artefakty pamięci przez openclaw/plugin-sdk/memory-host-core zamiast sięgać do prywatnego układu konkretnego pluginu pamięci.
• registerMemoryPromptSection, registerMemoryFlushPlan i registerMemoryRuntime to zgodne ze starszymi wersjami, wyłączne API pluginu pamięci.
• MemoryFlushPlan.model może przypiąć turn opróżniania do dokładnej referencji provider/model, takiej jak ollama/qwen3:8b, bez dziedziczenia aktywnego łańcucha fallback.
• registerMemoryEmbeddingProvider pozwala aktywnemu pluginowi pamięci zarejestrować jeden lub więcej identyfikatorów adapterów embeddingów (na przykład openai, gemini albo niestandardowy identyfikator zdefiniowany przez plugin).
• Konfiguracja użytkownika, taka jak agents.defaults.memorySearch.provider i agents.defaults.memorySearch.fallback, jest rozwiązywana względem tych zarejestrowanych identyfikatorów adapterów.

Zdarzenia i cykl życia

Zobacz Hooki pluginów, aby uzyskać przykłady, typowe nazwy hooków i semantykę strażników.

Semantyka decyzji hooków

• before_tool_call: zwrócenie { block: true } jest końcowe. Gdy dowolny handler je ustawi, handlery o niższym priorytecie są pomijane.
• before_tool_call: zwrócenie { block: false } jest traktowane jako brak decyzji (tak samo jak pominięcie block), a nie jako nadpisanie.
• before_install: zwrócenie { block: true } jest końcowe. Gdy dowolny handler je ustawi, handlery o niższym priorytecie są pomijane.
• before_install: zwrócenie { block: false } jest traktowane jako brak decyzji (tak samo jak pominięcie block), a nie jako nadpisanie.
• reply_dispatch: zwrócenie { handled: true, ... } jest końcowe. Gdy dowolny handler przejmie wysyłkę, handlery o niższym priorytecie i domyślna ścieżka wysyłki modelu są pomijane.
• message_sending: zwrócenie { cancel: true } jest końcowe. Gdy dowolny handler je ustawi, handlery o niższym priorytecie są pomijane.
• message_sending: zwrócenie { cancel: false } jest traktowane jako brak decyzji (tak samo jak pominięcie cancel), a nie jako nadpisanie.
• message_received: użyj typowanego pola threadId, gdy potrzebujesz routingu przychodzącego wątku/tematu. Zachowaj metadata dla dodatków specyficznych dla kanału.
• message_sending: użyj typowanych pól routingu replyToId / threadId, zanim przejdziesz do specyficznego dla kanału metadata.
• gateway_start: użyj ctx.config, ctx.workspaceDir i ctx.getCron?.() dla stanu startowego będącego własnością Gateway zamiast polegać na wewnętrznych hookach gateway:startup.
• cron_changed: obserwuj zmiany cyklu życia Cron będącego własnością Gateway. Użyj event.job?.state?.nextRunAtMs i ctx.getCron?.() podczas synchronizacji zewnętrznych harmonogramów wybudzania i utrzymuj OpenClaw jako źródło prawdy dla sprawdzania terminów oraz wykonania.

Pola obiektu API

Konwencja modułów wewnętrznych

W obrębie pluginu używaj lokalnych plików zbiorczych do importów wewnętrznych:

my-plugin/  api.ts            # Public exports for external consumers  runtime-api.ts    # Internal-only runtime exports  index.ts          # Plugin entry point  setup-entry.ts    # Lightweight setup-only entry (optional)

Publiczne powierzchnie dołączonego pluginu ładowanego przez fasadę (api.ts, runtime-api.ts, index.ts, setup-entry.ts i podobne publiczne pliki wejściowe) preferują aktywną migawkę konfiguracji środowiska uruchomieniowego, gdy OpenClaw już działa. Jeśli migawka środowiska uruchomieniowego jeszcze nie istnieje, przechodzą awaryjnie do rozwiązanego pliku konfiguracji na dysku. Fasady spakowanych dołączonych pluginów powinny być ładowane przez loadery fasad pluginów OpenClaw; bezpośrednie importy z dist/extensions/... omijają manifest i kontrole runtime sidecar, których instalacje pakietowe używają dla kodu należącego do pluginu.

Pluginy dostawców mogą udostępniać wąski, lokalny dla pluginu plik zbiorczy kontraktu, gdy pomocnik jest celowo specyficzny dla dostawcy i nie należy jeszcze do generycznej podścieżki SDK. Dołączone przykłady:

• Anthropic: publiczna granica api.ts / contract-api.ts dla pomocników strumienia nagłówka beta Claude i service_tier.
• @openclaw/openai-provider: api.ts eksportuje konstruktory dostawcy, pomocniki modelu domyślnego i konstruktory dostawcy czasu rzeczywistego.
• @openclaw/openrouter-provider: api.ts eksportuje konstruktor dostawcy oraz pomocniki onboardingu/konfiguracji.

Powiązane