Dettagli interni dell'architettura dei Plugin

​

Pipeline di caricamento

1. individua le radici 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. determina l’abilitazione di ciascun candidato
6. carica i moduli nativi abilitati: i moduli inclusi compilati usano un caricatore nativo; il codice sorgente TypeScript locale di terze parti usa Jiti come soluzione 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 di runtime

• il relativo punto di ingresso risolto esce dalla radice del plugin
• il relativo percorso (o la directory radice) è scrivibile da tutti
• per i plugin non inclusi, il proprietario del percorso non corrisponde all’uid corrente (o a root)

​

Comportamento basato anzitutto sul manifest

• identificare il plugin
• individuare canali/Skills/schema di configurazione o funzionalità del bundle dichiarati
• convalidare plugins.entries.<id>.config
• arricchire etichette e segnaposto dell’interfaccia di controllo
• mostrare i metadati di installazione/catalogo
• conservare descrittori di attivazione e configurazione economici senza caricare il runtime del plugin

• il caricamento della CLI viene ristretto ai plugin proprietari del comando primario richiesto
• la configurazione del canale/risoluzione del plugin viene ristretta ai plugin proprietari dell’id del canale richiesto
• la configurazione/risoluzione di runtime esplicita del provider viene ristretta ai plugin proprietari dell’id del provider richiesto
• la pianificazione dell’avvio del Gateway usa activation.onStartup per le importazioni esplicite all’avvio; i plugin senza metadati di avvio vengono caricati solo tramite trigger di attivazione più specifici

​

Confine della cache dei plugin

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

• risultati del rilevamento
• registri diretti dei manifest
• registri dei manifest ricostruiti dall’indice dei plugin installati
• ricerca del proprietario del provider, soppressione dei modelli, criteri dei provider o metadati degli artefatti pubblici
• qualsiasi altra risposta derivata dal manifest per la quale una modifica al manifest, all’indice installato o al percorso di caricamento debba essere visibile alla successiva lettura dei metadati

​

Modello del registro

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

​

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

​

Hook di runtime dei provider

• Metadati del manifest per ricerche economiche prima del runtime: setup.providers[].envVars, la compatibilità deprecata providerAuthEnvVars, providerAuthAliases, providerAuthChoices e channelEnvVars.
• Hook in fase di configurazione: catalog (discovery legacy) insieme ad applyConfigDefaults.
• Hook di runtime: oltre 40 hook facoltativi relativi ad autenticazione, risoluzione dei modelli, wrapping dei flussi, livelli di ragionamento, criteri di riproduzione ed endpoint di utilizzo. Consulta Ordine e utilizzo degli hook.

​

Ordine e utilizzo 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 del core per le superfici di file/note vocali.
• Utilizza la configurazione messages.tts e la selezione del provider del core.
• Restituisce un buffer audio PCM e la frequenza di campionamento. I Plugin devono ricampionare/codificare per i provider.
• listVoices è facoltativo per ciascun provider. Utilizzarlo per i selettori vocali o i flussi di configurazione gestiti dal fornitore.
• Il core passa una scadenza risolta della richiesta agli hook listVoices del provider; le impostazioni di timeout specifiche del provider possono sostituirla.
• Gli elenchi delle voci possono includere metadati più dettagliati, come impostazioni locali, genere e tag di personalità, per selettori consapevoli del provider.
• OpenAI ed ElevenLabs supportano attualmente 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,
    };
  },
});

• Mantenere nel core i criteri TTS, il ripiego e la consegna delle risposte.
• Utilizzare i provider vocali per il comportamento di sintesi gestito dal fornitore.
• L’input Microsoft legacy edge viene normalizzato nell’ID provider microsoft.
• Il modello di titolarità preferito è orientato all’azienda: un singolo Plugin del fornitore può gestire provider di testo, voce, immagini e contenuti multimediali futuri man mano che OpenClaw aggiunge i relativi contratti di funzionalità.

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

