​

Interni dei plugin

​

Modello di capacità pubblico

​

Posizione sulla compatibilità esterna

• plugin esterni esistenti: mantieni funzionanti le integrazioni basate su hook; trattale come baseline di compatibilità
• nuovi plugin bundled/nativi: preferisci la registrazione esplicita delle capacità rispetto a reach-in specifici del vendor o a nuovi design solo-hook
• plugin esterni che adottano la registrazione delle capacità: consentiti, ma tratta le superfici helper specifiche della 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 e senza rotture per i plugin esterni durante la transizione
• i sottopercorsi helper esportati non sono tutti equivalenti; preferisci il contratto ristretto e documentato, non esportazioni helper incidentali

​

Forme dei plugin

• plain-capability — registra esattamente un tipo di capacità (ad esempio un plugin solo-provider come mistral)
• hybrid-capability — registra più tipi di capacità (ad esempio openai possiede inferenza testuale, voce, comprensione dei media e generazione 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

• mantienilo funzionante
• documentalo come legacy
• preferisci before_model_resolve per lavoro di override di modello/provider
• preferisci before_prompt_build per lavoro di mutazione del prompt
• rimuovilo solo dopo che l’uso reale sarà diminuito e la copertura delle fixture dimostrerà la sicurezza della migrazione

​

Segnali di compatibilità

​

Panoramica dell’architettura

1. Manifest + discovery OpenClaw trova i plugin candidati dai percorsi configurati, dalle radici del workspace, dalle radici globali delle extension e dalle extension bundled. Il discovery legge prima i manifest nativi openclaw.plugin.json più i manifest dei bundle supportati.
2. Abilitazione + validazione Il core decide se un plugin scoperto è abilitato, disabilitato, bloccato o selezionato per uno slot esclusivo come la memory.
3. Caricamento runtime I plugin nativi OpenClaw vengono caricati in-process tramite jiti e registrano capacità in un registry centrale. I bundle compatibili vengono normalizzati in record di registry senza importare codice runtime.
4. Consumo della superficie Il resto di OpenClaw legge il registry per esporre strumenti, canali, configurazione del 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 al primo invio

• discovery + validazione della configurazione devono funzionare a partire dai metadati di manifest/schema senza eseguire codice del plugin
• il comportamento runtime nativo proviene dal percorso register(api) del modulo del plugin

​

Plugin di canale e lo strumento message condiviso

• il core possiede l’host dello strumento message condiviso, il wiring del prompt, la contabilità di sessione/thread e il dispatch dell’esecuzione
• i plugin di canale possiedono il discovery delle azioni in scope, il discovery delle capacità e ogni frammento di schema specifico del canale
• i plugin di canale possiedono la grammatica specifica del provider per le conversazioni di sessione, ad esempio come gli ID delle conversazioni codificano gli ID dei 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 trusted in entrata

• outbound.sendPoll è la baseline condivisa per i canali che si adattano al modello comune di poll
• actions.handleAction("poll") è il percorso preferito per semantiche di poll specifiche del canale o parametri poll aggiuntivi

​

Modello di ownership 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 model-provider OpenAI e il comportamento OpenAI di speech + realtime-voice + media-understanding + image-generation
• il plugin bundled elevenlabs possiede il comportamento di speech ElevenLabs
• il plugin bundled microsoft possiede il comportamento di speech Microsoft
• il plugin bundled google possiede il comportamento del model-provider Google più il comportamento Google di media-understanding + image-generation + web-search
• il plugin bundled firecrawl possiede il comportamento di web-fetch Firecrawl
• i plugin bundled minimax, mistral, moonshot e zai possiedono i loro backend di media-understanding
• il plugin voice-call è un plugin di funzionalità: possiede trasporto delle chiamate, strumenti, CLI, route e bridging del flusso media Twilio, ma consuma capacità condivise di speech più realtime-transcription e realtime-voice invece di importare direttamente i plugin dei vendor

• OpenAI vive in un singolo plugin anche se si estende tra modelli testuali, speech, 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 ownership
• capacità = 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 implementazioni

​

Stratificazione delle capacità

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

• il core possiede il criterio TTS al momento della risposta, l’ordine di fallback, le preferenze e la consegna ai canali
• openai, elevenlabs e microsoft possiedono le implementazioni di sintesi
• voice-call consuma l’helper 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/catalogo modelli/runtime hook
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // configurazione speech del vendor — implementa direttamente l'interfaccia SpeechProviderPlugin
    });

    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",
        // logica di credenziale + fetch
      }),
    );
  },
};

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 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 media-understanding
2. i plugin vendor registrano describeImage, transcribeAudio e describeVideo quando applicabile
3. i plugin di canale e di funzionalità consumano il comportamento condiviso del core invece di collegarsi direttamente al codice del vendor

