Przejdź do głównej treści

​
Przegląd Plugin SDK

Plugin SDK to typowany kontrakt między pluginami a rdzeniem. Ta strona jest dokumentacją tego, co importować i co można rejestrować.
Szukasz przewodnika krok po kroku?

​
Konwencja importu

Zawsze importuj z konkretnej ścieżki podrzędnej: 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
Każda ścieżka podrzędna to mały, samowystarczalny moduł. Dzięki temu uruchamianie pozostaje szybkie i zapobiega to 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 parasolowej i współdzielonych helperów, takich jak buildChannelConfigSchema. Nie dodawaj ani nie polegaj na pomocniczych ścieżkach wygodnych nazwanych od dostawców, takich jak openclaw/plugin-sdk/slack, openclaw/plugin-sdk/discord, openclaw/plugin-sdk/signal, openclaw/plugin-sdk/whatsapp ani pomocniczych ścieżkach markowanych kanałami. Wbudowane pluginy powinny składać ogólne ścieżki podrzędne SDK we własnych barrelach api.ts lub runtime-api.ts, a rdzeń powinien używać albo tych lokalnych barrelów pluginu, albo dodać wąski ogólny kontrakt SDK, gdy potrzeba jest rzeczywiście międzykanałowa. Wygenerowana mapa eksportów nadal zawiera mały zestaw pomocniczych ścieżek dla wbudowanych pluginów, takich jak plugin-sdk/feishu, plugin-sdk/feishu-setup, plugin-sdk/zalo, plugin-sdk/zalo-setup i plugin-sdk/matrix*. Te ścieżki podrzędne istnieją wyłącznie dla utrzymania i zgodności wbudowanych pluginów; są celowo pominięte w poniższej wspólnej tabeli i nie są zalecaną ścieżką importu dla nowych zewnętrznych pluginów.

​
Dokumentacja ścieżek podrzędnych

Najczęściej używane ścieżki podrzędne, pogrupowane według przeznaczenia. Wygenerowana pełna lista ponad 200 ścieżek podrzędnych znajduje się w scripts/lib/plugin-sdk-entrypoints.json. Zarezerwowane pomocnicze ścieżki dla wbudowanych pluginów nadal pojawiają się w tej wygenerowanej liście. Traktuj je jako powierzchnie szczegółów implementacyjnych/zgodności, chyba że strona dokumentacji jawnie promuje którąś z nich jako publiczną.

​
Wejście pluginu

