Interni dell'architettura dei Plugin

Documentation Index

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

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

​

Pipeline di caricamento

1. individua le root dei Plugin candidati
2. legge i manifest dei bundle nativi o 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 ciascun candidato
6. carica i moduli nativi abilitati: i moduli integrati compilati usano un loader nativo; il sorgente TypeScript locale di terze parti usa il fallback Jiti di emergenza
7. chiama gli hook nativi register(api) e raccoglie le registrazioni nel registro dei Plugin
8. espone il registro ai comandi e alle superfici 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/placeholder della Control UI
• mostrare metadati di installazione/catalogo
• preservare descrittori economici di attivazione e setup senza caricare il runtime del Plugin

• il caricamento della CLI si restringe ai Plugin che possiedono il comando primario richiesto
• la risoluzione di setup/Plugin del canale si restringe ai Plugin che possiedono l’id canale richiesto
• la risoluzione esplicita di setup/runtime del provider si restringe ai Plugin che possiedono l’id provider richiesto
• la pianificazione dell’avvio del Gateway usa activation.onStartup per importazioni di avvio esplicite e opt-out di avvio; i Plugin senza metadati di avvio vengono caricati solo tramite trigger di attivazione più ristretti

​

Confine della cache dei Plugin

• PluginLoaderCacheState e registri runtime attivi compatibili
• cache jiti/moduli e cache del loader delle superfici pubbliche usate per evitare di importare ripetutamente la stessa superficie runtime
• cache del filesystem per artefatti Plugin installati
• mappe per chiamata a vita breve per normalizzazione dei percorsi o risoluzione dei duplicati

• risultati di scoperta
• registri manifest diretti
• registri manifest ricostruiti dall’indice dei Plugin installati
• lookup del proprietario del provider, soppressione dei modelli, policy del provider o metadati degli artefatti pubblici
• qualsiasi altra risposta derivata dal manifest in cui un manifest modificato, un indice installato o un percorso di caricamento dovrebbe essere visibile alla lettura successiva dei metadati

​

Modello di registro

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

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

​

Callback di binding delle conversazioni

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, l’indizio di detach, l’id mittente e i metadati della conversazione

​

Hook runtime dei provider

• Metadati del manifest per lookup economico pre-runtime: setup.providers[].envVars, compatibilità deprecata providerAuthEnvVars, providerAuthAliases, providerAuthChoices e channelEnvVars.
• Hook in fase di configurazione: catalog (discovery legacy) più applyConfigDefaults.
• Hook runtime: oltre 40 hook opzionali che coprono auth, risoluzione dei modelli, wrapping dello stream, livelli di thinking, policy di replay ed endpoint di utilizzo. Vedi l’elenco completo in Ordine e uso degli hook.

​

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

​

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 core per superfici file/note vocali.
• Usa la configurazione core messages.tts e la selezione del provider.
• Restituisce buffer audio PCM + frequenza di campionamento. I Plugin devono ricampionare/codificare per i provider.
• listVoices è facoltativo per provider. Usalo per selettori di voci o flussi di configurazione posseduti dal vendor.
• Gli elenchi delle voci possono includere metadati più ricchi come impostazioni locali, 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 policy TTS, fallback e recapito della risposta nel core.
• Usa i provider speech 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 Plugin vendor può possedere provider di testo, speech, immagini e media futuri man mano che OpenClaw aggiunge quei contratti di capability.

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 cablaggio dei canali nel core.
• Mantieni il comportamento del vendor nel Plugin provider.
• L’espansione additiva deve restare tipizzata: nuovi metodi facoltativi, nuovi campi risultato facoltativi, nuove capability facoltative.
• La generazione video segue già lo stesso schema:
  • il core possiede il contratto di capability 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 extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.5",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Use the printed fields as the source of truth." },
  ],
  instructions: "Return entities and searchable tags.",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* è la superficie condivisa preferita per la comprensione di immagini/audio/video.
• extractStructuredWithModel(...) è la seam rivolta ai Plugin per l’estrazione delimitata, posseduta dal provider e basata prima sulle immagini. Includi almeno un input immagine; gli input testuali sono contesto supplementare. i Plugin di prodotto possiedono le loro route e i loro schemi mentre OpenClaw possiede il confine provider/runtime.
• Usa la configurazione audio core di media-understanding (tools.media.audio) e l’ordine di fallback dei provider.
• Restituisce { text: undefined } quando non viene prodotto alcun output di trascrizione (per esempio input saltato/non supportato).
• api.runtime.stt.transcribeAudioFile(...) rimane 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 attendibili.
• Per esecuzioni di fallback possedute da Plugin, gli operatori devono aderire esplicitamente con plugins.entries.<id>.subagent.allowModelOverride: true.
• Usa plugins.entries.<id>.subagent.allowedModels per limitare i Plugin attendibili a target canonici provider/model specifici, oppure "*" per consentire esplicitamente qualsiasi target.
• Le esecuzioni di subagent da Plugin non attendibili funzionano comunque, ma le richieste di override vengono rifiutate invece di ripiegare silenziosamente.
• Le sessioni subagent create dai Plugin vengono etichettate con l’id del Plugin creatore. Il fallback api.runtime.subagent.deleteSession(...) può eliminare solo quelle sessioni possedute; l’eliminazione arbitraria di sessioni richiede comunque una richiesta Gateway con ambito admin.

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 selezione del provider, risoluzione delle credenziali e semantica condivisa delle richieste nel core.
• Usa i provider di ricerca web per transport di ricerca specifici del vendor.
• api.runtime.webSearch.* è la superficie condivisa preferita per Plugin di funzionalità/canale che necessitano di 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 di provider di generazione immagini configurata.
• listProviders(...): elenca i provider di generazione immagini disponibili e le loro capability.

