​

Descripción general del Plugin SDK

​

Convención de importación

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

​

Referencia de subrutas

​

Entrada de plugin

​

API de registro

​

Registro de capacidades

​

Herramientas y comandos

​

Infraestructura

​

Metadatos de registro de CLI

• commands: raíces de comandos explícitas propiedad del registrador
• descriptors: descriptores de comandos en tiempo de análisis usados para la ayuda del CLI raíz, el enrutamiento y el registro diferido del CLI del plugin

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Administrar cuentas, verificación, dispositivos y estado de perfil de Matrix",
        hasSubcommands: true,
      },
    ],
  },
);

​

Registro de backends de CLI

• El id del backend se convierte en el prefijo del proveedor en referencias de modelo como codex-cli/gpt-5.
• La config del backend usa la misma forma que agents.defaults.cliBackends.<id>.
• La configuración del usuario sigue teniendo prioridad. OpenClaw fusiona agents.defaults.cliBackends.<id> sobre el valor predeterminado del plugin antes de ejecutar la CLI.
• Use normalizeConfig cuando un backend necesite reescrituras de compatibilidad después de la fusión (por ejemplo, normalizar formas antiguas de flags).

​

Ranuras exclusivas

​

Adaptadores de embeddings de memoria

• registerMemoryCapability es la API exclusiva preferida para plugins de memoria.
• registerMemoryCapability también puede exponer publicArtifacts.listArtifacts(...) para que plugins complementarios consuman artefactos de memoria exportados a través de openclaw/plugin-sdk/memory-host-core en lugar de acceder al diseño privado de un plugin de memoria específico.
• registerMemoryPromptSection, registerMemoryFlushPlan y registerMemoryRuntime son API exclusivas de plugins de memoria compatibles con versiones heredadas.
• registerMemoryEmbeddingProvider permite que el plugin de memoria activo registre uno o más id de adaptadores de embeddings (por ejemplo openai, gemini o un id personalizado definido por el plugin).
• La configuración del usuario, como agents.defaults.memorySearch.provider y agents.defaults.memorySearch.fallback, se resuelve contra esos id de adaptadores registrados.

​

Eventos y ciclo de vida

​

Semántica de decisión de hooks

• before_tool_call: devolver { block: true } es terminal. Una vez que cualquier controlador lo establece, se omiten los controladores de menor prioridad.
• before_tool_call: devolver { block: false } se trata como ausencia de decisión (igual que omitir block), no como una anulación.
• before_install: devolver { block: true } es terminal. Una vez que cualquier controlador lo establece, se omiten los controladores de menor prioridad.
• before_install: devolver { block: false } se trata como ausencia de decisión (igual que omitir block), no como una anulación.
• reply_dispatch: devolver { handled: true, ... } es terminal. Una vez que cualquier controlador reclama el despacho, se omiten los controladores de menor prioridad y la ruta predeterminada de despacho del modelo.
• message_sending: devolver { cancel: true } es terminal. Una vez que cualquier controlador lo establece, se omiten los controladores de menor prioridad.
• message_sending: devolver { cancel: false } se trata como ausencia de decisión (igual que omitir cancel), no como una anulación.

​

Campos del objeto API

​

Convención de módulos internos

my-plugin/
  api.ts            # Exportaciones públicas para consumidores externos
  runtime-api.ts    # Exportaciones internas solo para tiempo de ejecución
  index.ts          # Punto de entrada del plugin
  setup-entry.ts    # Entrada ligera solo para configuración (opcional)

• @openclaw/openai-provider: api.ts exporta constructores de proveedores, auxiliares de modelos predeterminados y constructores de proveedores en tiempo real
• @openclaw/openrouter-provider: api.ts exporta el constructor del proveedor más auxiliares de onboarding/configuración

​

Relacionado

• Puntos de entrada — opciones de definePluginEntry y defineChannelPluginEntry
• Auxiliares de tiempo de ejecución — referencia completa del espacio de nombres api.runtime
• Configuración y config — empaquetado, manifiestos y esquemas de configuración
• Pruebas — utilidades de prueba y reglas de lint
• Migración del SDK — migración desde superficies obsoletas
• Internos de plugins — arquitectura profunda y modelo de capacidades