Wewnętrzna architektura Pluginów

​

Potok ładowania

1. wykrywa potencjalne 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. określa, czy każdy kandydat ma być włączony
6. ładuje włączone moduły natywne: skompilowane moduły dołączone korzystają z natywnego modułu ładującego; lokalny kod źródłowy TypeScript pluginów zewnętrznych korzysta z awaryjnego mechanizmu Jiti
7. wywołuje natywne hooki register(api) i gromadzi rejestracje w rejestrze pluginów
8. udostępnia rejestr poleceniom i powierzchniom środowiska wykonawczego

• jego rozwiązany punkt wejścia znajduje się poza katalogiem głównym pluginu
• jego ścieżka (lub katalog główny) jest zapisywalna przez wszystkich
• w przypadku pluginów niedołączonych właściciel ścieżki nie odpowiada bieżącemu identyfikatorowi uid (ani użytkownikowi root)

​

Zachowanie oparte przede wszystkim na manifeście

• identyfikowania pluginu
• wykrywania zadeklarowanych kanałów, Skills, schematu konfiguracji lub możliwości pakietu
• walidowania plugins.entries.<id>.config
• uzupełniania etykiet i tekstów zastępczych interfejsu Control UI
• wyświetlania metadanych instalacji i katalogu
• zachowywania lekkich deskryptorów aktywacji i konfiguracji bez ładowania środowiska wykonawczego pluginu

• ładowanie przez CLI zawęża wybór do pluginów będących właścicielami żądanego polecenia głównego
• konfiguracja kanału i rozpoznawanie pluginu zawężają wybór do pluginów będących właścicielami żądanego identyfikatora kanału
• jawna konfiguracja dostawcy i rozpoznawanie środowiska wykonawczego zawężają wybór do pluginów będących właścicielami żądanego identyfikatora dostawcy
• planowanie uruchamiania Gateway używa activation.onStartup do jawnych importów startowych; pluginy bez metadanych uruchomieniowych są ładowane wyłącznie przez bardziej szczegółowe wyzwalacze aktywacji

​

Granica pamięci podręcznej pluginów

• PluginLoaderCacheState i zgodne aktywne rejestry środowiska wykonawczego
• pamięci podręczne jiti/modułów i pamięci podręczne modułów ładujących powierzchni publicznych, używane w celu uniknięcia wielokrotnego importowania tej samej powierzchni środowiska wykonawczego
• pamięci podręczne systemu plików dla artefaktów zainstalowanych pluginów
• krótkotrwałe mapy dla pojedynczego wywołania, służące do normalizacji ścieżek lub rozstrzygania duplikatów

• wyników wykrywania
• bezpośrednich rejestrów manifestów
• rejestrów manifestów odtwarzanych z indeksu zainstalowanych pluginów
• wyszukiwania właściciela dostawcy, wykluczania modeli, zasad dostawcy lub metadanych artefaktów publicznych
• żadnych innych odpowiedzi wyprowadzonych z manifestu, w przypadku których zmieniony manifest, indeks instalacji lub ścieżka ładowania powinny być widoczne przy następnym odczycie metadanych

​

Model rejestru

• moduł pluginu -> rejestracja w rejestrze
• środowisko wykonawcze rdzenia -> korzystanie z rejestru

​

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

​

Hooki środowiska wykonawczego dostawcy

• Metadane manifestu do szybkiego wyszukiwania przed uruchomieniem środowiska wykonawczego: setup.providers[].envVars, przestarzałe pole zgodności providerAuthEnvVars, providerAuthAliases, providerAuthChoices i channelEnvVars.
• Hooki etapu konfiguracji: catalog (starsze discovery) oraz applyConfigDefaults.
• Hooki środowiska wykonawczego: ponad 40 opcjonalnych hooków obejmujących uwierzytelnianie, rozpoznawanie modeli, opakowywanie strumieni, poziomy rozumowania, zasady ponownego odtwarzania i punkty końcowe użycia. Zobacz 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

