Descripción general del SDK de Plugin

El SDK de Plugin es el contrato tipado entre los plugins y el núcleo. Esta página es la referencia de qué importar y qué puedes registrar.

Convención de importación

Importa siempre desde una subruta específica:

Cada subruta es un módulo pequeño y autónomo. Esto mantiene el arranque rápido y evita problemas de dependencias circulares. Para helpers de entrada/compilación específicos de canal, prefiere openclaw/plugin-sdk/channel-core; reserva openclaw/plugin-sdk/core para la superficie general más amplia y helpers compartidos como buildChannelConfigSchema.

Para la configuración de canal, publica el JSON Schema propiedad del canal a través de openclaw.plugin.json#channelConfigs. La subruta plugin-sdk/channel-config-schema es para primitivas de esquema compartidas y el constructor genérico. Los plugins incluidos de OpenClaw usan plugin-sdk/bundled-channel-config-schema para conservar esquemas de canales incluidos. Las exportaciones de compatibilidad obsoletas permanecen en plugin-sdk/channel-config-schema-legacy; ninguna subruta de esquema incluido es un patrón para plugins nuevos.

Referencia de subrutas

El SDK de Plugin se expone como un conjunto de subrutas estrechas agrupadas por área (entrada de Plugin, canal, proveedor, autenticación, runtime, capacidad, memoria y helpers reservados de plugins incluidos). Para ver el catálogo completo, agrupado y enlazado, consulta Subrutas del SDK de Plugin.

El inventario de puntos de entrada del compilador vive en scripts/lib/plugin-sdk-entrypoints.json; las exportaciones del paquete se generan desde el subconjunto público después de restar las subrutas locales de pruebas/internas del repo listadas en scripts/lib/plugin-sdk-private-local-only-subpaths.json. Ejecuta pnpm plugin-sdk:surface para auditar el recuento de exportaciones públicas. Las subrutas públicas obsoletas que son lo bastante antiguas y no se usan en código de producción de extensiones incluidas se rastrean en scripts/lib/plugin-sdk-deprecated-public-subpaths.json; los barrels amplios de reexportación obsoleta se rastrean en scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

API de registro

El callback register(api) recibe un objeto OpenClawPluginApi con estos métodos:

Registro de capacidades

Los proveedores de embeddings registrados con api.registerEmbeddingProvider(...) también deben figurar en contracts.embeddingProviders en el manifiesto del Plugin. Esta es la superficie genérica de embeddings para la generación vectorial reutilizable. La búsqueda de memoria puede consumir esta superficie genérica de proveedor. El seam anterior api.registerMemoryEmbeddingProvider(...) y contracts.memoryEmbeddingProviders es compatibilidad obsoleta mientras migran los proveedores existentes específicos de memoria.

Los proveedores específicos de memoria que todavía exponen un runtime batchEmbed(...) permanecen en el contrato existente de procesamiento por lotes por archivo, salvo que su runtime establezca explícitamente sourceWideBatchEmbed: true. Esa opción permite que el host de memoria envíe fragmentos de varios archivos de memoria sucios y fuentes habilitadas en una sola llamada batchEmbed(...) hasta los límites de lote del host. Los adaptadores de lote que suben archivos de solicitud JSONL deben dividir los trabajos del proveedor antes de su límite de tamaño de subida, además de su límite de cantidad de solicitudes. El proveedor debe devolver un embedding por cada fragmento de entrada en el mismo orden que batch.chunks; omite la marca cuando el proveedor espera lotes locales al archivo o no puede preservar el orden de entrada en un trabajo más grande de toda la fuente.

Herramientas y comandos

Usa defineToolPlugin para plugins simples solo de herramientas con nombres de herramienta fijos. Usa api.registerTool(...) directamente para plugins mixtos o registro de herramientas totalmente dinámico.

Los comandos de Plugin pueden establecer agentPromptGuidance cuando el agente necesita una pista corta de enrutamiento propiedad del comando. Mantén ese texto sobre el comando en sí; no añadas política específica de proveedor o Plugin a los constructores de prompts del núcleo.

Las entradas de guía pueden ser cadenas heredadas, que se aplican a toda superficie de prompt, o entradas estructuradas:

agentPromptGuidance: [  "Global command hint.",  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },];

surfaces estructuradas pueden incluir openclaw_main, codex_app_server, cli_backend, acp_backend o subagent. pi_main sigue siendo un alias obsoleto de openclaw_main. Omite surfaces para guías intencionalmente aplicables a todas las superficies. No pases un array surfaces vacío; se rechaza para que una pérdida accidental de alcance no se convierta en texto de prompt global.

