---
read_when:
- Necesitas saber desde qué subruta del SDK importar
- Quieres una referencia de todos los métodos de registro en OpenClawPluginApi
- Está buscando una exportación específica del SDK
sidebarTitle: Plugin SDK overview
summary: Mapa de importación, referencia de la API de registro y arquitectura del SDK
title: Descripción general del SDK de Plugin
x-i18n:
generated_at: "2026-07-01T18:07:26Z"
model: gpt-5.5
postprocess_version: locale-links-v1
provider: openai
source_hash: c7df77e34db9b780ee0747a0f2178861624f528d9f7aec8592d6954a96869e96
source_path: plugins/sdk-overview.md
workflow: 16
---
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**.
Esta página es para autores de plugins que usan `openclaw/plugin-sdk/*` dentro de
OpenClaw. Para apps externas, scripts, paneles, trabajos de CI y extensiones de IDE
que quieren ejecutar agentes a través del Gateway, usa
[Integraciones de Gateway para apps externas](/es/gateway/external-apps) en su lugar.
¿Buscas una guía práctica? Empieza con [Crear plugins](/es/plugins/building-plugins), usa [Plugins de canal](/es/plugins/sdk-channel-plugins) para plugins de canal, [Plugins de proveedor](/es/plugins/sdk-provider-plugins) para plugins de proveedor, [Plugins de backend de CLI](/es/plugins/cli-backend-plugins) para backends de CLI de IA locales y [Hooks de Plugin](/es/plugins/hooks) para plugins de herramientas o hooks de ciclo de vida.
## Convención de importación
Importa siempre desde una subruta específica:
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
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.
No importes seams de conveniencia con marca de proveedor o canal (por ejemplo,
`openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`).
Los plugins incluidos componen subrutas genéricas del SDK dentro de sus propios barrels
`api.ts` / `runtime-api.ts`; los consumidores del núcleo deben usar esos barrels locales
del Plugin o añadir un contrato genérico estrecho del SDK cuando una necesidad sea realmente
transversal a canales.
Un pequeño conjunto de seams helper de plugins incluidos todavía aparece en el mapa de exportación
generado cuando tienen uso de propietarios rastreado. Existen solo para el mantenimiento de
plugins incluidos y no se recomiendan como rutas de importación para nuevos plugins de terceros.
`openclaw/plugin-sdk/discord` y `openclaw/plugin-sdk/telegram-account` también se
mantienen como fachadas de compatibilidad obsoletas para uso de propietarios rastreado. No
copies esas rutas de importación en plugins nuevos; usa helpers de runtime inyectados y
subrutas genéricas del SDK de canal en su lugar.
## 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](/es/plugins/sdk-subpaths).
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
| Método | Qué registra |
| ------------------------------------------------ | ------------------------------------- |
| `api.registerProvider(...)` | Inferencia de texto (LLM) |
| `api.registerAgentHarness(...)` | Ejecutor de agentes experimental de bajo nivel |
| `api.registerCliBackend(...)` | Backend local de inferencia de CLI |
| `api.registerChannel(...)` | Canal de mensajería |
| `api.registerEmbeddingProvider(...)` | Proveedor reutilizable de embeddings vectoriales |
| `api.registerSpeechProvider(...)` | Síntesis de texto a voz / STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Transcripción en tiempo real por streaming |
| `api.registerRealtimeVoiceProvider(...)` | Sesiones de voz en tiempo real dúplex |
| `api.registerMediaUnderstandingProvider(...)` | Análisis de imagen/audio/video |
| `api.registerImageGenerationProvider(...)` | Generación de imágenes |
| `api.registerMusicGenerationProvider(...)` | Generación de música |
| `api.registerVideoGenerationProvider(...)` | Generación de video |
| `api.registerWebFetchProvider(...)` | Proveedor de fetch / scraping web |
| `api.registerWebSearchProvider(...)` | Búsqueda web |
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`](/es/plugins/tool-plugins) 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.
| Método | Qué registra |
| ------------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | Herramienta de agente (obligatoria o `{ optional: true }`) |
| `api.registerCommand(def)` | Comando personalizado (omite el LLM) |
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:
```ts
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
| Método | Qué registra |
| ---------------------------------------------- | ------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Hook de evento |
| `api.registerHttpRoute(params)` | Endpoint HTTP de Gateway |
| `api.registerGatewayMethod(name, handler)` | Método RPC de Gateway |
| `api.registerGatewayDiscoveryService(service)` | Anunciante de descubrimiento de Gateway local |
| `api.registerCli(registrar, opts?)` | Subcomando de CLI |
| `api.registerNodeCliFeature(registrar, opts?)` | CLI de funcionalidad de Node bajo `openclaw nodes` |
| `api.registerService(service)` | Servicio en segundo plano |
| `api.registerInteractiveHandler(registration)` | Handler interactivo |
| `api.registerAgentToolResultMiddleware(...)` | Middleware de resultados de herramientas en runtime |
| `api.registerMemoryPromptSupplement(builder)` | Sección aditiva de prompt adyacente a memoria |
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus aditivo de búsqueda/lectura de memoria |
### 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.
| Método | Contrato que posee |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.session.state.registerSessionExtension(...)` | Estado de sesión propiedad del Plugin, compatible con JSON, proyectado a través de sesiones del Gateway |
| `api.session.workflow.enqueueNextTurnInjection(...)` | Contexto duradero de exactamente una vez inyectado en el siguiente turno del agente para una sesión |
| `api.registerTrustedToolPolicy(...)` | Política de herramientas de confianza previa al Plugin, protegida por manifiesto, que puede bloquear o reescribir parámetros de herramientas |
| `api.registerToolMetadata(...)` | Metadatos de visualización del catálogo de herramientas sin cambiar la implementación de la herramienta |
| `api.registerCommand(...)` | Comandos de Plugin con ámbito; los resultados de comandos pueden establecer `continueAgent: true` o `suppressReply: true`; los comandos nativos de Discord admiten `descriptionLocalizations` |
| `api.session.controls.registerControlUiDescriptor(...)` | Descriptores de contribución de la IU de control para superficies de sesión, herramienta, ejecución o configuración |
| `api.lifecycle.registerRuntimeLifecycle(...)` | Callbacks de limpieza para recursos de runtime propiedad del Plugin en rutas de restablecimiento, eliminación o recarga |
| `api.agent.events.registerAgentEventSubscription(...)` | Suscripciones a eventos saneadas para estado de workflow y monitores |
| `api.runContext.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Estado temporal de Plugin por ejecución borrado en el ciclo de vida terminal de la ejecución |
| `api.session.workflow.registerSessionSchedulerJob(...)` | Metadatos de limpieza para trabajos del planificador propiedad del Plugin; no planifica trabajo ni crea registros de tareas |
| `api.session.workflow.sendSessionAttachment(...)` | Entrega de adjuntos de archivo mediada por el host, solo para incluidos, a la ruta activa de sesión directa saliente |
| `api.session.workflow.scheduleSessionTurn(...)` / `unscheduleSessionTurnsByTag(...)` | Turnos de sesión programados respaldados por Cron, solo para incluidos, más limpieza basada en etiquetas |
| `api.session.controls.registerSessionAction(...)` | Acciones de sesión tipadas que los clientes pueden despachar a través del Gateway |
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:
| Arquetipo de Plugin | Hooks usados |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Workflow de aprobación | Extensión de sesión, continuación de comando, inyección del siguiente turno, descriptor de IU |
| Puerta de política de presupuesto/espacio de trabajo | Política de herramientas de confianza, metadatos de herramientas, proyección de sesión |
| Monitor de ciclo de vida en segundo plano | Limpieza de ciclo de vida de runtime, suscripción a eventos de agente, propiedad/limpieza del planificador de sesión, contribución al prompt Heartbeat, descriptor de IU |
| Asistente de configuración u onboarding | Extensión de sesión, comandos con ámbito, descriptor de IU de control |
Los espacios de nombres reservados de administración del núcleo (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) siempre permanecen como `operator.admin`, incluso si un Plugin intenta asignar un
ámbito de método de Gateway más estrecho. Prefiere prefijos específicos del Plugin para
métodos propiedad del Plugin.
Los plugins incluidos y los plugins instalados habilitados explícitamente con contratos de
manifiesto coincidentes pueden usar `api.registerAgentToolResultMiddleware(...)` cuando
necesitan reescribir un resultado de herramienta después de la ejecución y antes de que el runtime
devuelva ese resultado al modelo. Esta es la unión de confianza neutral al runtime
para reductores de salida asíncronos como tokenjuice.
Los plugins deben declarar `contracts.agentToolResultMiddleware` para cada runtime
objetivo, por ejemplo `["openclaw", "codex"]`. Los plugins instalados sin ese
contrato, o sin habilitación explícita, no pueden registrar este middleware; conserva
los hooks normales de Plugin de OpenClaw para el trabajo que no necesita temporización
de resultado de herramienta previa al modelo. La antigua ruta de registro de fábrica
de extensiones solo para el ejecutor embebido se eliminó.
### 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.
```typescript
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.
```typescript
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`:
```typescript
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.`.
- La configuración del usuario sigue teniendo prioridad. OpenClaw combina `agents.defaults.cliBackends.` 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](/es/plugins/cli-backend-plugins).
### Ranuras exclusivas
| Método | Qué registra |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `api.registerContextEngine(id, factory)` | Motor de contexto (uno activo a la vez). Las callbacks de ciclo de vida reciben `runtimeSettings` cuando el host puede proporcionar diagnósticos de modelo/proveedor/modo; los motores estrictos antiguos se reintentan sin esa clave. |
| `api.registerMemoryCapability(capability)` | Capacidad de memoria unificada |
| `api.registerMemoryPromptSection(builder)` | Constructor de sección de prompt de memoria |
| `api.registerMemoryFlushPlan(resolver)` | Resolvedor de plan de vaciado de memoria |
| `api.registerMemoryRuntime(runtime)` | Adaptador de runtime de memoria |
### Adaptadores obsoletos de embeddings de memoria
| Método | Qué registra |
| ---------------------------------------------- | ----------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptador de embeddings de memoria para el Plugin activo |
- `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
| Método | Qué hace |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | Hook de ciclo de vida tipado |
| `api.onConversationBindingResolved(handler)` | Callback de enlace de conversación |
Consulta [hooks de Plugin](/es/plugins/hooks) 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
| Campo | Tipo | Descripción |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | ID del Plugin |
| `api.name` | `string` | Nombre para mostrar |
| `api.version` | `string?` | Versión del Plugin (opcional) |
| `api.description` | `string?` | Descripción del Plugin (opcional) |
| `api.source` | `string` | Ruta de origen del Plugin |
| `api.rootDir` | `string?` | Directorio raíz del Plugin (opcional) |
| `api.config` | `OpenClawConfig` | Instantánea de configuración actual (instantánea activa del runtime en memoria cuando esté disponible) |
| `api.pluginConfig` | `Record` | Configuración específica del Plugin desde `plugins.entries..config` |
| `api.runtime` | `PluginRuntime` | [Helpers de runtime](/es/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger con alcance (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Modo de carga actual; `"setup-runtime"` es la ventana ligera de arranque/configuración previa a la entrada completa |
| `api.resolvePath(input)` | `(string) => string` | Resuelve una ruta relativa a la raíz del Plugin |
## 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)
```
Nunca importes tu propio Plugin mediante `openclaw/plugin-sdk/`
desde código de producción. Enruta los imports internos mediante `./api.ts` o
`./runtime-api.ts`. La ruta del SDK es solo el contrato externo.
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.
El código de producción de extensiones también debe evitar imports de `openclaw/plugin-sdk/`.
Si un helper es realmente compartido, promuévelo a una subruta neutral del SDK
como `openclaw/plugin-sdk/speech`, `.../provider-model-shared` u otra
superficie orientada a capacidades en lugar de acoplar dos Plugins entre sí.
## Relacionado
Opciones de `definePluginEntry` y `defineChannelPluginEntry`.
Referencia completa del espacio de nombres `api.runtime`.
Empaquetado, manifiestos y esquemas de configuración.
Utilidades de prueba y reglas de lint.
Migración desde superficies obsoletas.
Arquitectura profunda y modelo de capacidades.