​

Contratti e enforcement

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

1. enforcement della registrazione runtime Il registry dei plugin convalida le registrazioni durante il caricamento dei plugin. Esempi: provider id duplicati, speech provider id duplicati e registrazioni malformate producono diagnostica dei plugin invece di comportamento indefinito.
2. test di contratto I plugin bundled vengono catturati nei registry di contratto durante i test, così OpenClaw può verificare esplicitamente l’ownership. Oggi questo è usato per i model provider, gli speech provider, i web search provider e l’ownership delle registrazioni bundled.

​

Cosa appartiene a un contratto

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

• criterio specifico del vendor nascosto nel core
• escape hatch una tantum per il plugin che bypassano il registry
• codice del canale che accede direttamente a un’implementazione vendor
• oggetti runtime ad hoc che non fanno parte di OpenClawPluginApi o api.runtime

​

Modello di esecuzione

• un plugin nativo può registrare strumenti, handler 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 dentro il processo OpenClaw

• plugins.allow considera trusted gli id del plugin, non la 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 runtime non destinati a essere API pubbliche
• helper di convenienza specifici del vendor
• helper di setup/onboarding che sono dettagli di implementazione

​

Pipeline di caricamento

1. scopre le radici dei plugin candidati
2. legge i manifest nativi o dei bundle compatibili e i metadati dei package
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) — alias legacy) e raccoglie le registrazioni nel plugin registry
8. espone il registry alle superfici di comandi/runtime

​

Comportamento manifest-first

• identificare il plugin
• scoprire 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

​

Cosa memorizza in cache il loader

• risultati del discovery
• dati del manifest registry
• registry 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 registry

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

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

​

Callback di binding della conversazione

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // Ora esiste un binding per questo plugin + conversazione.
        console.log(event.binding?.conversationId);
        return;
      }

      // La richiesta è stata negata; pulisci eventuale stato locale in sospeso.
      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 detach, l’id del mittente e i metadati della conversazione

​

Runtime hook del provider

• metadati del manifest: providerAuthEnvVars per ricerca economica dell’auth env prima del caricamento runtime, più providerAuthChoices per etichette economiche di onboarding/auth-choice e metadati dei flag CLI prima del caricamento runtime
• hook in fase di configurazione: catalog / legacy discovery più applyConfigDefaults
• runtime hook: normalizeModelId, normalizeTransport, normalizeConfig, applyNativeStreamingUsageCompat, resolveConfigApiKey, resolveSyntheticAuth, 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 built-in

