Panoramica dell’SDK per Plugin

L'SDK dei plugin è il contratto tipizzato tra i plugin e il core. Questa pagina è il riferimento per cosa importare e cosa è possibile registrare.

Convenzione di importazione

Importa sempre da un sottopercorso specifico:

Ogni sottopercorso è un modulo piccolo e autonomo. Ciò mantiene rapido l'avvio e previene problemi di dipendenze circolari. Per gli helper di ingresso/compilazione specifici dei canali, preferisci openclaw/plugin-sdk/channel-core; riserva openclaw/plugin-sdk/core alla superficie generale più ampia e agli helper condivisi, come buildChannelConfigSchema.

Per la configurazione dei canali, pubblica lo schema JSON di proprietà del canale tramite openclaw.plugin.json#channelConfigs. Il sottopercorso plugin-sdk/channel-config-schema è destinato alle primitive di schema condivise e al generatore generico. I plugin inclusi in OpenClaw usano plugin-sdk/bundled-channel-config-schema per gli schemi conservati dei canali inclusi. Le esportazioni di compatibilità deprecate rimangono in plugin-sdk/channel-config-schema-legacy; nessuno dei sottopercorsi degli schemi inclusi costituisce un modello per i nuovi plugin.

Riferimento dei sottopercorsi

L'SDK dei plugin è esposto come un insieme di sottopercorsi circoscritti, raggruppati per area (ingresso del plugin, canale, provider, autenticazione, runtime, funzionalità, memoria e helper riservati ai plugin inclusi). Per il catalogo completo, raggruppato e con collegamenti, consulta Sottopercorsi dell'SDK dei plugin.

L'inventario dei punti di ingresso del compilatore si trova in scripts/lib/plugin-sdk-entrypoints.json; le esportazioni del pacchetto vengono generate dal sottoinsieme pubblico dopo aver sottratto i sottopercorsi di test e interni locali al repository elencati in scripts/lib/plugin-sdk-private-local-only-subpaths.json. Esegui pnpm plugin-sdk:surface per verificare il numero di esportazioni pubbliche. I sottopercorsi pubblici deprecati sufficientemente vecchi e non usati dal codice di produzione delle estensioni incluse sono monitorati in scripts/lib/plugin-sdk-deprecated-public-subpaths.json; i barrel generali deprecati di riesportazione sono monitorati in scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

API di registrazione

Il callback register(api) riceve un oggetto OpenClawPluginApi con questi metodi:

Registrazione delle funzionalità

I provider di worker devono inoltre dichiarare il proprio ID in contracts.workerProviders. Il core rende persistente l'intento durevole prima di provision(profile, operationId). I provider convalidano le impostazioni prima dell'allocazione esterna e generano WorkerProviderError in caso di rifiuto permanente del profilo. provision deve adottare lo stesso lease quando l'ID operazione si ripete. Il core rende persistenti le impostazioni convalidate del profilo insieme al lease e fornisce tale snapshot a destroy({ leaseId, profile }), che deve essere idempotente, e a inspect({ leaseId, profile }), che restituisce active, destroyed o unknown. Ciò consente ai provider di instradare le chiamate del ciclo di vita dopo il riavvio di un Gateway o la rimozione di un profilo denominato. Gli endpoint SSH usano un SecretRef per keyRef, mai materiale della chiave incorporato, e includono un hostKey proveniente da un output di provisioning attendibile, nel formato esatto algorithm base64, senza nome host né commento. Il core fissa hostKey e non considera mai attendibile una chiave ricevuta dalla prima connessione. Un provider che genera dinamicamente un keyRef può implementare resolveSshIdentity({ leaseId, profile, keyRef }); quando presente, tale resolver è autoritativo, mentre i provider che ne sono privi usano il resolver generico dei segreti configurato. I provider con lease rinnovabili possono anche implementare renew(leaseId). inspect deve generare un'eccezione in caso di errori transitori o indeterminati; restituisce unknown solo in caso di assenza accertata. Il core contrassegna come orfano un record locale attivo oppure considera l'assenza come completamento della dismissione dopo una richiesta di eliminazione resa persistente.

