Descripción general del SDK de plugins

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

Convención de importación

Importe siempre desde una subruta específica:

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

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

Referencia de subrutas

El SDK de plugins se expone como un conjunto de subrutas específicas agrupadas por área (entrada del plugin, canal, proveedor, autenticación, tiempo de ejecución, capacidad, memoria y auxiliares reservados para plugins incluidos). Para consultar el catálogo completo, agrupado y con enlaces, consulte Subrutas del SDK de plugins.

El inventario de puntos de entrada del compilador se encuentra en scripts/lib/plugin-sdk-entrypoints.json; las exportaciones de paquetes se generan a partir del subconjunto público después de restar las subrutas internas o de prueba locales del repositorio indicadas en scripts/lib/plugin-sdk-private-local-only-subpaths.json. Ejecute pnpm plugin-sdk:surface para auditar la cantidad de exportaciones públicas. Las subrutas públicas obsoletas que tienen suficiente antigüedad y no se usan en el código de producción de las extensiones incluidas se registran en scripts/lib/plugin-sdk-deprecated-public-subpaths.json; los módulos de exportación amplios y obsoletos de reexportación se registran en scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

API de registro

La función de retorno register(api) recibe un objeto OpenClawPluginApi con estos métodos:

Registro de capacidades

Los proveedores de trabajadores también deben declarar su identificador en contracts.workerProviders. El núcleo conserva la intención duradera antes de provision(profile, operationId). Los proveedores validan la configuración antes de la asignación externa y lanzan WorkerProviderError cuando un perfil se rechaza de forma permanente. provision debe adoptar el mismo arrendamiento cuando se repita el identificador de operación. El núcleo conserva con el arrendamiento la configuración validada del perfil y proporciona esa instantánea a destroy({ leaseId, profile }), que debe ser idempotente, y a inspect({ leaseId, profile }), que devuelve active, destroyed o unknown. Esto permite que los proveedores enruten las llamadas del ciclo de vida después de reiniciar el Gateway o eliminar un perfil con nombre. Los puntos de conexión SSH usan un SecretRef para keyRef, nunca material de clave insertado directamente, e incluyen un hostKey procedente de resultados de aprovisionamiento de confianza con el formato exacto algorithm base64, sin nombre de host ni comentario. El núcleo fija hostKey y nunca confía en una clave obtenida de la primera conexión. Un proveedor que genere un keyRef dinámico puede implementar resolveSshIdentity({ leaseId, profile, keyRef }); cuando está presente, ese resolvedor es la autoridad, mientras que los proveedores que no lo tengan usan el resolvedor genérico de secretos configurado. Los proveedores con arrendamientos renovables también pueden implementar renew(leaseId). inspect debe lanzar un error ante fallos transitorios o indeterminados; solo debe devolver unknown cuando la ausencia sea definitiva. El núcleo marca como huérfano un registro local activo o considera la ausencia como la finalización del desmontaje después de una solicitud de destrucción conservada.

Los proveedores de incrustaciones registrados con api.registerEmbeddingProvider(...) también deben figurar en contracts.embeddingProviders en el manifiesto del plugin. Esta es la superficie genérica de incrustaciones para la generación reutilizable de vectores. La búsqueda en memoria puede utilizar esta superficie genérica de proveedores. La interfaz anterior api.registerMemoryEmbeddingProvider(...) y contracts.memoryEmbeddingProviders es una compatibilidad obsoleta mientras migran los proveedores existentes específicos de memoria.

Los proveedores específicos de memoria que todavía exponen un batchEmbed(...) en tiempo de ejecución mantienen el contrato existente de procesamiento por lotes por archivo, a menos que su tiempo de ejecución establezca explícitamente sourceWideBatchEmbed: true. Esta habilitación permite que el host de memoria envíe fragmentos de varios archivos de memoria modificados y fuentes habilitadas en una sola llamada a batchEmbed(...), hasta los límites de lote del host. Los adaptadores de lotes que cargan archivos de solicitudes JSONL deben dividir los trabajos del proveedor antes de alcanzar tanto el límite de tamaño de carga como el límite de cantidad de solicitudes. El proveedor debe devolver una incrustación por cada fragmento de entrada en el mismo orden que batch.chunks; omita la opción cuando el proveedor espere lotes locales por archivo o no pueda conservar el orden de entrada en un trabajo más amplio que abarque toda la fuente.

