Przegląd Plugin SDK

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

Konwencja importu

Zawsze importuj z konkretnej ścieżki podrzędnej:

Każda ścieżka podrzędna 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; zostaw openclaw/plugin-sdk/core dla szerszej powierzchni nadrzędnej 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. Ścieżka podrzędna plugin-sdk/channel-config-schema jest przeznaczona dla współdzielonych prymitywów schematów i ogólnego buildera. Bundlowane Pluginy OpenClaw używają plugin-sdk/bundled-channel-config-schema dla zachowanych schematów bundlowanych kanałów. Przestarzałe eksporty zgodności pozostają w plugin-sdk/channel-config-schema-legacy; żadna z bundlowanych ścieżek podrzędnych schematów nie jest wzorem dla nowych Pluginów.

Odniesienie do ścieżek podrzędnych

SDK Plugin jest udostępniany jako zestaw wąskich ścieżek podrzędnych pogrupowanych według obszaru (wejście Pluginu, kanał, dostawca, uwierzytelnianie, runtime, capability, memory oraz zarezerwowane pomocniki bundlowanych Pluginów). Pełny katalog, pogrupowany i podlinkowany, znajdziesz w ścieżkach podrzędnych SDK Plugin.

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 ścieżek testowych/wewnętrznych wymienionych w scripts/lib/plugin-sdk-private-local-only-subpaths.json. Uruchom pnpm plugin-sdk:surface, aby przeprowadzić audyt liczby publicznych eksportów. Przestarzałe publiczne ścieżki podrzędne, które są wystarczająco stare i nieużywane przez kod produkcyjny bundlowanych rozszerzeń, są śledzone w scripts/lib/plugin-sdk-deprecated-public-subpaths.json; szerokie przestarzałe barrele 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

Dostawcy embeddingów zarejestrowani za pomocą api.registerEmbeddingProvider(...) muszą być także wymienieni w contracts.embeddingProviders w manifeście Pluginu. To ogólna powierzchnia embeddingów do generowania wektorów wielokrotnego użytku. Wyszukiwanie pamięci może korzystać z tej ogólnej powierzchni dostawcy. Starszy seam api.registerMemoryEmbeddingProvider(...) i contracts.memoryEmbeddingProviders jest przestarzałą zgodnością na czas migracji istniejących dostawców specyficznych dla pamięci.

Dostawcy specyficzni dla pamięci, którzy nadal eksponują runtime batchEmbed(...), pozostają przy istniejącym kontrakcie batchowania per plik, chyba że ich runtime jawnie ustawia sourceWideBatchEmbed: true. To włączenie pozwala hostowi pamięci przesyłać chunki z wielu brudnych plików pamięci i włączonych źródeł w jednym wywołaniu batchEmbed(...) do limitów batchy hosta. Adaptery batchy, które przesyłają pliki żądań JSONL, muszą dzielić zadania dostawcy przed osiągnięciem limitu rozmiaru uploadu oraz limitu liczby żądań. Dostawca musi zwrócić jeden embedding na każdy wejściowy chunk w tej samej kolejności co batch.chunks; pomiń flagę, gdy dostawca oczekuje batchy lokalnych dla pliku lub nie może zachować kolejności wejścia w większym zadaniu obejmującym całe źródło.

Narzędzia i polecenia

Użyj defineToolPlugin dla prostych Pluginów zawierających wyłącznie narzędzia ze stałymi nazwami narzędzi. Użyj bezpośrednio api.registerTool(...) dla mieszanych Pluginów lub w pełni dynamicznej rejestracji narzędzi.

Polecenia Pluginu mogą ustawić agentPromptGuidance, gdy agent potrzebuje krótkiej, należącej do polecenia wskazówki routingu. Zachowaj ten tekst o samym poleceniu; nie dodawaj polityki specyficznej dla dostawcy lub Pluginu do builderów promptów rdzenia.

Wpisy wskazówek mogą być starszymi stringami, które mają zastosowanie do każdej powierzchni promptu, albo wpisami strukturalnymi:

agentPromptGuidance: [  "Global command hint.",  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },];