SubpathKluczowe eksporty
plugin-sdk/plugin-entrydefinePluginEntry
plugin-sdk/coredefineChannelPluginEntry, createChatChannelPlugin, createChannelPluginBase, defineSetupPluginEntry, buildChannelConfigSchema
plugin-sdk/config-schemaOpenClawSchema
plugin-sdk/provider-entrydefineSingleProviderPluginEntry
SubpathKluczowe 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, plus DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled, splitSetupEntries
plugin-sdk/setupWspółdzielone helpery kreatora konfiguracji, prompty allowlist, konstruktory 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 konfiguracji/wrót akcji dla wielu kont, helpery fallbacku konta domyślnego
plugin-sdk/account-idDEFAULT_ACCOUNT_ID, helpery normalizacji identyfikatora konta
plugin-sdk/account-resolutionHelpery wyszukiwania konta + fallbacku do domyślnego
plugin-sdk/account-helpersWąskie helpery listy kont/akcji 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 fallbackiem kontraktu wbudowanego
plugin-sdk/channel-policyresolveChannelGroupRequireMention
plugin-sdk/channel-lifecyclecreateAccountStatusSink
plugin-sdk/inbound-envelopeWspółdzielone helpery routingu przychodzącego + budowania kopert
plugin-sdk/inbound-reply-dispatchWspółdzielone helpery rejestrowania i dispatchu danych 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/delegacji wysyłki
plugin-sdk/thread-bindings-runtimeHelpery cyklu życia i adapterów powiązań wątków
plugin-sdk/agent-media-payloadStarszy konstruktor ładunku mediów agenta
plugin-sdk/conversation-runtimeHelpery powiązań rozmowy/wątku, pairingu i skonfigurowanych powiązań
plugin-sdk/runtime-config-snapshotHelper migawki konfiguracji runtime
plugin-sdk/runtime-group-policyHelpery rozstrzygania polityki grup w runtime
plugin-sdk/channel-statusWspółdzielone helpery migawki/podsumowania statusu kanału
plugin-sdk/channel-config-primitivesWąskie prymitywy schematu konfiguracji kanału
plugin-sdk/channel-config-writesHelpery autoryzacji zapisów konfiguracji kanału
plugin-sdk/channel-plugin-commonWspółdzielone eksporty preambuły pluginów kanałów
plugin-sdk/allowlist-config-editHelpery edycji/odczytu konfiguracji allowlist
plugin-sdk/group-accessWspółdzielone helpery decyzji dostępu grupowego
plugin-sdk/direct-dmWspółdzielone helpery uwierzytelniania/ochrony bezpośrednich DM
plugin-sdk/interactive-runtimeHelpery normalizacji/redukcji ładunków odpowiedzi interaktywnych
plugin-sdk/channel-inboundHelpery debounce dla wejścia, dopasowywania wzmianek, polityki wzmianek i 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-feedbackPowiązanie feedbacku/reakcji
plugin-sdk/channel-secret-runtimeWąskie helpery kontraktu sekretów, takie jak collectSimpleChannelFieldAssignments, getChannelSurface, pushAssignment, oraz typy celu sekretu
SubpathKluczowe eksporty
plugin-sdk/provider-entrydefineSingleProviderPluginEntry
plugin-sdk/provider-setupKuratorowane helpery konfiguracji lokalnych/samodzielnie hostowanych dostawców
plugin-sdk/self-hosted-provider-setupSkoncentrowane helpery konfiguracji samodzielnie hostowanego dostawcy zgodnego z OpenAI
plugin-sdk/cli-backendDomyślne ustawienia backendu CLI + stałe watchdoga
plugin-sdk/provider-auth-runtimeHelpery runtime rozstrzygania klucza API dla pluginów dostawców
plugin-sdk/provider-auth-api-keyHelpery wdrażania/zapisu profilu klucza API, takie jak upsertApiKeyProfile
plugin-sdk/provider-auth-resultStandardowy konstruktor wyniku uwierzytelniania OAuth
plugin-sdk/provider-auth-loginWspółdzielone interaktywne helpery logowania dla pluginów dostawców
plugin-sdk/provider-env-varsHelpery wyszukiwania zmiennych środowiskowych uwierzytelniania dostawców
plugin-sdk/provider-authcreateProviderApiKeyAuthMethod, ensureApiKeyFromOptionEnvOrPrompt, upsertAuthProfile, upsertApiKeyProfile, writeOAuthCredentials
plugin-sdk/provider-model-sharedProviderReplayFamily, buildProviderReplayFamilyHooks, normalizeModelCompat, współdzielone konstruktory polityki 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 HTTP/zdolności endpointów dostawców
plugin-sdk/provider-web-fetch-contractWąskie helpery kontraktu konfiguracji/wyboru web-fetch, takie jak enablePluginInConfig i WebFetchProviderPlugin
plugin-sdk/provider-web-fetchHelpery rejestracji/pamięci podręcznej dostawców web-fetch
plugin-sdk/provider-web-search-contractWąskie helpery kontraktu konfiguracji/poświadczeń web-search, takie jak enablePluginInConfig, resolveProviderWebSearchPluginConfig oraz ustawiające/pobierające poświadczenia o ograniczonym zakresie
plugin-sdk/provider-web-searchHelpery rejestracji/pamięci podręcznej/runtime 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 łatek konfiguracji onboardingu
plugin-sdk/global-singletonPomocniki singletonów/map/pamięci podręcznej lokalnych dla procesu
SubpathKluczowe eksporty
plugin-sdk/command-authresolveControlCommandGate, helpery rejestru poleceń, helpery autoryzacji nadawcy
plugin-sdk/approval-auth-runtimeHelpery rozstrzygania zatwierdzającego i uwierzytelniania akcji w tym samym czacie
plugin-sdk/approval-client-runtimeNatywne helpery profilu/filtru zatwierdzeń exec
plugin-sdk/approval-delivery-runtimeNatywne adaptery zdolności/dostarczania zatwierdzeń
plugin-sdk/approval-gateway-runtimeWspółdzielony helper rozstrzygania gateway zatwierdzeń
plugin-sdk/approval-handler-adapter-runtimeLekkie helpery ładowania natywnego adaptera zatwierdzeń dla gorących punktów wejścia kanałów
plugin-sdk/approval-handler-runtimeSzersze helpery runtime obsługi zatwierdzeń; preferuj węższe ścieżki adapter/gateway, gdy są wystarczające
plugin-sdk/approval-native-runtimeNatywne helpery celu zatwierdzeń + powiązań kont
plugin-sdk/approval-reply-runtimeHelpery ładunków odpowiedzi dla zatwierdzeń exec/pluginów
plugin-sdk/command-auth-nativeNatywne uwierzytelnianie poleceń + natywne helpery celu 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/channel-secret-runtimeWąskie helpery zbierania kontraktów sekretów dla powierzchni sekretów kanałów/pluginów
plugin-sdk/secret-ref-runtimeWąskie helpery coerceSecretRef i typowania SecretRef dla parsowania kontraktów sekretów/konfiguracji
plugin-sdk/security-runtimeWspółdzielone helpery zaufania, bramkowania DM, treści zewnętrznej i zbierania sekretów
plugin-sdk/ssrf-policyHelpery allowlist hostów i polityki SSRF dla sieci prywatnych
plugin-sdk/ssrf-runtimeHelpery pinned-dispatcher, fetch chronionego SSRF i polityki SSRF
plugin-sdk/secret-inputHelpery parsowania wejścia sekretów
plugin-sdk/webhook-ingressHelpery requestów/celów webhooków
plugin-sdk/webhook-request-guardsHelpery rozmiaru body/timeoutu requestów
SubpathKluczowe eksporty
plugin-sdk/runtimeSzerokie helpery runtime/logowania/kopii zapasowych/instalacji pluginów
plugin-sdk/runtime-envWąskie helpery środowiska runtime, loggera, timeoutu, retry i backoff
plugin-sdk/channel-runtime-contextOgólne helpery rejestracji i wyszukiwania kontekstu runtime kanału
plugin-sdk/runtime-storecreatePluginRuntimeStore
plugin-sdk/plugin-runtimeWspółdzielone helpery poleceń/hooków/http/interaktywności pluginów
plugin-sdk/hook-runtimeWspółdzielone helpery pipeline webhooków/wewnętrznych hooków
plugin-sdk/lazy-runtimeHelpery leniwego importu/powiązań runtime, takie jak createLazyRuntimeModule, createLazyRuntimeMethod i createLazyRuntimeSurface
plugin-sdk/process-runtimeHelpery exec procesów
plugin-sdk/cli-runtimeHelpery formatowania CLI, oczekiwania i wersji
plugin-sdk/gateway-runtimeHelpery klienta gateway i łatek statusu kanałów
plugin-sdk/config-runtimeHelpery ładowania/zapisu konfiguracji
plugin-sdk/telegram-command-configHelpery normalizacji nazw/opisów poleceń Telegram i kontroli duplikatów/konfliktów, nawet gdy powierzchnia kontraktu wbudowanego Telegrama jest niedostępna
plugin-sdk/approval-runtimeHelpery zatwierdzeń exec/pluginów, konstruktory zdolności zatwierdzeń, helpery auth/profili, natywne helpery routingu/runtime
plugin-sdk/reply-runtimeWspółdzielone helpery runtime wejścia/odpowiedzi, chunkingu, dispatchu, heartbeat i planisty odpowiedzi
plugin-sdk/reply-dispatch-runtimeWąskie helpery dispatchu/finalizacji odpowiedzi
plugin-sdk/reply-historyWspółdzielone helpery historii odpowiedzi dla krótkiego okna, takie jak buildHistoryContext, recordPendingHistoryEntry i clearHistoryEntriesIfEnabled
plugin-sdk/reply-referencecreateReplyReferencePlanner
plugin-sdk/reply-chunkingWąskie helpery chunkingu tekstu/Markdown
plugin-sdk/session-store-runtimeHelpery ścieżek magazynu sesji + updated-at
plugin-sdk/state-pathsHelpery ścieżek katalogów stanu/OAuth
plugin-sdk/routingHelpery routingu/klucza sesji/powiązania kont, takie jak resolveAgentRoute, buildAgentSessionKey i resolveDefaultAgentBoundAccountId
plugin-sdk/status-helpersWspółdzielone helpery podsumowań statusu kanałów/kont, domyślne stany runtime i helpery metadanych problemów
plugin-sdk/target-resolver-runtimeWspółdzielone helpery resolvera celów
plugin-sdk/string-normalization-runtimeHelpery normalizacji slugów/ciągów
plugin-sdk/request-urlWyodrębnia ciągi URL 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ębnia kanoniczne pola celu wysyłki z argumentów narzędzi
plugin-sdk/temp-pathWspółdzielone helpery ścieżek tymczasowych pobrań
plugin-sdk/logging-coreLogger subsystemu i helpery redakcji
plugin-sdk/markdown-table-runtimeHelpery trybu tabel Markdown
plugin-sdk/json-storeMałe helpery odczytu/zapisu stanu JSON
plugin-sdk/file-lockRekurencyjne helpery blokowania plików
plugin-sdk/persistent-dedupeHelpery pamięci podręcznej deduplikacji na dysku
plugin-sdk/acp-runtimeHelpery runtime/sesji ACP i dispatchu odpowiedzi
plugin-sdk/agent-config-primitivesWąskie prymitywy schematu konfiguracji runtime agenta
plugin-sdk/boolean-paramElastyczny czytnik parametrów logicznych
plugin-sdk/dangerous-name-runtimeHelpery rozstrzygania dopasowań niebezpiecznych nazw
plugin-sdk/device-bootstrapHelpery bootstrapu urządzenia i tokenów pairingu
plugin-sdk/extension-sharedWspółdzielone prymitywy helperów kanałów pasywnych, statusu i ambient proxy
plugin-sdk/models-provider-runtimeHelpery odpowiedzi polecenia /models / dostawców
plugin-sdk/skill-commands-runtimeHelpery listowania poleceń Skills
plugin-sdk/native-command-registryNatywne helpery rejestru/budowania/serializacji poleceń
plugin-sdk/provider-zai-endpointHelpery wykrywania endpointów Z.AI
plugin-sdk/infra-runtimeHelpery zdarzeń systemowych/heartbeat
plugin-sdk/collection-runtimeMałe helpery ograniczonej pamięci podręcznej
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 pinned lookup
plugin-sdk/host-runtimeHelpery normalizacji hostname i hosta SCP
plugin-sdk/retry-runtimeHelpery konfiguracji retry i wykonawcy retry
plugin-sdk/agent-runtimeHelpery katalogu/tożsamości/obszaru roboczego agenta
plugin-sdk/directory-runtimeZapytania o katalog oparte na konfiguracji/deduplikacja
plugin-sdk/keyed-async-queueKeyedAsyncQueue
SubpathKluczowe eksporty
plugin-sdk/media-runtimeWspółdzielone helpery pobierania/przekształcania/przechowywania mediów oraz konstruktory ładunków mediów
plugin-sdk/media-generation-runtimeWspółdzielone helpery failover generowania mediów, wybór kandydatów i komunikaty o brakujących modelach
plugin-sdk/media-understandingTypy dostawców rozumienia mediów oraz eksporty helperów obrazu/audio dla dostawców
plugin-sdk/text-runtimeWspółdzielone helpery tekstu/Markdown/logowania, takie jak usuwanie tekstu widocznego dla asystenta, helpery renderowania/chunkingu/tabel Markdown, helpery redakcji, helpery tagów dyrektyw i narzędzia bezpiecznego tekstu
plugin-sdk/text-chunkingHelper chunkingu tekstu wychodzącego
plugin-sdk/speechTypy dostawców mowy oraz eksporty helperów dyrektyw, rejestru i walidacji dla dostawców
plugin-sdk/speech-coreWspółdzielone typy dostawców mowy, rejestr, dyrektywy i helpery normalizacji
plugin-sdk/realtime-transcriptionTypy dostawców transkrypcji realtime i helpery rejestru
plugin-sdk/realtime-voiceTypy dostawców głosu realtime i helpery rejestru
plugin-sdk/image-generationTypy dostawców generowania obrazów
plugin-sdk/image-generation-coreWspółdzielone typy generowania obrazów, failover, uwierzytelnianie i helpery rejestru
plugin-sdk/music-generationTypy dostawców/requestów/wyników generowania muzyki
plugin-sdk/music-generation-coreWspółdzielone typy generowania muzyki, helpery failover, wyszukiwanie dostawców i parsowanie model-ref
plugin-sdk/video-generationTypy dostawców/requestów/wyników generowania wideo
plugin-sdk/video-generation-coreWspółdzielone typy generowania wideo, helpery failover, wyszukiwanie dostawców i parsowanie 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 zdalnych/lokalnych mediów
plugin-sdk/zodReeksportowane zod dla użytkowników plugin SDK
plugin-sdk/testinginstallCommonResolveTargetErrorCases, shouldAckReaction
SubpathKluczowe eksporty
plugin-sdk/memory-corePowierzchnia helperów wbudowanego memory-core dla managera/konfiguracji/plików/CLI
plugin-sdk/memory-core-engine-runtimeFasada runtime indeksu/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 storage hosta pamięci
plugin-sdk/memory-core-host-multimodalHelpery multimodalnego 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-eventsHelpery dziennika zdarzeń hosta pamięci
plugin-sdk/memory-core-host-statusHelpery statusu 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-host-coreNeutralny względem dostawcy alias helperów głównego runtime hosta pamięci
plugin-sdk/memory-host-eventsNeutralny względem dostawcy alias helperów dziennika zdarzeń hosta pamięci
plugin-sdk/memory-host-filesNeutralny względem dostawcy alias helperów plików/runtime hosta pamięci
plugin-sdk/memory-host-markdownWspółdzielone helpery zarządzanego Markdown dla pluginów sąsiadujących z pamięcią
plugin-sdk/memory-host-searchAktywna fasada runtime pamięci dla dostępu do menedżera wyszukiwania
plugin-sdk/memory-host-statusNeutralny względem dostawcy alias helperów statusu hosta pamięci
plugin-sdk/memory-lancedbPowierzchnia helperów wbudowanego memory-lancedb
FamilyCurrent subpathsIntended use
Browserplugin-sdk/browser-cdp, plugin-sdk/browser-config-runtime, plugin-sdk/browser-config-support, plugin-sdk/browser-control-auth, plugin-sdk/browser-node-runtime, plugin-sdk/browser-profiles, plugin-sdk/browser-security-runtime, plugin-sdk/browser-setup-tools, plugin-sdk/browser-supportHelpery wsparcia wbudowanego pluginu przeglądarki (browser-support pozostaje barrelem zgodności)
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 wbudowanego Matrix
Lineplugin-sdk/line, plugin-sdk/line-core, plugin-sdk/line-runtime, plugin-sdk/line-surfacePowierzchnia helperów/runtime wbudowanego LINE
IRCplugin-sdk/irc, plugin-sdk/irc-surfacePowierzchnia helperów wbudowanego IRC
Channel-specific helpersplugin-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/twitchWbudowane ścieżki zgodności/helperów kanałów
Auth/plugin-specific helpersplugin-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-callWbudowane ścieżki helperów funkcji/pluginów; plugin-sdk/github-copilot-token obecnie eksportuje DEFAULT_COPILOT_API_BASE_URL, deriveCopilotApiBaseUrlFromToken i resolveCopilotApiToken