Herramientas y comandos

Use defineToolPlugin para plugins sencillos que solo proporcionan herramientas con nombres de herramientas fijos. Use api.registerTool(...) directamente para plugins mixtos o para el registro completamente dinámico de herramientas.

Los comandos de los plugins pueden establecer agentPromptGuidance cuando el agente necesite una breve indicación de enrutamiento propiedad del comando. Mantenga ese texto centrado en el propio comando; no añada políticas específicas de proveedores o plugins a los constructores de prompts del núcleo.

Las entradas de orientación pueden ser cadenas heredadas, que se aplican a todas las superficies de prompts, o entradas estructuradas:

agentPromptGuidance: [  "Indicación global del comando.",  { text: "Mostrar esto solo en el prompt principal de OpenClaw.", surfaces: ["openclaw_main"] },];

Los valores estructurados de surfaces pueden incluir openclaw_main, codex_app_server, cli_backend, acp_backend o subagent. pi_main sigue siendo un alias obsoleto de openclaw_main. Omita surfaces para aplicar intencionadamente la orientación a todas las superficies. No pase un arreglo surfaces vacío; se rechaza para evitar que una pérdida accidental del ámbito convierta el texto en contenido global del prompt.

Las instrucciones para desarrolladores del servidor de aplicaciones nativo de Codex son más estrictas que las de otras superficies de prompts: solo la orientación cuyo ámbito incluya explícitamente codex_app_server se promueve a ese canal de mayor prioridad. La orientación mediante cadenas heredadas y la orientación estructurada sin ámbito siguen estando disponibles para superficies de prompts que no sean de Codex por motivos de compatibilidad.

Los comandos del host Node se ejecutan en el host Node conectado, no dentro del proceso del Gateway. Si agentTool está presente, el Node publica un descriptor después de conectarse correctamente al Gateway; el Gateway lo expone a las ejecuciones del agente solo mientras ese Node esté conectado y únicamente si el command del descriptor forma parte de la superficie de comandos aprobados del Node. Configure agentTool.defaultPlatforms para incluir un comando no peligroso en la lista de permitidos predeterminada de comandos del Node; de lo contrario, se requiere una configuración explícita de gateway.nodes.allowCommands o una política de invocación de Node. agentTool.name debe ser seguro para el proveedor: debe comenzar con una letra, usar únicamente letras, dígitos, guiones bajos o guiones, y no superar los 64 caracteres. Las herramientas del Node respaldadas por MCP pueden establecer metadatos agentTool.mcp para que las superficies de catálogo y búsqueda de herramientas puedan mostrar la identidad del servidor o la herramienta MCP remotos, pero la ejecución sigue realizándose mediante el comando del Node anunciado.

Infraestructura

Los constructores de suplementos del prompt de memoria reciben el contexto opcional agentId, agentSessionKey y sandboxed. Las llamadas search y get de suplementos del corpus de memoria reciben el contexto opcional agentId y sandboxed. Los Plugins con almacenamiento propiedad del agente deben resolver dicho almacenamiento en cada llamada, en lugar de capturar una única ruta global durante el registro. Si se requiere un identificador de agente pero falta en una operación multiagente, se debe denegar la operación de forma segura en lugar de elegir un agente arbitrario.

Los controladores interactivos de Telegram pueden devolver { submitText } para dirigir el texto por la ruta normal de entrada del agente de Telegram después de que el controlador finalice correctamente. OpenClaw conserva el botón de devolución de llamada cuando la política de entrada omite el texto o falla el procesamiento, para que el usuario pueda volver a intentarlo cuando cambie la condición de bloqueo. Este campo de resultado es específico de Telegram; los demás canales conservan sus propios contratos de resultados interactivos.