Las instrucciones de desarrollador nativas del app-server de Codex son más estrictas que otras superficies de prompt: solo la guía explícitamente acotada a codex_app_server se promueve al carril de mayor prioridad. La guía heredada como cadena y la guía estructurada sin alcance siguen disponibles para superficies de prompt que no son Codex por compatibilidad.

Infraestructura

Hooks de host para plugins de flujo de trabajo

Los hooks de host son los seams del SDK para plugins que necesitan participar en el ciclo de vida del host en vez de limitarse a añadir un proveedor, canal o herramienta. Son contratos genéricos; Plan Mode puede usarlos, pero también flujos de aprobación, controles de política de workspace, monitores en segundo plano, asistentes de configuración y plugins compañeros de UI.

Usa los espacios de nombres agrupados para el código de Plugin nuevo:

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

Los métodos planos equivalentes siguen disponibles como alias de compatibilidad obsoletos para plugins existentes. No agregues código de Plugin nuevo que llame directamente a api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn o api.unscheduleSessionTurnsByTag.

scheduleSessionTurn(...) es una comodidad con ámbito de sesión sobre el planificador Cron del Gateway. Cron posee la temporización y crea el registro de tarea en segundo plano cuando se ejecuta el turno; el SDK de Plugin solo limita la sesión de destino, los nombres propiedad del Plugin y la limpieza. Usa api.runtime.tasks.managedFlows dentro del turno programado cuando el trabajo en sí necesita estado duradero de Task Flow de varios pasos.

Los contratos dividen intencionalmente la autoridad:

• Los plugins externos pueden poseer extensiones de sesión, descriptores de IU, comandos, metadatos de herramientas, inyecciones del siguiente turno y hooks normales.
• Las políticas de herramientas de confianza se ejecutan antes de los hooks before_tool_call ordinarios y son de confianza para el host. Las políticas incluidas se ejecutan primero; las políticas de plugins instalados requieren habilitación explícita más sus ids locales en contracts.trustedToolPolicies, y se ejecutan después en el orden de carga de plugins. Los ids de política tienen el ámbito del Plugin que los registra.
• La propiedad de comandos reservados es solo para incluidos. Los plugins externos deben usar sus propios nombres de comandos o alias.
• allowPromptInjection=false deshabilita los hooks que mutan prompts, incluidos agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, los campos de prompt del before_agent_start heredado y enqueueNextTurnInjection.

Ejemplos de consumidores que no son de Plan:

Registro de descubrimiento del Gateway

api.registerGatewayDiscoveryService(...) permite a un Plugin anunciar el Gateway activo en un transporte de descubrimiento local como mDNS/Bonjour. OpenClaw llama al servicio durante el inicio del Gateway cuando el descubrimiento local está habilitado, pasa los puertos actuales del Gateway y datos de pista TXT no secretos, y llama al handler stop devuelto durante el apagado 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() };  },});

Los plugins de descubrimiento del Gateway no deben tratar los valores TXT anunciados como secretos ni autenticación. El descubrimiento es una pista de enrutamiento; la autenticación del Gateway y el pinning TLS siguen siendo responsables de la confianza.

Metadatos de registro de CLI

api.registerCli(registrar, opts?) acepta dos tipos de metadatos de comandos:

• commands: nombres de comandos explícitos propiedad del registrador
• descriptors: descriptores de comandos en tiempo de análisis usados para la ayuda de CLI, enrutamiento y registro diferido de la CLI del Plugin
• parentPath: ruta opcional de comando padre para grupos de comandos anidados, como ["nodes"]

Para funciones de nodos emparejados, prefiere api.registerNodeCliFeature(registrar, opts?). Es un pequeño wrapper alrededor de api.registerCli(..., { parentPath: ["nodes"] }) y hace que comandos como openclaw nodes canvas sean funciones de nodo explícitas propiedad del Plugin.

Si quieres que un comando de Plugin permanezca con carga diferida en la ruta normal de la CLI raíz, proporciona descriptors que cubran cada raíz de comando de nivel superior expuesta por ese registrador.

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

Los comandos anidados reciben el comando padre resuelto como program:

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

Usa commands por sí solo únicamente cuando no necesites registro diferido de la CLI raíz. Esa ruta de compatibilidad temprana sigue siendo compatible, pero no instala marcadores de posición respaldados por descriptores para la carga diferida en tiempo de análisis.

Registro de backend de CLI

api.registerCliBackend(...) permite a un Plugin poseer la configuración predeterminada para un backend de CLI de IA local como claude-cli o my-cli.

