​

Wewnętrzne elementy Plugin

​

Publiczny model możliwości

​

Stan kompatybilności zewnętrznej

• istniejące zewnętrzne pluginy: zachowaj działanie integracji opartych na hookach; traktuj to jako bazowy poziom kompatybilności
• nowe pluginy bundled/natywne: preferuj jawną rejestrację możliwości zamiast zależnych od dostawcy wejść w implementację lub nowych projektów tylko z hookami
• zewnętrzne pluginy przyjmujące rejestrację możliwości: dozwolone, ale traktuj pomocnicze powierzchnie specyficzne dla możliwości jako ewoluujące, chyba że dokumentacja wyraźnie oznacza dany kontrakt jako stabilny

• API rejestracji możliwości to zamierzony kierunek
• legacy hooki pozostają najbezpieczniejszą ścieżką bez naruszania zgodności dla zewnętrznych pluginów w trakcie przejścia
• eksportowane podścieżki pomocnicze nie są równorzędne; preferuj wąski, udokumentowany kontrakt, a nie przypadkowe eksporty pomocnicze

​

Kształty pluginów

• plain-capability — rejestruje dokładnie jeden typ możliwości (na przykład plugin tylko dostawcy, taki jak mistral)
• hybrid-capability — rejestruje wiele typów możliwości (na przykład openai obsługuje wnioskowanie tekstowe, mowę, rozumienie mediów i generowanie obrazów)
• hook-only — rejestruje tylko hooki (typowane lub własne), bez możliwości, narzędzi, poleceń ani usług
• non-capability — rejestruje narzędzia, polecenia, usługi lub trasy, ale bez możliwości

​

Legacy hooki

• utrzymać jego działanie
• dokumentować go jako legacy
• dla pracy z nadpisywaniem modelu/dostawcy preferować before_model_resolve
• dla modyfikacji promptów preferować before_prompt_build
• usunąć dopiero wtedy, gdy realne użycie spadnie, a pokrycie fixture potwierdzi bezpieczeństwo migracji

​

Sygnały kompatybilności

​

Przegląd architektury

1. Manifest + wykrywanie OpenClaw znajduje kandydackie pluginy w skonfigurowanych ścieżkach, katalogach głównych workspace, globalnych katalogach rozszerzeń i bundled extensions. Wykrywanie najpierw odczytuje natywne manifesty openclaw.plugin.json oraz obsługiwane manifesty pakietów.
2. Włączanie + walidacja Core decyduje, czy wykryty plugin jest włączony, wyłączony, zablokowany czy wybrany do ekskluzywnego slotu, takiego jak pamięć.
3. Ładowanie środowiska uruchomieniowego Natywne pluginy OpenClaw są ładowane w procesie przez jiti i rejestrują możliwości w centralnym rejestrze. Zgodne pakiety są normalizowane do rekordów rejestru bez importowania kodu środowiska uruchomieniowego.
4. Konsumpcja powierzchni Pozostała część OpenClaw odczytuje rejestr, aby udostępniać narzędzia, kanały, konfigurację dostawców, hooki, trasy HTTP, polecenia CLI i usługi.

• metadane na etapie parsowania pochodzą z registerCli(..., { descriptors: [...] })
• rzeczywisty moduł CLI pluginu może pozostać lazy i zarejestrować się przy pierwszym wywołaniu

• wykrywanie + walidacja konfiguracji powinny działać na podstawie metadanych manifestu/schematu bez wykonywania kodu pluginu
• natywne zachowanie środowiska uruchomieniowego pochodzi ze ścieżki modułu pluginu register(api)

​

Pluginy kanałów i współdzielone narzędzie wiadomości

• core odpowiada za host współdzielonego narzędzia message, połączenie z promptami, prowadzenie sesji/wątków i dyspozycję wykonania
• pluginy kanałów odpowiadają za wykrywanie działań w danym zakresie, wykrywanie możliwości oraz wszelkie fragmenty schematu specyficzne dla kanału
• pluginy kanałów odpowiadają za gramatykę rozmów sesji specyficzną dla dostawcy, na przykład sposób, w jaki identyfikatory konwersacji kodują identyfikatory wątków lub dziedziczą po konwersacjach nadrzędnych
• pluginy kanałów wykonują końcowe działanie przez swój adapter działań

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• zaufane przychodzące requesterSenderId

• outbound.sendPoll to współdzielona baza dla kanałów pasujących do wspólnego modelu ankiet
• actions.handleAction("poll") to preferowana ścieżka dla semantyki ankiet specyficznej dla kanału lub dodatkowych parametrów ankiet

​

Model własności możliwości

• plugin firmowy powinien zwykle obsługiwać wszystkie powierzchnie OpenClaw skierowane do tej firmy
• plugin funkcjonalny powinien zwykle obsługiwać pełną powierzchnię funkcji, którą wprowadza
• kanały powinny korzystać ze współdzielonych możliwości core zamiast doraźnie ponownie implementować zachowanie dostawców

• bundled plugin openai odpowiada za zachowanie dostawcy modeli OpenAI oraz za zachowanie OpenAI dotyczące mowy + głosu w czasie rzeczywistym + rozumienia mediów + generowania obrazów
• bundled plugin elevenlabs odpowiada za zachowanie ElevenLabs dotyczące mowy
• bundled plugin microsoft odpowiada za zachowanie Microsoft dotyczące mowy
• bundled plugin google odpowiada za zachowanie dostawcy modeli Google oraz za zachowanie Google dotyczące rozumienia mediów + generowania obrazów + wyszukiwania w sieci
• bundled plugin firecrawl odpowiada za zachowanie Firecrawl dotyczące pobierania z sieci
• bundled pluginy minimax, mistral, moonshot i zai odpowiadają za swoje backendy rozumienia mediów
• bundled plugin qwen odpowiada za zachowanie dostawcy tekstowego Qwen oraz za rozumienie mediów i generowanie wideo
• plugin voice-call jest pluginem funkcjonalnym: odpowiada za transport połączeń, narzędzia, CLI, trasy i mostkowanie strumienia mediów Twilio, ale korzysta ze współdzielonych możliwości mowy oraz transkrypcji w czasie rzeczywistym i głosu w czasie rzeczywistym zamiast bezpośrednio importować pluginy dostawców