Hooks del host para Plugins de flujo de trabajo

Los hooks del host son los puntos de integración del SDK para los Plugins que necesitan participar en el ciclo de vida del host, en lugar de limitarse a añadir un proveedor, canal o herramienta. Son contratos genéricos; el modo de planificación puede utilizarlos, al igual que los flujos de aprobación, las puertas de políticas del espacio de trabajo, los monitores en segundo plano, los asistentes de configuración y los Plugins complementarios de la interfaz de usuario.

Un descriptor surface: "tab" añade una pestaña a la barra lateral de la interfaz de control. Los descriptores de pestañas de los Plugins activos se anuncian a los clientes del panel en el saludo del Gateway (controlUiTabs), por lo que la pestaña solo aparece mientras el Plugin está habilitado. Los Plugins incluidos pueden proporcionar una vista de panel de primera clase para su pestaña; otros Plugins pueden establecer path en una ruta HTTP del Plugin (consulte api.registerHttpRoute(...)) que el panel representa en un marco aislado. icon es una sugerencia de nombre de icono del panel, group selecciona la sección de la barra lateral (control o agent), order determina el orden entre las pestañas de los Plugins y requiredScopes oculta la pestaña en las conexiones que carecen de esos ámbitos de operador:

api.session.controls.registerControlUiDescriptor({  surface: "tab",  id: "logbook",  label: "Logbook",  description: "Your day as a timeline, built from screen snapshots.",  icon: "sun",  group: "control",  requiredScopes: ["operator.write"],});

Utilice los espacios de nombres agrupados para el código nuevo de Plugins:

• 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 los Plugins existentes. No añada código nuevo de Plugins 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 función práctica con ámbito de sesión basada en el programador Cron del Gateway. Cron controla la temporización y crea el registro de la tarea en segundo plano cuando se ejecuta el turno; el SDK del Plugin solo limita la sesión de destino, la nomenclatura propiedad del Plugin y la limpieza. Utilice api.runtime.tasks.managedFlows dentro del turno programado cuando el trabajo en sí necesite un estado persistente de flujo de tareas de varios pasos.

Los contratos separan la autoridad de forma intencionada:

• Los Plugins externos pueden controlar las extensiones de sesión, los descriptores de la interfaz de usuario, los comandos, los metadatos de las herramientas, las inyecciones del turno siguiente y los hooks normales.
• Las políticas de herramientas de confianza se ejecutan antes que los hooks before_tool_call normales y son de confianza para el host. Las políticas incluidas se ejecutan primero; las políticas de Plugins instalados requieren una habilitación explícita y sus identificadores locales en contracts.trustedToolPolicies, y se ejecutan a continuación según el orden de carga de los Plugins. Los identificadores de políticas están circunscritos al Plugin que los registra.
• La propiedad de los comandos reservados es exclusiva de los componentes incluidos. Los Plugins externos deben utilizar sus propios nombres de comandos o alias.
• allowPromptInjection=false deshabilita los hooks que modifican el prompt, incluidos agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, los campos de prompt del before_agent_start heredado y enqueueNextTurnInjection.

Ejemplos de consumidores ajenos al modo de planificación:

Registro de descubrimiento del Gateway

api.registerGatewayDiscoveryService(...) permite que un plugin anuncie el Gateway activo mediante un transporte de descubrimiento local, como mDNS/Bonjour. OpenClaw llama al servicio durante el inicio del Gateway cuando el descubrimiento local está habilitado, proporciona los puertos actuales del Gateway y los datos de indicación TXT no secretos, y llama al controlador stop devuelto durante el cierre 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 como autenticación. El descubrimiento es una indicación de enrutamiento; la autenticación del Gateway y la fijación de TLS siguen siendo responsables de la confianza.

Metadatos de registro de la 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 usados durante el análisis para la ayuda de la CLI, el enrutamiento y el registro diferido de la CLI del plugin
• parentPath: ruta opcional del comando principal para grupos de comandos anidados, como ["nodes"]

