Wewnętrzne mechanizmy architektury Plugin

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Potok ładowania

1. wykrywa kandydujące katalogi główne 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 każdego kandydata
6. ładuje włączone moduły natywne: zbudowane moduły bundled używają natywnego loadera; lokalny źródłowy TypeScript firm trzecich używa awaryjnego fallbacku Jiti
7. wywołuje natywne hooki register(api) i zbiera rejestracje w rejestrze pluginów
8. udostępnia rejestr poleceniom/powierzchniom runtime

​

Zachowanie manifest-first

• identyfikowania pluginu
• wykrywania zadeklarowanych kanałów/Skills/schematu konfiguracji lub możliwości pakietu
• walidacji 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 pluginu

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

​

Granica cache pluginów

• PluginLoaderCacheState i zgodne aktywne rejestry runtime
• cache Jiti/modułów i cache loaderów publicznych powierzchni używane do unikania wielokrotnego importowania tej samej powierzchni runtime
• cache systemu plików dla zainstalowanych artefaktów pluginów
• krótkotrwałe mapy na wywołanie do normalizacji ścieżek lub rozwiązywania duplikatów

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

​

Model rejestru

• rekordy pluginów (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ów

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

​

Callbacki wią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: rozwiązane wiązanie dla zatwierdzonych żądań
• request: podsumowanie pierwotnego żądania, wskazówka odłączenia, identyfikator nadawcy i metadane konwersacji

​

Hooki runtime providerów

• Metadane manifestu do taniego wyszukiwania przed runtime: setup.providers[].envVars, przestarzałe zgodnościowe providerAuthEnvVars, providerAuthAliases, providerAuthChoices i channelEnvVars.
• Hooki czasu konfiguracji: catalog (starsze discovery) plus applyConfigDefaults.
• Hooki runtime: ponad 40 opcjonalnych hooków obejmujących auth, rozwiązywanie modeli, owijanie strumienia, poziomy thinking, politykę replay i endpointy usage. Zobacz pełną listę w 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 ś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 normalny ładunek wyjściowy TTS rdzenia dla powierzchni plików/notatek głosowych.
• Używa konfiguracji rdzenia messages.tts i wyboru dostawcy.
• Zwraca bufor audio PCM + częstotliwość próbkowania. Pluginy muszą resamplować/kodować dla dostawców.
• listVoices jest opcjonalne dla każdego dostawcy. Używaj go dla należących do dostawcy selektorów głosów lub przepływów konfiguracji.
• Listy głosów mogą zawierać bogatsze metadane, takie jak lokalizacja, 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 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 posiadać dostawców tekstu, mowy, obrazu i przyszłych 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 okablowanie kanałów w rdzeniu.
• 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:
  • rdzeń posiada kontrakt możliwości i pomocnik środowiska uruchomieniowego
  • Pluginy dostawców rejestrują api.registerVideoGenerationProvider(...)
  • Pluginy funkcji/kanałów używają 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 obrazu/audio/wideo.
• extractStructuredWithModel(...) jest połączeniem dla Pluginów do ograniczonej ekstrakcji należącej do dostawcy, najpierw z obrazu. Dołącz co najmniej jedno wejście obrazu; wejścia tekstowe są uzupełniającym kontekstem. Pluginy produktowe posiadają swoje trasy i schematy, podczas gdy OpenClaw posiada granicę dostawcy/środowiska uruchomieniowego.
• Używa konfiguracji audio rozumienia mediów rdzenia (tools.media.audio) i kolejności fallbacku dostawców.
• Zwraca { text: undefined }, gdy nie zostanie utworzony wynik 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 na przebieg, a nie trwałymi zmianami sesji.
• OpenClaw honoruje te pola nadpisań tylko dla zaufanych wywołujących.
• Dla przebiegów fallback należących do Pluginu operatorzy muszą włączyć 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 subagentów Pluginów nadal działają, ale żądania nadpisań są odrzucane zamiast cicho wracać do wartości fallback.
• Sesje subagentów tworzone przez Plugin są tagowane identyfikatorem Pluginu tworzącego. Fallback api.runtime.subagent.deleteSession(...) może usuwać tylko te posiadane sesje; dowolne usuwanie sesji nadal wymaga żądania Gateway z zakresem administratora.

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 transportów wyszukiwania specyficznych dla dostawcy.
• api.runtime.webSearch.* jest preferowaną współdzieloną powierzchnią dla Pluginów funkcji/kanałów, które potrzebują zachowania wyszukiwania bez zależności od opakowania 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(...): wygeneruj obraz przy użyciu skonfigurowanego łańcucha dostawców generowania obrazów.
• listProviders(...): wyświetl 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ć normalnego uwierzytelniania Gateway, albo "plugin" dla uwierzytelniania/weryfikacji Webhook zarządzanej 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(...) usunięto 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 przejścia awaryjnego exact/prefix utrzymuj wyłącznie na tym samym poziomie uwierzytelniania.
• Trasy auth: "plugin" nie otrzymują automatycznie zakresów środowiska uruchomieniowego operatora. Służą do zarządzanych przez pluginy webhooków/weryfikacji podpisu, a nie do uprzywilejowanych wywołań pomocniczych Gateway.
• Trasy auth: "gateway" działają wewnątrz zakresu środowiska uruchomieniowego żądania Gateway, ale ten zakres jest celowo zachowawczy:
  • uwierzytelnianie bearer współdzielonym sekretem (gateway.auth.mode = "token" / "password") utrzymuje zakresy środowiska uruchomieniowego tras pluginów przypięte do operator.write, nawet jeśli wywołujący wysyła x-openclaw-scopes
  • zaufane tryby HTTP przenoszące tożsamość (na przykład trusted-proxy lub 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 przenoszących tożsamość, zakres środowiska uruchomieniowego wraca do operator.write
• Praktyczna zasada: nie zakładaj, że trasa pluginu uwierzytelniana przez gateway jest niejawną powierzchnią administracyjną. Jeśli Twoja trasa wymaga zachowania dostępnego tylko dla administratora, wymagaj trybu uwierzytelniania przenoszącego tożsamość i udokumentuj jawny kontrakt nagłówka x-openclaw-scopes.

​

Ścieżki importu Plugin SDK

• index.js — wejście dołączonego pluginu
• api.js — barrel pomocników/typów
• runtime-api.js — barrel tylko dla środowiska uruchomieniowego
• setup-entry.js — wejście pluginu konfiguracji

​

Schematy narzędzia 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 lub channel przed wyszukiwaniem w katalogu.
• messaging.targetResolver.looksLikeId(raw, normalized) informuje rdzeń, czy dane wejściowe powinny przejść bezpośrednio do rozwiązywania podobnego do identyfikatora zamiast wyszukiwania w katalogu.
• messaging.targetResolver.resolveTarget(...) jest przejściem awaryjnym pluginu, gdy rdzeń potrzebuje końcowego, należącego do dostawcy rozwiązania po normalizacji lub po braku trafienia w katalogu.
• messaging.resolveOutboundSessionRoute(...) odpowiada za konstrukcję trasy sesji specyficznej dla dostawcy, gdy cel zostanie rozwiązany.

• Używaj inferTargetChatType do decyzji o kategorii, które powinny nastąpić przed wyszukiwaniem peers/grup.
• Używaj looksLikeId do sprawdzeń typu „traktuj to jako jawny/natywny identyfikator celu”.
• Używaj resolveTarget do specyficznego dla dostawcy awaryjnego normalizowania, a nie do szerokiego wyszukiwania w katalogu.
• Utrzymuj natywne dla dostawcy identyfikatory, takie jak identyfikatory czatów, identyfikatory wątków, JID, uchwyty i identyfikatory pokojów, wewnątrz wartości target lub parametrów specyficznych dla dostawcy, a nie w ogólnych polach SDK.

​

Katalogi oparte na konfiguracji

• peers DM sterowani listą dozwolonych
• skonfigurowane mapy kanałów/grup
• statyczne awaryjne katalogi 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, którzy pojawiają się, gdy istnieją profile uwierzytelniania
• 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, ale emituje ostrzeżenie o wycofaniu
• jeśli zarejestrowano zarówno catalog, jak i discovery, OpenClaw używa catalog
• augmentModelCatalog jest przestarzałe; dołączeni dostawcy powinni publikować dodatkowe wiersze przez registerModelCatalogProvider

​

Inspekcja kanału tylko do odczytu

• resolveAccount(...) jest ścieżką środowiska uruchomieniowego. Może zakładać, że poświadczenia są w pełni zmaterializowane, i może szybko zgłaszać błąd, gdy wymagane sekrety są niedostępne.
• Ścieżki poleceń tylko do odczytu, takie jak openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve oraz przepływy doctor/naprawy konfiguracji nie powinny wymagać materializowania poświadczeń środowiska uruchomieniowego tylko po to, aby 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 mu pola źródła) wystarcza dla poleceń w stylu statusu.
• Używaj configured_unavailable, gdy poświadczenie jest skonfigurowane przez SecretRef, ale niedostępne w bieżącej ścieżce polecenia.

​

Pakiety pluginów

{
  "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, 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 dodatkowa dla bogatszych powierzchni katalogu/statusu
• docsLabel: zastępuje tekst linku do dokumentacji
• preferOver: identyfikatory Plugin/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ł na powierzchniach list skonfigurowanych kanałów, gdy ustawiono na false
• exposure.setup: ukrywa kanał w interaktywnych selektorach konfiguracji/ustawiania, gdy ustawiono na false
• exposure.docs: oznacza kanał jako wewnętrzny/prywatny dla powierzchni nawigacji dokumentacji
• showConfigured / showInSetup: starsze aliasy nadal akceptowane ze względu na zgodność; 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 podczas rozwiązywania 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ólne zachowanie powinien posiadać core: politykę, fallback, scalanie konfiguracji, cykl życia, semantykę widoczną dla kanałów oraz kształt pomocnika środowiska wykonawczego.
2. dodaj typowane powierzchnie rejestracji/środowiska wykonawczego Plugin Rozszerz OpenClawPluginApi i/lub api.runtime o najmniejszą użyteczną typowaną powierzchnię funkcjonalności.
3. połącz core + konsumentów kanałów/funkcji Kanały i Pluginy funkcji powinny używać nowej funkcjonalnoś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 funkcjonalności.
5. dodaj pokrycie kontraktu Dodaj testy, aby własność i kształt rejestracji pozostawały jawne z czasem.

​

Lista kontrolna funkcjonalności

• typy kontraktu core w src/<capability>/types.ts
• runner/pomocnik środowiska wykonawczego core w src/<capability>/runtime.ts
• powierzchnia rejestracji API Plugin w src/plugins/types.ts
• okablowanie rejestru Plugin w src/plugins/registry.ts
• ekspozycja środowiska wykonawczego Plugin w src/plugins/runtime/*, gdy Pluginy funkcji/kanałów muszą ją konsumować
• pomocniki przechwytywania/testów w src/test-utils/plugin-registration.ts
• asercje własności/kontraktu w src/plugins/contracts/registry.ts
• dokumentacja operatora/Plugin 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 posiada kontrakt funkcjonalności + orkiestrację
• Pluginy dostawców posiadają implementacje dostawców
• Pluginy funkcji/kanałów konsumują pomocniki środowiska wykonawczego
• testy kontraktu utrzymują własność jako jawną

​

Powiązane

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