Omówienie SDK Pluginów

SDK Pluginów jest typowanym kontraktem między pluginami a rdzeniem. Ta strona stanowi dokumentację referencyjną dotyczącą tego, co importować i co można rejestrować.

Konwencja importowania

Zawsze importuj z określonej ścieżki podrzędnej:

Każda ścieżka podrzędna jest małym, samodzielnym modułem. Zapewnia to szybkie uruchamianie i zapobiega problemom z zależnościami cyklicznymi. W przypadku funkcji pomocniczych punktu wejścia i kompilacji właściwych dla kanału preferuj openclaw/plugin-sdk/channel-core; używaj openclaw/plugin-sdk/core dla szerszej powierzchni zbiorczej i współdzielonych funkcji pomocniczych, takich jak buildChannelConfigSchema.

W przypadku konfiguracji kanału publikuj należący do kanału schemat JSON za pośrednictwem openclaw.plugin.json#channelConfigs. Ścieżka podrzędna plugin-sdk/channel-config-schema służy do współdzielonych elementów bazowych schematów i ogólnego konstruktora. Do zachowanych schematów wbudowanych kanałów wbudowane pluginy OpenClaw używają plugin-sdk/bundled-channel-config-schema. Przestarzałe eksporty zgodności pozostają dostępne w plugin-sdk/channel-config-schema-legacy; żadna ze ścieżek podrzędnych schematów wbudowanych nie stanowi wzorca dla nowych pluginów.

Dokumentacja ścieżek podrzędnych

SDK Pluginów jest udostępniany jako zestaw wąskich ścieżek podrzędnych pogrupowanych według obszaru (punkt wejścia pluginu, kanał, dostawca, uwierzytelnianie, środowisko wykonawcze, możliwości, pamięć i zarezerwowane funkcje pomocnicze wbudowanych pluginów). Pełny katalog — pogrupowany i zawierający odnośniki — znajduje się w sekcji Ścieżki podrzędne SDK Pluginów.

Wykaz 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 testowych i wewnętrznych ścieżek podrzędnych wymienionych w scripts/lib/plugin-sdk-private-local-only-subpaths.json. Uruchom pnpm plugin-sdk:surface, aby sprawdzić liczbę publicznych eksportów. Przestarzałe publiczne ścieżki podrzędne, które są dostatecznie stare i nie są używane przez kod produkcyjny wbudowanych rozszerzeń, są śledzone w scripts/lib/plugin-sdk-deprecated-public-subpaths.json; szerokie, przestarzałe moduły zbiorcze ponownego eksportu są śledzone w scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

API rejestracji

Funkcja zwrotna register(api) otrzymuje obiekt OpenClawPluginApi z następującymi metodami:

Rejestrowanie możliwości

Dostawcy procesów roboczych muszą również zadeklarować swój identyfikator w contracts.workerProviders. Rdzeń utrwala trwały zamiar przed wywołaniem provision(profile, operationId). Dostawcy sprawdzają ustawienia przed przydzieleniem zasobów zewnętrznych i zgłaszają WorkerProviderError w przypadku trwałego odrzucenia profilu. Gdy identyfikator operacji się powtarza, provision musi przyjąć tę samą dzierżawę. Rdzeń utrwala sprawdzone ustawienia profilu wraz z dzierżawą i przekazuje tę migawkę do destroy({ leaseId, profile }), które musi być idempotentne, oraz inspect({ leaseId, profile }), które zwraca active, destroyed lub unknown. Pozwala to dostawcom kierować wywołania cyklu życia po ponownym uruchomieniu Gateway lub usunięciu nazwanego profilu. Punkty końcowe SSH używają SecretRef dla keyRef, nigdy materiału klucza osadzonego bezpośrednio, oraz zawierają hostKey z zaufanych danych wyjściowych aprowizacji dokładnie w postaci algorithm base64, bez nazwy hosta ani komentarza. Rdzeń przypina hostKey i nigdy nie ufa kluczowi z pierwszego połączenia. Dostawca generujący dynamiczny keyRef może zaimplementować resolveSshIdentity({ leaseId, profile, keyRef }); jeśli ta funkcja jest dostępna, stanowi źródło rozstrzygające, natomiast dostawcy bez niej korzystają ze skonfigurowanej ogólnej funkcji rozpoznawania sekretów. Dostawcy z odnawialnymi dzierżawami mogą również zaimplementować renew(leaseId). inspect musi zgłaszać wyjątek w przypadku błędów przejściowych lub nieokreślonych; wartość unknown należy zwracać wyłącznie w przypadku autorytatywnie potwierdzonego braku. Rdzeń oznacza aktywny lokalny rekord jako osierocony albo traktuje brak jako zakończenie likwidacji po utrwalonym żądaniu zniszczenia.

