Wewnętrzne mechanizmy architektury Pluginów

​

Potok ładowania

1. wykrywa kandydackie katalogi główne Pluginów
2. odczytuje natywne lub zgodne manifesty paczek 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 każdego kandydata
6. ładuje włączone moduły natywne: zbudowane dołączone moduły używają natywnego loadera; niezbudowane natywne Pluginy używają jiti
7. wywołuje natywne haki register(api) 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 paczki
• walidacji plugins.entries.<id>.config
• wzbogacania etykiet/placeholderów w Control UI
• pokazywania metadanych instalacji/katalogu
• zachowywania tanich deskryptorów aktywacji i konfiguracji bez ładowania runtime Pluginu

• ładowanie CLI zawęża się do Pluginów będących właścicielami żądanego polecenia głównego
• konfiguracja kanału/rozwiązywanie Pluginu zawęża się do Pluginów będących właścicielami żądanego identyfikatora kanału
• jawne rozwiązywanie konfiguracji/runtime dostawcy zawęża się do Pluginów będących właścicielami żądanego identyfikatora dostawcy

​

Co loader buforuje

• 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 bufory.
• Dostrajaj okna buforowania przez 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
• starsze haki i haki typowane
• kanały
• dostawców
• handlery Gateway RPC
• trasy HTTP
• rejestratory CLI
• usługi w tle
• polecenia należące do Pluginów

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

​

Callbacki powiązań 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: oryginalne podsumowanie żądania, wskazówka odłączenia, identyfikator nadawcy oraz metadane konwersacji

​

Haki runtime dostawców

• Metadane manifestu do taniego wyszukiwania przed runtime: providerAuthEnvVars, providerAuthAliases, providerAuthChoices oraz channelEnvVars.
• Haki czasu konfiguracji: catalog (starsze discovery) oraz applyConfigDefaults.
• Haki runtime: ponad 40 opcjonalnych haków obejmujących auth, rozwiązywanie modeli, opakowywanie strumieni, poziomy thinking, politykę replay i endpointy użycia. Zobacz pełną listę w sekcji Kolejność haków i użycie.

​

Kolejność haków i użycie

​

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

​

Pomocniki runtime

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 payload wyjściowy core TTS dla powierzchni plików/notatek głosowych.
• Używa konfiguracji core messages.tts i wyboru dostawcy.
• Zwraca bufor audio PCM + częstotliwość próbkowania. Pluginy muszą przeprowadzić resampling/kodowanie dla dostawców.
• listVoices jest opcjonalne per dostawca. Używaj go do 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,
    };
  },
});

• Politykę TTS, fallback i dostarczanie odpowiedzi utrzymuj 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 ukierunkowany na firmę: jeden Plugin dostawcy może zarządzać tekstem, mową, obrazem i przyszłymi dostawcami mediów, gdy OpenClaw doda 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: "..." }),
});

• Orkiestrację, fallback, konfigurację i okablowanie kanałów utrzymuj w core.
• Zachowanie dostawcy utrzymuj w Pluginie dostawcy.
• Rozszerzanie addytywne powinno pozostać typowane: nowe opcjonalne metody, nowe opcjonalne pola wyników, nowe opcjonalne możliwości.
• Generowanie wideo podąża już za tym samym wzorcem:
  • core zarządza kontraktem możliwości i pomocnikiem runtime
  • Pluginy dostawców rejestrują api.registerVideoGenerationProvider(...)
  • Pluginy funkcji/kanałów korzystają z 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 obrazu/audio/wideo.
• Używa konfiguracji audio rozumienia mediów core (tools.media.audio) i kolejności fallbacku dostawców.
• Zwraca { text: undefined }, gdy nie powstaje wyjście transkrypcji (na przykład przy pominiętym/nieobsługiwanym wejściu).
• 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 są opcjonalnymi nadpisaniami per uruchomienie, a nie trwałymi zmianami sesji.
• OpenClaw respektuje te pola nadpisania tylko dla zaufanych wywołujących.
• Dla uruchomień 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 konkretnych kanonicznych celów provider/model, albo "*", aby jawnie zezwolić na dowolny cel.
• Uruchomienia podagentów niezaufanych Pluginów nadal działają, ale żądania nadpisania są odrzucane zamiast po cichu przechodzić do fallbacku.

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,
  },
});