​

Helpery środowiska wykonawczego

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 standardowy wynik TTS rdzenia dla powierzchni plików i wiadomości głosowych.
• Używa konfiguracji messages.tts rdzenia i wyboru dostawcy.
• Zwraca bufor dźwięku PCM i częstotliwość próbkowania. Pluginy muszą ponownie próbkować i kodować dane dla dostawców.
• listVoices jest opcjonalne dla każdego dostawcy. Używaj go w selektorach głosu lub procesach konfiguracji należących do dostawcy.
• Rdzeń przekazuje rozpoznany termin żądania do hooków listVoices dostawcy; ustawienia limitu czasu specyficzne dla dostawcy mogą go zastąpić.
• Listy głosów mogą zawierać bogatsze metadane, takie jak ustawienia regionalne, płeć i znaczniki osobowości, przeznaczone dla selektorów uwzględniających dostawcę.
• OpenAI i ElevenLabs obsługują obecnie telefonię. Microsoft jej nie obsługuje.

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

• Zasady TTS, mechanizmy rezerwowe i dostarczanie odpowiedzi pozostaw w rdzeniu.
• Używaj dostawców syntezy mowy do zachowań syntezy należących do dostawcy.
• Starsza wartość wejściowa Microsoft edge jest normalizowana do identyfikatora dostawcy microsoft.
• Preferowany model własności jest zorientowany na firmę: jeden plugin dostawcy może odpowiadać za dostawców tekstu, mowy, obrazów i przyszłych multimediów, gdy OpenClaw doda odpowiednie 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ę, mechanizmy rezerwowe, konfigurację i połączenia z kanałami pozostaw w rdzeniu.
• Zachowania dostawcy pozostaw w pluginie dostawcy.
• Rozszerzenia addytywne powinny pozostać typowane: nowe opcjonalne metody, nowe opcjonalne pola wyników i nowe opcjonalne możliwości.
• Generowanie filmów już korzysta z tego samego wzorca:
  • rdzeń odpowiada za kontrakt możliwości i helper środowiska wykonawczego
  • 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 extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.6-sol",
  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ą do rozpoznawania obrazów, dźwięku i filmów.
• extractStructuredWithModel(...) jest warstwą przeznaczoną dla pluginów do ograniczonej ekstrakcji należącej do dostawcy, w której obraz jest głównym źródłem. Uwzględnij co najmniej jeden obraz wejściowy; wejścia tekstowe stanowią kontekst uzupełniający. Pluginy produktu odpowiadają za własne trasy i schematy, natomiast OpenClaw odpowiada za granicę między dostawcą a środowiskiem wykonawczym.
• Używa konfiguracji dźwięku mechanizmu rozpoznawania multimediów rdzenia (tools.media.audio) i kolejności dostawców rezerwowych.
• Zwraca { text: undefined }, gdy nie powstanie wynik transkrypcji (na przykład w przypadku pominiętego lub 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 są opcjonalnymi nadpisaniami dla pojedynczego działania, a nie trwałymi zmianami sesji.
• OpenClaw respektuje te pola nadpisania tylko w przypadku zaufanych wywołujących.
• W przypadku należących do pluginu działań rezerwowych operatorzy muszą wyrazić zgodę za pomocą 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, albo "*", aby jawnie zezwolić na dowolny cel.
• Działania subagentów niezaufanych pluginów nadal działają, ale żądania nadpisania są odrzucane zamiast niejawnie korzystać z wartości rezerwowych.
• Sesje subagentów utworzone przez plugin są oznaczane identyfikatorem tworzącego je pluginu. Rezerwowe wywołanie api.runtime.subagent.deleteSession(...) może usuwać tylko te sesje, których właścicielem jest plugin; usuwanie dowolnych 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,
  },
});

