Creación de plugins

Los plugins amplían OpenClaw con nuevas capacidades: canales, proveedores de modelos, voz, transcripción en tiempo real, voz en tiempo real, comprensión de medios, generación de imágenes, generación de video, obtención web, búsqueda web, herramientas de agente o cualquier combinación. No necesitas agregar tu plugin al repositorio de OpenClaw. Publícalo en ClawHub o npm y los usuarios lo instalan con openclaw plugins install <package-name>. OpenClaw intenta primero con ClawHub y recurre automáticamente a npm si es necesario.

Requisitos previos

Node >= 22 y un administrador de paquetes (npm o pnpm)
Familiaridad con TypeScript (ESM)
Para plugins dentro del repositorio: repositorio clonado y pnpm install ejecutado

¿Qué tipo de plugin?

Plugin de canal

Conecta OpenClaw a una plataforma de mensajería (Discord, IRC, etc.)

Plugin de proveedor

Agrega un proveedor de modelos (LLM, proxy o endpoint personalizado)

Plugin de herramienta / hook

Registra herramientas de agente, hooks de eventos o servicios — continúa abajo

Si un plugin de canal es opcional y puede no estar instalado cuando se ejecuta la incorporación/configuración, usa createOptionalChannelSetupSurface(...) de openclaw/plugin-sdk/channel-setup. Produce un par adaptador + asistente de configuración que anuncia el requisito de instalación y falla de forma segura en escrituras reales de configuración hasta que el plugin esté instalado.

Inicio rápido: plugin de herramienta

Este recorrido crea un plugin mínimo que registra una herramienta de agente. Los plugins de canal y proveedor tienen guías dedicadas enlazadas arriba.

Crea el paquete y el manifiesto

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  }
}

Todo plugin necesita un manifiesto, incluso sin configuración. Consulta Manifest para ver el esquema completo. Los fragmentos canónicos de publicación en ClawHub se encuentran en docs/snippets/plugin-publish/.

Escribe el punto de entrada

// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds a custom tool to OpenClaw",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "Do a thing",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: `Got: ${params.input}` }] };
      },
    });
  },
});

definePluginEntry es para plugins que no son de canal. Para canales, usa defineChannelPluginEntry — consulta Plugins de canal. Para ver todas las opciones del punto de entrada, consulta Puntos de entrada.

Prueba y publica

Plugins externos: valida y publica con ClawHub, luego instala:

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin

OpenClaw también comprueba ClawHub antes que npm para especificaciones de paquete simples como @myorg/openclaw-my-plugin.Plugins dentro del repositorio: colócalos bajo el árbol del espacio de trabajo de plugins incluidos — se descubren automáticamente.

pnpm test -- <bundled-plugin-root>/my-plugin/

Capacidades del plugin

Un único plugin puede registrar cualquier cantidad de capacidades mediante el objeto api:

Capacidad	Método de registro	Guía detallada
Inferencia de texto (LLM)	`api.registerProvider(...)`	Plugins de proveedor
Backend de inferencia de CLI	`api.registerCliBackend(...)`	Backends de CLI
Canal / mensajería	`api.registerChannel(...)`	Plugins de canal
Voz (TTS/STT)	`api.registerSpeechProvider(...)`	Plugins de proveedor
Transcripción en tiempo real	`api.registerRealtimeTranscriptionProvider(...)`	Plugins de proveedor
Voz en tiempo real	`api.registerRealtimeVoiceProvider(...)`	Plugins de proveedor
Comprensión de medios	`api.registerMediaUnderstandingProvider(...)`	Plugins de proveedor
Generación de imágenes	`api.registerImageGenerationProvider(...)`	Plugins de proveedor
Generación de música	`api.registerMusicGenerationProvider(...)`	Plugins de proveedor
Generación de video	`api.registerVideoGenerationProvider(...)`	Plugins de proveedor
Obtención web	`api.registerWebFetchProvider(...)`	Plugins de proveedor
Búsqueda web	`api.registerWebSearchProvider(...)`	Plugins de proveedor
Herramientas de agente	`api.registerTool(...)`	Más abajo
Comandos personalizados	`api.registerCommand(...)`	Puntos de entrada
Hooks de eventos	`api.registerHook(...)`	Puntos de entrada
Rutas HTTP	`api.registerHttpRoute(...)`	Internals
Subcomandos de CLI	`api.registerCli(...)`	Puntos de entrada