Para funciones de nodos emparejados, se prefiere api.registerNodeCliFeature(registrar, opts?). Es un pequeño contenedor de api.registerCli(..., { parentPath: ["nodes"] }) y explicita que comandos como openclaw nodes canvas son funciones de nodo propiedad del plugin.

Si quieres que un comando de plugin mantenga la carga diferida en la ruta raíz normal de la CLI, 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: "Administrar cuentas, verificación, dispositivos y estado del perfil de Matrix",        hasSubcommands: true,      },    ],  },);

Los comandos anidados reciben el comando principal resuelto como program:

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Capturar o renderizar contenido del lienzo desde un nodo emparejado",        hasSubcommands: true,      },    ],  },);

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

Registro de backends de la CLI

api.registerCliBackend(...) permite que un plugin controle la configuración predeterminada de un backend local de CLI de IA, como claude-cli o my-cli.

• El id del backend se convierte en el prefijo del proveedor en referencias de modelos como my-cli/gpt-5.
• La config del backend usa la misma estructura que agents.defaults.cliBackends.<id>.
• La configuración del usuario sigue teniendo prioridad. OpenClaw combina agents.defaults.cliBackends.<id> sobre la configuración predeterminada del plugin antes de ejecutar la CLI.
• Usa normalizeConfig cuando un backend necesite reescrituras de compatibilidad después de la combinación (por ejemplo, para normalizar formatos antiguos de indicadores).
• Usa resolveExecutionArgs para reescrituras de argv con ámbito de solicitud que pertenezcan al dialecto de la CLI, como asignar los niveles de razonamiento de OpenClaw a un indicador de esfuerzo nativo. El hook recibe ctx.executionMode; usa "side-question" para añadir indicadores de aislamiento nativos del backend en llamadas efímeras de /btw. Si esos indicadores deshabilitan de forma fiable las herramientas nativas para una CLI que, de otro modo, siempre las tendría activadas, declara también sideQuestionToolMode: "disabled".
• Los backends que puedan deshabilitar todas las herramientas nativas para una ejecución específica pueden declarar nativeToolMode: "selectable". Las llamadas restringidas pasan una tupla ctx.toolAvailability.native vacía junto con una lista exacta de permitidos de MCP aislada del host; resolveExecutionArgs debe aplicar ambas en el argv final de una ejecución nueva o reanudada. OpenClaw produce un fallo seguro si el backend no puede hacerlo.

Para consultar una guía de creación integral, consulta plugins de backend de la CLI.

Espacios exclusivos

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 a la estructura privada de un plugin de memoria específico.
• registerMemoryPromptSection, registerMemoryFlushPlan y registerMemoryRuntime son API exclusivas para plugins de memoria compatibles con sistemas heredados.
• MemoryFlushPlan.model puede fijar el turno de volcado a una referencia exacta de provider/model, como ollama/qwen3:8b, sin heredar la cadena de alternativas activa.
• registerMemoryEmbeddingProvider está obsoleto. Los nuevos proveedores de embeddings deben usar api.registerEmbeddingProvider(...) y contracts.embeddingProviders.
• Los proveedores existentes específicos de memoria siguen funcionando durante el período de migración, pero la inspección de plugins lo notifica como deuda de compatibilidad para los plugins no incluidos.

Eventos y ciclo de vida

Consulta Hooks de plugins para ver ejemplos, nombres habituales de hooks y la semántica de las protecciones.

Semántica de decisión de los hooks

before_install es un hook del ciclo de vida del entorno de ejecución del plugin, no la superficie de políticas de instalación del operador. Usa security.installPolicy cuando una decisión de permitir/bloquear deba abarcar las rutas de instalación o actualización de la CLI y las respaldadas por el Gateway.