• Mantenere nel core l’orchestrazione, il ripiego, la configurazione e il collegamento ai canali.
• Mantenere il comportamento del fornitore nel Plugin del provider.
• L’espansione additiva deve rimanere tipizzata: nuovi metodi facoltativi, nuovi campi di risultato facoltativi, nuove funzionalità facoltative.
• La generazione video segue già lo stesso schema:
  • il core gestisce il contratto di funzionalità e l’helper di runtime
  • i Plugin dei fornitori registrano api.registerVideoGenerationProvider(...)
  • i Plugin di funzionalità/canale utilizzano api.runtime.videoGeneration.*

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.6-sol",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Use the printed fields as the source of truth." },
  ],
  instructions: "Return entities and searchable tags.",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});

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

• api.runtime.mediaUnderstanding.* è la superficie condivisa preferita per la comprensione di immagini/audio/video.
• extractStructuredWithModel(...) è l’interfaccia rivolta ai Plugin per un’estrazione delimitata, gestita dal provider e basata principalmente sulle immagini. Includere almeno un input immagine; gli input testuali forniscono contesto supplementare. I Plugin di prodotto gestiscono le proprie route e i propri schemi, mentre OpenClaw gestisce il confine provider/runtime.
• Utilizza la configurazione audio della comprensione multimediale del core (tools.media.audio) e l’ordine di ripiego dei provider.
• Restituisce { text: undefined } quando non viene prodotto alcun risultato di trascrizione, ad esempio per un input ignorato/non supportato.
• api.runtime.stt.transcribeAudioFile(...) rimane disponibile 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 sostituzioni facoltative per singola esecuzione, non modifiche persistenti della sessione.
• OpenClaw rispetta questi campi di sostituzione solo per i chiamanti attendibili.
• Per le esecuzioni di ripiego gestite dai Plugin, gli operatori devono fornire il consenso tramite plugins.entries.<id>.subagent.allowModelOverride: true.
• Utilizzare plugins.entries.<id>.subagent.allowedModels per limitare i Plugin attendibili a destinazioni canoniche provider/model specifiche, oppure "*" per consentire esplicitamente qualsiasi destinazione.
• Le esecuzioni dei sottoagenti di Plugin non attendibili continuano a funzionare, ma le richieste di sostituzione vengono rifiutate anziché ricorrere silenziosamente al ripiego.
• Le sessioni dei sottoagenti create dai Plugin vengono contrassegnate con l’ID del Plugin che le ha create. Il ripiego api.runtime.subagent.deleteSession(...) può eliminare soltanto tali sessioni di proprietà; l’eliminazione arbitraria delle sessioni richiede comunque una richiesta Gateway con ambito amministrativo.

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

• Mantenere nel core la selezione del provider, la risoluzione delle credenziali e la semantica condivisa delle richieste.
• Utilizzare i provider di ricerca web per i trasporti di ricerca specifici del fornitore.
• api.runtime.webSearch.* è la superficie condivisa preferita per i Plugin di funzionalità/canale che richiedono il comportamento di ricerca senza dipendere dal wrapper degli strumenti 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 utilizzando la catena configurata di provider per la generazione di immagini.
• listProviders(...): elenca i provider disponibili per la generazione di immagini e le relative funzionalità.

​

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 nel server HTTP del Gateway.
• auth: obbligatorio, "gateway" o "plugin". Usa "gateway" per richiedere la normale autenticazione del Gateway oppure "plugin" per l’autenticazione o la verifica dei Webhook gestita dal Plugin.
• match: facoltativo. "exact" (valore predefinito) o "prefix".
• handleUpgrade: gestore facoltativo per le richieste di upgrade WebSocket sulla stessa route.
• replaceExisting: facoltativo. Consente allo stesso Plugin di sostituire la registrazione della propria 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 tra path + match vengono rifiutati, a meno che non sia impostato 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 ripiego exact/prefix esclusivamente sullo stesso livello di autenticazione.
• Le route con auth: "plugin" non ricevono automaticamente gli ambiti di runtime dell’operatore. Sono destinate ai Webhook e alla verifica delle firme gestiti dal Plugin, non alle chiamate privilegiate agli helper del Gateway.
• Le route con auth: "gateway" vengono eseguite all’interno dell’ambito di runtime di una richiesta del Gateway. La superficie predefinita (gatewayRuntimeScopeSurface: "write-default") è intenzionalmente prudente:
  • l’autenticazione bearer con segreto condiviso (gateway.auth.mode = "token" / "password") e qualsiasi metodo di autenticazione diverso da proxy attendibile ricevono un unico ambito operator.write, anche se il chiamante invia x-openclaw-scopes
  • anche i chiamanti trusted-proxy senza un header x-openclaw-scopes esplicito mantengono la superficie precedente limitata a operator.write
  • i chiamanti trusted-proxy che inviano x-openclaw-scopes ricevono invece gli ambiti dichiarati
  • una route può scegliere gatewayRuntimeScopeSurface: "trusted-operator" per rispettare sempre x-openclaw-scopes nelle modalità di autenticazione associate a un’identità, usando come ripiego l’insieme completo degli ambiti predefiniti della CLI quando l’header è assente
