Przejdź do głównej treści

​
Przegląd Plugin SDK

Plugin SDK to typowany kontrakt między pluginami a rdzeniem. Ta strona jest opisem referencyjnym co importować oraz co można rejestrować.
Szukasz przewodnika krok po kroku?

​
Konwencja importu

Zawsze importuj z konkretnej podścieżki: 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
Każda podścieżka jest małym, samowystarczalnym modułem. Dzięki temu uruchamianie pozostaje szybkie i unika się problemów z zależnościami cyklicznymi. Dla pomocników wejściowych/budujących specyficznych dla kanałów preferuj openclaw/plugin-sdk/channel-core; zachowaj openclaw/plugin-sdk/core dla szerszej powierzchni zbiorczej i współdzielonych helperów, takich jak buildChannelConfigSchema. Nie dodawaj ani nie opieraj się na wygodnych warstwach nazwanych od dostawców, takich jak openclaw/plugin-sdk/slack, openclaw/plugin-sdk/discord, openclaw/plugin-sdk/signal, openclaw/plugin-sdk/whatsapp ani warstwach helperów oznakowanych nazwą kanału. Dołączone pluginy powinny składać ogólne podścieżki SDK we własnych barrelach api.ts lub runtime-api.ts, a rdzeń powinien albo używać tych lokalnych dla pluginu barrelów, albo dodać wąski ogólny kontrakt SDK, gdy potrzeba rzeczywiście dotyczy wielu kanałów. Wygenerowana mapa eksportów nadal zawiera mały zestaw warstw helperów dla dołączonych pluginów, takich jak plugin-sdk/feishu, plugin-sdk/feishu-setup, plugin-sdk/zalo, plugin-sdk/zalo-setup oraz plugin-sdk/matrix*. Te podścieżki istnieją wyłącznie na potrzeby utrzymania dołączonych pluginów i zgodności; celowo pominięto je w typowej tabeli poniżej i nie są zalecaną ścieżką importu dla nowych pluginów zewnętrznych.

​
Opis podścieżek

Najczęściej używane podścieżki, pogrupowane według celu. Wygenerowana pełna lista ponad 200 podścieżek znajduje się w scripts/lib/plugin-sdk-entrypoints.json. Zarezerwowane podścieżki helperów dla dołączonych pluginów nadal pojawiają się na tej wygenerowanej liście. Traktuj je jako powierzchnie implementacyjne/zgodnościowe, chyba że strona dokumentacji wyraźnie promuje którąś z nich jako publiczną.

​
Wejście pluginu