I provider di incorporamenti registrati con api.registerEmbeddingProvider(...) devono essere elencati anche in contracts.embeddingProviders nel manifesto del plugin. Questa è la superficie generica per gli incorporamenti, destinata alla generazione riutilizzabile di vettori. La ricerca in memoria può utilizzare questa superficie generica dei provider. La precedente interfaccia api.registerMemoryEmbeddingProvider(...) e contracts.memoryEmbeddingProviders costituisce una compatibilità deprecata durante la migrazione dei provider esistenti specifici per la memoria.

I provider specifici per la memoria che espongono ancora un batchEmbed(...) di runtime rimangono sul contratto di elaborazione in batch esistente per singolo file, a meno che il loro runtime non imposti esplicitamente sourceWideBatchEmbed: true. Questa adesione facoltativa consente all'host della memoria di inviare segmenti provenienti da più file di memoria modificati e da fonti abilitate in una singola chiamata batchEmbed(...), fino ai limiti di batch dell'host. Gli adattatori batch che caricano file di richiesta JSONL devono suddividere i processi del provider prima di raggiungere sia il limite delle dimensioni di caricamento sia quello del numero di richieste. Il provider deve restituire un incorporamento per ogni segmento di input, nello stesso ordine di batch.chunks; ometti il flag quando il provider prevede batch locali ai file o non può conservare l'ordine degli input in un processo più ampio esteso all'intera fonte.

Strumenti e comandi

Usa defineToolPlugin per semplici plugin che includono solo strumenti con nomi fissi. Usa direttamente api.registerTool(...) per i plugin misti o per la registrazione completamente dinamica degli strumenti.

I comandi dei plugin possono impostare agentPromptGuidance quando l'agente necessita di una breve indicazione di instradamento appartenente al comando. Limita il testo al comando stesso; non aggiungere criteri specifici per provider o plugin ai generatori dei prompt del core.

Le voci delle indicazioni possono essere stringhe legacy, che si applicano a ogni superficie dei prompt, oppure voci strutturate:

agentPromptGuidance: [  "Indicazione globale per il comando.",  { text: "Mostra questo solo nel prompt principale di OpenClaw.", surfaces: ["openclaw_main"] },];

Le surfaces strutturate possono includere openclaw_main, codex_app_server, cli_backend, acp_backend o subagent. pi_main rimane un alias deprecato di openclaw_main. Ometti surfaces per le indicazioni intenzionalmente applicabili a tutte le superfici. Non passare un array surfaces vuoto: viene rifiutato affinché una perdita accidentale dell'ambito non trasformi il testo in un prompt globale.

Le istruzioni native per sviluppatori del server applicativo Codex sono più rigorose rispetto alle altre superfici dei prompt: solo le indicazioni il cui ambito è esplicitamente codex_app_server vengono promosse in quel canale a priorità più elevata. Le indicazioni sotto forma di stringhe legacy e le indicazioni strutturate senza ambito rimangono disponibili alle superfici dei prompt diverse da Codex per compatibilità.

I comandi dell'host Node vengono eseguiti sull'host Node connesso, non all'interno del processo Gateway. Se agentTool è presente, il Node pubblica un descrittore dopo una connessione riuscita al Gateway; il Gateway lo espone alle esecuzioni dell'agente solo mentre quel Node è connesso e solo se il valore command del descrittore rientra nell'insieme di comandi approvati del Node. Impostare agentTool.defaultPlatforms per includere un comando non pericoloso nella allowlist predefinita dei comandi del Node; in caso contrario, è necessario configurare esplicitamente gateway.nodes.allowCommands o una policy di invocazione del Node. agentTool.name deve essere sicuro per il provider: deve iniziare con una lettera, utilizzare solo lettere, cifre, trattini bassi o trattini e non superare i 64 caratteri. Gli strumenti Node basati su MCP possono impostare i metadati agentTool.mcp affinché il catalogo e le superfici di ricerca degli strumenti possano mostrare l'identità del server/strumento MCP remoto, ma l'esecuzione avviene comunque tramite il comando Node pubblicizzato.

