Panoramica dell’SDK per Plugin

​

Convenzione di importazione

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

​

Riferimento dei sottopercorsi

​

API di registrazione

​

Registrazione delle funzionalità

​

Strumenti e comandi

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

​

Infrastruttura

​

Hook dell’host per i Plugin di flusso di lavoro

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

• 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 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.

​

Registrazione del rilevamento 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() };
  },
});

​

Metadati di registrazione della CLI

• 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"]

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

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

​

Registrazione del backend 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.

​

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

​

Semantica decisionale degli hook

• 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.

​

Campi dell’oggetto API

​

Convenzione per i moduli interni

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)

• 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