​

Interni dei plugin

​

Modello pubblico delle capacità

​

Posizione sulla compatibilità esterna

• plugin esterni esistenti: mantenere funzionanti le integrazioni basate su hook; trattare questo come riferimento di compatibilità
• nuovi plugin bundled/nativi: preferire la registrazione esplicita delle capacità invece di accessi specifici del vendor o nuovi design solo hook
• plugin esterni che adottano la registrazione delle capacità: consentito, ma trattare le superfici helper specifiche per capacità come in evoluzione, a meno che la documentazione non indichi esplicitamente che un contratto è stabile

• le API di registrazione delle capacità sono la direzione prevista
• gli hook legacy restano il percorso più sicuro per evitare rotture nei plugin esterni durante la transizione
• i sottopercorsi helper esportati non sono tutti equivalenti; preferisci il contratto ristretto documentato, non esportazioni helper incidentali

​

Forme dei plugin

• plain-capability — registra esattamente un tipo di capacità (per esempio un plugin solo provider come mistral)
• hybrid-capability — registra più tipi di capacità (per esempio openai possiede inferenza testuale, voce, comprensione dei media e generazione di immagini)
• hook-only — registra solo hook (tipizzati o personalizzati), nessuna capacità, strumento, comando o servizio
• non-capability — registra strumenti, comandi, servizi o route ma nessuna capacità

​

Hook legacy

• mantenerlo funzionante
• documentarlo come legacy
• preferire before_model_resolve per il lavoro di override di modello/provider
• preferire before_prompt_build per il lavoro di modifica del prompt
• rimuoverlo solo dopo che l’uso reale sarà diminuito e la copertura dei fixture avrà dimostrato la sicurezza della migrazione

​

Segnali di compatibilità

​

Panoramica dell’architettura

1. Manifest + individuazione OpenClaw trova i plugin candidati dai percorsi configurati, dalle radici del workspace, dalle radici globali delle estensioni e dalle estensioni bundled. L’individuazione legge prima i manifest nativi openclaw.plugin.json e i manifest bundle supportati.
2. Abilitazione + validazione Il core decide se un plugin individuato è abilitato, disabilitato, bloccato o selezionato per uno slot esclusivo come la memoria.
3. Caricamento di runtime I plugin nativi OpenClaw vengono caricati in-process tramite jiti e registrano capacità in un registro centrale. I bundle compatibili vengono normalizzati in record del registro senza importare il codice di runtime.
4. Consumo della superficie Il resto di OpenClaw legge il registro per esporre strumenti, canali, configurazione dei provider, hook, route HTTP, comandi CLI e servizi.

• i metadati in fase di parsing provengono da registerCli(..., { descriptors: [...] })
• il vero modulo CLI del plugin può restare lazy e registrarsi alla prima invocazione

• l’individuazione + la validazione della configurazione dovrebbero funzionare da metadati di manifest/schema senza eseguire il codice del plugin
• il comportamento di runtime nativo proviene dal percorso register(api) del modulo plugin

​

Plugin di canale e strumento condiviso dei messaggi

• il core possiede l’host dello strumento message condiviso, il wiring del prompt, la gestione di sessione/thread e il dispatch dell’esecuzione
• i plugin di canale possiedono il rilevamento di azioni con ambito, il rilevamento delle capacità e qualsiasi frammento di schema specifico del canale
• i plugin di canale possiedono la grammatica di conversazione della sessione specifica del provider, come il modo in cui gli ID conversazione codificano gli ID thread o ereditano dalle conversazioni padre
• i plugin di canale eseguono l’azione finale tramite il loro adattatore di azione

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• requesterSenderId inbound attendibile

• outbound.sendPoll è la base condivisa per i canali che si adattano al modello comune di sondaggio
• actions.handleAction("poll") è il percorso preferito per la semantica dei sondaggi specifica del canale o per parametri di sondaggio aggiuntivi

​

Modello di proprietà delle capacità

• un plugin aziendale dovrebbe di solito possedere tutte le superfici OpenClaw-facing di quell’azienda
• un plugin di funzionalità dovrebbe di solito possedere l’intera superficie della funzionalità che introduce
• i canali dovrebbero consumare capacità condivise del core invece di reimplementare in modo ad hoc il comportamento del provider

• il plugin bundled openai possiede il comportamento del provider di modelli OpenAI e il comportamento OpenAI per voce + voce in tempo reale + comprensione dei media + generazione di immagini
• il plugin bundled elevenlabs possiede il comportamento vocale ElevenLabs
• il plugin bundled microsoft possiede il comportamento vocale Microsoft
• il plugin bundled google possiede il comportamento del provider di modelli Google più il comportamento Google per comprensione dei media + generazione di immagini + ricerca web
• il plugin bundled firecrawl possiede il comportamento Firecrawl di recupero web
• i plugin bundled minimax, mistral, moonshot e zai possiedono i loro backend di comprensione dei media
• il plugin bundled qwen possiede il comportamento di provider testuale Qwen più il comportamento di comprensione dei media e generazione video
• il plugin voice-call è un plugin di funzionalità: possiede trasporto delle chiamate, strumenti, CLI, route e bridging del media-stream Twilio, ma consuma le capacità condivise di voce più trascrizione in tempo reale e voce in tempo reale invece di importare direttamente i plugin vendor