• Wybór dostawcy, rozwiązywanie poświadczeń i współdzieloną semantykę żądań utrzymuj w core.
• Używaj dostawców wyszukiwania w sieci dla transportów wyszukiwania specyficznych dla producenta.
• api.runtime.webSearch.* to preferowana współdzielona powierzchnia dla Pluginów funkcji/kanałów, 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 uwierzytelniania gateway, albo "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. Używaj zamiast tego api.registerHttpRoute(...).
• Trasy Pluginów muszą jawnie deklarować auth.
• Konflikty dokładnego path + match są odrzucane, chyba że ustawiono replaceExisting: true, i jeden Plugin nie może zastąpić trasy innego Pluginu.
• Nakładające się trasy z różnymi poziomami auth są odrzucane. Utrzymuj łańcuchy przejścia exact/prefix tylko na tym samym poziomie auth.
• Trasy auth: "plugin" nie otrzymują automatycznie zakresów runtime operatora. Są przeznaczone do Webhooków zarządzanych przez Plugin/weryfikacji podpisów, a nie uprzywilejowanych wywołań pomocniczych Gateway.
• Trasy auth: "gateway" działają wewnątrz zakresu runtime żądania Gateway, ale ten zakres jest celowo zachowawczy:
  • auth bearer wspólnego sekretu (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
  • tryby HTTP oparte na zaufanej tożsamości (na przykład trusted-proxy lub gateway.auth.mode = "none" na prywatnym ingressie) respektują x-openclaw-scopes tylko wtedy, gdy nagłówek jest jawnie obecny
  • jeśli x-openclaw-scopes jest nieobecny w takich żądaniach trasy Pluginu opartych na tożsamości, zakres runtime wraca do operator.write
• Praktyczna zasada: nie zakładaj, że trasa Pluginu z auth gateway jest niejawną powierzchnią administracyjną. Jeśli Twoja trasa potrzebuje zachowania tylko-admin, wymagaj trybu auth opartego na tożsamości i udokumentuj jawny kontrakt nagłówka x-openclaw-scopes.

​

Ścieżki importu Plugin SDK

• index.js — punkt wejścia dołączonego Pluginu
• api.js — barrel pomocników/typów
• runtime-api.js — barrel tylko runtime
• setup-entry.js — punkt wejścia Pluginu konfiguracji

​

Schematy narzędzi wiadomości

• presentation dla semantycznych bloków prezentacji (text, context, divider, buttons, select)
• delivery-pin dla żądań dostarczania przypiętego

​

Rozwiązywanie celów kanałów

• messaging.inferTargetChatType({ to }) decyduje, czy znormalizowany cel powinien być traktowany jako direct, group lub channel przed wyszukaniem w katalogu.
• messaging.targetResolver.looksLikeId(raw, normalized) mówi core, czy wejście powinno pominąć wyszukiwanie w katalogu i przejść bezpośrednio do rozwiązywania podobnego do identyfikatora.
• messaging.targetResolver.resolveTarget(...) to fallback Pluginu, gdy core potrzebuje końcowego rozwiązywania należącego do dostawcy po normalizacji lub po nieudanym wyszukaniu w katalogu.
• messaging.resolveOutboundSessionRoute(...) zarządza konstrukcją trasy sesji specyficznej dla dostawcy po rozwiązaniu celu.

• Używaj inferTargetChatType do decyzji kategorii, które powinny zapaść przed przeszukiwaniem peers/groups.
• Używaj looksLikeId do sprawdzeń typu „traktuj to jako jawny/natywny identyfikator celu”.
• Używaj resolveTarget do fallbacku normalizacji specyficznej dla dostawcy, a nie do szerokiego wyszukiwania w katalogu.
• Trzymaj natywne dla dostawcy identyfikatory, takie jak chat ids, thread ids, JIDs, handle i room ids, wewnątrz wartości target lub parametrów specyficznych dla dostawcy, a nie w ogólnych polach SDK.

​

Katalogi oparte na konfiguracji

• peers wiadomości prywatnych oparte na liście dozwolonych
• skonfigurowane mapy kanałów/grup
• statyczne fallbacki katalogu ograniczone do konta

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

​

Katalogi dostawców

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

• simple: zwykli dostawcy sterowani kluczem API lub env
• profile: dostawcy pojawiający się, gdy istnieją profile auth
• paired: dostawcy, którzy syntetyzują wiele powiązanych wpisów dostawców
• late: ostatnie przejście, po innych niejawnych dostawcach

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

​

Tylko do odczytu: inspekcja kanałów

• resolveAccount(...) to ścieżka runtime. Może zakładać, że poświadczenia są w pełni zmaterializowane i może szybko koń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 napraw doctor/config nie powinny wymagać materializacji poświadczeń runtime tylko po to, aby opisać konfigurację.

• Zwracaj tylko opisowy stan konta.
• Zachowuj enabled i configured.
• Uwzględniaj pola źródła/statusu poświadczeń, gdy to istotne, 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. Wystarczy zwrócić tokenStatus: "available" (oraz pasujące pole źródła).
• Używaj configured_unavailable, gdy poświadczenie jest skonfigurowane przez SecretRef, ale niedostępne w bieżącej ścieżce polecenia.

​

Paczki pakietów

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

• samą rejestrację kanału
• wszelkie trasy HTTP, które muszą być dostępne przed rozpoczęciem nasłuchiwania przez gateway
• wszelkie metody gateway, narzędzia lub usługi, które muszą istnieć w tym samym oknie

• 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 pomocnicza dla bogatszych powierzchni katalogu/statusu
• docsLabel: nadpisanie tekstu 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 powierzchni wyboru
• markdownCapable: oznacza kanał jako zdolny do obsługi Markdown dla decyzji o formatowaniu wychodzącym
• exposure.configured: ukrywa kanał na powierzchniach list skonfigurowanych kanałów, gdy ustawione na false
• exposure.setup: ukrywa kanał w interaktywnych selektorach setup/configure, gdy ustawione na false
• exposure.docs: oznacza kanał jako wewnętrzny/prywatny dla powierzchni nawigacji dokumentacji
• showConfigured / showInSetup: starsze aliasy nadal akceptowane dla zgodności; preferuj exposure
• quickstartAllowFrom: włącza kanał do standardowego przepływu quickstart allowFrom
• forceAccountBinding: wymusza jawne powiązanie konta nawet wtedy, gdy istnieje tylko jedno konto
• preferSessionLookupForAnnounceTarget: preferuje wyszukiwanie sesji przy rozwiązywaniu celów announce

• ~/.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: polityka, fallback, scalenie konfiguracji, cykl życia, semantyka skierowana do kanału i kształt pomocnika runtime.
2. dodaj typowane powierzchnie rejestracji/runtime Pluginu Rozszerz OpenClawPluginApi i/lub api.runtime o najmniejszą użyteczną typowaną powierzchnię możliwości.
3. podłącz konsumentów core + kanał/funkcja Kanały i Pluginy funkcji powinny korzystać z nowej możliwości przez core, a nie przez bezpośredni import implementacji producenta.
4. zarejestruj implementacje producentów Pluginy producentów rejestrują następnie swoje backendy względem tej możliwości.
5. dodaj pokrycie kontraktu Dodaj testy, aby własność i kształt rejestracji pozostały jawne w czasie.

​

Lista kontrolna możliwości

• typy kontraktu core w src/<capability>/types.ts
• runner/pomocnik runtime core w src/<capability>/runtime.ts
• powierzchnia rejestracji API Pluginu w src/plugins/types.ts
• okablowanie rejestru Pluginów w src/plugins/registry.ts
• ekspozycja runtime Pluginu w src/plugins/runtime/*, gdy Pluginy funkcji/kanałów muszą ją konsumować
• helpery capture/test w src/test-utils/plugin-registration.ts
• asercje własności/kontraktu 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 zarządza kontraktem możliwości + orkiestracją
• Pluginy producentów zarządzają implementacjami producenta
• Pluginy funkcji/kanałów konsumują pomocniki runtime
• testy kontraktowe utrzymują własność jako jawną

​

Powiązane

• Plugin architecture — publiczny model możliwości i kształty
• Plugin SDK subpaths
• Plugin SDK setup
• Building plugins