Dostawcy osadzeń zarejestrowani za pomocą api.registerEmbeddingProvider(...) muszą być również wymienieni w contracts.embeddingProviders w manifeście pluginu. Jest to ogólny interfejs osadzeń do generowania wektorów wielokrotnego użytku. Wyszukiwanie w pamięci może korzystać z tego ogólnego interfejsu dostawcy. Starszy interfejs api.registerMemoryEmbeddingProvider(...) i contracts.memoryEmbeddingProviders stanowi przestarzałą warstwę zgodności na czas migracji istniejących dostawców właściwych dla pamięci.

Dostawcy właściwi dla pamięci, którzy nadal udostępniają w środowisku wykonawczym batchEmbed(...), pozostają przy istniejącym kontrakcie grupowania osobno dla każdego pliku, chyba że ich środowisko wykonawcze jawnie ustawi sourceWideBatchEmbed: true. Ta opcja pozwala hostowi pamięci przesyłać fragmenty z wielu zmienionych plików pamięci i włączonych źródeł w jednym wywołaniu batchEmbed(...), do limitów rozmiaru partii hosta. Adaptery partii, które przesyłają pliki żądań JSONL, muszą dzielić zadania dostawcy zarówno przed osiągnięciem limitu rozmiaru przesyłanych danych, jak i limitu liczby żądań. Dostawca musi zwrócić jedno osadzenie dla każdego fragmentu wejściowego, w tej samej kolejności co batch.chunks; pomiń tę flagę, jeśli dostawca oczekuje partii lokalnych dla pliku lub nie może zachować kolejności danych wejściowych w większym zadaniu obejmującym całe źródło.

Narzędzia i polecenia

Używaj defineToolPlugin w przypadku prostych pluginów zawierających wyłącznie narzędzia o stałych nazwach. Używaj api.registerTool(...) bezpośrednio w przypadku pluginów mieszanych lub w pełni dynamicznego rejestrowania narzędzi.

Polecenia pluginów mogą ustawiać agentPromptGuidance, gdy agent potrzebuje krótkiej, należącej do polecenia wskazówki dotyczącej kierowania. Tekst powinien dotyczyć samego polecenia; nie dodawaj zasad właściwych dla dostawcy ani pluginu do konstruktorów promptów rdzenia.

Wpisy wskazówek mogą być starszymi ciągami znaków, które mają zastosowanie do każdej powierzchni promptu, albo wpisami ustrukturyzowanymi:

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

Ustrukturyzowane 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 w przypadku celowo stosowanych wskazówek dla wszystkich powierzchni. Nie przekazuj pustej tablicy surfaces; zostanie ona odrzucona, aby przypadkowa utrata zakresu nie spowodowała przekształcenia tekstu w globalny tekst promptu.

Instrukcje deweloperskie natywnego serwera aplikacji Codex podlegają surowszym regułom niż pozostałe powierzchnie promptów: tylko wskazówki jawnie ograniczone do codex_app_server są przenoszone do tego pasa o wyższym priorytecie. Starsze wskazówki w postaci ciągów znaków oraz ustrukturyzowane wskazówki bez określonego zakresu pozostają dostępne dla powierzchni promptów innych niż Codex w celu zachowania zgodności.