• OpenAI si trova in un unico plugin anche se copre modelli testuali, voce, immagini e futuro video
• un altro vendor può fare lo stesso per la propria area di superficie
• i canali non si preoccupano di quale plugin vendor possieda il provider; consumano il contratto di capacità condiviso esposto dal core

• plugin = confine di proprietà
• capability = contratto del core che più plugin possono implementare o consumare

1. definire la capacità mancante nel core
2. esporla tramite l’API/runtime dei plugin in modo tipizzato
3. collegare canali/funzionalità a quella capacità
4. lasciare che i plugin vendor registrino le implementazioni

​

Stratificazione delle capacità

• livello di capacità del core: orchestrazione condivisa, policy, fallback, regole di merge della configurazione, semantica di consegna e contratti tipizzati
• livello del plugin vendor: API specifiche del vendor, autenticazione, cataloghi di modelli, sintesi vocale, generazione di immagini, futuri backend video, endpoint di utilizzo
• livello del plugin di canale/funzionalità: integrazione Slack/Discord/voice-call/ecc. che consuma capacità del core e le presenta su una superficie

• il core possiede la policy TTS al momento della risposta, l’ordine di fallback, le preferenze e la consegna sui canali
• openai, elevenlabs e microsoft possiedono le implementazioni di sintesi
• voice-call consuma l’helper di runtime TTS per la telefonia

​

Esempio di plugin aziendale multi-capacità

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

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

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

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

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

export default plugin;

• un plugin possiede la superficie del vendor
• il core continua a possedere i contratti di capacità
• i plugin di canale e di funzionalità consumano helper api.runtime.*, non codice del vendor
• i test di contratto possono verificare che il plugin abbia registrato le capacità che dichiara di possedere

​

Esempio di capacità: comprensione video

1. il core definisce il contratto di comprensione dei media
2. i plugin vendor registrano describeImage, transcribeAudio e describeVideo secondo necessità
3. i plugin di canale e di funzionalità consumano il comportamento condiviso del core invece di collegarsi direttamente al codice del vendor

​

Contratti e applicazione

• gli autori di plugin ottengono un unico standard interno stabile
• il core può rifiutare proprietà duplicate, ad esempio due plugin che registrano lo stesso ID provider
• l’avvio può mostrare diagnostica utile per registrazioni non valide
• i test di contratto possono imporre la proprietà dei plugin bundled e prevenire derive silenziose

1. applicazione della registrazione a runtime Il registro dei plugin valida le registrazioni mentre i plugin vengono caricati. Esempi: ID provider duplicati, ID provider vocali duplicati e registrazioni non valide producono diagnostica dei plugin invece di comportamenti indefiniti.
2. test di contratto I plugin bundled vengono acquisiti nei registri di contratto durante le esecuzioni di test così OpenClaw può verificare esplicitamente la proprietà. Oggi questo viene usato per provider di modelli, provider vocali, provider di ricerca web e proprietà delle registrazioni bundled.

​

Cosa appartiene a un contratto

• tipizzati
• piccoli
• specifici per capacità
• posseduti dal core
• riutilizzabili da più plugin
• consumabili da canali/funzionalità senza conoscenza del vendor

• policy specifiche del vendor nascoste nel core
• vie di fuga specifiche per un singolo plugin che aggirano il registro
• codice di canale che entra direttamente in un’implementazione vendor
• oggetti di runtime ad hoc che non fanno parte di OpenClawPluginApi o api.runtime

​

Modello di esecuzione

• un plugin nativo può registrare strumenti, gestori di rete, hook e servizi
• un bug in un plugin nativo può mandare in crash o destabilizzare il gateway
• un plugin nativo malevolo equivale a esecuzione di codice arbitrario all’interno del processo OpenClaw

• plugins.allow si fida degli ID plugin, non della provenienza della sorgente.
• Un plugin del workspace con lo stesso ID di un plugin bundled oscura intenzionalmente la copia bundled quando quel plugin del workspace è abilitato/in allowlist.
• Questo è normale e utile per sviluppo locale, test di patch e hotfix.

​

Confine di esportazione

• sottopercorsi helper specifici dei plugin bundled
• sottopercorsi di plumbing di runtime non destinati a essere API pubbliche
• helper di comodità specifici del vendor
• helper di setup/onboarding che sono dettagli di implementazione

​

Pipeline di caricamento

1. individua le root candidate dei plugin
2. legge i manifest nativi o dei bundle compatibili e i metadati dei pacchetti
3. rifiuta i candidati non sicuri
4. normalizza la configurazione dei plugin (plugins.enabled, allow, deny, entries, slots, load.paths)
5. decide l’abilitazione per ogni candidato
6. carica i moduli nativi abilitati tramite jiti
7. chiama gli hook nativi register(api) (o activate(api) — un alias legacy) e raccoglie le registrazioni nel registro dei plugin
8. espone il registro alle superfici di comandi/runtime