​

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/verifica 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: restituisci 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 del 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 fallback exact/prefix solo sullo stesso livello di autenticazione.
• Le route auth: "plugin" non ricevono automaticamente gli scope runtime dell’operatore. Sono pensate per webhook/verifica delle firme gestiti dal plugin, non per chiamate privilegiate agli helper del Gateway.
• Le route auth: "gateway" vengono eseguite dentro uno scope runtime di richiesta Gateway, ma quello scope è intenzionalmente conservativo:
  • l’autenticazione bearer con segreto condiviso (gateway.auth.mode = "token" / "password") mantiene gli scope runtime delle route del plugin fissati a operator.write, anche se il chiamante invia x-openclaw-scopes
  • le modalità HTTP affidabili con identità (per esempio trusted-proxy o gateway.auth.mode = "none" su un ingresso privato) rispettano x-openclaw-scopes solo quando l’header è esplicitamente presente
  • se x-openclaw-scopes è assente in quelle richieste a route del plugin con identità, lo scope runtime ricade su operator.write
• Regola pratica: non presumere che una route del plugin con autenticazione gateway sia una superficie admin implicita. Se la tua route richiede comportamento riservato agli admin, richiedi una modalità di autenticazione con identità e documenta il contratto esplicito dell’header x-openclaw-scopes.

​

Percorsi di importazione del Plugin SDK

• index.js — ingresso del plugin incluso
• api.js — barrel di helper/tipi
• runtime-api.js — barrel solo runtime
• setup-entry.js — ingresso del plugin di configurazione

​

Schemi degli strumenti messaggio

• presentation per blocchi di presentazione semantici (text, context, divider, buttons, select)
• delivery-pin per richieste di consegna fissata

​

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 dovrebbe passare direttamente alla risoluzione simile a un id invece della ricerca nella directory.
• messaging.targetResolver.resolveTarget(...) è il fallback del plugin quando il core ha bisogno di una risoluzione finale di proprietà del 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 risolto un target.

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

​

Directory basate sulla configurazione

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

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

​

Cataloghi dei provider

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

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

• discovery funziona ancora come alias legacy, ma emette un avviso di deprecazione
• se vengono registrati sia catalog sia discovery, OpenClaw usa catalog
• augmentModelCatalog è deprecato; i provider inclusi dovrebbero pubblicare righe supplementari tramite registerModelCatalogProvider

​

Ispezione dei canali in sola lettura

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

• Restituisci solo stato account descrittivo.
• Preserva enabled e configured.
• Includi campi di sorgente/stato delle credenziali quando pertinente, come:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Non è necessario restituire valori token grezzi solo per segnalare la disponibilità in sola lettura. Restituire tokenStatus: "available" (e il campo sorgente corrispondente) è sufficiente per comandi di tipo status.
• Usa configured_unavailable quando una credenziale è configurata tramite SecretRef ma non disponibile nel percorso di comando corrente.

​

Pack di pacchetti

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

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

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

Metadati del catalogo 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": "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 di catalogo/stato più ricche
• docsLabel: sovrascrive il testo del link alla documentazione
• preferOver: id di Plugin/canali a priorità inferiore che questa voce di catalogo dovrebbe superare
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: controlli del testo della superficie di selezione
• markdownCapable: marca il canale come compatibile con markdown per le decisioni di formattazione in uscita
• exposure.configured: nasconde il canale dalle superfici di elenco dei canali configurati quando impostato a false
• exposure.setup: nasconde il canale dai selettori interattivi di setup/configurazione quando impostato a false
• exposure.docs: marca il canale come interno/privato per le superfici di navigazione della documentazione
• showConfigured / showInSetup: alias legacy ancora accettati per compatibilità; preferisci exposure
• quickstartAllowFrom: abilita il canale al flusso standard quickstart allowFrom
• forceAccountBinding: richiede un binding esplicito dell’account anche quando esiste un solo account
• preferSessionLookupForAnnounceTarget: preferisce la ricerca della sessione quando risolve i 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", (ctx) => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Aggiungere una nuova capability

1. definisci il contratto core Decidi quale comportamento condiviso il core dovrebbe possedere: policy, 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 più piccola superficie di capability tipizzata utile.
3. collega core e consumer di canale/funzionalità I canali e i Plugin di funzionalità dovrebbero consumare la nuova capability tramite il core, non importando direttamente un’implementazione vendor.
4. registra le implementazioni vendor I Plugin vendor registrano quindi i loro backend rispetto alla capability.
5. aggiungi copertura del contratto Aggiungi test così ownership e forma di registrazione restano esplicite nel tempo.

​

Checklist capability

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

​

Template capability

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

​

Correlati

• Architettura dei Plugin — modello e forme pubbliche delle capability
• Sottopercorsi dell’SDK Plugin
• Setup dell’SDK Plugin
• Creare Plugin