Polecenia hosta Node są wykonywane na połączonym hoście Node, a nie wewnątrz procesu Gateway. Jeśli obecne jest agentTool, Node publikuje deskryptor po pomyślnym połączeniu z Gateway; Gateway udostępnia go uruchomieniom agenta tylko wtedy, gdy ten Node jest połączony, i tylko jeśli command deskryptora znajduje się w zatwierdzonym zestawie poleceń Node. Ustaw agentTool.defaultPlatforms, aby dodać niegroźne polecenie do domyślnej listy dozwolonych poleceń Node; w przeciwnym razie wymagane jest jawne gateway.nodes.allowCommands lub zasada wywołań Node. agentTool.name musi być bezpieczne dla dostawcy: zaczynać się literą, zawierać wyłącznie litery, cyfry, podkreślenia lub łączniki i mieć nie więcej niż 64 znaki. Narzędzia Node oparte na MCP mogą ustawić metadane agentTool.mcp, aby katalog i interfejsy wyszukiwania narzędzi mogły wyświetlać tożsamość zdalnego serwera/narzędzia MCP, ale wykonanie nadal odbywa się za pośrednictwem ogłoszonego polecenia Node.

Infrastruktura

Konstruktory uzupełnień promptu pamięci otrzymują opcjonalny kontekst agentId, agentSessionKey i sandboxed. Wywołania search i get uzupełnienia korpusu pamięci otrzymują opcjonalny kontekst agentId i sandboxed. Pluginy korzystające z pamięci masowej należącej do agenta powinny ustalać tę pamięć dla każdego wywołania, zamiast przechwytywać jedną globalną ścieżkę podczas rejestracji. Jeśli identyfikator agenta jest wymagany, ale nie został podany w operacji wieloagentowej, należy bezpiecznie przerwać operację zamiast wybierać dowolnego agenta.

Procedury obsługi interakcji Telegramu mogą zwracać { submitText }, aby po pomyślnym zakończeniu procedury skierować tekst przez standardową ścieżkę przychodzącą agenta Telegramu. OpenClaw zachowuje przycisk wywołania zwrotnego, gdy zasada obsługi wiadomości przychodzących pomija tekst lub przetwarzanie kończy się niepowodzeniem, dzięki czemu użytkownik może spróbować ponownie po zmianie warunku blokującego. To pole wyniku jest specyficzne dla Telegramu; pozostałe kanały zachowują własne kontrakty wyników interakcji.

Haki hosta dla Pluginów przepływu pracy

Haki hosta są punktami integracji SDK dla Pluginów, które muszą uczestniczyć w cyklu życia hosta, zamiast jedynie dodawać dostawcę, kanał lub narzędzie. Są to kontrakty ogólnego przeznaczenia; może z nich korzystać Tryb planowania, ale także przepływy zatwierdzania, bramy zasad przestrzeni roboczej, monitory działające w tle, kreatory konfiguracji i Pluginy towarzyszące interfejsu użytkownika.

Deskryptor surface: "tab" dodaje kartę na pasku bocznym interfejsu sterowania. Deskryptory kart aktywnych Pluginów są ogłaszane klientom panelu w komunikacie powitalnym Gateway (controlUiTabs), więc karta pojawia się tylko wtedy, gdy Plugin jest włączony. Wbudowane Pluginy mogą dostarczać pełnoprawny widok panelu dla swojej karty; pozostałe Pluginy mogą ustawić path na trasę HTTP Pluginu (zobacz api.registerHttpRoute(...)), którą panel renderuje w izolowanej ramce. icon jest podpowiedzią nazwy ikony panelu, group wybiera sekcję paska bocznego (control lub agent), order określa kolejność wśród kart Pluginów, a requiredScopes ukrywa kartę przed połączeniami, które nie mają tych zakresów operatora:

api.session.controls.registerControlUiDescriptor({  surface: "tab",  id: "logbook",  label: "Logbook",  description: "Your day as a timeline, built from screen snapshots.",  icon: "sun",  group: "control",  requiredScopes: ["operator.write"],});

W nowym kodzie Pluginów używaj pogrupowanych przestrzeni nazw:

• 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 metody płaskie pozostają dostępne jako przestarzałe aliasy zgodności dla istniejących Pluginów. Nie dodawaj nowego kodu Pluginu, który bezpośrednio 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.

scheduleSessionTurn(...) jest udogodnieniem ograniczonym do sesji, zbudowanym na harmonogramie Cron Gateway. Cron odpowiada za czas wykonania i tworzy rekord zadania działającego w tle, gdy tura zostaje uruchomiona; SDK Pluginu ogranicza jedynie sesję docelową, nazewnictwo należące do Pluginu i 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 Pluginy mogą odpowiadać za rozszerzenia sesji, deskryptory interfejsu użytkownika, polecenia, metadane narzędzi, wstrzyknięcia do następnej tury i zwykłe haki.
• Zaufane zasady narzędzi są wykonywane przed zwykłymi hakami before_tool_call i są zaufane przez hosta. Zasady wbudowane są wykonywane jako pierwsze; zasady zainstalowanych Pluginów wymagają jawnego włączenia oraz umieszczenia ich lokalnych identyfikatorów w contracts.trustedToolPolicies, a następnie są wykonywane w kolejności ładowania Pluginów. Identyfikatory zasad są ograniczone do rejestrującego je Pluginu.
• Zastrzeżone polecenia mogą należeć wyłącznie do wbudowanych Pluginów. Zewnętrzne Pluginy 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 promptu ze starszego before_agent_start oraz enqueueNextTurnInjection.

Przykłady zastosowań poza Trybem planowania:

Rejestracja wykrywania Gateway

api.registerGatewayDiscoveryService(...) umożliwia Pluginowi rozgłaszanie aktywnego Gateway za pomocą lokalnego transportu wykrywania, takiego jak mDNS/Bonjour. OpenClaw wywołuje usługę podczas uruchamiania Gateway, gdy lokalne wykrywanie jest włączone, przekazuje bieżące porty Gateway i niepoufne dane pomocnicze TXT oraz wywołuje zwróconą procedurę obsługi stop podczas wyłączania 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 wykrywania Gateway nie mogą traktować rozgłaszanych wartości TXT jako danych poufnych ani danych uwierzytelniających. Wykrywanie jest wskazówką dotyczącą routingu; uwierzytelnianie Gateway i przypinanie TLS nadal odpowiadają za zaufanie.

Metadane rejestracji CLI

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

• commands: jawne nazwy poleceń należące do rejestratora
• descriptors: deskryptory poleceń używane podczas parsowania na potrzeby pomocy CLI, routingu i leniwej rejestracji CLI Pluginu
• parentPath: opcjonalna ścieżka polecenia nadrzędnego dla zagnieżdżonych grup poleceń, takich jak ["nodes"]

W przypadku funkcji sparowanych węzłów preferuj api.registerNodeCliFeature(registrar, opts?). Jest to niewielka nakładka na api.registerCli(..., { parentPath: ["nodes"] }), która jednoznacznie określa polecenia takie jak openclaw nodes canvas jako należące do Pluginu funkcje węzłów.

Jeśli polecenie Pluginu ma pozostać ładowane leniwie w standardowej głównej ścieżce CLI, podaj descriptors obejmujące każdy główny element polecenia 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ą rozpoznane 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 zachowana ze względów zgodności ścieżka natychmiastowego ładowania jest nadal obsługiwana, ale nie instaluje symboli zastępczych opartych na deskryptorach na potrzeby leniwego ładowania podczas parsowania.

Rejestracja zaplecza CLI

api.registerCliBackend(...) umożliwia Pluginowi zarządzanie domyślną konfiguracją lokalnego zaplecza CLI opartego na AI, takiego jak claude-cli lub my-cli.