​
API rejestracji

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

​
Rejestracja capabilities

MethodWhat it registers
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 realtime
api.registerRealtimeVoiceProvider(...)Dwukierunkowe sesje głosu realtime
api.registerMediaUnderstandingProvider(...)Analiza obrazu/audio/wideo
api.registerImageGenerationProvider(...)Generowanie obrazów
api.registerMusicGenerationProvider(...)Generowanie muzyki
api.registerVideoGenerationProvider(...)Generowanie wideo
api.registerWebFetchProvider(...)Dostawca web fetch / scrape
api.registerWebSearchProvider(...)Wyszukiwanie w sieci

​
Narzędzia i polecenia

MethodWhat it registers
api.registerTool(tool, opts?)Narzędzie agenta (wymagane lub { optional: true })
api.registerCommand(def)Polecenie niestandardowe (pomija LLM)

​
Infrastruktura

MethodWhat it registers
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)Handler interaktywny
api.registerMemoryPromptSupplement(builder)Addytywna sekcja promptu sąsiadująca z pamięcią
api.registerMemoryCorpusSupplement(adapter)Addytywny korpus wyszukiwania/odczytu pamięci
Zarezerwowane przestrzenie nazw administracyjnych rdzenia (config.*, exec.approvals.*, wizard.*, update.*) zawsze pozostają operator.admin, nawet jeśli plugin próbuje przypisać węższy zakres metody gateway. Dla metod należących do pluginów preferuj prefiksy specyficzne dla pluginu.