• Anthropic usa resolveDynamicModel, capabilities, buildAuthDoctorHint, resolveUsageAuth, fetchUsageSnapshot, isCacheTtlEligible, resolveDefaultThinkingLevel, applyConfigDefaults, isModernModelRef e wrapStreamFn perché possiede forward-compat di Claude 4.6, hint della famiglia provider, indicazioni di riparazione auth, integrazione con endpoint di utilizzo, eleggibilità della prompt-cache, valori predefiniti della configurazione consapevoli dell’auth, criterio di thinking predefinito/adaptive di Claude e modellazione specifica di Anthropic dello stream per header beta, /fast / serviceTier e context1m.
• Gli helper stream specifici di Claude per Anthropic restano per ora nel seam pubblico api.ts / contract-api.ts del plugin bundled stesso. Quella superficie di pacchetto esporta wrapAnthropicProviderStream, resolveAnthropicBetas, resolveAnthropicFastMode, resolveAnthropicServiceTier e i builder 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 OpenAI openai-completions -> openai-responses, hint auth consapevoli di Codex, soppressione Spark, righe sintetiche dell’elenco OpenAI e il criterio GPT-5 di thinking / live-model; la famiglia stream openai-responses-defaults possiede i wrapper condivisi nativi di OpenAI Responses per header di attribuzione, /fast/serviceTier, verbosità del testo, ricerca web nativa Codex, modellazione del payload di compatibilità reasoning e gestione del contesto Responses.
• OpenRouter usa catalog più resolveDynamicModel e prepareDynamicModel perché il provider è pass-through e può esporre nuovi model id prima che il catalogo statico di OpenClaw venga aggiornato; usa anche capabilities, wrapStreamFn e isCacheTtlEligible per mantenere fuori dal core header di richiesta specifici del provider, metadati di routing, patch di reasoning e criterio della prompt-cache. Il suo criterio di replay proviene dalla famiglia passthrough-gemini, mentre la famiglia stream openrouter-thinking possiede l’iniezione del reasoning proxy e gli skip di modello non supportato / auto.
• GitHub Copilot usa catalog, auth, resolveDynamicModel e capabilities più prepareRuntimeAuth e fetchUsageSnapshot perché necessita di login device posseduto dal provider, comportamento di fallback del modello, peculiarità di trascrizione 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, il criterio di fallback del refresh OAuth, la scelta predefinita del trasporto, righe sintetiche del catalogo Codex e l’integrazione con l’endpoint di utilizzo ChatGPT; condivide la stessa famiglia 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 replay google-gemini possiede fallback forward-compat di Gemini 3.1, validazione nativa del replay Gemini, sanitizzazione del replay bootstrap, modalità di output reasoning con tag e matching modern-model, mentre la famiglia stream google-thinking possiede la normalizzazione del payload thinking di Gemini; Gemini CLI OAuth usa anche formatApiKey, resolveUsageAuth e fetchUsageSnapshot per formattazione del token, parsing del token e wiring dell’endpoint quota.
• Anthropic Vertex usa buildReplayPolicy attraverso la famiglia replay anthropic-by-model così la pulizia specifica del replay 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 specifica di Bedrock di errore throttle/not-ready/context-overflow per il traffico Anthropic-on-Bedrock; il suo criterio di replay condivide comunque la stessa guardia solo-Claude anthropic-by-model.
• OpenRouter, Kilocode, Opencode e Opencode Go usano buildReplayPolicy tramite la famiglia replay passthrough-gemini perché fanno da proxy ai modelli Gemini tramite trasporti compatibili OpenAI e necessitano di sanitizzazione della thought-signature di Gemini senza validazione nativa del replay Gemini o riscritture bootstrap.
• MiniMax usa buildReplayPolicy tramite la famiglia replay hybrid-anthropic-openai perché un provider possiede sia la semantica Anthropic-message sia quella compatibile OpenAI; mantiene la rimozione dei blocchi thinking solo-Claude sul lato Anthropic mentre sovrascrive la modalità di output reasoning tornando a quella nativa, e la famiglia stream minimax-fast-mode possiede le riscritture del modello fast-mode sul percorso stream condiviso.
• Moonshot usa catalog più wrapStreamFn perché continua a usare il trasporto OpenAI condiviso ma necessita di normalizzazione del payload thinking posseduta dal provider; la famiglia stream moonshot-thinking mappa la configurazione più lo stato /think sul suo payload thinking binario nativo.
• Kilocode usa catalog, capabilities, wrapStreamFn e isCacheTtlEligible perché necessita di header di richiesta posseduti dal provider, normalizzazione del payload reasoning, hint di trascrizione Gemini e gating Anthropic cache-TTL; la famiglia stream kilocode-thinking mantiene l’iniezione del thinking Kilo sul percorso stream proxy condiviso saltando kilo/auto e altri proxy model id che non supportano payload reasoning espliciti.
• Z.AI usa resolveDynamicModel, prepareExtraParams, wrapStreamFn, isCacheTtlEligible, isBinaryThinking, isModernModelRef, resolveUsageAuth e fetchUsageSnapshot perché possiede fallback GLM-5, valori predefiniti tool_stream, UX del thinking binario, matching modern-model e sia auth d’uso sia recupero quota; la famiglia stream tool-stream-default-on mantiene il wrapper tool_stream default-on fuori dalla colla scritta a mano per-provider.
• xAI usa normalizeResolvedModel, normalizeTransport, contributeResolvedModelCompat, prepareExtraParams, wrapStreamFn, resolveSyntheticAuth, resolveDynamicModel e isModernModelRef perché possiede la normalizzazione nativa del trasporto xAI Responses, le riscritture degli alias fast-mode di Grok, tool_stream predefinito, pulizia di strict-tool / reasoning-payload, riuso dell’auth di fallback per strumenti posseduti dal plugin, risoluzione forward-compat dei modelli Grok e patch di compatibilità possedute dal provider come il profilo schema strumenti xAI, keyword di schema non supportate, web_search nativo e decodifica degli argomenti delle chiamate agli strumenti con entità HTML.
• Mistral, OpenCode Zen e OpenCode Go usano solo capabilities per tenere fuori dal core le peculiarità di trascrizione/tooling.
• 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 text provider più registrazioni condivise di media-understanding e video-generation 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 usare i trasporti condivisi.