Para la API de registro completa, consulta Resumen del SDK. Si tu plugin registra métodos RPC personalizados del gateway, mantenlos en un prefijo específico del plugin. Los espacios de nombres administrativos del núcleo (config.*, exec.approvals.*, wizard.*, update.*) permanecen reservados y siempre se resuelven a operator.admin, incluso si un plugin solicita un alcance más limitado. Semántica de guardas de hooks a tener en cuenta:

before_tool_call: { block: true } es terminal y detiene los controladores de menor prioridad.
before_tool_call: { block: false } se trata como sin decisión.
before_tool_call: { requireApproval: true } pausa la ejecución del agente y solicita aprobación del usuario mediante la superposición de aprobación de ejecución, botones de Telegram, interacciones de Discord o el comando /approve en cualquier canal.
before_install: { block: true } es terminal y detiene los controladores de menor prioridad.
before_install: { block: false } se trata como sin decisión.
message_sending: { cancel: true } es terminal y detiene los controladores de menor prioridad.
message_sending: { cancel: false } se trata como sin decisión.

El comando /approve gestiona tanto aprobaciones de ejecución como de plugins con un respaldo acotado: cuando no se encuentra un id de aprobación de ejecución, OpenClaw vuelve a intentar el mismo id mediante las aprobaciones del plugin. El reenvío de aprobaciones del plugin puede configurarse de forma independiente mediante approvals.plugin en la configuración. Si una lógica personalizada de aprobación necesita detectar ese mismo caso de respaldo acotado, prefiere isApprovalNotFoundError de openclaw/plugin-sdk/error-runtime en lugar de comparar manualmente cadenas de vencimiento de aprobación. Consulta semántica de decisiones de hooks del Resumen del SDK para obtener detalles.

Registro de herramientas de agente

Las herramientas son funciones tipadas que el LLM puede invocar. Pueden ser obligatorias (siempre disponibles) u opcionales (activación del usuario):