• id zaplecza staje się prefiksem dostawcy w odwołaniach do modeli, takich jak my-cli/gpt-5.
• config zaplecza używa tej samej struktury co agents.defaults.cliBackends.<id>.
• Konfiguracja użytkownika nadal ma pierwszeństwo. Przed uruchomieniem CLI OpenClaw nakłada agents.defaults.cliBackends.<id> na domyślną konfigurację Pluginu.
• Użyj normalizeConfig, gdy zaplecze wymaga po scaleniu przekształceń zapewniających zgodność (na przykład normalizacji starych struktur flag).
• Użyj resolveExecutionArgs do modyfikacji argumentów argv w zakresie żądania, które należą do dialektu CLI, takich jak mapowanie poziomów rozumowania OpenClaw na natywną flagę nakładu. Hook otrzymuje ctx.executionMode; użyj "side-question", aby dodać natywne dla zaplecza flagi izolacji dla efemerycznych wywołań /btw. Jeśli te flagi niezawodnie wyłączają natywne narzędzia w CLI, w którym są one poza tym zawsze włączone, zadeklaruj również sideQuestionToolMode: "disabled".
• Zaplecza, które mogą wyłączyć wszystkie natywne narzędzia dla określonego uruchomienia, mogą deklarować nativeToolMode: "selectable". Ograniczone wywołania przekazują pustą krotkę ctx.toolAvailability.native wraz z dokładną listą dozwolonych MCP izolowaną przez hosta; resolveExecutionArgs musi wymuszać oba te ograniczenia w końcowych argumentach argv nowego lub wznawianego uruchomienia. Jeśli zaplecze nie może tego zrobić, OpenClaw bezpiecznie odmawia wykonania.

Kompletny przewodnik tworzenia znajduje się w sekcji Pluginy zaplecza CLI.

Wyłączne miejsca

Przestarzałe adaptery osadzania pamięci

• registerMemoryCapability jest preferowanym wyłącznym interfejsem API Pluginu pamięci.
• registerMemoryCapability może również udostępniać publicArtifacts.listArtifacts(...), aby towarzyszące Pluginy mogły korzystać z wyeksportowanych artefaktów pamięci za pośrednictwem openclaw/plugin-sdk/memory-host-core, zamiast uzyskiwać dostęp do prywatnego układu konkretnego Pluginu pamięci.
• registerMemoryPromptSection, registerMemoryFlushPlan i registerMemoryRuntime to wyłączne interfejsy API Pluginu pamięci zachowane ze względów zgodności ze starszymi wersjami.
• 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 rezerwowego.
• 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 okresie migracji, ale inspekcja Pluginu zgłasza to jako dług zgodności w przypadku Pluginów, które nie są dołączone.

Zdarzenia i cykl życia

Przykłady, typowe nazwy hooków i semantykę zabezpieczeń opisano w sekcji Hooki Pluginu.

Semantyka decyzji hooków

before_install jest hookiem cyklu życia środowiska wykonawczego Pluginu, a nie powierzchnią zasad instalacji operatora. Użyj security.installPolicy, gdy decyzja o zezwoleniu lub zablokowaniu musi obejmować ścieżki instalacji lub aktualizacji obsługiwane przez CLI i Gateway.

• before_tool_call: zwrócenie { block: true } jest rozstrzygające. Gdy dowolny moduł obsługi ustawi tę wartość, moduły obsługi 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 rozstrzygające. Gdy dowolny moduł obsługi ustawi tę wartość, moduły obsługi 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 rozstrzygające. Gdy dowolny moduł obsługi przejmie wysyłanie, moduły obsługi o niższym priorytecie oraz domyślna ścieżka wysyłania modelu są pomijane.
• message_sending: zwrócenie { cancel: true } jest rozstrzygające. Gdy dowolny moduł obsługi ustawi tę wartość, moduły obsługi 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: gdy potrzebujesz kierowania przychodzących wiadomości według wątku lub tematu, użyj typowanego pola threadId. Pole metadata zachowaj na dodatkowe dane specyficzne dla kanału.
• message_sending: najpierw używaj typowanych pól kierowania replyToId / threadId, a dopiero potem korzystaj z pola metadata specyficznego dla kanału.
• gateway_start: do stanu uruchamiania będącego własnością Gateway używaj ctx.config, ctx.workspaceDir i ctx.getCron?.() zamiast polegać na wewnętrznych punktach zaczepienia gateway:startup. Cron może być w tym momencie nadal ładowany.
• cron_reconciled: po uruchomieniu lub ponownym załadowaniu harmonogramu odbuduj pełną zewnętrzną projekcję Cron. Obejmuje ona reason oraz efektywny stan enabled, w tym enabled: false, natomiast ctx.getCron?.() zwraca dokładnie uzgodniony harmonogram. Przekaż ctx.abortSignal do trwałych operacji projekcji; zostaną one przerwane, gdy ta migawka harmonogramu zostanie zastąpiona lub Gateway zostanie zamknięty.
• cron_changed: obserwuj zmiany cyklu życia Cron będącego własnością Gateway. Zdarzenia scheduled i removed są wskazówkami uzgadniania po zatwierdzeniu, a nie uporządkowanym dziennikiem zmian. W zdarzeniu zaplanowania pole event.nextRunAtMs nie występuje, gdy zadanie nie ma następnego wybudzenia; zdarzenie usunięcia nadal zawiera migawkę usuniętego zadania.