Infrastruttura

I builder dei supplementi del prompt di memoria ricevono il contesto facoltativo agentId, agentSessionKey e sandboxed. Le chiamate search e get del supplemento del corpus di memoria ricevono il contesto facoltativo agentId e sandboxed. I Plugin con archiviazione appartenente all'agente devono risolvere tale archiviazione per ogni chiamata, anziché acquisire un unico percorso globale durante la registrazione. Se un ID agente è obbligatorio ma manca in un'operazione multi-agente, rifiutare l'operazione in modo sicuro anziché scegliere un agente arbitrario.

I gestori interattivi di Telegram possono restituire { submitText } per instradare il testo attraverso il normale percorso in ingresso dell'agente di Telegram dopo l'esito positivo del gestore. OpenClaw mantiene il pulsante di callback quando la policy in ingresso ignora il testo o l'elaborazione non riesce, affinché l'utente possa riprovare dopo la modifica della condizione bloccante. Questo campo del risultato è specifico di Telegram; gli altri canali mantengono i propri contratti per i risultati interattivi.

Hook dell'host per i Plugin di flusso di lavoro

Gli hook dell'host sono i punti di integrazione dell'SDK per i Plugin che devono partecipare al ciclo di vita dell'host, anziché limitarsi ad aggiungere un provider, un canale o uno strumento. Sono contratti generici; possono essere utilizzati dalla modalità di pianificazione, ma anche da flussi di lavoro di approvazione, controlli delle policy dello spazio di lavoro, monitor in background, procedure guidate di configurazione e Plugin complementari per l'interfaccia utente.

Un descrittore surface: "tab" aggiunge una scheda nella barra laterale della UI di controllo. I descrittori delle schede dei Plugin attivi vengono comunicati ai client della dashboard nel messaggio hello del Gateway (controlUiTabs), quindi la scheda viene visualizzata solo mentre il Plugin è abilitato. I Plugin inclusi possono fornire una vista della dashboard di prima classe per la propria scheda; gli altri Plugin possono impostare path su una route HTTP del Plugin (vedere api.registerHttpRoute(...)) che la dashboard visualizza in un frame con sandbox. icon è un suggerimento per il nome dell'icona della dashboard, group seleziona la sezione della barra laterale (control o agent), order determina l'ordinamento tra le schede dei Plugin e requiredScopes nasconde la scheda alle connessioni prive di tali ambiti operatore:

api.session.controls.registerControlUiDescriptor({  surface: "tab",  id: "logbook",  label: "Logbook",  description: "Your day as a timeline, built from screen snapshots.",  icon: "sun",  group: "control",  requiredScopes: ["operator.write"],});

Utilizzare gli spazi dei nomi raggruppati per il nuovo codice dei Plugin:

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

I metodi piatti equivalenti rimangono disponibili come alias di compatibilità deprecati per i Plugin esistenti. Non aggiungere nuovo codice di Plugin che chiami direttamente api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn o api.unscheduleSessionTurnsByTag.

scheduleSessionTurn(...) è una funzione di utilità con ambito di sessione basata sullo scheduler Cron del Gateway. Cron gestisce la temporizzazione e crea il record dell'attività in background quando il turno viene eseguito; l'SDK del Plugin limita soltanto la sessione di destinazione, la denominazione appartenente al Plugin e la pulizia. Utilizzare api.runtime.tasks.managedFlows all'interno del turno pianificato quando il lavoro stesso richiede uno stato Task Flow persistente e articolato in più passaggi.

I contratti separano intenzionalmente l'autorità:

• I Plugin esterni possono gestire estensioni di sessione, descrittori dell'interfaccia utente, comandi, metadati degli strumenti, inserimenti nel turno successivo e hook normali.
• Le policy attendibili degli strumenti vengono eseguite prima dei normali hook before_tool_call e sono considerate attendibili dall'host. Le policy incluse vengono eseguite per prime; quelle dei Plugin installati richiedono l'abilitazione esplicita e l'inclusione dei relativi ID locali in contracts.trustedToolPolicies, quindi vengono eseguite nell'ordine di caricamento dei Plugin. Gli ID delle policy hanno come ambito il Plugin che le registra.
• La titolarità dei comandi riservati è limitata ai componenti inclusi. I Plugin esterni devono utilizzare nomi di comando o alias propri.
• allowPromptInjection=false disabilita gli hook che modificano il prompt, inclusi agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, i campi del prompt provenienti dal precedente before_agent_start e enqueueNextTurnInjection.

Esempi di utilizzatori non legati alla modalità di pianificazione:

Registrazione del rilevamento del Gateway

api.registerGatewayDiscoveryService(...) consente a un Plugin di annunciare il Gateway attivo su un trasporto di rilevamento locale come mDNS/Bonjour. OpenClaw chiama il servizio durante l'avvio del Gateway quando il rilevamento locale è abilitato, passa le porte correnti del Gateway e dati di suggerimento TXT non segreti, quindi chiama il gestore stop restituito durante l'arresto del Gateway.

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

I Plugin di rilevamento del Gateway non devono considerare segreti o dati di autenticazione i valori TXT annunciati. Il rilevamento è un suggerimento per l'instradamento; l'autenticazione del Gateway e il pinning TLS continuano a determinare l'attendibilità.

Metadati di registrazione della CLI

api.registerCli(registrar, opts?) accetta due tipi di metadati dei comandi:

• commands: nomi espliciti dei comandi di proprietà del registratore
• descriptors: descrittori dei comandi usati durante l'analisi per la guida della CLI, l'instradamento e la registrazione differita della CLI del Plugin
• parentPath: percorso facoltativo del comando padre per gruppi di comandi annidati, come ["nodes"]

Per le funzionalità dei nodi associati, preferisci api.registerNodeCliFeature(registrar, opts?). È un piccolo wrapper di api.registerCli(..., { parentPath: ["nodes"] }) e rende comandi come openclaw nodes canvas funzionalità dei nodi esplicitamente di proprietà del Plugin.

Se vuoi che un comando del Plugin rimanga caricato in modo differito nel normale percorso radice della CLI, fornisci descriptors che coprano ogni radice di comando di primo livello esposta dal registratore.

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Gestisci account Matrix, verifica, dispositivi e stato del profilo",        hasSubcommands: true,      },    ],  },);

I comandi annidati ricevono il comando padre risolto come program:

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Acquisisci o visualizza il contenuto del canvas da un nodo associato",        hasSubcommands: true,      },    ],  },);

Utilizza solo commands esclusivamente quando non ti serve la registrazione differita della CLI radice. Questo percorso di compatibilità con caricamento immediato rimane supportato, ma non installa segnaposto basati su descrittori per il caricamento differito durante l'analisi.

Registrazione del backend CLI

api.registerCliBackend(...) consente a un Plugin di gestire la configurazione predefinita per un backend CLI di IA locale come claude-cli o my-cli.