• Wybór dostawcy, rozpoznawanie poświadczeń i współdzieloną semantykę żądań pozostaw w rdzeniu.
• Używaj dostawców wyszukiwania w sieci do transportów wyszukiwania specyficznych dla dostawcy.
• api.runtime.webSearch.* jest preferowaną współdzieloną powierzchnią dla pluginów funkcji/kanałów, które wymagają wyszukiwania bez zależności od otoki 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 na serwerze HTTP Gateway.
• auth: wymagane, "gateway" lub "plugin". Użyj "gateway", aby wymagać standardowego uwierzytelniania Gateway, albo "plugin" do uwierzytelniania zarządzanego przez plugin lub weryfikacji Webhooka.
• match: opcjonalne. "exact" (domyślnie) lub "prefix".
• handleUpgrade: opcjonalna procedura obsługi żądań przełączenia na WebSocket w tej samej trasie.
• 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 jego użycie spowoduje błąd ładowania pluginu. Zamiast niego użyj api.registerHttpRoute(...).
• Trasy pluginów muszą jawnie deklarować auth.
• Konflikty identycznych wartości 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 przechodzenia awaryjnego exact/prefix utrzymuj wyłącznie na tym samym poziomie uwierzytelniania.
• Trasy z auth: "plugin" nie otrzymują automatycznie zakresów środowiska uruchomieniowego operatora. Służą do Webhooków zarządzanych przez plugin i weryfikacji podpisów, a nie do uprzywilejowanych wywołań pomocniczych Gateway.
• Trasy z auth: "gateway" działają w zakresie środowiska uruchomieniowego żądania Gateway. Domyślny zakres (gatewayRuntimeScopeSurface: "write-default") jest celowo zachowawczy:
  • uwierzytelnianie tokenem okaziciela ze współdzielonym sekretem (gateway.auth.mode = "token" / "password") oraz każda metoda uwierzytelniania inna niż trusted-proxy otrzymują pojedynczy zakres operator.write, nawet jeśli wywołujący wysyła x-openclaw-scopes
  • wywołujący przez trusted-proxy bez jawnego nagłówka x-openclaw-scopes również zachowują starszy zakres ograniczony do operator.write
  • wywołujący przez trusted-proxy, którzy wysyłają x-openclaw-scopes, otrzymują zamiast tego zadeklarowane zakresy
  • trasa może wybrać gatewayRuntimeScopeSurface: "trusted-operator", aby zawsze respektować x-openclaw-scopes w trybach uwierzytelniania przenoszących tożsamość (a przy braku nagłówka używać pełnego domyślnego zestawu zakresów CLI)
• Praktyczna zasada: nie zakładaj, że trasa pluginu uwierzytelniana przez Gateway jest niejawnie powierzchnią administracyjną. Jeśli trasa wymaga zachowania dostępnego wyłącznie administratorowi, wybierz powierzchnię zakresów trusted-operator, wymagaj trybu uwierzytelniania przenoszącego tożsamość i udokumentuj jawny kontrakt nagłówka x-openclaw-scopes.
• Po dopasowaniu trasy i uwierzytelnieniu zwykłe procedury obsługi podlegają kontroli przyjmowania pracy głównej przez Gateway. Gateway będący w stanie przygotowania lub ponownego uruchamiania zwraca 503 przed wywołaniem procedury obsługi. Wąskim wyjątkiem jest trasa z auth: "gateway", do której manifest nadaje uprawnienie i która wybiera również właściwą dla trasy powierzchnię trusted-operator; pozostaje ona osiągalna, aby wysyłanie poleceń sterujących zawieszeniem nie zostało zablokowane, podczas gdy zwykłe trasy równorzędne tego samego pluginu pozostają za granicą kontroli przyjmowania. Własność handleUpgrade dla WebSocketu korzysta z tej samej atomowej granicy kontroli przyjmowania; gdy procedura obsługi zaakceptuje gniazdo, jego dalszy cykl życia należy do pluginu i nie jest śledzony przez tę granicę.

​

Ścieżki importu SDK pluginów