• OpenAI znajduje się w jednym pluginie, nawet jeśli obejmuje modele tekstowe, mowę, obrazy i przyszłe wideo
• inny dostawca może zrobić to samo dla własnego obszaru funkcjonalnego
• kanały nie muszą wiedzieć, który plugin dostawcy jest właścicielem dostawcy; korzystają ze współdzielonego kontraktu możliwości udostępnianego przez core

• plugin = granica własności
• możliwość = kontrakt core, który wiele pluginów może implementować lub wykorzystywać

1. zdefiniowanie brakującej możliwości w core
2. udostępnienie jej przez API/runtime pluginów w sposób typowany
3. podłączenie kanałów/funkcji do tej możliwości
4. pozwolenie pluginom dostawców na rejestrowanie implementacji

​

Warstwowanie możliwości

• warstwa możliwości core: współdzielona orkiestracja, polityka, fallback, reguły scalania konfiguracji, semantyka dostarczania i typowane kontrakty
• warstwa pluginów dostawców: API specyficzne dla dostawcy, autoryzacja, katalogi modeli, synteza mowy, generowanie obrazów, przyszłe backendy wideo, endpointy użycia
• warstwa pluginów kanałów/funkcji: integracje Slack/Discord/voice-call itd., które wykorzystują możliwości core i prezentują je na określonej powierzchni

• core odpowiada za politykę TTS w czasie odpowiedzi, kolejność fallbacków, preferencje i dostarczanie przez kanały
• openai, elevenlabs i microsoft odpowiadają za implementacje syntezy
• voice-call wykorzystuje pomocnik środowiska uruchomieniowego TTS dla telefonii

​

Przykład pluginu firmy z wieloma możliwościami

import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
import {
  describeImageWithModel,
  transcribeOpenAiCompatibleAudio,
} from "openclaw/plugin-sdk/media-understanding";