• L'id del backend diventa il prefisso del provider nei riferimenti ai modelli come my-cli/gpt-5.
• La config del backend usa la stessa struttura di agents.defaults.cliBackends.<id>.
• La configurazione dell'utente continua ad avere la precedenza. OpenClaw sovrappone agents.defaults.cliBackends.<id> alla configurazione predefinita del Plugin prima di eseguire la CLI.
• Utilizza normalizeConfig quando un backend richiede riscritture di compatibilità dopo l'unione (ad esempio, per normalizzare vecchie strutture dei flag).
• Utilizza resolveExecutionArgs per le riscritture di argv relative alla richiesta che appartengono al dialetto della CLI, come la mappatura dei livelli di ragionamento di OpenClaw a un flag nativo di intensità. L'hook riceve ctx.executionMode; utilizza "side-question" per aggiungere flag di isolamento nativi del backend per le chiamate temporanee /btw. Se tali flag disabilitano in modo affidabile gli strumenti nativi per una CLI altrimenti sempre attiva, dichiara anche sideQuestionToolMode: "disabled".
• I backend in grado di disabilitare tutti gli strumenti nativi per un'esecuzione specifica possono dichiarare nativeToolMode: "selectable". Le chiamate con restrizioni passano una tupla ctx.toolAvailability.native vuota insieme a una lista di autorizzazioni MCP esatta e isolata dall'host; resolveExecutionArgs deve applicarle entrambe all'argv finale di una nuova esecuzione o di una ripresa. OpenClaw interrompe l'operazione in modo sicuro se il backend non è in grado di farlo.

Per una guida completa alla creazione, consulta i Plugin per backend CLI.

Slot esclusivi

Adattatori di embedding della memoria deprecati

• registerMemoryCapability è l'API esclusiva preferita per i Plugin di memoria.
• registerMemoryCapability può anche esporre publicArtifacts.listArtifacts(...) affinché i Plugin complementari possano utilizzare gli artefatti di memoria esportati tramite openclaw/plugin-sdk/memory-host-core, invece di accedere alla struttura privata di uno specifico Plugin di memoria.
• registerMemoryPromptSection, registerMemoryFlushPlan e registerMemoryRuntime sono API esclusive per Plugin di memoria compatibili con le versioni precedenti.
• MemoryFlushPlan.model può vincolare il turno di scaricamento a un riferimento esatto provider/model, come ollama/qwen3:8b, senza ereditare la catena di fallback attiva.
• registerMemoryEmbeddingProvider è deprecato. I nuovi provider di embedding devono utilizzare api.registerEmbeddingProvider(...) e contracts.embeddingProviders.
• I provider esistenti specifici della memoria continuano a funzionare durante la finestra di migrazione, ma l'ispezione dei Plugin segnala questa condizione come debito di compatibilità per i Plugin non inclusi.

Eventi e ciclo di vita

Consulta Hook dei Plugin per esempi, nomi comuni degli hook e semantica delle condizioni di protezione.

Semantica decisionale degli hook

before_install è un hook del ciclo di vita del runtime del Plugin, non l'interfaccia dei criteri di installazione dell'operatore. Utilizza security.installPolicy quando una decisione di autorizzazione/blocco deve coprire i percorsi di installazione o aggiornamento tramite CLI e Gateway.

• before_tool_call: la restituzione di { block: true } è terminale. Quando un gestore la imposta, i gestori con priorità inferiore vengono ignorati.
• before_tool_call: la restituzione di { block: false } viene trattata come nessuna decisione (come se block fosse omesso), non come una sostituzione.
• before_install: la restituzione di { block: true } è terminale. Quando un gestore la imposta, i gestori con priorità inferiore vengono ignorati.
• before_install: la restituzione di { block: false } viene trattata come nessuna decisione (come se block fosse omesso), non come una sostituzione.
• reply_dispatch: la restituzione di { handled: true, ... } è terminale. Quando un gestore prende in carico l'invio, i gestori con priorità inferiore e il percorso predefinito di invio al modello vengono ignorati.
• message_sending: la restituzione di { cancel: true } è terminale. Quando un gestore la imposta, i gestori con priorità inferiore vengono ignorati.
• message_sending: la restituzione di { cancel: false } viene trattata come nessuna decisione (come se cancel fosse omesso), non come una sostituzione.
• message_received: usa il campo tipizzato threadId quando è necessario instradare thread o argomenti in ingresso. Mantieni metadata per i dati aggiuntivi specifici del canale.
• message_sending: usa i campi di instradamento tipizzati replyToId / threadId prima di ricorrere a metadata specifici del canale.
• gateway_start: usa ctx.config, ctx.workspaceDir e ctx.getCron?.() per lo stato di avvio gestito dal Gateway, invece di fare affidamento sugli hook interni gateway:startup. A questo punto Cron potrebbe essere ancora in fase di caricamento.
• cron_reconciled: ricostruisce una proiezione Cron esterna completa dopo l'avvio o il ricaricamento dello scheduler. Include reason e lo stato effettivo enabled, compreso enabled: false, mentre ctx.getCron?.() restituisce lo scheduler riconciliato esatto. Passa ctx.abortSignal alle operazioni di proiezione persistenti; l'operazione viene interrotta quando l'istantanea dello scheduler viene sostituita o il Gateway si chiude.
• cron_changed: osserva le modifiche al ciclo di vita di Cron gestito dal Gateway. Gli eventi scheduled e removed sono indicazioni di riconciliazione successive al commit, non un registro ordinato delle differenze. Il campo event.nextRunAtMs di un evento pianificato è assente quando l'attività non prevede una successiva riattivazione; un evento di rimozione contiene comunque l'istantanea dell'attività eliminata.