PodścieżkaKluczowe eksporty
plugin-sdk/plugin-entrydefinePluginEntry
plugin-sdk/coredefineChannelPluginEntry, createChatChannelPlugin, createChannelPluginBase, defineSetupPluginEntry, buildChannelConfigSchema
plugin-sdk/config-schemaOpenClawSchema
plugin-sdk/provider-entrydefineSingleProviderPluginEntry
PodścieżkaKluczowe eksporty
plugin-sdk/channel-coredefineChannelPluginEntry, defineSetupPluginEntry, createChatChannelPlugin, createChannelPluginBase
plugin-sdk/config-schemaEksport głównego schematu Zod openclaw.json (OpenClawSchema)
plugin-sdk/channel-setupcreateOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, a także DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled, splitSetupEntries
plugin-sdk/setupWspółdzielone helpery kreatora konfiguracji, prompty listy dozwolonych oraz kreatory statusu konfiguracji
plugin-sdk/setup-runtimecreatePatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy
plugin-sdk/setup-adapter-runtimecreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolsformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
plugin-sdk/account-coreHelpery wielu kont i bramki akcji konfiguracji oraz helpery zapasowe dla konta domyślnego
plugin-sdk/account-idDEFAULT_ACCOUNT_ID, helpery normalizacji identyfikatorów kont
plugin-sdk/account-resolutionWyszukiwanie kont i helpery zapasowe dla ustawień domyślnych
plugin-sdk/account-helpersWąskie helpery list akcji na koncie / działań na koncie
plugin-sdk/channel-pairingcreateChannelPairingController
plugin-sdk/channel-reply-pipelinecreateChannelReplyPipeline
plugin-sdk/channel-config-helperscreateHybridChannelConfigAdapter
plugin-sdk/channel-config-schemaTypy schematu konfiguracji kanału
plugin-sdk/telegram-command-configHelpery normalizacji/walidacji niestandardowych poleceń Telegram z zapasowym kontraktem dołączonym
plugin-sdk/channel-policyresolveChannelGroupRequireMention
plugin-sdk/channel-lifecyclecreateAccountStatusSink
plugin-sdk/inbound-envelopeWspółdzielone helpery tras wejściowych i budowania kopert
plugin-sdk/inbound-reply-dispatchWspółdzielone helpery zapisu i wysyłki dla zdarzeń przychodzących
plugin-sdk/messaging-targetsHelpery parsowania/dopasowywania celów
plugin-sdk/outbound-mediaWspółdzielone helpery ładowania mediów wychodzących
plugin-sdk/outbound-runtimeHelpery tożsamości wychodzącej / delegowania wysyłki
plugin-sdk/thread-bindings-runtimeCykl życia powiązań wątków i helpery adapterów
plugin-sdk/agent-media-payloadStarszy kreator payloadów mediów agenta
plugin-sdk/conversation-runtimeHelpery powiązań rozmów/wątków, parowania i skonfigurowanych powiązań
plugin-sdk/runtime-config-snapshotHelper migawki konfiguracji środowiska uruchomieniowego
plugin-sdk/runtime-group-policyHelpery rozwiązywania zasad grup w środowisku uruchomieniowym
plugin-sdk/channel-statusWspółdzielone helpery migawek/podsumowań stanu kanału
plugin-sdk/channel-config-primitivesWąskie prymitywy schematu konfiguracji kanału
plugin-sdk/channel-config-writesHelpery autoryzacji zapisu konfiguracji kanału
plugin-sdk/channel-plugin-commonWspółdzielone eksporty preludium pluginu kanału
plugin-sdk/allowlist-config-editHelpery odczytu/edycji konfiguracji listy dozwolonych
plugin-sdk/group-accessWspółdzielone helpery decyzji o dostępie grupowym
plugin-sdk/direct-dmWspółdzielone helpery autoryzacji/ochrony bezpośrednich wiadomości
plugin-sdk/interactive-runtimeHelpery normalizacji/redukcji payloadów odpowiedzi interaktywnych
plugin-sdk/channel-inboundDebounce, dopasowanie wzmianek, helpery kopert
plugin-sdk/channel-send-resultTypy wyników odpowiedzi
plugin-sdk/channel-actionscreateMessageToolButtonsSchema, createMessageToolCardSchema
plugin-sdk/channel-targetsHelpery parsowania/dopasowywania celów
plugin-sdk/channel-contractTypy kontraktu kanału
plugin-sdk/channel-feedbackIntegracja opinii/reakcji
PodścieżkaKluczowe eksporty
plugin-sdk/provider-entrydefineSingleProviderPluginEntry
plugin-sdk/provider-setupDobrane helpery konfiguracji dla dostawców lokalnych / self-hosted
plugin-sdk/self-hosted-provider-setupSkoncentrowane helpery konfiguracji samodzielnie hostowanych dostawców zgodnych z OpenAI
plugin-sdk/cli-backendDomyślne ustawienia backendu CLI oraz stałe watchdog
plugin-sdk/provider-auth-runtimeHelpery rozwiązywania kluczy API w czasie działania dla pluginów dostawców
plugin-sdk/provider-auth-api-keyHelpery onboardingu/zapisu profilu dla kluczy API
plugin-sdk/provider-auth-resultStandardowy kreator wyników autoryzacji OAuth
plugin-sdk/provider-auth-loginWspółdzielone interaktywne helpery logowania dla pluginów dostawców
plugin-sdk/provider-env-varsHelpery wyszukiwania zmiennych środowiskowych autoryzacji dostawcy
plugin-sdk/provider-authcreateProviderApiKeyAuthMethod, ensureApiKeyFromOptionEnvOrPrompt, upsertAuthProfile
plugin-sdk/provider-model-sharedProviderReplayFamily, buildProviderReplayFamilyHooks, normalizeModelCompat, współdzielone kreatory polityk replay, helpery endpointów dostawców oraz helpery normalizacji identyfikatorów modeli, takie jak normalizeNativeXaiModelId
plugin-sdk/provider-catalog-sharedfindCatalogTemplate, buildSingleProviderApiKeyCatalog, supportsNativeStreamingUsageCompat, applyProviderNativeStreamingUsageCompat
plugin-sdk/provider-httpOgólne helpery możliwości HTTP/endpointów dostawców
plugin-sdk/provider-web-fetchHelpery rejestracji/pamięci podręcznej dla dostawców web-fetch
plugin-sdk/provider-web-searchHelpery rejestracji/pamięci podręcznej/konfiguracji dla dostawców web-search
plugin-sdk/provider-toolsProviderToolCompatFamily, buildProviderToolCompatFamilyHooks, czyszczenie schematu Gemini + diagnostyka oraz helpery zgodności xAI, takie jak resolveXaiModelCompatPatch / applyXaiModelCompat
plugin-sdk/provider-usagefetchClaudeUsage i podobne
plugin-sdk/provider-streamProviderStreamFamily, buildProviderStreamFamilyHooks, composeProviderStreamWrappers, typy wrapperów strumieni oraz współdzielone helpery wrapperów Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot
plugin-sdk/provider-onboardHelpery poprawek konfiguracji onboardingu
plugin-sdk/global-singletonPomocniki singletonów/map/pamięci podręcznej lokalnych dla procesu
PodścieżkaKluczowe eksporty
plugin-sdk/command-authresolveControlCommandGate, helpery rejestru poleceń, helpery autoryzacji nadawcy
plugin-sdk/approval-auth-runtimeHelpery rozwiązywania zatwierdzających i autoryzacji działań w tym samym czacie
plugin-sdk/approval-client-runtimeHelpery profili/filtrów zatwierdzania natywnego exec
plugin-sdk/approval-delivery-runtimeAdaptery możliwości/dostarczania natywnego zatwierdzania
plugin-sdk/approval-native-runtimeHelpery celu i powiązania kont dla natywnego zatwierdzania
plugin-sdk/approval-reply-runtimeHelpery payloadów odpowiedzi dla zatwierdzania exec/pluginów
plugin-sdk/command-auth-nativeHelpery natywnej autoryzacji poleceń i natywnych celów sesji
plugin-sdk/command-detectionWspółdzielone helpery wykrywania poleceń
plugin-sdk/command-surfaceHelpery normalizacji treści poleceń i powierzchni poleceń
plugin-sdk/allow-fromformatAllowFromLowercase
plugin-sdk/security-runtimeWspółdzielone helpery zaufania, bramkowania DM, treści zewnętrznych i zbierania sekretów
plugin-sdk/ssrf-policyHelpery listy dozwolonych hostów i polityki SSRF dla sieci prywatnych
plugin-sdk/ssrf-runtimeHelpery pinned-dispatcher, fetch chronionego przed SSRF oraz polityki SSRF
plugin-sdk/secret-inputHelpery parsowania danych wejściowych sekretów
plugin-sdk/webhook-ingressHelpery żądań/celów webhooków
plugin-sdk/webhook-request-guardsHelpery rozmiaru treści i limitu czasu żądań
PodścieżkaKluczowe eksporty
plugin-sdk/runtimeSzerokie helpery runtime/logowania/kopii zapasowych/instalacji pluginów
plugin-sdk/runtime-envWąskie helpery środowiska runtime, loggera, limitów czasu, ponawiania i backoff
plugin-sdk/runtime-storecreatePluginRuntimeStore
plugin-sdk/plugin-runtimeWspółdzielone helpery poleceń/hooków/http/interakcji pluginów
plugin-sdk/hook-runtimeWspółdzielone helpery potoku webhooków i hooków wewnętrznych
plugin-sdk/lazy-runtimeHelpery leniwego importu/powiązań runtime, takie jak createLazyRuntimeModule, createLazyRuntimeMethod i createLazyRuntimeSurface
plugin-sdk/process-runtimeHelpery wykonywania procesów
plugin-sdk/cli-runtimeHelpery formatowania CLI, oczekiwania i wersji
plugin-sdk/gateway-runtimeHelpery klienta Gateway i poprawek stanu kanału
plugin-sdk/config-runtimeHelpery ładowania/zapisu konfiguracji
plugin-sdk/telegram-command-configNormalizacja nazw/opisów poleceń Telegram i sprawdzanie duplikatów/konfliktów, nawet gdy dołączona powierzchnia kontraktu Telegram nie jest dostępna
plugin-sdk/approval-runtimeHelpery zatwierdzania exec/pluginów, kreatory możliwości zatwierdzania, helpery autoryzacji/profili, helpery natywnego routingu/runtime
plugin-sdk/reply-runtimeWspółdzielone helpery runtime przychodzących wiadomości/odpowiedzi, dzielenie na fragmenty, wysyłka, heartbeat, planer odpowiedzi
plugin-sdk/reply-dispatch-runtimeWąskie helpery wysyłki/finalizacji odpowiedzi
plugin-sdk/reply-historyWspółdzielone helpery krótkookresowej historii odpowiedzi, takie jak buildHistoryContext, recordPendingHistoryEntry i clearHistoryEntriesIfEnabled
plugin-sdk/reply-referencecreateReplyReferencePlanner
plugin-sdk/reply-chunkingWąskie helpery dzielenia tekstu/markdown
plugin-sdk/session-store-runtimeHelpery ścieżek pamięci sesji i updated-at
plugin-sdk/state-pathsHelpery ścieżek katalogów stanu/OAuth
plugin-sdk/routingHelpery routingu/powiązań kluczy sesji/kont, takie jak resolveAgentRoute, buildAgentSessionKey i resolveDefaultAgentBoundAccountId
plugin-sdk/status-helpersWspółdzielone helpery podsumowań stanu kanałów/kont, domyślne stany runtime i helpery metadanych problemów
plugin-sdk/target-resolver-runtimeWspółdzielone helpery rozwiązywania celów
plugin-sdk/string-normalization-runtimeHelpery normalizacji slugów/ciągów znaków
plugin-sdk/request-urlWyodrębnianie URL-i tekstowych z wejść podobnych do fetch/request
plugin-sdk/run-commandUruchamianie poleceń z limitem czasu i znormalizowanymi wynikami stdout/stderr
plugin-sdk/param-readersTypowe czytniki parametrów narzędzi/CLI
plugin-sdk/tool-sendWyodrębnianie kanonicznych pól celu wysyłki z argumentów narzędzia
plugin-sdk/temp-pathWspółdzielone helpery ścieżek tymczasowego pobierania
plugin-sdk/logging-coreLogger podsystemu i helpery redagowania
plugin-sdk/markdown-table-runtimeHelpery trybów tabel markdown
plugin-sdk/json-storeMałe helpery odczytu/zapisu stanu JSON
plugin-sdk/file-lockReentrantne helpery blokady plików
plugin-sdk/persistent-dedupeHelpery pamięci podręcznej deduplikacji opartej na dysku
plugin-sdk/acp-runtimeHelpery sesji/runtime ACP
plugin-sdk/agent-config-primitivesWąskie prymitywy schematu konfiguracji runtime agenta
plugin-sdk/boolean-paramLuźny czytnik parametrów logicznych
plugin-sdk/dangerous-name-runtimeHelpery rozwiązywania dopasowań nazw niebezpiecznych
plugin-sdk/device-bootstrapHelpery bootstrapu urządzenia i tokenów parowania
plugin-sdk/extension-sharedWspółdzielone prymitywy pomocnicze dla kanałów pasywnych i stanu
plugin-sdk/models-provider-runtimeHelpery odpowiedzi polecenia /models i dostawców
plugin-sdk/skill-commands-runtimeHelpery listowania poleceń Skills
plugin-sdk/native-command-registryHelpery rejestru/budowy/serializacji natywnych poleceń
plugin-sdk/provider-zai-endpointHelpery wykrywania endpointów Z.AI
plugin-sdk/infra-runtimeHelpery zdarzeń systemowych/heartbeat
plugin-sdk/collection-runtimeMałe helpery ograniczonych pamięci podręcznych
plugin-sdk/diagnostic-runtimeHelpery flag i zdarzeń diagnostycznych
plugin-sdk/error-runtimeGraf błędów, formatowanie, współdzielone helpery klasyfikacji błędów, isApprovalNotFoundError
plugin-sdk/fetch-runtimeOpakowany fetch, proxy i helpery przypiętego wyszukiwania
plugin-sdk/host-runtimeHelpery normalizacji nazw hostów i hostów SCP
plugin-sdk/retry-runtimeHelpery konfiguracji ponawiania i wykonawcy ponowień
plugin-sdk/agent-runtimeHelpery katalogów/tożsamości/przestrzeni roboczych agenta
plugin-sdk/directory-runtimeZapytania do katalogów oparte na konfiguracji / deduplikacja
plugin-sdk/keyed-async-queueKeyedAsyncQueue
PodścieżkaKluczowe eksporty
plugin-sdk/media-runtimeWspółdzielone helpery pobierania/przekształcania/przechowywania mediów oraz kreatory payloadów mediów
plugin-sdk/media-understandingTypy dostawców rozumienia mediów oraz helpery obrazów/audio po stronie dostawcy
plugin-sdk/text-runtimeWspółdzielone helpery tekstu/markdown/logowania, takie jak usuwanie tekstu widocznego dla asystenta, helpery renderowania/dzielenia/tabel markdown, helpery redagowania, helpery tagów dyrektyw i narzędzia bezpiecznego tekstu
plugin-sdk/text-chunkingHelper dzielenia tekstu wychodzącego
plugin-sdk/speechTypy dostawców mowy oraz helpery dyrektyw, rejestru i walidacji po stronie dostawcy
plugin-sdk/speech-coreWspółdzielone typy dostawców mowy, rejestr, dyrektywy i helpery normalizacji
plugin-sdk/realtime-transcriptionTypy dostawców transkrypcji w czasie rzeczywistym i helpery rejestru
plugin-sdk/realtime-voiceTypy dostawców głosu w czasie rzeczywistym i helpery rejestru
plugin-sdk/image-generationTypy dostawców generowania obrazów
plugin-sdk/image-generation-coreWspółdzielone typy generowania obrazów, failover, autoryzacja i helpery rejestru
plugin-sdk/video-generationTypy żądań/wyników generowania wideo i dostawców
plugin-sdk/video-generation-coreWspółdzielone typy generowania wideo, helpery failover, wyszukiwania dostawców i parsowania model-ref
plugin-sdk/webhook-targetsRejestr celów webhooków i helpery instalacji tras
plugin-sdk/webhook-pathHelpery normalizacji ścieżek webhooków
plugin-sdk/web-mediaWspółdzielone helpery ładowania mediów zdalnych/lokalnych
plugin-sdk/zodReeksport zod dla użytkowników Plugin SDK
plugin-sdk/testinginstallCommonResolveTargetErrorCases, shouldAckReaction
PodścieżkaKluczowe eksporty
plugin-sdk/memory-coreDołączona powierzchnia helperów memory-core dla helperów managera/konfiguracji/plików/CLI
plugin-sdk/memory-core-engine-runtimeFasada runtime indeksowania/wyszukiwania pamięci
plugin-sdk/memory-core-host-engine-foundationEksporty silnika bazowego hosta pamięci
plugin-sdk/memory-core-host-engine-embeddingsEksporty silnika embeddingów hosta pamięci
plugin-sdk/memory-core-host-engine-qmdEksporty silnika QMD hosta pamięci
plugin-sdk/memory-core-host-engine-storageEksporty silnika pamięci masowej hosta pamięci
plugin-sdk/memory-core-host-multimodalMultimodalne helpery hosta pamięci
plugin-sdk/memory-core-host-queryHelpery zapytań hosta pamięci
plugin-sdk/memory-core-host-secretHelpery sekretów hosta pamięci
plugin-sdk/memory-core-host-statusHelpery stanu hosta pamięci
plugin-sdk/memory-core-host-runtime-cliHelpery runtime CLI hosta pamięci
plugin-sdk/memory-core-host-runtime-coreHelpery głównego runtime hosta pamięci
plugin-sdk/memory-core-host-runtime-filesHelpery plików/runtime hosta pamięci
plugin-sdk/memory-lancedbDołączona powierzchnia helperów memory-lancedb
RodzinaBieżące podścieżkiPrzeznaczenie
Przeglądarkaplugin-sdk/browser-config-support, plugin-sdk/browser-supportHelpery wsparcia dołączonego pluginu przeglądarki
Matrixplugin-sdk/matrix, plugin-sdk/matrix-helper, plugin-sdk/matrix-runtime-heavy, plugin-sdk/matrix-runtime-shared, plugin-sdk/matrix-runtime-surface, plugin-sdk/matrix-surface, plugin-sdk/matrix-thread-bindingsPowierzchnia helperów/runtime dla dołączonego Matrix
Lineplugin-sdk/line, plugin-sdk/line-core, plugin-sdk/line-runtime, plugin-sdk/line-surfacePowierzchnia helperów/runtime dla dołączonego LINE
IRCplugin-sdk/irc, plugin-sdk/irc-surfacePowierzchnia helperów dla dołączonego IRC
Helpery specyficzne dla kanałówplugin-sdk/googlechat, plugin-sdk/zalouser, plugin-sdk/bluebubbles, plugin-sdk/bluebubbles-policy, plugin-sdk/mattermost, plugin-sdk/mattermost-policy, plugin-sdk/feishu-conversation, plugin-sdk/msteams, plugin-sdk/nextcloud-talk, plugin-sdk/nostr, plugin-sdk/tlon, plugin-sdk/twitchWarstwy zgodności/helperów dla dołączonych kanałów
Helpery specyficzne dla autoryzacji/pluginówplugin-sdk/github-copilot-login, plugin-sdk/github-copilot-token, plugin-sdk/diagnostics-otel, plugin-sdk/diffs, plugin-sdk/llm-task, plugin-sdk/thread-ownership, plugin-sdk/voice-callWarstwy helperów dla dołączonych funkcji/pluginów; plugin-sdk/github-copilot-token obecnie eksportuje DEFAULT_COPILOT_API_BASE_URL, deriveCopilotApiBaseUrlFromToken oraz resolveCopilotApiToken