Strukturalne surfaces mogą zawierać openclaw_main, codex_app_server, cli_backend, acp_backend lub subagent. pi_main pozostaje przestarzałym aliasem dla openclaw_main. Pomiń surfaces dla celowych wskazówek obejmujących wszystkie powierzchnie. Nie przekazuj pustej tablicy surfaces; jest odrzucana, aby przypadkowa utrata zakresu nie stała się globalnym tekstem promptu.

Instrukcje deweloperskie natywnego serwera aplikacji Codex są bardziej rygorystyczne niż inne powierzchnie promptów: tylko wskazówki jawnie ograniczone do codex_app_server są promowane do tej ścieżki o wyższym priorytecie. Starsze wskazówki stringowe i nieograniczone zakresowo wskazówki strukturalne pozostają dostępne dla powierzchni promptów innych niż Codex ze względu na zgodność.

Infrastruktura

Hooki hosta dla Pluginów workflow

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

Używaj pogrupowanych przestrzeni nazw dla nowego kodu Plugin:

• 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. Nie dodawaj nowego kodu Plugin, który wywołuje bezpośrednio 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.

scheduleSessionTurn(...) to wygodna funkcja o zakresie sesji nad harmonogramem Cron Gateway. Cron odpowiada za czas i tworzy rekord zadania w tle, gdy tura jest uruchamiana; Plugin SDK ogranicza tylko sesję docelową, nazewnictwo należące do Plugin oraz czyszczenie. Użyj api.runtime.tasks.managedFlows wewnątrz zaplanowanej tury, gdy sama praca wymaga trwałego, wieloetapowego stanu Task Flow.

Kontrakty celowo rozdzielają uprawnienia:

• Zewnętrzne Plugin mogą odpowiadać za rozszerzenia sesji, deskryptory UI, polecenia, metadane narzędzi, wstrzyknięcia do następnej tury oraz zwykłe haki.
• Zaufane polityki narzędzi działają przed zwykłymi hakami before_tool_call i są zaufane przez hosta. Wbudowane polityki działają jako pierwsze; polityki zainstalowanych Plugin wymagają jawnego włączenia oraz ich lokalnych identyfikatorów w contracts.trustedToolPolicies i działają następnie w kolejności ładowania Plugin. Identyfikatory polityk są ograniczone do rejestrującego Plugin.
• Zarezerwowana własność poleceń jest dostępna tylko dla wbudowanych Plugin. Zewnętrzne Plugin powinny używać własnych nazw poleceń lub aliasów.
• allowPromptInjection=false wyłącza haki modyfikujące prompt, w tym agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, pola promptów ze starszego before_agent_start oraz enqueueNextTurnInjection.

Przykłady konsumentów spoza Plan:

Rejestracja wykrywania Gateway

api.registerGatewayDiscoveryService(...) pozwala Plugin ogłaszać aktywny Gateway w lokalnym transporcie wykrywania, takim jak mDNS/Bonjour. OpenClaw wywołuje usługę podczas startu Gateway, gdy lokalne wykrywanie jest włączone, przekazuje bieżące porty Gateway i nietajne 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() };  },});

Plugin wykrywania Gateway nie mogą traktować ogłaszanych wartości TXT jako sekretów ani uwierzytelniania. Wykrywanie jest wskazówką routingu; zaufanie nadal należy do uwierzytelniania Gateway i przypinania TLS.

Metadane rejestracji CLI

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

• commands: jawne nazwy poleceń należące do rejestratora
• descriptors: deskryptory poleceń czasu parsowania używane do pomocy CLI, routingu i leniwej rejestracji CLI Plugin
• 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 czyni polecenia takie jak openclaw nodes canvas jawnymi funkcjami węzłów należącymi do Plugin.

Jeśli chcesz, aby polecenie Plugin pozostało ładowane leniwie w normalnej ścieżce głównego CLI, podaj descriptors, które obejmują każdy główny korzeń polecenia 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 Plugin odpowiadać za domyślną konfigurację lokalnego backendu CLI AI, takiego jak claude-cli lub my-cli.

