​

Vue d’ensemble du SDK Plugin

​

Convention d’import

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

​

Référence des sous-chemins

​

Entrée de plugin

​

API d’enregistrement

​

Enregistrement des capacités

​

Outils et commandes

​

Infrastructure

​

Métadonnées d’enregistrement CLI

• commands : racines de commandes explicites appartenant à l’enregistreur
• descriptors : descripteurs de commandes au moment de l’analyse, utilisés pour l’aide CLI racine, le routage et l’enregistrement CLI paresseux du 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,
      },
    ],
  },
);

​

Enregistrement de backend CLI

• L’id du backend devient le préfixe de fournisseur dans les références de modèle comme codex-cli/gpt-5.
• La config du backend utilise la même forme que agents.defaults.cliBackends.<id>.
• La configuration utilisateur reste prioritaire. OpenClaw fusionne agents.defaults.cliBackends.<id> par-dessus la valeur par défaut du plugin avant d’exécuter la CLI.
• Utilisez normalizeConfig lorsqu’un backend a besoin de réécritures de compatibilité après fusion (par exemple pour normaliser d’anciennes formes de drapeaux).

​

Emplacements exclusifs

​

Adaptateurs d’embeddings Memory

• registerMemoryCapability est l’API de plugin Memory exclusive préférée.
• registerMemoryCapability peut aussi exposer publicArtifacts.listArtifacts(...) afin que des plugins compagnons puissent consommer des artefacts Memory exportés via openclaw/plugin-sdk/memory-host-core au lieu d’atteindre la disposition privée d’un plugin Memory spécifique.
• registerMemoryPromptSection, registerMemoryFlushPlan, et registerMemoryRuntime sont des API exclusives compatibles avec l’ancien système pour les plugins Memory.
• registerMemoryEmbeddingProvider permet au plugin Memory actif d’enregistrer un ou plusieurs identifiants d’adaptateur d’embeddings (par exemple openai, gemini, ou un identifiant personnalisé défini par un plugin).
• La configuration utilisateur telle que agents.defaults.memorySearch.provider et agents.defaults.memorySearch.fallback se résout par rapport à ces identifiants d’adaptateur enregistrés.

​

Événements et cycle de vie

​

Sémantique de décision des hooks

• before_tool_call : renvoyer { block: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• before_tool_call : renvoyer { block: false } est traité comme aucune décision (identique à l’omission de block), et non comme un remplacement.
• before_install : renvoyer { block: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• before_install : renvoyer { block: false } est traité comme aucune décision (identique à l’omission de block), et non comme un remplacement.
• reply_dispatch : renvoyer { handled: true, ... } est terminal. Dès qu’un gestionnaire revendique la répartition, les gestionnaires de priorité inférieure et le chemin de répartition par défaut du modèle sont ignorés.
• message_sending : renvoyer { cancel: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• message_sending : renvoyer { cancel: false } est traité comme aucune décision (identique à l’omission de cancel), et non comme un remplacement.

​

Champs de l’objet API

​

Convention des modules internes

my-plugin/
  api.ts            # Exports publics pour les consommateurs externes
  runtime-api.ts    # Exports d’exécution internes uniquement
  index.ts          # Point d’entrée du plugin
  setup-entry.ts    # Point d’entrée léger de configuration initiale uniquement (facultatif)

• @openclaw/openai-provider : api.ts exporte des constructeurs de fournisseur, des helpers de modèle par défaut, et des constructeurs de fournisseur temps réel
• @openclaw/openrouter-provider : api.ts exporte le constructeur de fournisseur ainsi que des helpers d’onboarding/configuration

​

Liens associés

• Points d’entrée — options de definePluginEntry et defineChannelPluginEntry
• Helpers d’exécution — référence complète de l’espace de noms api.runtime
• Configuration initiale et configuration — packaging, manifestes, schémas de configuration
• Testing — utilitaires de test et règles de lint
• Migration du SDK — migration depuis des surfaces obsolètes
• Internes des plugins — architecture détaillée et modèle de capacité