• index.js — punkt wejścia wbudowanego pluginu
• api.js — moduł zbiorczy funkcji pomocniczych i typów
• runtime-api.js — moduł zbiorczy przeznaczony wyłącznie dla środowiska uruchomieniowego
• setup-entry.js — punkt wejścia pluginu konfiguracji

​

Schematy narzędzia wiadomości

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

​

Rozpoznawanie celów kanałów

• messaging.inferTargetChatType({ to }) przed przeszukaniem katalogu określa, czy znormalizowany cel powinien być traktowany jako direct, group czy channel.
• messaging.targetResolver.looksLikeId(raw, normalized) informuje rdzeń, czy dane wejściowe powinny od razu przejść do rozpoznawania podobnego do identyfikatora, zamiast przeszukiwać katalog.
• messaging.targetResolver.reservedLiterals zawiera niekwalifikowane słowa, które są odwołaniami do kanałów lub sesji danego dostawcy. Rozpoznawanie zachowuje skonfigurowane wpisy katalogu przed odrzuceniem zastrzeżonych literałów, a następnie bezpiecznie kończy się niepowodzeniem, gdy nie ma dopasowania w katalogu.
• messaging.targetResolver.resolveTarget(...) jest mechanizmem awaryjnym pluginu, gdy rdzeń potrzebuje ostatecznego rozpoznania należącego do dostawcy po normalizacji lub braku dopasowania w katalogu.
• messaging.resolveOutboundSessionRoute(...) odpowiada za budowanie trasy sesji właściwej dla dostawcy po rozpoznaniu celu.

• Używaj inferTargetChatType do decyzji o kategorii, które powinny nastąpić przed wyszukiwaniem kontaktów lub grup.
• Używaj looksLikeId do sprawdzania, czy wartość należy „traktować jako jawny lub natywny identyfikator celu”.
• Używaj resolveTarget jako właściwego dla dostawcy mechanizmu awaryjnego normalizacji, a nie do szerokiego przeszukiwania katalogu.
• Natywne identyfikatory dostawcy, takie jak identyfikatory czatów, wątków, JID-y, uchwyty i identyfikatory pokojów, przechowuj w wartościach target lub parametrach właściwych dla dostawcy, a nie w ogólnych polach SDK.

​

Katalogi oparte na konfiguracji

• kontakty w wiadomościach prywatnych określone przez listę dozwolonych
• skonfigurowane mapowania kanałów lub grup
• statyczne mechanizmy awaryjne katalogu ograniczone do konta

• filtrowanie zapytań
• stosowanie limitów
• funkcje pomocnicze deduplikacji i normalizacji
• budowanie ChannelDirectoryEntry[]

​

Katalogi dostawców

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

• simple: zwykli dostawcy używający klucza API lub zmiennych środowiskowych
• profile: dostawcy pojawiający się, gdy istnieją profile uwierzytelniania
• paired: dostawcy tworzą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 zarejestrowano zarówno catalog, jak i discovery, OpenClaw używa catalog i emituje ostrzeżenie
• augmentModelCatalog jest przestarzałe; wbudowani 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 natychmiast zgłaszać błąd, gdy brakuje wymaganych sekretów.
• Ścieżki poleceń tylko do odczytu, takie jak openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, a także przepływy naprawy przez doctor lub konfigurację, nie powinny wymagać materializowania poświadczeń środowiska uruchomieniowego wyłącznie w celu opisania konfiguracji.

• Zwracaj wyłącznie opisowy stan konta.
• Zachowaj enabled i configured.
• W stosownych przypadkach uwzględniaj pola źródła/stanu danych uwierzytelniających, takie jak:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Nie musisz zwracać nieprzetworzonych wartości tokenów wyłącznie po to, aby zgłosić dostępność w trybie tylko do odczytu. Zwrócenie tokenStatus: "available" (oraz odpowiadającego mu pola źródła) wystarcza w poleceniach wyświetlających stan.
• Użyj configured_unavailable, gdy dane uwierzytelniające są skonfigurowane za pośrednictwem SecretRef, ale niedostępne w bieżącej ścieżce polecenia.