​

Comportamento manifest-first

• identificare il plugin
• individuare canali/Skills/schema di configurazione dichiarati o capacità del bundle
• validare plugins.entries.<id>.config
• arricchire etichette/segnaposto della Control UI
• mostrare metadati di installazione/catalogo
• preservare descrittori economici di attivazione e setup senza caricare il runtime del plugin

​

Cosa mette in cache il loader

• risultati di individuazione
• dati del registro dei manifest
• registri dei plugin caricati

• Imposta OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1 o OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1 per disabilitare queste cache.
• Regola le finestre della cache con OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS e OPENCLAW_PLUGIN_MANIFEST_CACHE_MS.

​

Modello di registro

• record dei plugin (identità, sorgente, origine, stato, diagnostica)
• strumenti
• hook legacy e hook tipizzati
• canali
• provider
• gestori RPC del gateway
• route HTTP
• registrar CLI
• servizi in background
• comandi posseduti dal plugin

• modulo del plugin -> registrazione nel registro
• runtime del core -> consumo del registro

​

Callback di binding della conversazione

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" o "denied"
• decision: "allow-once", "allow-always" o "deny"
• binding: il binding risolto per le richieste approvate
• request: il riepilogo della richiesta originale, il suggerimento di distacco, l’ID del mittente e i metadati della conversazione

​

Hook di runtime del provider

• metadati del manifest: providerAuthEnvVars per un lookup economico dell’autenticazione provider tramite env prima del caricamento del runtime, providerAuthAliases per varianti del provider che condividono autenticazione, channelEnvVars per un lookup economico dell’env/setup del canale prima del caricamento del runtime, più providerAuthChoices per etichette economiche di onboarding/scelta di autenticazione e metadati dei flag CLI prima del caricamento del runtime
• hook in fase di configurazione: catalog / legacy discovery più applyConfigDefaults
• hook di runtime: normalizeModelId, normalizeTransport, normalizeConfig, applyNativeStreamingUsageCompat, resolveConfigApiKey, resolveSyntheticAuth, resolveExternalAuthProfiles, shouldDeferSyntheticProfileAuth, resolveDynamicModel, prepareDynamicModel, normalizeResolvedModel, contributeResolvedModelCompat, capabilities, normalizeToolSchemas, inspectToolSchemas, resolveReasoningOutputMode, prepareExtraParams, createStreamFn, wrapStreamFn, resolveTransportTurnState, resolveWebSocketSessionPolicy, formatApiKey, refreshOAuth, buildAuthDoctorHint, matchesContextOverflowError, classifyFailoverReason, isCacheTtlEligible, buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, isBinaryThinking, supportsXHighThinking, resolveDefaultThinkingLevel, isModernModelRef, prepareRuntimeAuth, resolveUsageAuth, fetchUsageSnapshot, createEmbeddingProvider, buildReplayPolicy, sanitizeReplayHistory, validateReplayTurns, onModelSelected

​

Ordine e uso degli hook

​

Esempio di provider

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

​

Esempi integrati