• Backend id staje się prefiksem dostawcy w odwołaniach do modeli, takich jak my-cli/gpt-5.
• Backend config używa tego samego kształtu co agents.defaults.cliBackends.<id>.
• Konfiguracja użytkownika nadal ma pierwszeństwo. OpenClaw nakłada agents.defaults.cliBackends.<id> na 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 do przepisywania argv w zakresie żądania, które należy do dialektu CLI, na przykład mapowania poziomów myślenia OpenClaw na natywną flagę wysiłku. Hook otrzymuje ctx.executionMode; użyj "side-question", aby dodać natywne dla backendu flagi izolacji dla efemerycznych wywołań /btw. Jeśli te flagi niezawodnie wyłączają natywne narzędzia dla CLI, które poza tym są zawsze włączone, zadeklaruj także sideQuestionToolMode: "disabled".

Pełny przewodnik tworzenia znajdziesz w pluginach backendów CLI.

Wyłączne sloty

Przestarzałe adaptery osadzania 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 korzystać z wyeksportowanych artefaktów 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ąć turę opróżniania do dokładnego odwołania provider/model, takiego jak ollama/qwen3:8b, bez dziedziczenia aktywnego łańcucha fallback.
• registerMemoryEmbeddingProvider jest przestarzałe. Nowi dostawcy osadzania powinni używać api.registerEmbeddingProvider(...) i contracts.embeddingProviders.
• Istniejący dostawcy specyficzni dla pamięci nadal działają w oknie migracji, ale inspekcja pluginu zgłasza to jako dług zgodności dla pluginów niedostarczanych w pakiecie.

Zdarzenia i cykl życia

Zobacz hooki pluginów, aby poznać przykłady, typowe nazwy hooków i semantykę zabezpieczeń.

Semantyka decyzji hooków

before_install jest hookiem cyklu życia runtime pluginu, a nie powierzchnią zasad instalacji operatora. Użyj security.installPolicy, gdy decyzja zezwolenia/blokady musi obejmować ścieżki instalacji lub aktualizacji oparte na CLI i Gateway.

• before_tool_call: zwrócenie { block: true } jest terminalne. 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 terminalne. 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 terminalne. Gdy dowolny handler przejmie wysyłkę, handlery o niższym priorytecie oraz domyślna ścieżka wysyłki modelu są pomijane.
• message_sending: zwrócenie { cancel: true } jest terminalne. 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 przed przejściem na specyficzne dla kanału metadata.
• gateway_start: użyj ctx.config, ctx.workspaceDir i ctx.getCron?.() dla stanu uruchamiania należącego do Gateway zamiast polegać na wewnętrznych hookach gateway:startup.
• cron_changed: obserwuj zmiany cyklu życia cron należącego do Gateway. Użyj event.job?.state?.nextRunAtMs i ctx.getCron?.() podczas synchronizowania zewnętrznych harmonogramów wybudzeń oraz zachowaj OpenClaw jako źródło prawdy dla kontroli terminów i wykonania.

Pola obiektu API

Konwencja modułów wewnętrznych

W swoim pluginie 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 pluginów pakietowych ładowanych przez fasadę (api.ts, runtime-api.ts, index.ts, setup-entry.ts oraz podobne publiczne pliki wejściowe) preferują aktywny snapshot konfiguracji runtime, gdy OpenClaw już działa. Jeśli snapshot runtime jeszcze nie istnieje, wracają do rozpoznanego pliku konfiguracji na dysku. Fasady spakowanych pluginów pakietowych powinny być ładowane przez loadery fasad pluginów OpenClaw; bezpośrednie importy z dist/extensions/... omijają manifest i kontrole sidecar runtime, których spakowane instalacje używają dla kodu należącego do pluginu.

Pluginy dostawców mogą udostępniać wąski, lokalny dla pluginu plik zbiorczy kontraktu, gdy helper jest celowo specyficzny dla dostawcy i nie należy jeszcze do ogólnej podścieżki SDK. Przykłady pakietowe:

• Anthropic: publiczny szew api.ts / contract-api.ts dla helperów strumienia beta-header Claude i service_tier.
• @openclaw/openai-provider: api.ts eksportuje konstruktory dostawców, helpery modeli domyślnych i konstruktory dostawców realtime.
• @openclaw/openrouter-provider: api.ts eksportuje konstruktor dostawcy oraz helpery onboardingu/konfiguracji.

Powiązane