• Regola pratica: non presumere che una route di Plugin autenticata tramite Gateway sia implicitamente una superficie amministrativa. Se la route richiede un comportamento riservato agli amministratori, scegli la superficie degli ambiti trusted-operator, richiedi una modalità di autenticazione associata a un’identità e documenta il contratto esplicito dell’header x-openclaw-scopes.
• Dopo la corrispondenza della route e l’autenticazione, i normali gestori partecipano all’ammissione del lavoro radice del Gateway. Un Gateway in fase di preparazione o riavvio restituisce 503 prima di invocare il gestore. La limitata eccezione è una route con auth: "gateway", autorizzata dal manifesto, che sceglie anche la superficie trusted-operator specifica della route; questa rimane raggiungibile per evitare che l’invio dei controlli di sospensione resti bloccato, mentre le normali route affini dello stesso Plugin rimangono dietro il limite di ammissione. La proprietà WebSocket di handleUpgrade usa lo stesso limite di ammissione atomico; dopo che il gestore accetta un socket, il successivo ciclo di vita del socket appartiene al Plugin e non viene monitorato da questo limite.

​

Percorsi di importazione dell’SDK dei Plugin

• index.js — punto di ingresso del Plugin integrato
• api.js — barrel di helper e tipi
• runtime-api.js — barrel riservato al runtime
• setup-entry.js — punto di ingresso del Plugin di configurazione

​

Schemi dello strumento per i messaggi

• presentation per i blocchi di presentazione semantici (text, context, divider, chart, table, buttons, select)
• delivery-pin per le richieste di consegna con elemento fissato

​

Risoluzione delle destinazioni dei canali

• messaging.inferTargetChatType({ to }) decide se una destinazione normalizzata deve essere trattata come direct, group o channel prima della ricerca nella directory.
• messaging.targetResolver.looksLikeId(raw, normalized) indica al core se un input deve passare direttamente alla risoluzione simile a un identificatore invece che alla ricerca nella directory.
• messaging.targetResolver.reservedLiterals elenca le parole isolate che costituiscono riferimenti a canali o sessioni per quel fornitore. La risoluzione preserva le voci configurate della directory prima di rifiutare i valori letterali riservati, quindi termina in modo sicuro in caso di mancata corrispondenza nella directory.
• messaging.targetResolver.resolveTarget(...) è il ripiego del Plugin quando il core necessita di una risoluzione finale gestita dal fornitore dopo la normalizzazione o dopo una mancata corrispondenza nella directory.
• messaging.resolveOutboundSessionRoute(...) gestisce la costruzione della route di sessione specifica del fornitore dopo la risoluzione di una destinazione.

• Usa inferTargetChatType per le decisioni di categoria che devono avvenire prima della ricerca tra contatti o gruppi.
• Usa looksLikeId per i controlli del tipo “tratta questo valore come identificatore esplicito o nativo della destinazione”.
• Usa resolveTarget per il ripiego della normalizzazione specifica del fornitore, non per una ricerca estesa nella directory.
• Mantieni gli identificatori nativi del fornitore, come identificatori di chat, identificatori di thread, JID, handle e identificatori di stanza, nei valori target o nei parametri specifici del fornitore, non nei campi generici dell’SDK.

​

Directory basate sulla configurazione

• contatti per messaggi diretti determinati da una lista consentita
• mappe configurate di canali o gruppi
• ripieghi statici della directory limitati all’account

• filtraggio delle query
• applicazione dei limiti
• helper di deduplicazione e normalizzazione
• creazione di ChannelDirectoryEntry[]

​

Cataloghi dei fornitori

• { provider } per una singola voce del fornitore
• { providers } per più voci di fornitori

