​

Panoramica dell’SDK dei plugin

​

Convenzione di importazione

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

​

Riferimento dei sottopercorsi

​

Entry del plugin

​

API di registrazione

​

Registrazione delle capability

​

Strumenti e comandi

​

Infrastruttura

​

Metadati di registrazione CLI

• commands: radici di comando esplicite possedute dal registrar
• descriptors: descrittori di comando a tempo di parsing usati per help della CLI root, instradamento e registrazione lazy della CLI del plugin

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Manage Matrix accounts, verification, devices, and profile state",
        hasSubcommands: true,
      },
    ],
  },
);

​

Registrazione del backend CLI

• L’id del backend diventa il prefisso provider nei riferimenti ai modelli come codex-cli/gpt-5.
• La config del backend usa la stessa struttura di agents.defaults.cliBackends.<id>.
• La configurazione utente continua ad avere la precedenza. OpenClaw unisce agents.defaults.cliBackends.<id> sopra la configurazione predefinita del plugin prima di eseguire la CLI.
• Usa normalizeConfig quando un backend necessita di riscritture di compatibilità dopo l’unione (ad esempio normalizzare vecchie forme di flag).

​

Slot esclusivi

​

Adattatori di embedding della memoria

• registerMemoryCapability è l’API preferita del plugin di memoria esclusivo.
• registerMemoryCapability può anche esporre publicArtifacts.listArtifacts(...) così i plugin companion possono usare gli artifact di memoria esportati tramite openclaw/plugin-sdk/memory-host-core invece di raggiungere il layout privato di uno specifico plugin di memoria.
• registerMemoryPromptSection, registerMemoryFlushPlan e registerMemoryRuntime sono API esclusive del plugin di memoria compatibili con i sistemi legacy.
• registerMemoryEmbeddingProvider consente al plugin di memoria attivo di registrare uno o più id di adattatore embedding (ad esempio openai, gemini o un id personalizzato definito dal plugin).
• La configurazione utente come agents.defaults.memorySearch.provider e agents.defaults.memorySearch.fallback viene risolta rispetto agli id di adattatore registrati.

​

Eventi e ciclo di vita

​

Semantica delle decisioni degli hook

• before_tool_call: restituire { block: true } è terminale. Non appena un handler lo imposta, gli handler a priorità più bassa vengono saltati.
• before_tool_call: restituire { block: false } viene trattato come nessuna decisione (come omettere block), non come un override.
• before_install: restituire { block: true } è terminale. Non appena un handler lo imposta, gli handler a priorità più bassa vengono saltati.
• before_install: restituire { block: false } viene trattato come nessuna decisione (come omettere block), non come un override.
• reply_dispatch: restituire { handled: true, ... } è terminale. Non appena un handler rivendica il dispatch, gli handler a priorità più bassa e il percorso di dispatch predefinito del modello vengono saltati.
• message_sending: restituire { cancel: true } è terminale. Non appena un handler lo imposta, gli handler a priorità più bassa vengono saltati.
• message_sending: restituire { cancel: false } viene trattato come nessuna decisione (come omettere cancel), non come un override.

​

Campi dell’oggetto API

​

Convenzione dei moduli interni

my-plugin/
  api.ts            # Esportazioni pubbliche per consumer esterni
  runtime-api.ts    # Esportazioni runtime solo interne
  index.ts          # Punto di ingresso del plugin
  setup-entry.ts    # Entry leggera solo setup (facoltativa)

• @openclaw/openai-provider: api.ts esporta builder del provider, helper per il modello predefinito e builder del provider realtime
• @openclaw/openrouter-provider: api.ts esporta il builder del provider più helper di onboarding/configurazione

​

Correlati

• Punti di ingresso — opzioni di definePluginEntry e defineChannelPluginEntry
• Helper di runtime — riferimento completo dello spazio dei nomi api.runtime
• Setup e configurazione — packaging, manifest, schemi di configurazione
• Test — utility di test e regole lint
• Migrazione SDK — migrazione dalle superfici deprecate
• Interni del plugin — architettura approfondita e modello delle capability