Wewnętrzne mechanizmy architektury Plugin

​

Potok ładowania

1. wykrywa katalogi główne kandydatów Plugin
2. odczytuje natywne lub zgodne manifesty pakietów oraz metadane pakietów
3. odrzuca niebezpiecznych kandydatów
4. normalizuje konfigurację Plugin (plugins.enabled, allow, deny, entries, slots, load.paths)
5. decyduje o włączeniu każdego kandydata
6. ładuje włączone moduły natywne: zbudowane moduły pakietowane używają natywnego loadera; lokalne źródła TypeScript firm trzecich używają awaryjnego fallbacku Jiti
7. wywołuje natywne hooki register(api) i zbiera rejestracje w rejestrze Plugin
8. udostępnia rejestr poleceniom i powierzchniom runtime

​

Zachowanie oparte najpierw na manifeście

• identyfikowania Plugin
• wykrywania zadeklarowanych kanałów/Skills/schematu konfiguracji lub możliwości pakietu
• walidowania plugins.entries.<id>.config
• uzupełniania etykiet/placeholderów Control UI
• pokazywania metadanych instalacji/katalogu
• zachowywania tanich deskryptorów aktywacji i konfiguracji bez ładowania runtime Plugin

• ładowanie CLI zawęża zakres do Plugin, które są właścicielami żądanego polecenia głównego
• konfiguracja kanału/rozwiązywanie Plugin zawęża zakres do Plugin, które są właścicielami żądanego identyfikatora kanału
• jawna konfiguracja providera/rozwiązywanie runtime zawęża zakres do Plugin, które są właścicielami żądanego identyfikatora providera
• planowanie uruchamiania Gateway używa activation.onStartup dla jawnych importów startowych i rezygnacji ze startu; Plugin bez metadanych startowych ładują się tylko przez węższe wyzwalacze aktywacji

​

Granica cache Plugin

• PluginLoaderCacheState i zgodne aktywne rejestry runtime
• cache jiti/modułów oraz cache loadera powierzchni publicznych używane, aby unikać wielokrotnego importowania tej samej powierzchni runtime
• cache systemu plików dla zainstalowanych artefaktów Plugin
• krótkotrwałe mapy per wywołanie do normalizacji ścieżek lub rozwiązywania duplikatów

• wyników wykrywania
• bezpośrednich rejestrów manifestów
• rejestrów manifestów rekonstruowanych z indeksu zainstalowanych Plugin
• wyszukiwania właściciela providera, tłumienia modeli, polityki providera lub metadanych publicznych artefaktów
• jakiejkolwiek innej odpowiedzi wyprowadzonej z manifestu, gdzie zmieniony manifest, zainstalowany indeks lub ścieżka ładowania powinny być widoczne przy następnym odczycie metadanych

​

Model rejestru

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

• moduł Plugin -> rejestracja w rejestrze
• runtime rdzenia -> użycie rejestru

​

Callbacki powiązania rozmowy

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: rozwiązane powiązanie dla zatwierdzonych żądań
• request: oryginalne podsumowanie żądania, podpowiedź odłączenia, identyfikator nadawcy i metadane rozmowy

​

Hooki runtime providera

• Metadane manifestu do taniego wyszukiwania przed runtime: setup.providers[].envVars, przestarzała zgodność providerAuthEnvVars, providerAuthAliases, providerAuthChoices i channelEnvVars.
• Hooki czasu konfiguracji: catalog (starsze discovery) oraz applyConfigDefaults.
• Hooki runtime: ponad 40 opcjonalnych hooków obejmujących auth, rozwiązywanie modeli, opakowywanie strumieni, poziomy myślenia, politykę replay oraz endpointy użycia. Zobacz pełną listę w sekcji Kolejność i użycie hooków.

​

Kolejność i użycie hooków

​

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 normalny ładunek wyjściowy TTS rdzenia dla powierzchni plików/notatek głosowych.
• Używa konfiguracji messages.tts rdzenia i wyboru dostawcy.
• Zwraca bufor audio PCM + częstotliwość próbkowania. Pluginy muszą ponownie próbkować/kodować dla dostawców.
• listVoices jest opcjonalne dla każdego dostawcy. Używaj go dla należących do vendora selektorów głosów albo przepływów konfiguracji.
• 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 rdzeniu.
• Używaj dostawców mowy dla zachowania syntezy należącego do vendora.
• Starsze wejście Microsoft edge jest normalizowane do identyfikatora dostawcy microsoft.
• Preferowany model własności jest zorientowany na firmę: jeden Plugin vendora może posiadać dostawców tekstu, mowy, obrazu i przyszłych mediów, gdy OpenClaw doda te kontrakty funkcjonalnoś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 okablowanie kanałów w rdzeniu.
• Zachowaj zachowanie vendora w Pluginie dostawcy.
• Rozszerzanie addytywne powinno pozostać typowane: nowe opcjonalne metody, nowe opcjonalne pola wyników, nowe opcjonalne funkcjonalności.
• Generowanie wideo już stosuje ten sam wzorzec:
  • rdzeń posiada kontrakt funkcjonalności i pomocnik runtime
  • Pluginy vendoró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 extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.5",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Use the printed fields as the source of truth." },
  ],
  instructions: "Return entities and searchable tags.",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  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.* jest preferowaną współdzieloną powierzchnią dla rozumienia obrazów/audio/wideo.
