Interni dell'architettura dei Plugin

Documentation Index

Fetch the complete documentation index at: https://docs.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 bundled compilati usano un loader nativo; il sorgente TypeScript locale di terze parti usa il fallback di emergenza Jiti
7. chiama gli hook nativi register(api) e raccoglie le registrazioni nel registro dei plugin
8. espone il registro ai comandi e alle superfici di runtime

​

Comportamento manifest-first

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

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

​

Confine della cache dei plugin

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

• risultati di discovery
• registri manifest diretti
• registri manifest ricostruiti dall’indice dei plugin installati
• lookup del proprietario del provider, soppressione dei modelli, policy provider o metadati di 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 successiva lettura dei metadati

​

Modello del registro

• record dei plugin (identità, sorgente, origine, stato, diagnostica)
• tool
• hook legacy e hook tipizzati
• canali
• provider
• handler RPC del gateway
• rotte HTTP
• registrar CLI
• servizi in background
• comandi posseduti dai plugin

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

​

Callback di associazione 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: l’associazione risolta per le richieste approvate
• request: il riepilogo della richiesta originale, suggerimento di detach, id mittente e metadati della conversazione

​

Hook runtime dei provider

• Metadati del manifest per lookup economici prima del runtime: setup.providers[].envVars, compatibilità deprecata providerAuthEnvVars, providerAuthAliases, providerAuthChoices e channelEnvVars.
• Hook in fase di configurazione: catalog (legacy discovery) più applyConfigDefaults.
• Hook runtime: oltre 40 hook opzionali che coprono auth, risoluzione dei modelli, wrapping degli stream, livelli di pensiero, 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/nota vocale.
• 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 è opzionale per provider. Usalo per selettori vocali o flussi di configurazione di proprietà del vendor.
• Gli elenchi delle voci possono includere metadati più ricchi come locale, genere e tag di personalità per selettori consapevoli del provider.
• OpenAI ed ElevenLabs supportano la telefonia oggi. 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 consegna delle risposte nel core.
• Usa provider di sintesi vocale per il comportamento di sintesi di proprietà del vendor.
• L’input Microsoft legacy edge viene normalizzato all’id provider microsoft.
• Il modello di proprietà preferito è orientato all’azienda: un Plugin del vendor può possedere provider di testo, sintesi vocale, 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 opzionali, nuovi campi di risultato opzionali, nuove capability opzionali.
• La generazione video segue già lo stesso schema:
  • il core possiede il contratto di capability e l’helper di runtime
  • i Plugin dei 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 core di comprensione media (tools.media.audio) e l’ordine di fallback dei provider.
• Restituisce { text: undefined } quando non viene prodotto alcun output di trascrizione (per esempio input ignorato/non supportato).
• api.runtime.stt.transcribeAudioFile(...) resta un 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 opzionali per esecuzione, non modifiche persistenti della sessione.
• OpenClaw rispetta quei campi di override solo per chiamanti fidati.
• 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 fidati a target canonici provider/model specifici, oppure "*" per consentire esplicitamente qualsiasi target.
• Le esecuzioni subagent di Plugin non fidati funzionano comunque, ma le richieste di override vengono respinte invece di ricadere silenziosamente sul fallback.
• Le sessioni subagent create da Plugin sono 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 ancora 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 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 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 di provider di generazione immagini.
• listProviders(...): elenca i provider di generazione immagini disponibili e le loro capability.

​

Route HTTP 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 Gateway.
• auth: obbligatorio. Usa "gateway" per richiedere la normale autenticazione Gateway, oppure "plugin" per autenticazione/verifica webhook gestita dal Plugin.
• match: opzionale. "exact" (predefinito) o "prefix".
• replaceExisting: opzionale. 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 dei plugin devono dichiarare auth esplicitamente.
• I conflitti esatti di 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 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 helper privilegiate del Gateway.
• Le route auth: "gateway" vengono eseguite all’interno di uno scope runtime di richiesta del 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 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 tali richieste a route plugin con identità, lo scope runtime ripiega su operator.write
• Regola pratica: non dare per scontato che una route plugin autenticata dal gateway sia una superficie amministrativa implicita. Se la tua route richiede un comportamento riservato agli amministratori, richiedi una modalità di autenticazione con identità e documenta il contratto esplicito dell’header x-openclaw-scopes.