​
API rejestracji

Wywołanie zwrotne register(api) otrzymuje obiekt OpenClawPluginApi z następującymi metodami:

​
Rejestracja możliwości

MetodaCo rejestruje
api.registerProvider(...)Wnioskowanie tekstowe (LLM)
api.registerCliBackend(...)Lokalny backend wnioskowania CLI
api.registerChannel(...)Kanał wiadomości
api.registerSpeechProvider(...)Synteza tekst-na-mowę / STT
api.registerRealtimeTranscriptionProvider(...)Strumieniowa transkrypcja w czasie rzeczywistym
api.registerRealtimeVoiceProvider(...)Dwukierunkowe sesje głosowe w czasie rzeczywistym
api.registerMediaUnderstandingProvider(...)Analiza obrazów/audio/wideo
api.registerImageGenerationProvider(...)Generowanie obrazów
api.registerVideoGenerationProvider(...)Generowanie wideo
api.registerWebFetchProvider(...)Dostawca pobierania / scrapingu z sieci
api.registerWebSearchProvider(...)Wyszukiwanie w sieci

​
Narzędzia i polecenia

MetodaCo rejestruje
api.registerTool(tool, opts?)Narzędzie agenta (wymagane lub { optional: true })
api.registerCommand(def)Niestandardowe polecenie (omija LLM)