const plugin: OpenClawPluginDefinition = {
  id: "exampleai",
  name: "ExampleAI",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // auth/model catalog/runtime hooks
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // vendor speech config — implement the SpeechProviderPlugin interface directly
    });

    api.registerMediaUnderstandingProvider({
      id: "exampleai",
      capabilities: ["image", "audio", "video"],
      async describeImage(req) {
        return describeImageWithModel({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
    });

    api.registerWebSearchProvider(
      createPluginBackedWebSearchProvider({
        id: "exampleai-search",
        // credential + fetch logic
      }),
    );
  },
};

export default plugin;

• jeden plugin jest właścicielem powierzchni dostawcy
• core nadal jest właścicielem kontraktów możliwości
• kanały i pluginy funkcjonalne wykorzystują helpery api.runtime.*, a nie kod dostawcy
• testy kontraktowe mogą sprawdzać, że plugin zarejestrował możliwości, do których przyznaje się jako właściciel

​

Przykład możliwości: rozumienie wideo

1. core definiuje kontrakt rozumienia mediów
2. pluginy dostawców rejestrują describeImage, transcribeAudio i describeVideo, jeśli dotyczy
3. kanały i pluginy funkcjonalne wykorzystują współdzielone zachowanie core zamiast podłączać się bezpośrednio do kodu dostawcy

​

Kontrakty i egzekwowanie

• autorzy pluginów otrzymują jeden stabilny wewnętrzny standard
• core może odrzucać duplikaty własności, na przykład gdy dwa pluginy rejestrują ten sam identyfikator dostawcy
• uruchamianie może pokazywać użyteczne diagnostyki dla nieprawidłowej rejestracji
• testy kontraktowe mogą wymuszać własność bundled pluginów i zapobiegać cichemu dryfowi

1. egzekwowanie rejestracji w czasie działania Rejestr pluginów waliduje rejestracje podczas ładowania pluginów. Przykłady: zduplikowane identyfikatory dostawców, zduplikowane identyfikatory dostawców mowy i nieprawidłowe rejestracje powodują diagnostyki pluginów zamiast niezdefiniowanego zachowania.
2. testy kontraktowe Bundled pluginy są przechwytywane w rejestrach kontraktowych podczas uruchamiania testów, dzięki czemu OpenClaw może jawnie sprawdzać własność. Dziś jest to używane dla dostawców modeli, dostawców mowy, dostawców wyszukiwania w sieci oraz własności rejestracji bundled pluginów.

​

Co należy do kontraktu

• typowane
• małe
• specyficzne dla możliwości
• należące do core
• wielokrotnego użytku przez wiele pluginów
• możliwe do wykorzystania przez kanały/funkcje bez wiedzy o dostawcy

• polityka specyficzna dla dostawcy ukryta w core
• jednorazowe furtki dla pluginów, które omijają rejestr
• kod kanału sięgający bezpośrednio do implementacji dostawcy
• doraźne obiekty środowiska uruchomieniowego, które nie są częścią OpenClawPluginApi ani api.runtime

​

Model wykonania

• natywny plugin może rejestrować narzędzia, handlery sieciowe, hooki i usługi
• błąd natywnego pluginu może spowodować awarię lub destabilizację gateway
• złośliwy natywny plugin jest równoważny dowolnemu wykonaniu kodu wewnątrz procesu OpenClaw

• plugins.allow ufa identyfikatorom pluginów, a nie pochodzeniu źródła.
• Plugin workspace z tym samym identyfikatorem co bundled plugin celowo przesłania bundled kopię, gdy taki plugin workspace jest włączony/znajduje się na allowliście.
• To normalne i przydatne dla lokalnego programowania, testowania poprawek i hotfixów.

​

Granica eksportu

• podścieżki pomocnicze specyficzne dla bundled pluginów
• podścieżki infrastruktury runtime, które nie są przeznaczone jako publiczne API
• helpery wygody specyficzne dla dostawców
• helpery konfiguracji/onboardingu, które są szczegółami implementacji

​

Potok ładowania

1. wykrywa katalogi główne kandydackich pluginów
2. odczytuje natywne lub zgodne manifesty pakietów i metadane pakietów
3. odrzuca niebezpiecznych kandydatów
4. normalizuje konfigurację pluginów (plugins.enabled, allow, deny, entries, slots, load.paths)
5. decyduje o włączeniu dla każdego kandydata
6. ładuje włączone natywne moduły przez jiti
7. wywołuje natywne hooki register(api) (lub activate(api) — starszy alias) i zbiera rejestracje do rejestru pluginów
8. udostępnia rejestr powierzchniom poleceń/runtime

​

Zachowanie manifest-first

• identyfikacji pluginu
• wykrywania zadeklarowanych kanałów/Skills/schematu konfiguracji lub możliwości pakietu
• walidacji plugins.entries.<id>.config
• uzupełniania etykiet/placeholderów w Control UI
• wyświetlania metadanych instalacji/katalogu
• zachowania tanich deskryptorów aktywacji i konfiguracji bez ładowania runtime pluginu

• ładowanie CLI zawęża się do pluginów, które są właścicielami żądanej głównej komendy
• rozwiązywanie konfiguracji kanałów/pluginów zawęża się do pluginów, które są właścicielami żądanego identyfikatora kanału
• jawne rozwiązywanie konfiguracji/runtime dostawców zawęża się do pluginów, które są właścicielami żądanego identyfikatora dostawcy

​

Co loader przechowuje w pamięci podręcznej

• wyników wykrywania
• danych rejestru manifestów
• załadowanych rejestrów pluginów

• Ustaw OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1 lub OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1, aby wyłączyć te pamięci podręczne.
• Dostosuj okna pamięci podręcznej za pomocą OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS i OPENCLAW_PLUGIN_MANIFEST_CACHE_MS.

​

Model rejestru

• rekordy pluginów (tożsamość, źródło, pochodzenie, status, diagnostyka)
• narzędzia
• legacy hooki i hooki typowane
• kanały
• dostawców
• handlery RPC Gateway
• trasy HTTP
• rejestratory CLI
• usługi działające w tle
• polecenia należące do pluginów

• moduł pluginu -> rejestracja w rejestrze
• runtime core -> konsumpcja rejestru

​

Callbacki powiązania konwersacji

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" lub "denied"
• decision: "allow-once", "allow-always" lub "deny"
• binding: rozstrzygnięte powiązanie dla zatwierdzonych żądań
• request: podsumowanie oryginalnego żądania, wskazówka odłączenia, identyfikator nadawcy oraz metadane konwersacji

​

Hooki środowiska uruchomieniowego dostawcy

• metadane manifestu: providerAuthEnvVars dla taniego wyszukiwania uwierzytelniania dostawcy przez env przed załadowaniem runtime, providerAuthAliases dla wariantów dostawcy współdzielących uwierzytelnianie, channelEnvVars dla taniego wyszukiwania env/konfiguracji kanału przed załadowaniem runtime oraz providerAuthChoices dla tanich etykiet onboardingu/wyboru uwierzytelniania i metadanych flag CLI przed załadowaniem runtime
• hooki czasu konfiguracji: catalog / starsze discovery oraz applyConfigDefaults
• hooki runtime: normalizeModelId, normalizeTransport, normalizeConfig, applyNativeStreamingUsageCompat, resolveConfigApiKey, resolveSyntheticAuth, resolveExternalAuthProfiles, shouldDeferSyntheticProfileAuth, resolveDynamicModel, prepareDynamicModel, normalizeResolvedModel, contributeResolvedModelCompat, capabilities, normalizeToolSchemas, inspectToolSchemas, resolveReasoningOutputMode, prepareExtraParams, createStreamFn, wrapStreamFn, resolveTransportTurnState, resolveWebSocketSessionPolicy, formatApiKey, refreshOAuth, buildAuthDoctorHint, matchesContextOverflowError, classifyFailoverReason, isCacheTtlEligible, buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, isBinaryThinking, supportsXHighThinking, resolveDefaultThinkingLevel, isModernModelRef, prepareRuntimeAuth, resolveUsageAuth, fetchUsageSnapshot, createEmbeddingProvider, buildReplayPolicy, sanitizeReplayHistory, validateReplayTurns, onModelSelected

​

Kolejność hooków i sposób użycia

​

Przykład dostawcy

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

Wbudowane przykłady

• Anthropic używa resolveDynamicModel, capabilities, buildAuthDoctorHint, resolveUsageAuth, fetchUsageSnapshot, isCacheTtlEligible, resolveDefaultThinkingLevel, applyConfigDefaults, isModernModelRef i wrapStreamFn, ponieważ odpowiada za zgodność forward-compat Claude 4.6, wskazówki dotyczące rodziny dostawców, wskazówki naprawy auth, integrację endpointu użycia, kwalifikowalność prompt-cache, domyślne wartości konfiguracji zależne od auth, domyślną/adaptacyjną politykę rozumowania Claude oraz kształtowanie streamu specyficzne dla Anthropic dla nagłówków beta, /fast / serviceTier i context1m.
• Helpery streamu Anthropic specyficzne dla Claude pozostają na razie we własnej publicznej powierzchni api.ts / contract-api.ts bundled pluginu. Ta powierzchnia pakietu eksportuje wrapAnthropicProviderStream, resolveAnthropicBetas, resolveAnthropicFastMode, resolveAnthropicServiceTier oraz niższopoziomowe konstruktory wrapperów Anthropic zamiast rozszerzać ogólne SDK o reguły nagłówków beta jednego dostawcy.
• OpenAI używa resolveDynamicModel, normalizeResolvedModel i capabilities, a także buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, supportsXHighThinking i isModernModelRef, ponieważ odpowiada za zgodność forward-compat GPT-5.4, bezpośrednią normalizację OpenAI openai-completions -> openai-responses, wskazówki auth świadome Codex, tłumienie Spark, syntetyczne wiersze listy OpenAI oraz politykę rozumowania / modeli live GPT-5; rodzina streamów openai-responses-defaults odpowiada za współdzielone natywne wrappery OpenAI Responses dla nagłówków atrybucji, /fast/serviceTier, szczegółowości tekstu, natywnego wyszukiwania w sieci Codex, kształtowania ładunku reasoning-compat oraz zarządzania kontekstem Responses.
• OpenRouter używa catalog, a także resolveDynamicModel i prepareDynamicModel, ponieważ dostawca działa jako pass-through i może udostępniać nowe identyfikatory modeli przed aktualizacją statycznego katalogu OpenClaw; używa także capabilities, wrapStreamFn i isCacheTtlEligible, aby utrzymać nagłówki żądań specyficzne dla dostawcy, metadane routingu, poprawki rozumowania i politykę prompt-cache poza core. Jego polityka replay pochodzi z rodziny passthrough-gemini, podczas gdy rodzina streamów openrouter-thinking odpowiada za wstrzykiwanie rozumowania proxy oraz pomijanie nieobsługiwanych modeli / auto.
• GitHub Copilot używa catalog, auth, resolveDynamicModel i capabilities, a także prepareRuntimeAuth i fetchUsageSnapshot, ponieważ potrzebuje logowania urządzenia należącego do dostawcy, zachowania fallback modeli, niuansów transkryptu Claude, wymiany tokenu GitHub -> token Copilot oraz endpointu użycia należącego do dostawcy.
• OpenAI Codex używa catalog, resolveDynamicModel, normalizeResolvedModel, refreshOAuth i augmentModelCatalog, a także prepareExtraParams, resolveUsageAuth i fetchUsageSnapshot, ponieważ nadal działa na transportach core OpenAI, ale odpowiada za własną normalizację transportu/base URL, politykę fallback odświeżania OAuth, domyślny wybór transportu, syntetyczne wiersze katalogu Codex oraz integrację endpointu użycia ChatGPT; współdzieli tę samą rodzinę streamów openai-responses-defaults co bezpośrednie OpenAI.
• Google AI Studio i Gemini CLI OAuth używają resolveDynamicModel, buildReplayPolicy, sanitizeReplayHistory, resolveReasoningOutputMode, wrapStreamFn i isModernModelRef, ponieważ rodzina replay google-gemini odpowiada za fallback zgodności forward-compat Gemini 3.1, natywną walidację replay Gemini, sanityzację bootstrap replay, tryb wyjścia rozumowania z tagami oraz dopasowywanie nowoczesnych modeli, podczas gdy rodzina streamów google-thinking odpowiada za normalizację ładunku rozumowania Gemini; Gemini CLI OAuth używa również formatApiKey, resolveUsageAuth i fetchUsageSnapshot do formatowania tokenu, parsowania tokenu i połączenia endpointu limitów.
• Anthropic Vertex używa buildReplayPolicy przez rodzinę replay anthropic-by-model, dzięki czemu czyszczenie replay specyficzne dla Claude pozostaje ograniczone do identyfikatorów Claude, a nie do każdego transportu anthropic-messages.
• Amazon Bedrock używa buildReplayPolicy, matchesContextOverflowError, classifyFailoverReason i resolveDefaultThinkingLevel, ponieważ odpowiada za klasyfikację błędów throttle/not-ready/context-overflow specyficznych dla Bedrock dla ruchu Anthropic-on-Bedrock; jego polityka replay nadal współdzieli tę samą ochronę tylko dla Claude anthropic-by-model.
• OpenRouter, Kilocode, Opencode i Opencode Go używają buildReplayPolicy przez rodzinę replay passthrough-gemini, ponieważ przekazują modele Gemini przez transporty zgodne z OpenAI i potrzebują sanityzacji sygnatur myśli Gemini bez natywnej walidacji replay Gemini ani przekształceń bootstrap.
• MiniMax używa buildReplayPolicy przez rodzinę replay hybrid-anthropic-openai, ponieważ jeden dostawca odpowiada zarówno za semantykę wiadomości Anthropic, jak i zgodność z OpenAI; zachowuje usuwanie bloków rozumowania tylko dla Claude po stronie Anthropic, jednocześnie nadpisując tryb wyjścia rozumowania z powrotem na natywny, a rodzina streamów minimax-fast-mode odpowiada za przepisania modeli trybu fast na współdzielonej ścieżce streamu.
• Moonshot używa catalog oraz wrapStreamFn, ponieważ nadal korzysta ze współdzielonego transportu OpenAI, ale potrzebuje normalizacji ładunku rozumowania należącej do dostawcy; rodzina streamów moonshot-thinking mapuje konfigurację oraz stan /think na swój natywny binarny ładunek rozumowania.
• Kilocode używa catalog, capabilities, wrapStreamFn i isCacheTtlEligible, ponieważ potrzebuje nagłówków żądań należących do dostawcy, normalizacji ładunku rozumowania, wskazówek transkryptu Gemini oraz bramkowania cache-TTL Anthropic; rodzina streamów kilocode-thinking utrzymuje wstrzykiwanie rozumowania Kilo na współdzielonej ścieżce streamu proxy, jednocześnie pomijając kilo/auto i inne identyfikatory modeli proxy, które nie obsługują jawnych ładunków rozumowania.
• Z.AI używa resolveDynamicModel, prepareExtraParams, wrapStreamFn, isCacheTtlEligible, isBinaryThinking, isModernModelRef, resolveUsageAuth i fetchUsageSnapshot, ponieważ odpowiada za fallback GLM-5, domyślne wartości tool_stream, UX binary thinking, dopasowywanie nowoczesnych modeli oraz zarówno auth użycia, jak i pobieranie limitów; rodzina streamów tool-stream-default-on utrzymuje wrapper tool_stream domyślnie włączony poza ręcznie pisanym kodem specyficznym dla dostawcy.
• xAI używa normalizeResolvedModel, normalizeTransport, contributeResolvedModelCompat, prepareExtraParams, wrapStreamFn, resolveSyntheticAuth, resolveDynamicModel i isModernModelRef, ponieważ odpowiada za normalizację natywnego transportu xAI Responses, przepisania aliasów trybu fast Grok, domyślne tool_stream, czyszczenie strict-tool / ładunku rozumowania, ponowne użycie auth fallback dla narzędzi należących do pluginu, rozstrzyganie modeli Grok zgodne z forward-compat oraz poprawki zgodności należące do dostawcy, takie jak profil schematu narzędzi xAI, nieobsługiwane słowa kluczowe schematu, natywne web_search i dekodowanie argumentów wywołań narzędzi z encji HTML.
• Mistral, OpenCode Zen i OpenCode Go używają tylko capabilities, aby utrzymać niuanse transkryptu/narzędzi poza core.
• Bundled dostawcy tylko katalogowi, tacy jak byteplus, cloudflare-ai-gateway, huggingface, kimi-coding, nvidia, qianfan, synthetic, together, venice, vercel-ai-gateway i volcengine, używają tylko catalog.
• Qwen używa catalog dla swojego dostawcy tekstowego oraz współdzielonych rejestracji rozumienia mediów i generowania wideo dla swoich powierzchni multimodalnych.
• MiniMax i Xiaomi używają catalog oraz hooków użycia, ponieważ ich zachowanie /usage należy do pluginu, mimo że wnioskowanie nadal działa przez współdzielone transporty.

​

Narzędzia pomocnicze środowiska uruchomieniowego

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech zwraca zwykły ładunek wyjściowy TTS z core dla powierzchni plików/notatek głosowych.
• Używa konfiguracji core messages.tts i wyboru dostawcy.
• Zwraca bufor dźwięku PCM + częstotliwość próbkowania. Pluginy muszą przeprowadzić resampling/kodowanie dla dostawców.
• listVoices jest opcjonalne dla każdego dostawcy. Używaj go dla selektorów głosów lub przepływów konfiguracji należących do dostawcy.
• Listy głosów mogą zawierać bogatsze metadane, takie jak locale, płeć i tagi osobowości dla selektorów świadomych dostawcy.
• OpenAI i ElevenLabs obsługują dziś telefonię. Microsoft nie.

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• Zachowaj politykę TTS, fallback i dostarczanie odpowiedzi w core.
• Używaj dostawców mowy dla zachowania syntezy należącego do dostawcy.
• Starsze wejście Microsoft edge jest normalizowane do identyfikatora dostawcy microsoft.
• Preferowany model własności jest zorientowany na firmę: jeden plugin dostawcy może obsługiwać tekst, mowę, obrazy i przyszłych dostawców mediów, gdy OpenClaw dodaje te kontrakty możliwości.

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• Zachowaj orkiestrację, fallback, konfigurację i podłączenie kanałów w core.
• Zachowaj zachowanie dostawcy w pluginie dostawcy.
• Rozszerzanie addytywne powinno pozostać typowane: nowe opcjonalne metody, nowe opcjonalne pola wyników, nowe opcjonalne możliwości.
• Generowanie wideo już stosuje ten sam wzorzec:
  • core jest właścicielem kontraktu możliwości i helpera runtime
  • pluginy dostawców rejestrują api.registerVideoGenerationProvider(...)
  • pluginy funkcjonalne/kanałowe wykorzystują api.runtime.videoGeneration.*

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* to preferowana współdzielona powierzchnia dla rozumienia obrazów/audio/wideo.
• Używa konfiguracji audio rozumienia mediów z core (tools.media.audio) oraz kolejności fallback dostawców.
• Zwraca { text: undefined }, gdy nie powstanie wynik transkrypcji (na przykład w przypadku pominiętego/nieobsługiwanego wejścia).
• api.runtime.stt.transcribeAudioFile(...) pozostaje aliasem zgodności.

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider i model to opcjonalne nadpisania dla pojedynczego przebiegu, a nie trwałe zmiany sesji.
• OpenClaw honoruje te pola nadpisania tylko dla zaufanych wywołujących.
• W przypadku przebiegów fallback należących do pluginu operatorzy muszą wyrazić zgodę przez plugins.entries.<id>.subagent.allowModelOverride: true.
• Użyj plugins.entries.<id>.subagent.allowedModels, aby ograniczyć zaufane pluginy do określonych kanonicznych celów provider/model, lub "*" aby jawnie dopuścić dowolny cel.
• Niezaufane przebiegi subagenta pluginów nadal działają, ale żądania nadpisania są odrzucane zamiast po cichu przechodzić do fallback.

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• Zachowaj wybór dostawcy, rozstrzyganie poświadczeń i współdzieloną semantykę żądań w core.
• Używaj dostawców wyszukiwania w sieci dla transportów wyszukiwania specyficznych dla dostawcy.
• api.runtime.webSearch.* to preferowana współdzielona powierzchnia dla pluginów funkcjonalnych/kanałowych, które potrzebują zachowania wyszukiwania bez zależności od wrappera narzędzia agenta.

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): generuje obraz przy użyciu skonfigurowanego łańcucha dostawców generowania obrazów.
• listProviders(...): wyświetla dostępnych dostawców generowania obrazów i ich możliwości.