• Anthropic usa resolveDynamicModel, capabilities, buildAuthDoctorHint, resolveUsageAuth, fetchUsageSnapshot, isCacheTtlEligible, resolveDefaultThinkingLevel, applyConfigDefaults, isModernModelRef e wrapStreamFn perché possiede la forward-compat di Claude 4.6, i suggerimenti della famiglia provider, la guida di riparazione dell’autenticazione, l’integrazione dell’endpoint di utilizzo, l’idoneità della prompt-cache, i valori predefiniti di configurazione sensibili all’autenticazione, la policy di thinking predefinita/adattiva di Claude e il model shaping dello stream specifico di Anthropic per header beta, /fast / serviceTier e context1m.
• Gli helper di stream specifici di Claude di Anthropic restano per ora nella propria seam pubblica api.ts / contract-api.ts del plugin bundled. Questa superficie del pacchetto esporta wrapAnthropicProviderStream, resolveAnthropicBetas, resolveAnthropicFastMode, resolveAnthropicServiceTier e i builder di wrapper Anthropic di livello inferiore invece di ampliare l’SDK generico attorno alle regole degli header beta di un solo provider.
• OpenAI usa resolveDynamicModel, normalizeResolvedModel e capabilities più buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, supportsXHighThinking e isModernModelRef perché possiede la forward-compat di GPT-5.4, la normalizzazione diretta di OpenAI openai-completions -> openai-responses, i suggerimenti di autenticazione consapevoli di Codex, la soppressione di Spark, le righe sintetiche dell’elenco OpenAI e la policy di thinking / modello live di GPT-5; la famiglia di stream openai-responses-defaults possiede i wrapper condivisi nativi di OpenAI Responses per header di attribuzione, /fast/serviceTier, verbosità del testo, ricerca web nativa di Codex, model shaping del payload di compatibilità del reasoning e gestione del contesto di Responses.
• OpenRouter usa catalog più resolveDynamicModel e prepareDynamicModel perché il provider è pass-through e può esporre nuovi ID modello prima che il catalogo statico di OpenClaw venga aggiornato; usa anche capabilities, wrapStreamFn e isCacheTtlEligible per mantenere header di richiesta specifici del provider, metadati di routing, patch del reasoning e policy della prompt-cache fuori dal core. La sua policy di replay proviene dalla famiglia passthrough-gemini, mentre la famiglia di stream openrouter-thinking possiede l’iniezione del reasoning del proxy e i salti per modello non supportato / auto.
• GitHub Copilot usa catalog, auth, resolveDynamicModel e capabilities più prepareRuntimeAuth e fetchUsageSnapshot perché ha bisogno di login dispositivo posseduto dal provider, comportamento di fallback del modello, peculiarità della trascrizione di Claude, uno scambio token GitHub -> token Copilot e un endpoint di utilizzo posseduto dal provider.
• OpenAI Codex usa catalog, resolveDynamicModel, normalizeResolvedModel, refreshOAuth e augmentModelCatalog più prepareExtraParams, resolveUsageAuth e fetchUsageSnapshot perché continua a funzionare sui trasporti OpenAI del core ma possiede la propria normalizzazione di trasporto/base URL, la policy di fallback per il refresh OAuth, la scelta predefinita del trasporto, le righe sintetiche del catalogo Codex e l’integrazione dell’endpoint di utilizzo di ChatGPT; condivide la stessa famiglia di stream openai-responses-defaults di OpenAI diretto.
• Google AI Studio e Gemini CLI OAuth usano resolveDynamicModel, buildReplayPolicy, sanitizeReplayHistory, resolveReasoningOutputMode, wrapStreamFn e isModernModelRef perché la famiglia di replay google-gemini possiede il fallback di forward-compat di Gemini 3.1, la validazione nativa del replay Gemini, la sanitizzazione del replay di bootstrap, la modalità di output del reasoning con tag e il matching dei modelli moderni, mentre la famiglia di stream google-thinking possiede la normalizzazione del payload di thinking di Gemini; Gemini CLI OAuth usa anche formatApiKey, resolveUsageAuth e fetchUsageSnapshot per formattazione del token, parsing del token e collegamento dell’endpoint quota.
• Anthropic Vertex usa buildReplayPolicy tramite la famiglia di replay anthropic-by-model così la pulizia del replay specifica di Claude resta limitata agli ID Claude invece che a ogni trasporto anthropic-messages.
• Amazon Bedrock usa buildReplayPolicy, matchesContextOverflowError, classifyFailoverReason e resolveDefaultThinkingLevel perché possiede la classificazione degli errori specifica di Bedrock per throttling/non pronto/overflow del contesto per il traffico Anthropic-on-Bedrock; la sua policy di replay condivide comunque lo stesso guard solo-Claude anthropic-by-model.
• OpenRouter, Kilocode, Opencode e Opencode Go usano buildReplayPolicy tramite la famiglia di replay passthrough-gemini perché fanno da proxy ai modelli Gemini tramite trasporti compatibili con OpenAI e necessitano della sanitizzazione della thought-signature di Gemini senza validazione nativa del replay Gemini né riscritture di bootstrap.
• MiniMax usa buildReplayPolicy tramite la famiglia di replay hybrid-anthropic-openai perché un unico provider possiede sia la semantica di messaggi Anthropic sia quella compatibile con OpenAI; mantiene la rimozione dei blocchi di thinking solo-Claude sul lato Anthropic, mentre riporta la modalità di output del reasoning a quella nativa, e la famiglia di stream minimax-fast-mode possiede le riscritture del modello in fast mode sul percorso di stream condiviso.
• Moonshot usa catalog più wrapStreamFn perché continua a usare il trasporto OpenAI condiviso ma richiede una normalizzazione del payload di thinking posseduta dal provider; la famiglia di stream moonshot-thinking mappa la configurazione più lo stato /think sul proprio payload nativo di binary thinking.
• Kilocode usa catalog, capabilities, wrapStreamFn e isCacheTtlEligible perché ha bisogno di header di richiesta posseduti dal provider, normalizzazione del payload di reasoning, suggerimenti di trascrizione Gemini e gating TTL della cache Anthropic; la famiglia di stream kilocode-thinking mantiene l’iniezione del thinking Kilo sul percorso di stream proxy condiviso saltando kilo/auto e altri ID modello proxy che non supportano payload di reasoning espliciti.
• Z.AI usa resolveDynamicModel, prepareExtraParams, wrapStreamFn, isCacheTtlEligible, isBinaryThinking, isModernModelRef, resolveUsageAuth e fetchUsageSnapshot perché possiede il fallback GLM-5, i valori predefiniti tool_stream, la UX del binary thinking, il matching dei modelli moderni e sia l’autenticazione per l’utilizzo sia il recupero della quota; la famiglia di stream tool-stream-default-on mantiene il wrapper tool_stream attivo per impostazione predefinita fuori dalla colla scritta a mano per singolo provider.
• xAI usa normalizeResolvedModel, normalizeTransport, contributeResolvedModelCompat, prepareExtraParams, wrapStreamFn, resolveSyntheticAuth, resolveDynamicModel e isModernModelRef perché possiede la normalizzazione nativa del trasporto xAI Responses, le riscritture alias della fast mode di Grok, il tool_stream predefinito, la pulizia di strict-tool / payload di reasoning, il riuso dell’autenticazione di fallback per gli strumenti posseduti dal plugin, la risoluzione forward-compat del modello Grok e patch di compatibilità possedute dal provider come il profilo di schema degli strumenti xAI, keyword di schema non supportate, web_search nativo e la decodifica delle entità HTML negli argomenti delle chiamate di strumenti.
• Mistral, OpenCode Zen e OpenCode Go usano solo capabilities per mantenere le peculiarità di trascrizione/strumentazione fuori dal core.
• I provider bundled solo catalogo come byteplus, cloudflare-ai-gateway, huggingface, kimi-coding, nvidia, qianfan, synthetic, together, venice, vercel-ai-gateway e volcengine usano solo catalog.
• Qwen usa catalog per il proprio provider testuale più registrazioni condivise di comprensione dei media e generazione video per le sue superfici multimodali.
• MiniMax e Xiaomi usano catalog più hook di utilizzo perché il loro comportamento /usage è posseduto dal plugin anche se l’inferenza continua a passare attraverso i trasporti condivisi.