​
Metadane rejestracji CLI

api.registerCli(registrar, opts?) akceptuje dwa rodzaje metadanych najwyższego poziomu:
  • commands: jawne korzenie poleceń należące do rejestratora
  • descriptors: deskryptory poleceń na etapie parsowania używane do pomocy głównego CLI, routingu i leniwej rejestracji CLI pluginów
Jeśli chcesz, aby polecenie pluginu pozostało ładowane leniwie w zwykłej ścieżce głównego CLI, podaj descriptors, które obejmują każdy 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: "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ę lokalnego backendu CLI AI, takiego jak codex-cli.
  • id backendu staje się prefiksem dostawcy w odwołaniach do modeli, takich jak codex-cli/gpt-5.
  • 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 wartością domyślną pluginu przed uruchomieniem CLI.
  • Użyj normalizeConfig, gdy backend potrzebuje przeróbek zgodności po scaleniu (na przykład normalizacji starych kształtów flag).

​
Wyłączne sloty

MethodWhat it registers
api.registerContextEngine(id, factory)Silnik kontekstu (aktywny naraz jest jeden)
api.registerMemoryCapability(capability)Ujednolicona capability pamięci
api.registerMemoryPromptSection(builder)Konstruktor 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

MethodWhat it registers
api.registerMemoryEmbeddingProvider(adapter)Adapter embeddingów pamięci dla aktywnego pluginu
  • registerMemoryCapability to preferowane wyłączne API pluginów pamięci.
  • registerMemoryCapability może też udostępniać publicArtifacts.listArtifacts(...), aby pluginy towarzyszące mogły używać eksportowanych 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 wstecz, wyłączne API starszych pluginów pamięci.
  • registerMemoryEmbeddingProvider pozwala aktywnemu pluginowi pamięci zarejestrować 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 i agents.defaults.memorySearch.fallback, jest rozstrzygana względem tych zarejestrowanych identyfikatorów adapterów.