​
Infrastruktura

MetodaCo rejestruje
api.registerHook(events, handler, opts?)Hook zdarzeń
api.registerHttpRoute(params)Endpoint HTTP Gateway
api.registerGatewayMethod(name, handler)Metoda RPC Gateway
api.registerCli(registrar, opts?)Podpolecenie CLI
api.registerService(service)Usługa działająca w tle
api.registerInteractiveHandler(registration)Obsługa interaktywna
Zarezerwowane przestrzenie nazw administracyjnych rdzenia (config.*, exec.approvals.*, wizard.*, update.*) zawsze pozostają operator.admin, nawet jeśli plugin próbuje przypisać węższy zakres dla metody Gateway. Dla metod należących do pluginu preferuj prefiksy specyficzne dla pluginu.

​
Metadane rejestracji CLI

api.registerCli(registrar, opts?) akceptuje dwa rodzaje metadanych najwyższego poziomu:
  • commands: jawne główne polecenia należące do rejestratora
  • descriptors: deskryptory poleceń na etapie parsowania używane dla głównej pomocy CLI, routingu i leniwej rejestracji CLI pluginu
Jeśli chcesz, aby polecenie pluginu pozostało leniwie ładowane w normalnej ścieżce głównego CLI, podaj descriptors, które obejmują każdy główny korzeń poleceń udostępniany przez ten rejestrator. 
api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Zarządzaj kontami Matrix, weryfikacją, urządzeniami i stanem profilu",
        hasSubcommands: true,
      },
    ],
  },
);
Używaj samego commands tylko wtedy, gdy nie potrzebujesz leniwej rejestracji głównego CLI. Ta ścieżka zgodności eager nadal jest obsługiwana, ale nie instaluje placeholderów opartych na deskryptorach dla leniwego ładowania na etapie parsowania.

