Vue d’ensemble du SDK Plugin

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Convention d’importation

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

​

Référence des sous-chemins

​

API d’enregistrement

​

Enregistrement des capacités

​

Outils et commandes

​

Infrastructure

​

Hooks hôte pour les Plugins de workflow

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

• Les plugins externes peuvent posséder les extensions de session, les descripteurs d’UI, les commandes, les métadonnées d’outils, les injections au tour suivant et les hooks normaux.
• Les politiques d’outils approuvées s’exécutent avant les hooks before_tool_call ordinaires et sont réservées aux éléments groupés, car elles participent à la politique de sécurité de l’hôte.
• La propriété des commandes réservées est réservée aux éléments groupés. Les plugins externes doivent utiliser leurs propres noms de commandes ou alias.
• allowPromptInjection=false désactive les hooks qui modifient le prompt, notamment agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, les champs de prompt de l’ancien before_agent_start, et enqueueNextTurnInjection.

​

Enregistrement de découverte 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() };
  },
});

​

Métadonnées d’enregistrement CLI

• commands : noms de commandes explicites appartenant au registrar
• descriptors : descripteurs de commande au moment de l’analyse utilisés pour l’aide CLI, le routage et l’enregistrement CLI paresseux des plugins
• parentPath : chemin de commande parent facultatif pour les groupes de commandes imbriqués, comme ["nodes"]

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

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Capture or render canvas content from a paired node",
        hasSubcommands: true,
      },
    ],
  },
);

​

Enregistrement du backend CLI

• Le id du backend devient le préfixe du 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 prévaut toujours. OpenClaw fusionne agents.defaults.cliBackends.<id> par-dessus la valeur par défaut du plugin avant d’exécuter le CLI.
• Utilisez normalizeConfig lorsqu’un backend a besoin de réécritures de compatibilité après la fusion (par exemple pour normaliser d’anciennes formes de flags).
• Utilisez resolveExecutionArgs pour les réécritures d’argv limitées à la requête qui appartiennent au dialecte CLI, comme le mappage des niveaux de réflexion OpenClaw vers un flag d’effort natif.

​

Emplacements exclusifs

​

Adaptateurs d’embedding de mémoire

• registerMemoryCapability est l’API exclusive de plugin de mémoire préférée.
• registerMemoryCapability peut aussi exposer publicArtifacts.listArtifacts(...) afin que les plugins compagnons puissent consommer les artefacts de mémoire exportés via openclaw/plugin-sdk/memory-host-core au lieu d’accéder à la disposition privée d’un plugin de mémoire spécifique.
• registerMemoryPromptSection, registerMemoryFlushPlan et registerMemoryRuntime sont des API exclusives de plugin de mémoire compatibles avec l’ancien comportement.
• MemoryFlushPlan.model peut épingler le tour de vidage à une référence provider/model exacte, comme ollama/qwen3:8b, sans hériter de la chaîne de repli active.
• registerMemoryEmbeddingProvider permet au plugin de mémoire actif d’enregistrer un ou plusieurs ids d’adaptateur d’embedding (par exemple openai, gemini ou un id personnalisé défini par un plugin).
• La configuration utilisateur comme agents.defaults.memorySearch.provider et agents.defaults.memorySearch.fallback se résout par rapport à ces ids d’adaptateur enregistrés.

​

Événements et cycle de vie

​

Sémantique de décision des hooks

• before_tool_call : retourner { block: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• before_tool_call : retourner { block: false } est traité comme une absence de décision (identique à l’omission de block), pas comme une surcharge.
• before_install : retourner { block: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• before_install : retourner { block: false } est traité comme une absence de décision (identique à l’omission de block), pas comme une surcharge.
• reply_dispatch : retourner { handled: true, ... } est terminal. Dès qu’un gestionnaire revendique l’envoi, les gestionnaires de priorité inférieure et le chemin d’envoi au modèle par défaut sont ignorés.
• message_sending : retourner { cancel: true } est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
• message_sending : retourner { cancel: false } est traité comme une absence de décision (identique à l’omission de cancel), pas comme une surcharge.
• message_received : utilisez le champ typé threadId lorsque vous avez besoin du routage de thread/sujet entrant. Gardez metadata pour les compléments propres au canal.
• message_sending : utilisez les champs de routage typés replyToId / threadId avant de revenir à metadata propre au canal.
• gateway_start : utilisez ctx.config, ctx.workspaceDir et ctx.getCron?.() pour l’état de démarrage appartenant au gateway au lieu de vous appuyer sur les hooks internes gateway:startup.
• cron_changed : observez les changements de cycle de vie de cron appartenant au gateway. Utilisez event.job?.state?.nextRunAtMs et ctx.getCron?.() lors de la synchronisation de planificateurs de réveil externes, et gardez OpenClaw comme source de vérité pour les vérifications d’échéance et l’exécution.

​

Champs de l’objet API

​

Convention de module interne

my-plugin/
  api.ts            # Public exports for external consumers
  runtime-api.ts    # Internal-only runtime exports
  index.ts          # Plugin entry point
  setup-entry.ts    # Lightweight setup-only entry (optional)

• Anthropic : jointure publique api.ts / contract-api.ts pour Claude beta-header et les assistants de flux service_tier.
• @openclaw/openai-provider : api.ts exporte les constructeurs de fournisseur, les assistants de modèle par défaut et les constructeurs de fournisseur en temps réel.
• @openclaw/openrouter-provider : api.ts exporte le constructeur de fournisseur ainsi que les assistants d’intégration/configuration.

​

Connexe