​
Zdarzenia i cykl życia

MethodWhat it does
api.on(hookName, handler, opts?)Typowany hook cyklu życia
api.onConversationBindingResolved(handler)Callback rozstrzygnięcia powiązania rozmowy

​
Semantyka decyzji hooków

  • before_tool_call: zwrócenie { block: true } jest ostateczne. Gdy dowolny handler to 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 ostateczne. Gdy dowolny handler to 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 ostateczne. Gdy dowolny handler przejmie dispatch, handlery o niższym priorytecie i domyślna ścieżka dispatchu modelu są pomijane.
  • message_sending: zwrócenie { cancel: true } jest ostateczne. Gdy dowolny handler to 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.

​
Pola obiektu API

FieldTypeDescription
api.idstringIdentyfikator pluginu
api.namestringNazwa wyświetlana
api.versionstring?Wersja pluginu (opcjonalnie)
api.descriptionstring?Opis pluginu (opcjonalnie)
api.sourcestringŚcieżka źródłowa pluginu
api.rootDirstring?Katalog główny pluginu (opcjonalnie)
api.configOpenClawConfigBieżąca migawka konfiguracji (aktywna migawka runtime w pamięci, gdy jest 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 uruchamiania/konfiguracji przed pełnym wejściem
api.resolvePath(input)(string) => stringRozstrzyga ścieżkę 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            # Publiczne eksporty dla odbiorców zewnętrznych
  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 do konfiguracji (opcjonalnie)
Nigdy nie importuj własnego pluginu przez openclaw/plugin-sdk/<your-plugin> z kodu produkcyjnego. Kieruj importy wewnętrzne przez ./api.ts lub ./runtime-api.ts. Ścieżka SDK jest wyłącznie kontraktem zewnętrznym.
Publiczne powierzchnie wbudowanych pluginów ładowane przez fasadę (api.ts, runtime-api.ts, index.ts, setup-entry.ts i podobne publiczne pliki wejściowe) teraz preferują aktywną migawkę konfiguracji runtime, gdy OpenClaw już działa. Jeśli migawka runtime jeszcze nie istnieje, wracają do rozstrzygniętego 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 ścieżki podrzędnej SDK. Aktualny wbudowany przykład: dostawca Anthropic przechowuje helpery strumienia Claude we własnej publicznej ścieżce api.ts / contract-api.ts zamiast promować logikę nagłówka beta Anthropic i service_tier do ogólnego kontraktu plugin-sdk/*. Inne aktualne wbudowane przykłady:
  • @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
Kod produkcyjny rozszerzeń powinien też unikać importów openclaw/plugin-sdk/<other-plugin>. Jeśli helper jest rzeczywiście współdzielony, przenieś go do neutralnej ścieżki podrzędnej SDK, takiej jak openclaw/plugin-sdk/speech, .../provider-model-shared lub innej powierzchni zorientowanej na capability, zamiast sprzęgać dwa pluginy ze sobą.

​
Powiązane