​

Helper di 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 restituisce il normale payload di output TTS del core per superfici file/messaggio vocale.
• Usa la configurazione core messages.tts e la selezione del provider.
• Restituisce buffer audio PCM + sample rate. I plugin devono ricampionare/codificare per i provider.
• listVoices è facoltativo per provider. Usalo per selettori vocali o flussi di setup posseduti dal vendor.
• Gli elenchi di voci possono includere metadati più ricchi come locale, genere e tag di personalità per selettori consapevoli del provider.
• OpenAI ed ElevenLabs supportano oggi la telefonia. Microsoft no.

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

• Mantieni nel core la policy TTS, il fallback e la consegna delle risposte.
• Usa i provider vocali per il comportamento di sintesi posseduto dal vendor.
• L’input legacy Microsoft edge viene normalizzato all’ID provider microsoft.
• Il modello di proprietà preferito è orientato all’azienda: un solo plugin vendor può possedere provider testuali, vocali, di immagini e futuri provider media man mano che OpenClaw aggiunge questi contratti di capacità.

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

• Mantieni orchestrazione, fallback, configurazione e wiring dei canali nel core.
• Mantieni il comportamento del vendor nel plugin provider.
• L’espansione additiva dovrebbe restare tipizzata: nuovi metodi facoltativi, nuovi campi risultato facoltativi, nuove capacità facoltative.
• La generazione video segue già lo stesso pattern:
  • il core possiede il contratto di capacità e l’helper di runtime
  • i plugin vendor registrano api.registerVideoGenerationProvider(...)
  • i plugin di funzionalità/canale consumano 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.* è la superficie condivisa preferita per la comprensione di immagini/audio/video.
• Usa la configurazione audio media-understanding del core (tools.media.audio) e l’ordine di fallback del provider.
• Restituisce { text: undefined } quando non viene prodotto alcun output di trascrizione (per esempio input saltato/non supportato).
• api.runtime.stt.transcribeAudioFile(...) resta come alias di compatibilità.

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 e model sono override facoltativi per singola esecuzione, non modifiche persistenti della sessione.
• OpenClaw onora questi campi di override solo per chiamanti attendibili.
• Per le esecuzioni di fallback possedute dal plugin, gli operatori devono effettuare l’opt-in con plugins.entries.<id>.subagent.allowModelOverride: true.
• Usa plugins.entries.<id>.subagent.allowedModels per limitare i plugin attendibili a target canonici specifici provider/model, oppure "*" per consentire esplicitamente qualsiasi target.
• Le esecuzioni subagent di plugin non attendibili continuano a funzionare, ma le richieste di override vengono rifiutate invece di ricadere silenziosamente nel fallback.

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

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

• Mantieni nel core la selezione del provider, la risoluzione delle credenziali e la semantica condivisa delle richieste.
• Usa i provider di ricerca web per i trasporti di ricerca specifici del vendor.
• api.runtime.webSearch.* è la superficie condivisa preferita per i plugin di funzionalità/canale che hanno bisogno di comportamento di ricerca senza dipendere dal wrapper dello strumento agente.

​

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(...): genera un’immagine usando la catena di provider di generazione immagini configurata.
• listProviders(...): elenca i provider di generazione immagini disponibili e le loro capacità.

​

Route HTTP del Gateway

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