• simple: fornitori basati su una semplice chiave API o su variabili d’ambiente
• profile: fornitori che compaiono quando esistono profili di autenticazione
• paired: fornitori che sintetizzano più voci correlate
• late: ultimo passaggio, dopo gli altri fornitori impliciti

• discovery continua a funzionare come alias precedente, ma emette un avviso di deprecazione
• se vengono registrati sia catalog sia discovery, OpenClaw usa catalog ed emette un avviso
• augmentModelCatalog è deprecato; i fornitori integrati devono pubblicare righe supplementari tramite registerModelCatalogProvider

​

Ispezione dei canali in sola lettura

• resolveAccount(...) è il percorso di runtime. Può presumere che le credenziali siano completamente materializzate e può terminare immediatamente con un errore quando mancano i segreti richiesti.
• I percorsi dei comandi in sola lettura, come openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve e i flussi di riparazione di doctor o della configurazione, non devono materializzare le credenziali di runtime soltanto per descrivere la configurazione.

• Restituisce solo lo stato descrittivo dell’account.
• Mantiene enabled e configured.
• Include i campi relativi all’origine e allo stato delle credenziali quando pertinenti, ad esempio:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Non è necessario restituire i valori grezzi dei token solo per segnalare la disponibilità in sola lettura. Restituire tokenStatus: "available" (e il campo di origine corrispondente) è sufficiente per i comandi di stato.
• Usa configured_unavailable quando una credenziale è configurata tramite SecretRef ma non è disponibile nel percorso del comando corrente.

​

Pacchetti di Plugin

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

• la registrazione del canale stesso
• tutti i percorsi HTTP che devono essere disponibili prima che il Gateway inizi l’ascolto
• tutti i metodi, gli strumenti o i servizi del Gateway che devono esistere durante la stessa finestra temporale

• 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ù dettagliate
• docsLabel: sostituisce il testo del collegamento alla documentazione
• preferOver: id di Plugin/canali con priorità inferiore che questa voce di catalogo deve superare
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: controlli del testo della superficie di selezione
• markdownCapable: contrassegna il canale come compatibile con Markdown per le decisioni sulla formattazione in uscita
• exposure.configured: nasconde il canale dalle superfici che elencano i canali configurati quando è impostato su false
• exposure.setup: nasconde il canale dai selettori interattivi di 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 rapido standard allowFrom
• forceAccountBinding: richiede un’associazione esplicita dell’account anche quando esiste un solo account
• preferSessionLookupForAnnounceTarget: preferisce la ricerca della sessione durante la risoluzione delle destinazioni 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";
import { resolveSessionAgentId } from "openclaw/plugin-sdk/memory-host-core";

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

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

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

​

Aggiunta di una nuova funzionalità

1. Definisci il contratto del core. Stabilisci quale comportamento condiviso deve essere gestito dal core: criteri, fallback, unione della configurazione, ciclo di vita, semantica rivolta ai canali e struttura degli helper di runtime.
2. Aggiungi superfici tipizzate per la registrazione e il runtime dei plugin. Estendi OpenClawPluginApi e/o api.runtime con la più piccola superficie tipizzata utile per la funzionalità.
3. Collega il core e i componenti consumer dei canali/delle funzionalità. I canali e i plugin di funzionalità devono utilizzare la nuova funzionalità tramite il core, senza importare direttamente un’implementazione specifica di un fornitore.
4. Registra le implementazioni dei fornitori. I plugin dei fornitori registrano quindi i propri backend per la funzionalità.
5. Aggiungi la copertura del contratto. Aggiungi test affinché la titolarità e la struttura della registrazione rimangano esplicite nel tempo.

​

Elenco di controllo della funzionalità

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

​

Modello di funzionalità

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

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

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(pluginManifest.contracts?.videoGenerationProviders).toEqual(["openai"]);

• il core gestisce il contratto della funzionalità e l’orchestrazione
• i plugin dei fornitori gestiscono le implementazioni specifiche dei fornitori
• i plugin di funzionalità/canale utilizzano gli helper di runtime
• i test del contratto mantengono esplicita la titolarità

​

Argomenti correlati

• Architettura dei plugin — modello pubblico e strutture delle funzionalità
• Sottopercorsi dell’SDK dei plugin
• Configurazione dell’SDK dei plugin
• Creazione di plugin