​

Trasy HTTP Gateway

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: ścieżka trasy pod serwerem HTTP gateway.
• auth: wymagane. Użyj "gateway", aby wymagać zwykłego auth gateway, lub "plugin" dla auth zarządzanego przez plugin / weryfikacji Webhook.
• match: opcjonalne. "exact" (domyślnie) lub "prefix".
• replaceExisting: opcjonalne. Pozwala temu samemu pluginowi zastąpić własną istniejącą rejestrację trasy.
• handler: zwróć true, gdy trasa obsłużyła żądanie.

• api.registerHttpHandler(...) zostało usunięte i spowoduje błąd ładowania pluginu. Zamiast tego użyj api.registerHttpRoute(...).
• Trasy pluginów muszą jawnie deklarować auth.
• Konflikty dokładnych path + match są odrzucane, chyba że ustawiono replaceExisting: true, a jeden plugin nie może zastąpić trasy innego pluginu.
• Nakładające się trasy z różnymi poziomami auth są odrzucane. Łańcuchy przejścia exact/prefix utrzymuj tylko na tym samym poziomie auth.
• Trasy auth: "plugin" nie otrzymują automatycznie zakresów runtime operatora. Służą do webhooków / weryfikacji podpisów zarządzanych przez plugin, a nie do uprzywilejowanych wywołań helperów Gateway.
• Trasy auth: "gateway" działają wewnątrz zakresu runtime żądania Gateway, ale ten zakres jest celowo konserwatywny:
  • auth bearer oparty na współdzielonym sekrecie (gateway.auth.mode = "token" / "password") utrzymuje zakresy runtime tras pluginów przypięte do operator.write, nawet jeśli wywołujący wysyła x-openclaw-scopes
  • zaufane tryby HTTP przekazujące tożsamość (na przykład trusted-proxy lub gateway.auth.mode = "none" na prywatnym ingressie) honorują x-openclaw-scopes tylko wtedy, gdy nagłówek jest jawnie obecny
  • jeśli x-openclaw-scopes jest nieobecny w takich żądaniach tras pluginów z przekazywaną tożsamością, zakres runtime wraca do operator.write