• path: percorso della route sotto il server HTTP del gateway.
• auth: obbligatorio. Usa "gateway" per richiedere la normale autenticazione del gateway, oppure "plugin" per autenticazione/validazione webhook gestita dal plugin.
• match: facoltativo. "exact" (predefinito) oppure "prefix".
• replaceExisting: facoltativo. Consente allo stesso plugin di sostituire la propria registrazione di route esistente.
• handler: restituisce true quando la route ha gestito la richiesta.

• api.registerHttpHandler(...) è stato rimosso e causerà un errore di caricamento del plugin. Usa invece api.registerHttpRoute(...).
• Le route dei plugin devono dichiarare auth esplicitamente.
• I conflitti esatti path + match vengono rifiutati a meno che replaceExisting: true, e un plugin non può sostituire la route di un altro plugin.
• Le route sovrapposte con livelli auth diversi vengono rifiutate. Mantieni le catene di fallthrough exact/prefix solo allo stesso livello di auth.
• Le route auth: "plugin" non ricevono automaticamente scope di runtime operatore. Servono per webhook/validazione firme gestiti dal plugin, non per chiamate helper del Gateway con privilegi.
• Le route auth: "gateway" vengono eseguite all’interno di uno scope di runtime della richiesta Gateway, ma tale scope è intenzionalmente conservativo:
  • l’autenticazione bearer con segreto condiviso (gateway.auth.mode = "token" / "password") mantiene gli scope di runtime delle route plugin fissati a operator.write, anche se il chiamante invia x-openclaw-scopes
  • le modalità HTTP affidabili basate su identità (per esempio trusted-proxy o gateway.auth.mode = "none" su un ingresso privato) onorano x-openclaw-scopes solo quando l’header è esplicitamente presente
  • se x-openclaw-scopes è assente in quelle richieste di route plugin basate su identità, lo scope di runtime ricade su operator.write
• Regola pratica: non presumere che una route plugin con autenticazione gateway sia implicitamente una superficie admin. Se la tua route richiede comportamento solo admin, richiedi una modalità di autenticazione basata su identità e documenta il contratto esplicito dell’header x-openclaw-scopes.

​

Percorsi di import dell’SDK plugin