register(api) {
  // Herramienta obligatoria — siempre disponible
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // Herramienta opcional — el usuario debe agregarla a la lista de permitidos
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a workflow",
      parameters: Type.Object({ pipeline: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

Los usuarios habilitan herramientas opcionales en la configuración:

{
  tools: { allow: ["workflow_tool"] },
}

Los nombres de herramientas no deben entrar en conflicto con las herramientas del núcleo (los conflictos se omiten)
Usa optional: true para herramientas con efectos secundarios o requisitos binarios adicionales
Los usuarios pueden habilitar todas las herramientas de un plugin agregando el id del plugin a tools.allow

Convenciones de importación

Importa siempre desde rutas específicas openclaw/plugin-sdk/<subpath>:

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// Incorrecto: raíz monolítica (obsoleta, se eliminará)
import { ... } from "openclaw/plugin-sdk";

Para la referencia completa de subrutas, consulta Resumen del SDK. Dentro de tu plugin, usa archivos barrel locales (api.ts, runtime-api.ts) para importaciones internas; nunca importes tu propio plugin mediante su ruta del SDK. Para plugins de proveedor, mantén los helpers específicos del proveedor en esos barrels de raíz del paquete, a menos que la interfaz sea realmente genérica. Ejemplos actuales incluidos:

Anthropic: envoltorios de flujo de Claude y helpers de service_tier / beta
OpenAI: constructores de proveedores, helpers de modelos predeterminados, proveedores en tiempo real
OpenRouter: constructor de proveedor más helpers de incorporación/configuración

Si un helper solo es útil dentro de un paquete de proveedor incluido, mantenlo en esa interfaz de raíz del paquete en lugar de promoverlo a openclaw/plugin-sdk/*. Algunas interfaces helper generadas openclaw/plugin-sdk/<bundled-id> todavía existen para mantenimiento y compatibilidad de plugins incluidos, por ejemplo plugin-sdk/feishu-setup o plugin-sdk/zalo-setup. Trátalas como superficies reservadas, no como el patrón predeterminado para nuevos plugins de terceros.

Lista de comprobación previa al envío

package.json tiene los metadatos openclaw correctos

El manifiesto openclaw.plugin.json está presente y es válido

El punto de entrada usa defineChannelPluginEntry o definePluginEntry

Todas las importaciones usan rutas específicas plugin-sdk/<subpath>

Las importaciones internas usan módulos locales, no autoimportaciones del SDK

Las pruebas pasan (pnpm test -- <bundled-plugin-root>/my-plugin/)

pnpm check pasa (plugins dentro del repositorio)

Pruebas de versiones beta

Observa las etiquetas de versiones de GitHub en openclaw/openclaw y suscríbete mediante Watch > Releases. Las etiquetas beta tienen este aspecto: v2026.3.N-beta.1. También puedes activar notificaciones para la cuenta oficial de OpenClaw en X @openclaw para recibir anuncios de versiones.
Prueba tu plugin con la etiqueta beta en cuanto aparezca. El margen antes de la versión estable suele ser de solo unas horas.
Publica en el hilo de tu plugin en el canal plugin-forum de Discord después de probar con all good o indicando qué falló. Si todavía no tienes un hilo, crea uno.
Si algo falla, abre o actualiza una incidencia titulada Beta blocker: <plugin-name> - <summary> y aplica la etiqueta beta-blocker. Pon el enlace de la incidencia en tu hilo.
Abre un PR a main titulado fix(<plugin-id>): beta blocker - <summary> y enlaza la incidencia tanto en el PR como en tu hilo de Discord. Los colaboradores no pueden etiquetar PRs, así que el título es la señal del lado del PR para mantenedores y automatización. Los bloqueadores con PR se fusionan; los bloqueadores sin PR podrían enviarse igualmente. Los mantenedores observan estos hilos durante las pruebas beta.
El silencio significa verde. Si pierdes la ventana, tu corrección probablemente llegue en el siguiente ciclo.

Siguientes pasos

Plugins de canal

Crea un plugin de canal de mensajería

Plugins de proveedor

Crea un plugin de proveedor de modelos

Resumen del SDK

Referencia del mapa de importaciones y de la API de registro

Helpers de tiempo de ejecución

TTS, búsqueda, subagente mediante api.runtime

Pruebas

Utilidades y patrones de prueba

Manifiesto del plugin

Referencia completa del esquema del manifiesto

Relacionado

Arquitectura de plugins — análisis en profundidad de la arquitectura interna
Resumen del SDK — referencia del Plugin SDK
Manifest — formato del manifiesto del plugin
Plugins de canal — creación de plugins de canal
Plugins de proveedor — creación de plugins de proveedor

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Creación de plugins

Creación de plugins

Requisitos previos

¿Qué tipo de plugin?

Plugin de canal

Plugin de proveedor

Plugin de herramienta / hook

Inicio rápido: plugin de herramienta

Capacidades del plugin

Registro de herramientas de agente

Convenciones de importación

Lista de comprobación previa al envío

Pruebas de versiones beta

Siguientes pasos

Plugins de canal

Plugins de proveedor

Resumen del SDK

Helpers de tiempo de ejecución

Pruebas

Manifiesto del plugin

Relacionado

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

​Creación de plugins

​Requisitos previos

​¿Qué tipo de plugin?

Plugin de canal

Plugin de proveedor

Plugin de herramienta / hook

​Inicio rápido: plugin de herramienta

​Capacidades del plugin

​Registro de herramientas de agente

​Convenciones de importación

​Lista de comprobación previa al envío

​Pruebas de versiones beta

​Siguientes pasos

Plugins de canal

Plugins de proveedor

Resumen del SDK

Helpers de tiempo de ejecución

Pruebas

Manifiesto del plugin

​Relacionado

Creación de plugins

Requisitos previos

¿Qué tipo de plugin?

Inicio rápido: plugin de herramienta

Capacidades del plugin

Registro de herramientas de agente

Convenciones de importación

Lista de comprobación previa al envío

Pruebas de versiones beta

Siguientes pasos

Relacionado