• Praktyczna zasada: nie zakładaj, że trasa pluginu z auth gateway jest niejawnie powierzchnią administracyjną. Jeśli twoja trasa potrzebuje zachowania tylko dla administratora, wymagaj trybu auth przekazującego tożsamość i udokumentuj jawny kontrakt nagłówka x-openclaw-scopes.

​

Ścieżki importu Plugin SDK

• openclaw/plugin-sdk/plugin-entry dla prymitywów rejestracji pluginów.
• openclaw/plugin-sdk/core dla ogólnego współdzielonego kontraktu skierowanego do pluginów.
• openclaw/plugin-sdk/config-schema dla eksportu głównego schematu Zod openclaw.json (OpenClawSchema).
• Stabilne prymitywy kanałów, takie jak openclaw/plugin-sdk/channel-setup, openclaw/plugin-sdk/setup-runtime, openclaw/plugin-sdk/setup-adapter-runtime, openclaw/plugin-sdk/setup-tools, openclaw/plugin-sdk/channel-pairing, openclaw/plugin-sdk/channel-contract, openclaw/plugin-sdk/channel-feedback, openclaw/plugin-sdk/channel-inbound, openclaw/plugin-sdk/channel-lifecycle, openclaw/plugin-sdk/channel-reply-pipeline, openclaw/plugin-sdk/command-auth, openclaw/plugin-sdk/secret-input i openclaw/plugin-sdk/webhook-ingress dla współdzielonego podłączenia konfiguracji/auth/odpowiedzi/Webhook. channel-inbound jest wspólnym miejscem dla debounce, dopasowywania wzmianek, helperów polityki wzmianek przychodzących, formatowania kopert przychodzących oraz helperów kontekstu kopert przychodzących. channel-setup to wąska ścieżka konfiguracji opcjonalnej instalacji. setup-runtime to bezpieczna dla runtime powierzchnia konfiguracji używana przez setupEntry / odroczone uruchamianie, w tym bezpieczne importowo adaptery łatek konfiguracji. setup-adapter-runtime to świadoma env ścieżka adaptera konfiguracji konta. setup-tools to mała ścieżka helperów CLI/archiwów/dokumentacji (formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR).
• Podścieżki domenowe, takie jak openclaw/plugin-sdk/channel-config-helpers, openclaw/plugin-sdk/allow-from, openclaw/plugin-sdk/channel-config-schema, openclaw/plugin-sdk/telegram-command-config, openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/approval-gateway-runtime, openclaw/plugin-sdk/approval-handler-adapter-runtime, openclaw/plugin-sdk/approval-handler-runtime, openclaw/plugin-sdk/approval-runtime, openclaw/plugin-sdk/config-runtime, openclaw/plugin-sdk/infra-runtime, openclaw/plugin-sdk/agent-runtime, openclaw/plugin-sdk/lazy-runtime, openclaw/plugin-sdk/reply-history, openclaw/plugin-sdk/routing, openclaw/plugin-sdk/status-helpers, openclaw/plugin-sdk/text-runtime, openclaw/plugin-sdk/runtime-store i openclaw/plugin-sdk/directory-runtime dla współdzielonych helperów runtime/konfiguracji. telegram-command-config to wąska publiczna ścieżka dla normalizacji/walidacji niestandardowych poleceń Telegram i pozostaje dostępna nawet wtedy, gdy bundled powierzchnia kontraktu Telegram jest tymczasowo niedostępna. text-runtime to współdzielona ścieżka tekstu/Markdown/logowania, obejmująca usuwanie tekstu widocznego dla asystenta, helpery renderowania/dzielenia Markdown, helpery redakcji, helpery tagów dyrektyw oraz bezpieczne narzędzia tekstowe.
• Powierzchnie kanałów specyficzne dla zatwierdzeń powinny preferować jeden kontrakt approvalCapability w pluginie. Core odczytuje wtedy auth zatwierdzeń, dostarczanie, renderowanie, natywne routowanie i leniwe zachowanie natywnego handlera przez tę jedną możliwość zamiast mieszać zachowanie zatwierdzeń z niezwiązanymi polami pluginu.
• openclaw/plugin-sdk/channel-runtime jest przestarzałe i pozostaje jedynie jako shima zgodności dla starszych pluginów. Nowy kod powinien importować węższe prymitywy ogólne, a kod repo nie powinien dodawać nowych importów tej shimy.
• Wewnętrzne elementy bundled extensions pozostają prywatne. Zewnętrzne pluginy powinny używać tylko podścieżek openclaw/plugin-sdk/*. Kod core/testów OpenClaw może używać publicznych punktów wejścia repo pod katalogiem głównym pakietu pluginu, takich jak index.js, api.js, runtime-api.js, setup-entry.js oraz wąsko ukierunkowane pliki, takie jak login-qr-api.js. Nigdy nie importuj src/* pakietu pluginu z core ani z innego rozszerzenia.
• Podział punktów wejścia repo: <plugin-package-root>/api.js to barrel helperów/typów, <plugin-package-root>/runtime-api.js to barrel tylko runtime, <plugin-package-root>/index.js to punkt wejścia bundled pluginu, a <plugin-package-root>/setup-entry.js to punkt wejścia pluginu konfiguracji.
• Aktualne przykłady bundled dostawców:
  • Anthropic używa api.js / contract-api.js dla helperów streamu Claude, takich jak wrapAnthropicProviderStream, helpery nagłówków beta i parsowanie service_tier.
  • OpenAI używa api.js dla konstruktorów dostawców, helperów modeli domyślnych i konstruktorów dostawców realtime.
  • OpenRouter używa api.js dla swojego konstruktora dostawcy oraz helperów onboardingu/konfiguracji, podczas gdy register.runtime.js może nadal ponownie eksportować ogólne helpery plugin-sdk/provider-stream do użytku lokalnego w repo.
• Publiczne punkty wejścia ładowane przez fasadę preferują aktywny snapshot konfiguracji runtime, gdy taki istnieje, a następnie wracają do rozstrzygniętego pliku konfiguracji na dysku, gdy OpenClaw nie udostępnia jeszcze snapshotu runtime.
• Ogólne współdzielone prymitywy pozostają preferowanym publicznym kontraktem SDK. Nadal istnieje mały zastrzeżony zestaw zgodności helperów oznaczonych marką bundled kanałów. Traktuj je jako powierzchnie utrzymaniowe/zgodnościowe dla bundled, a nie nowe cele importu dla podmiotów trzecich; nowe kontrakty międzykanałowe powinny nadal trafiać do ogólnych podścieżek plugin-sdk/* albo lokalnych barrelów pluginu api.js / runtime-api.js.

• Unikaj głównego barrelu openclaw/plugin-sdk w nowym kodzie.
• Najpierw preferuj wąskie, stabilne prymitywy. Nowsze podścieżki setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ allowlist/status/message-tool są zamierzonym kontraktem dla nowych prac nad bundled i zewnętrznymi pluginami. Parsowanie/dopasowywanie celów należy do openclaw/plugin-sdk/channel-targets. Bramki działań wiadomości i helpery identyfikatorów wiadomości reakcji należą do openclaw/plugin-sdk/channel-actions.
• Barrele helperów specyficznych dla bundled extensions nie są domyślnie stabilne. Jeśli helper jest potrzebny tylko bundled extension, trzymaj go za lokalną warstwą api.js lub runtime-api.js tego rozszerzenia zamiast promować go do openclaw/plugin-sdk/<extension>.
• Nowe współdzielone ścieżki helperów powinny być ogólne, a nie oznaczone marką kanału. Wspólne parsowanie celów należy do openclaw/plugin-sdk/channel-targets; elementy wewnętrzne specyficzne dla kanału pozostają za lokalną warstwą api.js lub runtime-api.js należącego pluginu.
• Podścieżki specyficzne dla możliwości, takie jak image-generation, media-understanding i speech, istnieją, ponieważ bundled/natywne pluginy używają ich już dziś. Ich obecność sama w sobie nie oznacza, że każdy eksportowany helper jest długoterminowym zamrożonym kontraktem zewnętrznym.

​

Schematy narzędzia wiadomości

• createMessageToolButtonsSchema() dla ładunków w stylu siatki przycisków
• createMessageToolCardSchema() dla strukturalnych ładunków kart

​

Rozstrzyganie celów kanału

• messaging.inferTargetChatType({ to }) decyduje, czy znormalizowany cel powinien być traktowany jako direct, group czy channel przed wyszukaniem w katalogu.
• messaging.targetResolver.looksLikeId(raw, normalized) mówi core, czy dane wejście powinno pominąć bezpośrednio do rozstrzygania podobnego do identyfikatora zamiast wyszukiwania w katalogu.
• messaging.targetResolver.resolveTarget(...) to fallback pluginu, gdy core potrzebuje końcowego rozstrzygnięcia należącego do dostawcy po normalizacji lub po braku trafienia w katalogu.
• messaging.resolveOutboundSessionRoute(...) odpowiada za konstruowanie trasy sesji specyficzne dla dostawcy po rozstrzygnięciu celu.

• Używaj inferTargetChatType dla decyzji kategorialnych, które powinny zapadać przed wyszukiwaniem peerów/grup.
• Używaj looksLikeId do sprawdzeń typu „traktuj to jako jawny/natywny identyfikator celu”.
• Używaj resolveTarget dla fallbacku normalizacji specyficznego dla dostawcy, a nie dla szerokiego wyszukiwania w katalogu.
• Natywne identyfikatory dostawcy, takie jak identyfikatory czatów, identyfikatory wątków, JID-y, handle i identyfikatory pokoi, przechowuj wewnątrz wartości target lub parametrów specyficznych dla dostawcy, a nie w ogólnych polach SDK.

​

Katalogi oparte na konfiguracji

• peery DM sterowane allowlistą
• skonfigurowane mapy kanałów/grup
• statyczne fallbacki katalogów ograniczone do konta

• filtrowanie zapytań
• stosowanie limitów
• deduplikację/helpery normalizacji
• budowanie ChannelDirectoryEntry[]

​

Katalogi dostawców

• { provider } dla jednego wpisu dostawcy
• { providers } dla wielu wpisów dostawców

• simple: dostawcy używający zwykłego klucza API lub env
• profile: dostawcy pojawiający się, gdy istnieją profile auth
• paired: dostawcy syntetyzujący wiele powiązanych wpisów dostawców
• late: ostatni przebieg, po innych niejawnych dostawcach

• discovery nadal działa jako starszy alias
• jeśli zarejestrowano zarówno catalog, jak i discovery, OpenClaw używa catalog

​

Kanałowa inspekcja tylko do odczytu

• resolveAccount(...) to ścieżka runtime. Może zakładać, że poświadczenia są w pełni zmaterializowane i może szybko zakończyć się błędem, gdy brakuje wymaganych sekretów.
• Ścieżki poleceń tylko do odczytu, takie jak openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve oraz przepływy naprawy doctor/config, nie powinny wymagać materializacji poświadczeń runtime tylko po to, by opisać konfigurację.

• Zwracaj tylko opisowy stan konta.
• Zachowuj enabled i configured.
• Dołączaj pola źródła/statusu poświadczeń, gdy ma to znaczenie, takie jak:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Nie musisz zwracać surowych wartości tokenów tylko po to, by raportować dostępność tylko do odczytu. Zwrócenie tokenStatus: "available" (oraz odpowiadającego mu pola źródła) wystarcza dla poleceń typu status.
• Używaj configured_unavailable, gdy poświadczenie jest skonfigurowane przez SecretRef, ale niedostępne w bieżącej ścieżce polecenia.

​

Package packi

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• sama rejestracja kanału
• wszelkie trasy HTTP, które muszą być dostępne zanim gateway zacznie nasłuchiwać
• wszelkie metody Gateway, narzędzia lub usługi, które muszą istnieć w tym samym oknie czasowym

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

Metadane katalogu kanałów

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: etykieta dodatkowa dla bogatszych powierzchni katalogu/statusu
• docsLabel: nadpisuje tekst linku do dokumentacji
• preferOver: identyfikatory pluginów/kanałów o niższym priorytecie, które ten wpis katalogu powinien wyprzedzać
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: kontrolki tekstu dla powierzchni wyboru
• markdownCapable: oznacza kanał jako obsługujący Markdown dla decyzji o formatowaniu outbound
• exposure.configured: ukrywa kanał z powierzchni listowania skonfigurowanych kanałów, gdy ustawiono false
• exposure.setup: ukrywa kanał z interaktywnych selektorów konfiguracji/ustawiania, gdy ustawiono false
• exposure.docs: oznacza kanał jako wewnętrzny/prywatny dla powierzchni nawigacji dokumentacji
• showConfigured / showInSetup: starsze aliasy nadal akceptowane dla kompatybilności; preferuj exposure
• quickstartAllowFrom: włącza kanał do standardowego przepływu allowFrom szybkiego startu
• forceAccountBinding: wymaga jawnego powiązania konta nawet wtedy, gdy istnieje tylko jedno konto
• preferSessionLookupForAnnounceTarget: preferuje wyszukiwanie sesji przy rozstrzyganiu celów ogłoszeń

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

Pluginy silnika kontekstu

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", () => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", () => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Dodawanie nowej możliwości

1. zdefiniuj kontrakt core Zdecyduj, jakim współdzielonym zachowaniem powinien zarządzać core: polityką, fallbackiem, scalaniem konfiguracji, cyklem życia, semantyką skierowaną do kanałów i kształtem helpera runtime.
2. dodaj typowane powierzchnie rejestracji/runtime pluginów Rozszerz OpenClawPluginApi i/lub api.runtime o najmniejszą użyteczną typowaną powierzchnię możliwości.
3. podłącz konsumentów core + kanałów/funkcji Kanały i pluginy funkcjonalne powinny korzystać z nowej możliwości przez core, a nie przez bezpośredni import implementacji dostawcy.
4. zarejestruj implementacje dostawców Pluginy dostawców następnie rejestrują swoje backendy względem tej możliwości.
5. dodaj pokrycie kontraktowe Dodaj testy, aby własność i kształt rejestracji pozostawały jawne w czasie.

​

Lista kontrolna możliwości

• typy kontraktów core w src/<capability>/types.ts
• helper runtime/runner core w src/<capability>/runtime.ts
• powierzchnia rejestracji API pluginów w src/plugins/types.ts
• podłączenie rejestru pluginów w src/plugins/registry.ts
• udostępnienie runtime pluginów w src/plugins/runtime/*, gdy pluginy funkcjonalne/kanałowe muszą z niej korzystać
• helpery przechwytywania/testów w src/test-utils/plugin-registration.ts
• asercje własności/kontraktów w src/plugins/contracts/registry.ts
• dokumentacja operatora/pluginów w docs/

​

Szablon możliwości

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• core jest właścicielem kontraktu możliwości + orkiestracji
• pluginy dostawców są właścicielami implementacji dostawców
• pluginy funkcjonalne/kanałowe korzystają z helperów runtime
• testy kontraktowe utrzymują jawną własność