• openclaw/plugin-sdk/plugin-entry per le primitive di registrazione dei plugin.
• openclaw/plugin-sdk/core per il contratto generico condiviso rivolto ai plugin.
• openclaw/plugin-sdk/config-schema per l’esportazione dello schema Zod root openclaw.json (OpenClawSchema).
• Primitive stabili di canale come openclaw/plugin-sdk/channel-setup, openclaw/plugin-sdk/setup-runtime, openclaw/plugin-sdk/setup-adapter-runtime, openclaw/plugin-sdk/setup-tools, openclaw/plugin-sdk/channel-pairing, openclaw/plugin-sdk/channel-contract, openclaw/plugin-sdk/channel-feedback, openclaw/plugin-sdk/channel-inbound, openclaw/plugin-sdk/channel-lifecycle, openclaw/plugin-sdk/channel-reply-pipeline, openclaw/plugin-sdk/command-auth, openclaw/plugin-sdk/secret-input e openclaw/plugin-sdk/webhook-ingress per il wiring condiviso di setup/auth/reply/webhook. channel-inbound è la sede condivisa per debounce, corrispondenza delle mention, helper della mention-policy inbound, formattazione delle envelope e helper del contesto delle envelope inbound. channel-setup è la seam ristretta di setup con installazione facoltativa. setup-runtime è la superficie di setup sicura per il runtime usata da setupEntry / avvio differito, inclusi gli adattatori di patch di setup sicuri per l’import. setup-adapter-runtime è la seam dell’adattatore di setup account consapevole dell’env. setup-tools è la piccola seam helper per CLI/archivi/documentazione (formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR).
• Sottopercorsi di dominio come openclaw/plugin-sdk/channel-config-helpers, openclaw/plugin-sdk/allow-from, openclaw/plugin-sdk/channel-config-schema, openclaw/plugin-sdk/telegram-command-config, openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/approval-gateway-runtime, openclaw/plugin-sdk/approval-handler-adapter-runtime, openclaw/plugin-sdk/approval-handler-runtime, openclaw/plugin-sdk/approval-runtime, openclaw/plugin-sdk/config-runtime, openclaw/plugin-sdk/infra-runtime, openclaw/plugin-sdk/agent-runtime, openclaw/plugin-sdk/lazy-runtime, openclaw/plugin-sdk/reply-history, openclaw/plugin-sdk/routing, openclaw/plugin-sdk/status-helpers, openclaw/plugin-sdk/text-runtime, openclaw/plugin-sdk/runtime-store e openclaw/plugin-sdk/directory-runtime per helper condivisi di runtime/configurazione. telegram-command-config è la seam pubblica ristretta per normalizzazione/validazione dei comandi personalizzati Telegram e resta disponibile anche se la superficie di contratto Telegram bundled è temporaneamente non disponibile. text-runtime è la seam condivisa per testo/Markdown/logging, inclusi stripping del testo visibile all’assistente, helper di rendering/chunking Markdown, helper di redazione, helper dei tag direttiva e utilità di testo sicuro.
• Le seam di canale specifiche per l’approvazione dovrebbero preferire un singolo contratto approvalCapability sul plugin. Il core legge poi autenticazione di approvazione, consegna, render, routing nativo e comportamento lazy del gestore nativo tramite quella sola capacità invece di mescolare il comportamento di approvazione in campi non correlati del plugin.
• openclaw/plugin-sdk/channel-runtime è deprecato e rimane solo come shim di compatibilità per plugin meno recenti. Il nuovo codice dovrebbe importare invece le primitive generiche più ristrette, e il codice del repo non dovrebbe aggiungere nuovi import dello shim.
• Gli interni delle estensioni bundled restano privati. I plugin esterni dovrebbero usare solo i sottopercorsi openclaw/plugin-sdk/*. Il codice core/test di OpenClaw può usare i punti di ingresso pubblici del repo sotto la root di un pacchetto plugin come index.js, api.js, runtime-api.js, setup-entry.js e file a ambito ristretto come login-qr-api.js. Non importare mai src/* di un pacchetto plugin dal core o da un’altra estensione.
• Suddivisione dei punti di ingresso del repo: <plugin-package-root>/api.js è il barrel helper/tipi, <plugin-package-root>/runtime-api.js è il barrel solo runtime, <plugin-package-root>/index.js è l’entry del plugin bundled, e <plugin-package-root>/setup-entry.js è l’entry del plugin di setup.
• Esempi attuali di provider bundled:
  • Anthropic usa api.js / contract-api.js per helper di stream Claude come wrapAnthropicProviderStream, helper per header beta e parsing di service_tier.
  • OpenAI usa api.js per builder provider, helper del modello predefinito e builder provider realtime.
  • OpenRouter usa api.js per il proprio builder provider più helper di onboarding/configurazione, mentre register.runtime.js può ancora riesportare helper generici plugin-sdk/provider-stream per uso locale nel repo.
• I punti di ingresso pubblici caricati tramite facade preferiscono lo snapshot attivo della configurazione di runtime quando esiste, poi ricadono sul file di configurazione risolto su disco quando OpenClaw non sta ancora servendo uno snapshot di runtime.
• Le primitive generiche condivise restano il contratto pubblico preferito dell’SDK. Esiste ancora un piccolo insieme di compatibilità riservato di seam helper brandizzate per canali bundled. Trattale come seam di manutenzione/compatibilità bundled, non come nuovi target di import per terze parti; i nuovi contratti cross-channel dovrebbero comunque arrivare su sottopercorsi generici plugin-sdk/* o sui barrel locali del plugin api.js / runtime-api.js.

• Evita il barrel root openclaw/plugin-sdk per il nuovo codice.
• Preferisci prima le primitive stabili e ristrette. I sottopercorsi più recenti setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ allowlist/status/message-tool sono il contratto previsto per il nuovo lavoro su plugin bundled ed esterni. Il parsing/matching dei target appartiene a openclaw/plugin-sdk/channel-targets. I gate delle azioni sui messaggi e gli helper message-id delle reazioni appartengono a openclaw/plugin-sdk/channel-actions.
• I barrel helper specifici delle estensioni bundled non sono stabili per impostazione predefinita. Se un helper serve solo a un’estensione bundled, tienilo dietro la seam locale api.js o runtime-api.js dell’estensione invece di promuoverlo in openclaw/plugin-sdk/<extension>.
• Le nuove seam helper condivise dovrebbero essere generiche, non brandizzate per canale. Il parsing condiviso dei target appartiene a openclaw/plugin-sdk/channel-targets; gli interni specifici del canale restano dietro la seam locale api.js o runtime-api.js del plugin proprietario.
• Sottopercorsi specifici della capacità come image-generation, media-understanding e speech esistono perché i plugin bundled/nativi li usano oggi. La loro presenza non significa di per sé che ogni helper esportato sia un contratto esterno congelato a lungo termine.

​

Schemi dello strumento dei messaggi

• createMessageToolButtonsSchema() per payload in stile griglia di pulsanti
• createMessageToolCardSchema() per payload di card strutturate

​

Risoluzione dei target di canale

• messaging.inferTargetChatType({ to }) decide se un target normalizzato deve essere trattato come direct, group o channel prima del lookup nella directory.
• messaging.targetResolver.looksLikeId(raw, normalized) dice al core se un input deve saltare direttamente alla risoluzione simile a ID invece che alla ricerca nella directory.
• messaging.targetResolver.resolveTarget(...) è il fallback del plugin quando il core ha bisogno di una risoluzione finale posseduta dal provider dopo la normalizzazione o dopo un mancato riscontro nella directory.
• messaging.resolveOutboundSessionRoute(...) possiede la costruzione della route di sessione specifica del provider una volta che un target è stato risolto.

• Usa inferTargetChatType per decisioni di categoria che dovrebbero avvenire prima della ricerca in peer/gruppi.
• Usa looksLikeId per controlli del tipo “tratta questo come ID target esplicito/nativo”.
• Usa resolveTarget per il fallback di normalizzazione specifico del provider, non per una ricerca ampia nella directory.
• Mantieni gli ID nativi del provider come chat id, thread id, JID, handle e room id dentro valori target o parametri specifici del provider, non in campi SDK generici.

​

Directory supportate dalla configurazione

• peer DM guidati da allowlist
• mappe configurate di canali/gruppi
• fallback statici della directory con ambito account

• filtraggio delle query
• applicazione del limite
• helper di deduplica/normalizzazione
• costruzione di ChannelDirectoryEntry[]

​

Cataloghi provider

• { provider } per una voce provider
• { providers } per più voci provider

• simple: provider semplici guidati da chiave API o env
• profile: provider che compaiono quando esistono profili di autenticazione
• paired: provider che sintetizzano più voci provider correlate
• late: ultimo passaggio, dopo gli altri provider impliciti

• discovery continua a funzionare come alias legacy
• se sono registrati sia catalog sia discovery, OpenClaw usa catalog

​

Ispezione in sola lettura dei canali

• resolveAccount(...) è il percorso di runtime. Può presumere che le credenziali siano completamente materializzate e può fallire rapidamente quando mancano segreti richiesti.
• I percorsi di comando in sola lettura come openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve e i flussi di doctor/riparazione della configurazione non dovrebbero aver bisogno di materializzare credenziali di runtime solo per descrivere la configurazione.

• Restituire solo lo stato descrittivo dell’account.
• Preservare enabled e configured.
• Includere campi di sorgente/stato delle credenziali quando rilevanti, come:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Non è necessario restituire i valori raw dei token solo per riportare la disponibilità in sola lettura. Restituire tokenStatus: "available" (e il relativo campo di sorgente) è sufficiente per i comandi in stile status.
• Usa configured_unavailable quando una credenziale è configurata tramite SecretRef ma non disponibile nel percorso di comando corrente.

​

Package pack

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

• la registrazione del canale stessa
• eventuali route HTTP che devono essere disponibili prima che il gateway inizi ad ascoltare
• eventuali metodi gateway, strumenti o servizi che devono esistere durante quella stessa finestra

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

Metadati del catalogo dei canali

{
  "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": "Chat self-hosted tramite bot webhook di Nextcloud Talk.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: etichetta secondaria per superfici più ricche di catalogo/stato
• docsLabel: sovrascrive il testo del link per il collegamento alla documentazione
• preferOver: ID plugin/canale a priorità più bassa che questa voce di catalogo dovrebbe superare
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: controlli di testo per la superficie di selezione
• markdownCapable: segna il canale come capace di Markdown per le decisioni di formattazione outbound
• exposure.configured: nasconde il canale dalle superfici di elenco dei canali configurati quando impostato su false
• exposure.setup: nasconde il canale dai picker interattivi di setup/configurazione quando impostato su false
• exposure.docs: segna il canale come interno/privato per le superfici di navigazione della documentazione
• showConfigured / showInSetup: alias legacy ancora accettati per compatibilità; preferisci exposure
• quickstartAllowFrom: include il canale nel flusso standard quickstart allowFrom
• forceAccountBinding: richiede un account binding esplicito anche quando esiste un solo account
• preferSessionLookupForAnnounceTarget: preferisce il lookup di sessione durante la risoluzione dei target di annuncio

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

​

Plugin del motore di contesto

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

​

Aggiunta di una nuova capacità

1. definire il contratto del core Decidi quale comportamento condiviso dovrebbe possedere il core: policy, fallback, merge della configurazione, ciclo di vita, semantica rivolta ai canali e forma dell’helper di runtime.
2. aggiungere superfici tipizzate di registrazione/runtime dei plugin Estendi OpenClawPluginApi e/o api.runtime con la superficie di capacità tipizzata più piccola utile.
3. collegare i consumer del core + canale/funzionalità I canali e i plugin di funzionalità dovrebbero consumare la nuova capacità tramite il core, non importando direttamente un’implementazione vendor.
4. registrare implementazioni vendor I plugin vendor registrano poi i propri backend rispetto alla capacità.
5. aggiungere copertura contrattuale Aggiungi test così che proprietà e forma di registrazione restino esplicite nel tempo.

​

Checklist della capacità

• tipi di contratto del core in src/<capability>/types.ts
• runner/helper di runtime del core in src/<capability>/runtime.ts
• superficie di registrazione dell’API plugin in src/plugins/types.ts
• wiring del registro dei plugin in src/plugins/registry.ts
• esposizione di runtime del plugin in src/plugins/runtime/* quando i plugin di funzionalità/canale devono consumarla
• helper di acquisizione/test in src/test-utils/plugin-registration.ts
• asserzioni di proprietà/contratto in src/plugins/contracts/registry.ts
• documentazione per operatori/plugin in docs/

​

Template della capacità

// 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"]);

• il core possiede il contratto di capacità + l’orchestrazione
• i plugin vendor possiedono le implementazioni vendor
• i plugin di funzionalità/canale consumano helper di runtime
• i test di contratto mantengono esplicita la proprietà