Gli scheduler di riattivazione esterni devono applicare il debounce o aggregare gli eventi cron_changed, quindi rileggere la vista persistente completa dallo scheduler acquisito più di recente da cron_reconciled. Non adottare lo scheduler dal contesto di cron_changed: un'indicazione separata proveniente da uno scheduler precedente può sovrapporsi a un ricaricamento successivo.

Usa cron_reconciled come attivatore dell'istantanea completa per lo stato persistente caricato all'avvio del Gateway o alla sostituzione dello scheduler. Non viene riprodotto durante un ricaricamento a caldo del solo Plugin. I gestori di osservazione vengono eseguiti in parallelo e gli invii asincroni senza attesa possono sovrapporsi, quindi i consumer non devono dipendere dall'ordine di completamento degli eventi. Mantieni OpenClaw come fonte autorevole per i controlli delle scadenze e l'esecuzione.

Per un adattatore a esecuzione singola con sostituzione persistente, nuovi tentativi/backoff e arresto ordinato, consulta Proiezione Cron esterna sicura.

Campi dell'oggetto API

Convenzione per i moduli interni

All'interno del Plugin, usa file barrel locali per le importazioni interne:

my-plugin/  api.ts            # Esportazioni pubbliche per consumer esterni  runtime-api.ts    # Esportazioni di runtime esclusivamente interne  index.ts          # Punto di ingresso del Plugin  setup-entry.ts    # Punto di ingresso leggero per la sola configurazione (facoltativo)

Le superfici pubbliche dei Plugin inclusi caricati tramite facade (api.ts, runtime-api.ts, index.ts, setup-entry.ts e file di ingresso pubblici simili) preferiscono l'istantanea della configurazione di runtime attiva quando OpenClaw è già in esecuzione. Se non esiste ancora alcuna istantanea di runtime, ricorrono al file di configurazione risolto sul disco. Le facade dei Plugin inclusi nel pacchetto devono essere caricate tramite i loader di facade dei Plugin di OpenClaw; le importazioni dirette da dist/extensions/... aggirano i controlli del manifest e del sidecar di runtime utilizzati dalle installazioni pacchettizzate per il codice di proprietà del Plugin.

I Plugin dei provider possono esporre un barrel di contratto locale e circoscritto al Plugin quando un helper è intenzionalmente specifico del provider e non appartiene ancora a un sottopercorso generico dell'SDK. Esempi inclusi:

• Anthropic: interfaccia pubblica api.ts / contract-api.ts per gli helper delle intestazioni beta di Claude e del flusso service_tier.
• @openclaw/openai-provider: api.ts esporta i costruttori dei provider, gli helper per il modello predefinito e i costruttori dei provider in tempo reale.
• @openclaw/openrouter-provider: api.ts esporta il costruttore del provider insieme agli helper di onboarding/configurazione.

Contenuti correlati