​
Rejestracja backendu CLI

api.registerCliBackend(...) pozwala pluginowi posiadać domyślną konfigurację dla lokalnego backendu CLI AI, takiego jak claude-cli lub codex-cli.
  • id backendu staje się prefiksem dostawcy w odwołaniach do modeli, takich jak claude-cli/opus.
  • config backendu używa tego samego kształtu co agents.defaults.cliBackends.<id>.
  • Konfiguracja użytkownika nadal ma pierwszeństwo. OpenClaw scala agents.defaults.cliBackends.<id> z konfiguracją domyślną pluginu przed uruchomieniem CLI.
  • Użyj normalizeConfig, gdy backend wymaga poprawek zgodności po scaleniu (na przykład normalizacji starych kształtów flag).

​
Wyłączne sloty

MetodaCo rejestruje
api.registerContextEngine(id, factory)Silnik kontekstu (aktywny jeden naraz)
api.registerMemoryPromptSection(builder)Kreator sekcji promptu pamięci
api.registerMemoryFlushPlan(resolver)Resolver planu opróżniania pamięci
api.registerMemoryRuntime(runtime)Adapter runtime pamięci

​
Adaptery embeddingów pamięci

MetodaCo rejestruje
api.registerMemoryEmbeddingProvider(adapter)Adapter embeddingów pamięci dla aktywnego pluginu
  • registerMemoryPromptSection, registerMemoryFlushPlan oraz registerMemoryRuntime są wyłączne dla pluginów pamięci.
  • registerMemoryEmbeddingProvider pozwala aktywnemu pluginowi pamięci rejestrować jeden lub więcej identyfikatorów adapterów embeddingów (na przykład openai, gemini lub własny identyfikator zdefiniowany przez plugin).
  • Konfiguracja użytkownika, taka jak agents.defaults.memorySearch.provider oraz agents.defaults.memorySearch.fallback, jest rozwiązywana względem tych zarejestrowanych identyfikatorów adapterów.