​

Pakiety rozszerzeń

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

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

• 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 bardziej rozbudowanych powierzchni katalogu/stanu
• docsLabel: zastępuje tekst odnośnika do dokumentacji
• preferOver: identyfikatory pluginów/kanałów o niższym priorytecie, nad którymi ten wpis katalogu powinien mieć pierwszeństwo
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: elementy sterujące treścią powierzchni wyboru
• markdownCapable: oznacza kanał jako obsługujący Markdown na potrzeby decyzji dotyczących formatowania wiadomości wychodzących
• exposure.configured: po ustawieniu na false ukrywa kanał na powierzchniach list skonfigurowanych kanałów
• exposure.setup: po ustawieniu na false ukrywa kanał w interaktywnych selektorach konfiguracji
• exposure.docs: oznacza kanał jako wewnętrzny/prywatny na potrzeby powierzchni nawigacyjnych dokumentacji
• showConfigured / showInSetup: starsze aliasy nadal akceptowane w celu zachowania zgodności; preferuj exposure
• quickstartAllowFrom: włącza kanał do standardowego przepływu szybkiego startu allowFrom
• forceAccountBinding: wymaga jawnego powiązania konta, nawet jeśli 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";
import { resolveSessionAgentId } from "openclaw/plugin-sdk/memory-host-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, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";
import { resolveSessionAgentId } from "openclaw/plugin-sdk/memory-host-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, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Dodawanie nowej funkcji

1. Zdefiniuj kontrakt rdzenia. Określ, za jakie współdzielone zachowanie powinien odpowiadać rdzeń: zasady, mechanizm rezerwowy, scalanie konfiguracji, cykl życia, semantykę udostępnianą kanałom oraz strukturę pomocniczych funkcji środowiska wykonawczego.
2. Dodaj typowane powierzchnie rejestracji Pluginów i środowiska wykonawczego. Rozszerz OpenClawPluginApi lub api.runtime o najmniejszą użyteczną, typowaną powierzchnię funkcji.
3. Połącz rdzeń z odbiorcami kanałów i funkcji. Kanały i Pluginy funkcji powinny korzystać z nowej funkcji za pośrednictwem rdzenia, zamiast bezpośrednio importować implementację dostawcy.
4. Zarejestruj implementacje dostawców. Następnie Pluginy dostawców rejestrują swoje backendy dla tej funkcji.
5. Dodaj testy kontraktu. Dodaj testy, aby odpowiedzialność i sposób rejestracji pozostawały z czasem jawne.

​

Lista kontrolna funkcji

• typy kontraktu rdzenia w src/<capability>/types.ts
• moduł uruchamiający lub funkcję pomocniczą środowiska wykonawczego rdzenia w src/<capability>/runtime.ts
• powierzchnię rejestracji API Pluginów w src/plugins/types.ts
• połączenia rejestru Pluginów w src/plugins/registry.ts
• udostępnienie środowiska wykonawczego Pluginów w src/plugins/runtime/*, gdy Pluginy funkcji lub kanałów muszą z niego korzystać
• funkcje pomocnicze do przechwytywania i testowania w src/test-utils/plugin-registration.ts
• asercje odpowiedzialności i kontraktu w src/plugins/contracts/registry.ts
• dokumentację dla operatorów i Pluginów w docs/

​

Szablon funkcji

// 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(pluginManifest.contracts?.videoGenerationProviders).toEqual(["openai"]);

• rdzeń odpowiada za kontrakt funkcji i koordynację
• Pluginy dostawców odpowiadają za implementacje dostawców
• Pluginy funkcji i kanałów korzystają z funkcji pomocniczych środowiska wykonawczego
• testy kontraktu zachowują jawność odpowiedzialności

​

Powiązane materiały

• Architektura Pluginów — publiczny model funkcji i ich struktury
• Ścieżki podrzędne zestawu SDK Pluginów
• Konfiguracja zestawu SDK Pluginów
• Tworzenie Pluginów