• extractStructuredWithModel(...) jest punktem styku dla Pluginów do ograniczonej ekstrakcji należącej do dostawcy i zaczynającej od obrazu. Dołącz co najmniej jedno wejście obrazu; wejścia tekstowe są kontekstem uzupełniającym. Pluginy produktowe posiadają swoje trasy i schematy, podczas gdy OpenClaw posiada granicę dostawcy/runtime.
• Używa konfiguracji audio rozumienia mediów rdzenia (tools.media.audio) i kolejności fallbacku dostawców.
• Zwraca { text: undefined }, gdy nie powstanie żadne wyjście transkrypcji (na przykład pominięte/nieobsługiwane wejście).
• 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 dla pojedynczego przebiegu, a nie trwałymi zmianami sesji.
• OpenClaw honoruje te pola nadpisania tylko dla zaufanych wywołujących.
• Dla należących do Pluginu przebiegów fallbacku 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.
• Niezaufane przebiegi podagentów Pluginów nadal działają, ale żądania nadpisania są odrzucane zamiast cicho wracać do fallbacku.
• Sesje podagentów utworzone przez Plugin są tagowane identyfikatorem tworzącego Pluginu. Fallback api.runtime.subagent.deleteSession(...) może usuwać tylko te posiadane sesje; dowolne usuwanie sesji nadal wymaga żądania Gateway o zakresie administracyjnym.

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, rozwiązywanie poświadczeń i współdzieloną semantykę żądań w rdzeniu.
• Używaj dostawców wyszukiwania w sieci dla specyficznych dla vendora transportów wyszukiwania.
• api.runtime.webSearch.* jest preferowaną współdzieloną powierzchnią dla Pluginów funkcji/kanałów, które potrzebują zachowania wyszukiwania bez zależności od wrappera narzędzi 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(...): wygeneruj obraz za pomocą skonfigurowanego łańcucha dostawców generowania obrazów.
• listProviders(...): wyświetl dostępnych dostawców generowania obrazów i ich funkcjonalnoś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 uwierzytelniania/weryfikacji Webhook zarządzanych przez plugin.
• match: opcjonalne. "exact" (domyślnie) albo "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.
• Dokładne konflikty 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 przekazywania exact/prefix utrzymuj wyłącznie na tym samym poziomie uwierzytelniania.
• 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ń pomocniczych Gateway.
• Trasy auth: "gateway" działają wewnątrz zakresu runtime żądania Gateway, ale ten zakres jest celowo zachowawczy:
  • uwierzytelnianie bearer ze współdzielonym sekretem (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 niosące tożsamość (na przykład trusted-proxy albo gateway.auth.mode = "none" na prywatnym wejściu) honorują x-openclaw-scopes tylko wtedy, gdy nagłówek jest jawnie obecny
  • jeśli x-openclaw-scopes nie ma w tych żądaniach tras pluginów niosących tożsamość, zakres runtime wraca do operator.write
• Praktyczna zasada: nie zakładaj, że trasa pluginu uwierzytelniana przez gateway jest niejawną powierzchnią administracyjną. Jeśli trasa wymaga zachowania dostępnego tylko dla administratora, wymagaj trybu uwierzytelniania niosącego tożsamość i udokumentuj jawny kontrakt nagłówka x-openclaw-scopes.

​

Ścieżki importu Plugin SDK

• index.js — wejście pluginu wbudowanego
• api.js — beczka pomocników/typów
• runtime-api.js — beczka tylko dla runtime
• setup-entry.js — wejście pluginu konfiguracji

​

Schematy narzędzi wiadomości

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

​

Rozwiązywanie celów kanału

• messaging.inferTargetChatType({ to }) decyduje, czy znormalizowany cel powinien być traktowany jako direct, group albo channel przed wyszukiwaniem w katalogu.
• messaging.targetResolver.looksLikeId(raw, normalized) mówi core, czy wejście powinno od razu przejść do rozwiązywania podobnego do identyfikatora zamiast wyszukiwania w katalogu.
• messaging.targetResolver.reservedLiterals wymienia gołe słowa, które są referencjami kanału/sesji dla tego dostawcy. Rozwiązywanie zachowuje skonfigurowane wpisy katalogu przed odrzuceniem zarezerwowanych literałów, a następnie zamyka się błędem przy braku trafienia w katalogu.
• messaging.targetResolver.resolveTarget(...) jest fallbackiem pluginu, gdy core potrzebuje końcowego, należącego do dostawcy rozstrzygnięcia po normalizacji albo po braku trafienia w katalogu.
• messaging.resolveOutboundSessionRoute(...) odpowiada za budowę trasy sesji specyficznej dla dostawcy po rozwiązaniu celu.

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

​

Katalogi oparte na konfiguracji

• peery DM sterowane listą dozwolonych
• skonfigurowane mapy kanałów/grup
• statyczne fallbacki katalogu ograniczone do konta

• filtrowanie zapytań
• stosowanie limitu
• pomocniki deduplikacji/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 uwierzytelniania
• 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, ale emituje ostrzeżenie o wycofaniu
• jeśli zarejestrowane są zarówno catalog, jak i discovery, OpenClaw używa catalog
• augmentModelCatalog jest przestarzałe; wbudowani dostawcy powinni publikować wiersze uzupełniające przez registerModelCatalogProvider

​

Inspekcja kanału tylko do odczytu

• resolveAccount(...) jest ścieżką runtime. Może zakładać, że poświadczenia są w pełni zmaterializowane, i 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 naprawy doctor/config nie powinny musieć materializować poświadczeń runtime tylko po to, by opisać konfigurację.

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

​

Pakiety pakietów

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

• sama rejestracja kanału
• wszystkie trasy HTTP, które muszą być dostępne, zanim Gateway zacznie nasłuchiwać
• wszystkie metody, narzędzia lub usługi Gateway, 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 pomocnicza dla bogatszych powierzchni katalogu/statusu
• docsLabel: zastępuje 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 powierzchni wyboru
• markdownCapable: oznacza kanał jako obsługujący markdown dla decyzji o formatowaniu wychodzącym
• exposure.configured: ukrywa kanał z powierzchni list skonfigurowanych kanałów, gdy ustawione na false
• exposure.setup: ukrywa kanał z interaktywnych selektorów konfiguracji, 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 szybkiego startu allowFrom
• forceAccountBinding: wymaga jawnego powiązania konta, nawet gdy istnieje tylko jedno konto
• preferSessionLookupForAnnounceTarget: preferuje wyszukiwanie sesji przy rozwiązywaniu 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", (ctx) => ({
    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", (ctx) => ({
    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 funkcjonalności

1. zdefiniuj kontrakt core Zdecyduj, jakie współdzielone zachowanie powinien posiadać core: politykę, fallback, scalanie konfiguracji, cykl życia, semantykę skierowaną do kanałów i kształt pomocników środowiska uruchomieniowego.
2. dodaj typowane powierzchnie rejestracji/środowiska uruchomieniowego pluginu Rozszerz OpenClawPluginApi i/lub api.runtime o najmniejszą użyteczną typowaną powierzchnię funkcjonalności.
3. podłącz core oraz konsumentów kanału/funkcji Kanały i pluginy funkcji powinny konsumować nową funkcjonalność przez core, a nie przez bezpośredni import implementacji dostawcy.
4. zarejestruj implementacje dostawców Pluginy dostawców rejestrują następnie swoje backendy względem funkcjonalności.
5. dodaj pokrycie kontraktu Dodaj testy, aby własność i kształt rejestracji pozostały jawne w czasie.

​

Lista kontrolna funkcjonalności

• typy kontraktu core w src/<capability>/types.ts
• pomocnik runnera/środowiska uruchomieniowego core w src/<capability>/runtime.ts
• powierzchnię rejestracji API pluginu w src/plugins/types.ts
• podłączenie rejestru pluginów w src/plugins/registry.ts
• ekspozycję środowiska uruchomieniowego pluginu w src/plugins/runtime/*, gdy pluginy funkcji/kanałów muszą ją konsumować
• pomocniki przechwytywania/testowe w src/test-utils/plugin-registration.ts
• asercje własności/kontraktu w src/plugins/contracts/registry.ts
• dokumentację operatora/pluginu w docs/

​

Szablon funkcjonalnoś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 capability i orkiestracji
• pluginy dostawców są właścicielami implementacji dostawców
• pluginy funkcji/kanałów używają helperów runtime
• testy kontraktu utrzymują jawne ownership

​

Powiązane

• Architektura Plugin — publiczny model capability i kształty
• Podścieżki Plugin SDK
• Konfiguracja Plugin SDK
• Tworzenie pluginów