​
Zdarzenia i cykl życia

MetodaCo robi
api.on(hookName, handler, opts?)Typowany hook cyklu życia
api.onConversationBindingResolved(handler)Callback rozwiązania powiązania rozmowy

​
Semantyka decyzji hooków

  • before_tool_call: zwrócenie { block: true } jest ostateczne. Gdy którykolwiek handler ustawi tę wartość, 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 ostateczne. Gdy którykolwiek handler ustawi tę wartość, 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.
  • message_sending: zwrócenie { cancel: true } jest ostateczne. Gdy którykolwiek handler ustawi tę wartość, 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.

​
Pola obiektu API

PoleTypOpis
api.idstringIdentyfikator pluginu
api.namestringNazwa wyświetlana
api.versionstring?Wersja pluginu (opcjonalna)
api.descriptionstring?Opis pluginu (opcjonalny)
api.sourcestringŚcieżka źródłowa pluginu
api.rootDirstring?Katalog główny pluginu (opcjonalny)
api.configOpenClawConfigBieżąca migawka konfiguracji (aktywna migawka runtime w pamięci, gdy dostępna)
api.pluginConfigRecord<string, unknown>Konfiguracja specyficzna dla pluginu z plugins.entries.<id>.config
api.runtimePluginRuntimeHelpery runtime
api.loggerPluginLoggerLogger o ograniczonym zakresie (debug, info, warn, error)
api.registrationModePluginRegistrationModeBieżący tryb ładowania; "setup-runtime" to lekkie okno uruchomienia/konfiguracji przed pełnym wejściem
api.resolvePath(input)(string) => stringRozwiązywanie ścieżki względem katalogu głównego pluginu