​

Helper 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 TTS del core per superfici file/voice-note.
• 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 picker della voce o flussi di setup posseduti dal vendor.
• Gli elenchi delle voci possono includere metadati più ricchi come locale, genere e tag di personalità per picker consapevoli del provider.
• OpenAI e 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 il criterio TTS, il fallback e la consegna della risposta.
• Usa gli speech provider per il comportamento di sintesi posseduto dal vendor.
• L’input legacy Microsoft edge viene normalizzato all’id provider microsoft.
• Il modello di ownership preferito è orientato all’azienda: un plugin vendor può possedere provider di testo, voce, immagini e futuri 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 nel core orchestrazione, fallback, configurazione e wiring dei canali.
• Mantieni il comportamento del vendor nel plugin provider.
• L’espansione additiva deve restare tipizzata: nuovi metodi opzionali, nuovi campi opzionali del risultato, nuove capacità opzionali.
• La generazione video segue già lo stesso pattern:
  • il core possiede il contratto di capacità e l’helper 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,
  // Facoltativo quando il MIME non può essere dedotto in modo affidabile:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* è la superficie condivisa preferita per la comprensione di immagini/audio/video.
• Usa la configurazione audio core di media-understanding (tools.media.audio) e l’ordine di fallback del provider.
• Restituisce { text: undefined } quando non viene prodotto alcun output di trascrizione (ad 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-esecuzione, non modifiche persistenti della sessione.
• OpenClaw onora quei campi di override solo per chiamanti trusted.
• Per esecuzioni di fallback possedute dal plugin, gli operatori devono effettuare opt-in con plugins.entries.<id>.subagent.allowModelOverride: true.
• Usa plugins.entries.<id>.subagent.allowedModels per limitare i plugin trusted a target canonici specifici provider/model, oppure "*" per consentire esplicitamente qualsiasi target.
• Le esecuzioni subagent di plugin non trusted continuano a funzionare, ma le richieste di override vengono rifiutate invece di ricadere silenziosamente.

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 web-search provider per trasporti di ricerca specifici del vendor.
• api.runtime.webSearch.* è la superficie condivisa preferita per plugin di funzionalità/canale che necessitano del comportamento di ricerca senza dipendere dal wrapper dello strumento dell’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 configurata dei provider di image-generation.
• listProviders(...): elenca i provider disponibili di image-generation 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 auth del gateway, oppure "plugin" per auth/validazione webhook gestite dal plugin.
• match: facoltativo. "exact" (predefinito) o "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 esplicitamente auth.
• 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 sullo stesso livello auth.
• Le route auth: "plugin" non ricevono automaticamente gli scope runtime dell’operatore. Sono destinate a webhook/validazione delle firme gestiti dal plugin, non a chiamate privilegiate agli helper del Gateway.
• Le route auth: "gateway" vengono eseguite all’interno di uno scope runtime di richiesta Gateway, ma tale scope è intenzionalmente conservativo:
  • l’autenticazione bearer con segreto condiviso (gateway.auth.mode = "token" / "password") mantiene gli scope runtime delle route plugin fissati a operator.write, anche se il chiamante invia x-openclaw-scopes
  • le modalità HTTP trusted con identità (ad 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 a route plugin con identità, lo scope runtime ricade su operator.write
• Regola pratica: non presumere che una route plugin con auth gateway sia implicitamente una superficie admin. Se la tua route richiede comportamento solo-admin, richiedi una modalità auth con identità e documenta il contratto esplicito dell’header x-openclaw-scopes.

​

Percorsi di import del Plugin SDK

• 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 di 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 setup condiviso, auth, risposta e wiring dei webhook. channel-inbound è la sede condivisa per debounce, matching delle mention, formattazione degli envelope e helper del contesto degli envelope in entrata. channel-setup è il seam di setup ristretto per 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 è il seam dell’adattatore di setup dell’account consapevole dell’env. setup-tools è il piccolo seam di helper CLI/archivio/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-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 è il seam pubblico ristretto per normalizzazione/validazione dei custom command di Telegram e resta disponibile anche se la superficie contrattuale bundled di Telegram è temporaneamente non disponibile. text-runtime è il seam condiviso di testo/markdown/logging, incluso lo stripping del testo visibile all’assistente, helper di rendering/chunking markdown, helper di redazione, helper per directive-tag e utility di testo sicuro.
• I seam di canale specifici per le approvazioni dovrebbero preferire un unico contratto approvalCapability sul plugin. Il core legge quindi auth, consegna, rendering e comportamento di instradamento nativo delle approvazioni attraverso quella singola capacità invece di mescolare il comportamento di approvazione in campi del plugin non correlati.
• openclaw/plugin-sdk/channel-runtime è deprecato e rimane solo come shim di compatibilità per plugin più vecchi. 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 extension bundled restano privati. I plugin esterni dovrebbero usare solo i sottopercorsi openclaw/plugin-sdk/*. Il codice/test del core OpenClaw può usare i punti di ingresso pubblici del repo sotto la root del pacchetto del plugin come index.js, api.js, runtime-api.js, setup-entry.js e file a portata ristretta come login-qr-api.js. Non importare mai src/* di un pacchetto plugin dal core o da un’altra extension.
• Suddivisione del punto di ingresso del repo: <plugin-package-root>/api.js è il barrel helper/types, <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 stream di Claude come wrapAnthropicProviderStream, helper per header beta e parsing di service_tier.
  • OpenAI usa api.js per builder del provider, helper del modello predefinito e builder dei 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 del repo.
• I punti di ingresso pubblici caricati tramite facade preferiscono lo snapshot di configurazione runtime attivo quando esiste, poi ricadono sulla configurazione risolta su disco quando OpenClaw non sta ancora servendo uno snapshot runtime.
• Le primitive generiche condivise restano il contratto SDK pubblico preferito. Esiste ancora un piccolo insieme di compatibilità riservato di seam helper branded per canali bundled. Trattali come seam di manutenzione bundled/compatibilità, non come nuovi target di import per terze parti; i nuovi contratti cross-channel dovrebbero continuare ad arrivare sui sottopercorsi generici plugin-sdk/* o sui barrel locali del plugin api.js / runtime-api.js.

• Evita il barrel root openclaw/plugin-sdk nel nuovo codice.
• Preferisci prima le primitive stabili ristrette. I più recenti sottopercorsi 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 di messaggio e gli helper message-id delle reazioni appartengono a openclaw/plugin-sdk/channel-actions.
• I barrel helper specifici delle extension bundled non sono stabili per impostazione predefinita. Se un helper serve solo a una extension bundled, mantienilo dietro il seam locale api.js o runtime-api.js dell’extension invece di promuoverlo in openclaw/plugin-sdk/<extension>.
• I nuovi seam helper condivisi dovrebbero essere generici, non branded per canale. Il parsing condiviso dei target appartiene a openclaw/plugin-sdk/channel-targets; gli interni specifici del canale restano dietro il 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 message

• 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 della ricerca nella directory.
• messaging.targetResolver.looksLikeId(raw, normalized) dice al core se un input deve saltare direttamente alla risoluzione tipo-id invece della ricerca nella directory.
• messaging.targetResolver.resolveTarget(...) è il fallback del plugin quando il core necessita di una risoluzione finale posseduta dal provider dopo la normalizzazione o dopo una directory miss.
• messaging.resolveOutboundSessionRoute(...) possiede la costruzione della route di sessione specifica del provider una volta risolto il target.

• Usa inferTargetChatType per decisioni di categoria che dovrebbero avvenire prima di cercare peer/gruppi.
• Usa looksLikeId per i controlli “tratta questo come un 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 all’interno dei valori target o dei 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 di directory con ambito account

• filtro delle query
• applicazione dei limiti
• helper di deduplica/normalizzazione
• costruzione di ChannelDirectoryEntry[]

​

Cataloghi dei provider

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

• simple: provider semplici guidati da API-key o env
• profile: provider che appaiono quando esistono auth profile
• 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 del canale in sola lettura

• resolveAccount(...) è il percorso runtime. Può assumere 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 doctor/config non dovrebbero dover materializzare credenziali runtime solo per descrivere la configurazione.

• Restituisci solo lo stato descrittivo dell’account.
• Preserva enabled e configured.
• Includi campi di source/status delle credenziali quando rilevanti, come:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Non è necessario restituire valori raw dei token solo per riportare la disponibilità in sola lettura. È sufficiente restituire tokenStatus: "available" (e il relativo campo source).
• 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 stesso
• ogni route HTTP che deve essere disponibile prima che il gateway inizi ad ascoltare
• ogni metodo gateway, strumento o servizio che deve esistere in quella stessa finestra

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

Metadati di catalogo del canale

{
  "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: etichetta secondaria per superfici più ricche di catalogo/stato
• docsLabel: sovrascrive il testo del link alla documentazione
• preferOver: id di plugin/canale a priorità inferiore che questa voce di catalogo dovrebbe superare
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: controlli del testo per la superficie di selezione
• markdownCapable: contrassegna il canale come compatibile con markdown per decisioni di formattazione in uscita
• showConfigured: nasconde il canale dalle superfici di elenco dei canali configurati quando impostato su false
• quickstartAllowFrom: abilita il canale al flusso quickstart standard allowFrom
• forceAccountBinding: richiede il binding esplicito dell’account anche quando esiste un solo account
• preferSessionLookupForAnnounceTarget: preferisce la ricerca della sessione durante la risoluzione dei target di announce

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

​

Plugin del motore di contesto

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 }) {
      return { messages, estimatedTokens: 0 };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import { 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 }) {
      return { messages, estimatedTokens: 0 };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Aggiungere una nuova capacità

1. definisci il contratto del core Decidi quale comportamento condiviso dovrebbe possedere il core: criterio, fallback, merge della configurazione, lifecycle, semantica rivolta ai canali e forma dell’helper runtime.
2. aggiungi superfici tipizzate di registrazione/runtime del plugin Estendi OpenClawPluginApi e/o api.runtime con la superficie di capacità tipizzata più piccola utile.
3. collega consumatori 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. registra implementazioni vendor I plugin vendor registrano quindi i loro backend rispetto alla capacità.
5. aggiungi copertura contrattuale Aggiungi test in modo che ownership e forma della registrazione restino esplicite nel tempo.

​

Checklist della capacità

• tipi di contratto del core in src/<capability>/types.ts
• runner/helper runtime del core in src/<capability>/runtime.ts
• superficie di registrazione API del plugin in src/plugins/types.ts
• wiring del plugin registry in src/plugins/registry.ts
• esposizione del runtime del plugin in src/plugins/runtime/* quando i plugin di funzionalità/canale devono consumarlo
• helper di cattura/test in src/test-utils/plugin-registration.ts
• assert di ownership/contratto in src/plugins/contracts/registry.ts
• documentazione per operatori/plugin in docs/

​

Template della capacità

// contratto del core
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// API del plugin
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// helper runtime condiviso per plugin di funzionalità/canale
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 della capacità + l’orchestrazione
• i plugin vendor possiedono le implementazioni del vendor
• i plugin di funzionalità/canale consumano helper runtime
• i test di contratto mantengono esplicita l’ownership