​

Percorsi di importazione dell’SDK dei plugin

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

​

Schemi degli strumenti di messaggio

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

​

Risoluzione delle destinazioni del canale

• messaging.inferTargetChatType({ to }) decide se una destinazione normalizzata debba essere trattata come direct, group o channel prima della lookup nella directory.
• messaging.targetResolver.looksLikeId(raw, normalized) indica al core se un input dovrebbe saltare direttamente alla risoluzione simile a 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 un mancato riscontro nella directory.
• messaging.resolveOutboundSessionRoute(...) possiede la costruzione della route di sessione specifica del provider una volta risolta una destinazione.

• Usa inferTargetChatType per decisioni di categoria che dovrebbero avvenire prima della ricerca in peer/gruppi.
• Usa looksLikeId per verifiche del tipo “tratta questo come un id destinazione esplicito/nativo”.
• Usa resolveTarget per il fallback di normalizzazione specifico del provider, non per ricerche ampie nella directory.
• Mantieni id provider-native come id chat, id thread, JID, handle e id stanza 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 statiche con scope di account

• filtraggio delle query
• applicazione del limite
• helper di deduplicazione/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 altri provider impliciti

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

​

Ispezione di canale 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 di riparazione doctor/config non dovrebbero dover materializzare credenziali runtime solo per descrivere la configurazione.

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

​

Pacchetti bundle

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

• la registrazione del canale stesso
• qualsiasi route HTTP che deve essere disponibile prima che il gateway inizi ad ascoltare
• qualsiasi metodo, tool o servizio del gateway che deve 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": "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: sostituisce il testo del link per il link alla documentazione
• preferOver: ID di plugin/canale a priorità più bassa che questa voce di catalogo dovrebbe superare
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: controlli del testo della superficie di selezione
• markdownCapable: contrassegna 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 su false
• exposure.setup: nasconde il canale dai selettori interattivi di setup/configurazione quando impostato su false
• exposure.docs: contrassegna 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 quickstart standard allowFrom
• forceAccountBinding: richiede un binding esplicito dell’account anche quando esiste un solo account
• preferSessionLookupForAnnounceTarget: preferisce la ricerca della sessione quando risolve i target degli annunci

• ~/.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 del core Decidi quale comportamento condiviso deve possedere il core: policy, fallback, merge della configurazione, ciclo di vita, semantica rivolta al canale e forma degli helper runtime.
2. aggiungi superfici tipizzate di registrazione/runtime del plugin Estendi OpenClawPluginApi e/o api.runtime con la superficie tipizzata utile più piccola.
3. collega core + consumer di canale/funzionalità I canali e i plugin di funzionalità dovrebbero consumare la nuova capability tramite il core, non importando direttamente un’implementazione del vendor.
4. registra le implementazioni del vendor I plugin vendor poi registrano i propri backend rispetto alla capability.
5. aggiungi copertura del contratto Aggiungi test in modo che proprietà e forma della registrazione restino esplicite nel tempo.

​

Checklist della capability

• tipi del contratto core in src/<capability>/types.ts
• helper runner/runtime del 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 capture/test in src/test-utils/plugin-registration.ts
• asserzioni di proprietà/contratto in src/plugins/contracts/registry.ts
• documentazione operatore/plugin in docs/

​

Template della 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 helper runtime
• i test di contratto mantengono esplicita la proprietà

​

Correlati

• Architettura dei plugin — modello e forme pubbliche delle capability
• Sottopercorsi del Plugin SDK
• Setup del Plugin SDK
• Creare plugin