​
Konwencja modułów wewnętrznych

Wewnątrz pluginu używaj lokalnych plików barrel do importów wewnętrznych: 
my-plugin/
  api.ts            # Eksporty publiczne dla zewnętrznych konsumentów
  runtime-api.ts    # Eksporty runtime tylko do użytku wewnętrznego
  index.ts          # Punkt wejścia pluginu
  setup-entry.ts    # Lekki punkt wejścia tylko dla konfiguracji (opcjonalnie)
Nigdy nie importuj własnego pluginu przez openclaw/plugin-sdk/<your-plugin> w kodzie produkcyjnym. Kieruj importy wewnętrzne przez ./api.ts lub ./runtime-api.ts. Ścieżka SDK jest wyłącznie kontraktem zewnętrznym.
Publiczne powierzchnie dołączonych pluginów ładowane przez fasady (api.ts, runtime-api.ts, index.ts, setup-entry.ts i podobne publiczne pliki wejściowe) preferują teraz aktywną migawkę konfiguracji runtime, gdy OpenClaw już działa. Jeśli migawka runtime nie istnieje jeszcze, wracają do rozwiązanego pliku konfiguracji na dysku. Pluginy dostawców mogą także udostępniać wąski lokalny barrel kontraktu pluginu, gdy helper jest celowo specyficzny dla dostawcy i jeszcze nie należy do ogólnej podścieżki SDK. Obecny dołączony przykład: dostawca Anthropic trzyma swoje helpery strumieni Claude we własnej publicznej warstwie api.ts / contract-api.ts zamiast promować logikę nagłówków beta Anthropic i service_tier do ogólnego kontraktu plugin-sdk/*. Inne obecne dołączone przykłady:
  • @openclaw/openai-provider: api.ts eksportuje buildery dostawców, helpery modeli domyślnych i buildery dostawców realtime
  • @openclaw/openrouter-provider: api.ts eksportuje builder dostawcy oraz helpery onboardingu/konfiguracji
Kod produkcyjny rozszerzeń powinien także unikać importów openclaw/plugin-sdk/<other-plugin>. Jeśli helper jest rzeczywiście współdzielony, przenieś go do neutralnej podścieżki SDK, takiej jak openclaw/plugin-sdk/speech, .../provider-model-shared albo innej powierzchni zorientowanej na możliwości, zamiast łączyć ze sobą dwa pluginy.

​
Powiązane