• 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 considera que no hay decisión (igual que omitir block), no una sobrescritura.
• 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 considera que no hay decisión (igual que omitir block), no una sobrescritura.
• reply_dispatch: devolver { handled: true, ... } es terminal. Una vez que cualquier controlador asume el despacho, se omiten los controladores de menor prioridad y la ruta predeterminada de despacho al 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 considera que no hay decisión (igual que omitir cancel), no una sobrescritura.
• message_received: usa el campo tipado threadId cuando necesites enrutar hilos o temas entrantes. Reserva metadata para datos adicionales específicos del canal.
• message_sending: usa los campos de enrutamiento tipados replyToId / threadId antes de recurrir a metadata específica del canal.
• gateway_start: usa ctx.config, ctx.workspaceDir y ctx.getCron?.() para el estado de inicio que pertenece al Gateway, en lugar de depender de hooks internos gateway:startup. Cron podría seguir cargándose en este punto.
• cron_reconciled: reconstruye una proyección externa completa de Cron después del inicio o de una recarga del planificador. Incluye reason y el estado efectivo enabled, incluso enabled: false, mientras que ctx.getCron?.() devuelve el planificador reconciliado exacto. Pasa ctx.abortSignal al trabajo de proyección persistente; se cancela cuando esa instantánea del planificador se sustituye o se cierra el Gateway.
• cron_changed: observa los cambios del ciclo de vida de Cron que pertenece al Gateway. Los eventos scheduled y removed son indicios de reconciliación posteriores a la confirmación, no un registro ordenado de diferencias. El campo event.nextRunAtMs de un evento programado no está presente cuando la tarea no tiene una próxima activación; un evento eliminado sigue incluyendo la instantánea de la tarea eliminada.

Los planificadores de activación externos deben aplicar antirrebote o agrupar los eventos cron_changed y después volver a leer la vista persistente completa desde el último planificador capturado por cron_reconciled. No adoptes el planificador de un contexto cron_changed: un indicio desacoplado de un planificador anterior puede solaparse con una recarga posterior.

Usa cron_reconciled como desencadenante de instantánea completa para el estado persistente cargado al iniciar el Gateway o sustituir el planificador. No se reproduce durante una recarga en caliente exclusiva de un Plugin. Los controladores de observación se ejecutan en paralelo y los despachos sin espera pueden solaparse, por lo que los consumidores no deben depender del orden de finalización de los eventos. Mantén OpenClaw como fuente de verdad para las comprobaciones de vencimiento y la ejecución.

Para consultar un adaptador de ejecución única con sustitución persistente, reintentos/espera incremental y cierre ordenado, consulta Proyección externa segura de Cron.

Campos del objeto de la API

Convención de módulos internos

Dentro de tu Plugin, usa archivos de exportación agrupada locales para las importaciones internas:

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

Las superficies públicas de los Plugins incluidos cargados mediante fachada (api.ts, runtime-api.ts, index.ts, setup-entry.ts y archivos de entrada públicos similares) usan preferentemente la instantánea de configuración activa del entorno de ejecución cuando OpenClaw ya está en ejecución. Si todavía no existe una instantánea del entorno de ejecución, recurren al archivo de configuración resuelto en disco. Las fachadas empaquetadas de Plugins incluidos deben cargarse mediante los cargadores de fachadas de Plugins de OpenClaw; las importaciones directas desde dist/extensions/... omiten las comprobaciones del manifiesto y del archivo auxiliar del entorno de ejecución que las instalaciones empaquetadas usan para el código que pertenece al Plugin.

Los Plugins de proveedor pueden exponer un archivo restringido de contrato local del Plugin cuando una utilidad es deliberadamente específica del proveedor y todavía no corresponde a una subruta genérica del SDK. Ejemplos incluidos:

• Anthropic: interfaz pública api.ts / contract-api.ts para las utilidades de encabezados beta de Claude y del flujo service_tier.
• @openclaw/openai-provider: api.ts exporta constructores de proveedores, utilidades del modelo predeterminado y constructores de proveedores en tiempo real.
• @openclaw/openrouter-provider: api.ts exporta el constructor del proveedor, además de utilidades de incorporación/configuración.

Contenido relacionado