Zewnętrzne harmonogramy wybudzania powinny stosować opóźnianie lub scalanie zdarzeń cron_changed, a następnie ponownie odczytywać pełny trwały widok z harmonogramu ostatnio przechwyconego przez cron_reconciled. Nie przejmuj harmonogramu z kontekstu cron_changed: odłączona wskazówka ze starszego harmonogramu może nałożyć się na późniejsze ponowne załadowanie.

Używaj cron_reconciled jako wyzwalacza pełnej migawki trwałego stanu ładowanego podczas uruchamiania Gateway lub zastępowania harmonogramu. Nie jest on odtwarzany przy przeładowaniu na gorąco dotyczącym wyłącznie pluginu. Moduły obsługi obserwacji działają równolegle, a wywołania typu „uruchom i nie czekaj” mogą się nakładać, dlatego odbiorcy nie mogą polegać na kolejności zakończenia zdarzeń. Zachowaj OpenClaw jako źródło prawdy dla sprawdzania terminów i wykonywania.

Adapter z pojedynczym wykonywaniem, trwałym zastępowaniem, ponawianiem z opóźnieniem i czystym zamykaniem opisano w sekcji Bezpieczna zewnętrzna projekcja Cron.

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            # Eksporty publiczne dla zewnętrznych odbiorców  runtime-api.ts    # Eksporty środowiska wykonawczego wyłącznie do użytku wewnętrznego  index.ts          # Punkt wejścia pluginu  setup-entry.ts    # Lekki punkt wejścia wyłącznie do konfiguracji (opcjonalny)

Publiczne powierzchnie wbudowanego pluginu ładowane przez fasadę (api.ts, runtime-api.ts, index.ts, setup-entry.ts i podobne publiczne pliki wejściowe) preferują aktywną migawkę konfiguracji środowiska wykonawczego, gdy OpenClaw już działa. Jeśli migawka środowiska wykonawczego jeszcze nie istnieje, używają zastępczo rozpoznanego pliku konfiguracyjnego na dysku. Spakowane fasady wbudowanych pluginów należy ładować przez programy ładujące fasady pluginów OpenClaw; bezpośrednie importy z dist/extensions/... omijają kontrole manifestu i plików pomocniczych środowiska wykonawczego, 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 funkcja pomocnicza jest celowo specyficzna dla dostawcy i nie należy jeszcze do ogólnej podścieżki SDK. Przykłady wbudowane:

• Anthropic: publiczny punkt styku api.ts / contract-api.ts dla funkcji pomocniczych nagłówków wersji beta Claude i strumieni service_tier.
• @openclaw/openai-provider: api.ts eksportuje konstruktory dostawcy, funkcje pomocnicze modelu domyślnego oraz konstruktory dostawcy czasu rzeczywistego.
• @openclaw/openrouter-provider: api.ts eksportuje konstruktor dostawcy oraz funkcje pomocnicze wdrażania i konfiguracji.

Powiązane materiały