• El id del backend se convierte en el prefijo del proveedor en refs de modelo como my-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 combina agents.defaults.cliBackends.<id> sobre el valor predeterminado del Plugin antes de ejecutar la CLI.
• Usa normalizeConfig cuando un backend necesita reescrituras de compatibilidad después de la combinación (por ejemplo, normalizar formas antiguas de flags).
• Usa resolveExecutionArgs para reescrituras de argv con alcance de solicitud que pertenecen al dialecto de la CLI, como mapear los niveles de razonamiento de OpenClaw a un flag nativo de esfuerzo. El hook recibe ctx.executionMode; usa "side-question" para añadir flags de aislamiento nativos del backend para llamadas efímeras de /btw. Si esos flags deshabilitan de forma fiable las herramientas nativas para una CLI que de otro modo estaría siempre activa, declara también sideQuestionToolMode: "disabled".

Para una guía de autoría de extremo a extremo, consulta Plugins de backend de CLI.

Ranuras exclusivas

Adaptadores obsoletos de embeddings de memoria

• registerMemoryCapability es la API exclusiva preferida para Plugins de memoria.
• registerMemoryCapability también puede exponer publicArtifacts.listArtifacts(...) para que los Plugins complementarios puedan consumir artefactos de memoria exportados mediante 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 compatibles con sistemas heredados para Plugins de memoria.
• MemoryFlushPlan.model puede fijar el turno de vaciado a una referencia exacta de provider/model, como ollama/qwen3:8b, sin heredar la cadena de fallback activa.
• registerMemoryEmbeddingProvider está obsoleto. Los proveedores nuevos de embeddings deben usar api.registerEmbeddingProvider(...) y contracts.embeddingProviders.
• Los proveedores existentes específicos de memoria siguen funcionando durante la ventana de migración, pero la inspección de Plugins informa esto como deuda de compatibilidad para Plugins no empaquetados.

Eventos y ciclo de vida

Consulta hooks de Plugin para ver ejemplos, nombres comunes de hooks y semántica de guards.

Semántica de decisión de hooks

before_install es un hook de ciclo de vida del runtime de Plugins, no la superficie de política de instalación del operador. Usa security.installPolicy cuando una decisión de permitir/bloquear debe cubrir rutas de instalación o actualización respaldadas por CLI y Gateway.

• before_tool_call: devolver { block: true } es terminal. Una vez que cualquier handler lo establece, se omiten los handlers 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 handler lo establece, se omiten los handlers 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 handler reclama el despacho, se omiten los handlers de menor prioridad y la ruta predeterminada de despacho del modelo.
• message_sending: devolver { cancel: true } es terminal. Una vez que cualquier handler lo establece, se omiten los handlers de menor prioridad.
• message_sending: devolver { cancel: false } se trata como ausencia de decisión (igual que omitir cancel), no como una anulación.
• message_received: usa el campo tipado threadId cuando necesites enrutamiento entrante de hilo/tema. Mantén metadata para extras específicos del canal.
• message_sending: usa los campos tipados de enrutamiento replyToId / threadId antes de recurrir a metadata específico del canal.
• gateway_start: usa ctx.config, ctx.workspaceDir y ctx.getCron?.() para el estado de arranque propiedad del Gateway en lugar de depender de hooks internos gateway:startup.
• cron_changed: observa los cambios de ciclo de vida de Cron propiedad del Gateway. Usa event.job?.state?.nextRunAtMs y ctx.getCron?.() al sincronizar programadores de activación externos, y mantén OpenClaw como la fuente de verdad para las comprobaciones de vencimiento y la ejecución.

Campos del objeto API

Convención de módulos internos

Dentro de tu Plugin, usa archivos barrel locales para imports internos:

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)

Las superficies públicas de Plugins empaquetados cargadas por facade (api.ts, runtime-api.ts, index.ts, setup-entry.ts y archivos públicos de entrada similares) prefieren la instantánea de configuración activa del runtime cuando OpenClaw ya se está ejecutando. Si aún no existe una instantánea de runtime, recurren al archivo de configuración resuelto en disco. Las facades de Plugins empaquetados deben cargarse mediante los cargadores de facade de Plugins de OpenClaw; los imports directos desde dist/extensions/... omiten el manifiesto y las comprobaciones de sidecar de runtime que las instalaciones empaquetadas usan para código propiedad del Plugin.

Los Plugins de proveedor pueden exponer un barrel estrecho de contrato local al Plugin cuando un helper es intencionalmente específico del proveedor y todavía no pertenece a una subruta genérica del SDK. Ejemplos empaquetados:

• Anthropic: seam público api.ts / contract-api.ts para helpers de stream de beta-header de Claude y service_tier.
• @openclaw/openai-provider: api.ts exporta constructores de proveedor, helpers de modelo predeterminado y constructores de proveedor realtime.
• @openclaw/openrouter-provider: api.ts exporta el constructor de proveedor más helpers de onboarding/configuración.

Relacionado