Creación de plugins

Los plugins extienden 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 y los usuarios lo instalan con openclaw plugins install clawhub:<package-name>. Las especificaciones de paquete simples aún se instalan desde npm durante la transición de lanzamiento.

Requisitos previos

Node >= 22 y un gestor de paquetes (npm o pnpm)
Familiaridad con TypeScript (ESM)
Para plugins en el repositorio: repositorio clonado y pnpm install ejecutado. El desarrollo de plugins desde un checkout de código fuente es solo con pnpm porque OpenClaw carga los plugins incluidos desde los paquetes de espacio de trabajo extensions/*.

¿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 backend de CLI

Asigna una CLI de IA local al ejecutor de respaldo de texto de OpenClaw

Plugin de herramienta / hook

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

Para un plugin de canal cuya instalación no esté garantizada cuando se ejecuta la incorporación/configuración, usa createOptionalChannelSetupSurface(...) desde openclaw/plugin-sdk/channel-setup. Produce un par adaptador de configuración + asistente que anuncia el requisito de instalación y falla de forma cerrada en escrituras de configuración reales 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.

Crear 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. Las herramientas registradas en tiempo de ejecución deben listarse en contracts.tools para que OpenClaw pueda descubrir el plugin propietario sin cargar todos los entornos de ejecución de plugins. Los plugins también deberían declarar activation.onStartup de forma intencional. Este ejemplo lo establece en true. Consulta Manifiesto para ver el esquema completo. Los fragmentos canónicos de publicación en ClawHub se encuentran en docs/snippets/plugin-publish/.

Escribir 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 de punto de entrada, consulta Puntos de entrada.

Probar y publicar

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

Las especificaciones de paquete simples como @myorg/openclaw-my-plugin se instalan desde npm durante la transición de lanzamiento. Usa clawhub: cuando quieras resolución de ClawHub.Plugins en el repositorio: colócalos bajo el árbol de espacio de trabajo de plugins incluidos; se descubren automáticamente.

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

Capacidades del plugin

Un solo plugin puede registrar cualquier número 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(...)`	Plugins de backend 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
Middleware de resultados de herramientas	`api.registerAgentToolResultMiddleware(...)`	Resumen del SDK
Herramientas de agente	`api.registerTool(...)`	Abajo
Comandos personalizados	`api.registerCommand(...)`	Puntos de entrada
Hooks de plugin	`api.on(...)`	Hooks de plugin
Hooks de eventos internos	`api.registerHook(...)`	Puntos de entrada
Rutas HTTP	`api.registerHttpRoute(...)`	Aspectos internos
Subcomandos de CLI	`api.registerCli(...)`	Puntos de entrada

Para ver la API de registro completa, consulta Resumen del SDK. Los plugins incluidos pueden usar api.registerAgentToolResultMiddleware(...) cuando necesitan reescritura asíncrona de resultados de herramientas antes de que el modelo vea la salida. Declara los entornos de ejecución objetivo en contracts.agentToolResultMiddleware, por ejemplo ["pi", "codex"]. Esta es una interfaz de confianza para plugins incluidos; los plugins externos deberían preferir los hooks normales de plugins de OpenClaw salvo que OpenClaw desarrolle una política de confianza explícita para esta capacidad. Si tu plugin registra métodos RPC personalizados del Gateway, mantenlos en un prefijo específico del plugin. Los espacios de nombres de administración del núcleo (config.*, exec.approvals.*, wizard.*, update.*) permanecen reservados y siempre se resuelven en operator.admin, incluso si un plugin solicita un alcance más estrecho. Semántica de guardas de hooks a tener en cuenta:

before_tool_call: { block: true } es terminal y detiene los manejadores de menor prioridad.
before_tool_call: { block: false } se trata como ninguna decisión.
before_tool_call: { requireApproval: true } pausa la ejecución del agente y solicita aprobación al 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 manejadores de menor prioridad.
before_install: { block: false } se trata como ninguna decisión.
message_sending: { cancel: true } es terminal y detiene los manejadores de menor prioridad.
message_sending: { cancel: false } se trata como ninguna decisión.
message_received: prefiere el campo tipado threadId cuando necesites enrutamiento de hilos/temas entrantes. Mantén metadata para extras específicos del canal.
message_sending: prefiere los campos de enrutamiento tipados replyToId / threadId en lugar de claves de metadatos específicas del canal.

El comando /approve maneja tanto aprobaciones de ejecución como de plugins con respaldo acotado: cuando no se encuentra un id de aprobación de ejecución, OpenClaw reintenta el mismo id mediante las aprobaciones de plugins. El reenvío de aprobaciones de plugins puede configurarse de forma independiente mediante approvals.plugin en la configuración. Si la canalización de aprobación personalizada necesita detectar ese mismo caso de respaldo acotado, prefiere isApprovalNotFoundError desde openclaw/plugin-sdk/error-runtime en lugar de comparar manualmente cadenas de expiración de aprobación. Consulta Hooks de plugin para ver ejemplos y la referencia de hooks.

Registrar herramientas de agente

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

register(api) {
  // Required tool - always available
  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 }] };
    },
  });

  // Optional tool - user must add to allowlist
  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 },
  );
}

Las fábricas de herramientas reciben un objeto de contexto proporcionado por el entorno de ejecución. Usa ctx.activeModel cuando una herramienta necesite registrar, mostrar o adaptarse al modelo activo para el turno actual. El objeto puede incluir provider, modelId y modelRef. Trátalo como metadatos informativos del entorno de ejecución, no como un límite de seguridad frente al operador local, el código de Plugin instalado o un entorno de ejecución de OpenClaw modificado. Para herramientas locales sensibles, mantén una aceptación explícita del Plugin o del operador y falla de forma cerrada cuando los metadatos del modelo activo falten o no sean adecuados. Cada herramienta registrada con api.registerTool(...) también debe declararse en el manifiesto del Plugin:

{
  "contracts": {
    "tools": ["my_tool", "workflow_tool"]
  },
  "toolMetadata": {
    "workflow_tool": {
      "optional": true
    }
  }
}

OpenClaw captura y almacena en caché el descriptor validado de la herramienta registrada, por lo que los plugins no duplican description ni datos de esquema en el manifiesto. El contrato del manifiesto solo declara propiedad y descubrimiento; la ejecución sigue llamando a la implementación activa de la herramienta registrada. Define toolMetadata.<tool>.optional: true para herramientas registradas con api.registerTool(..., { optional: true }) para que OpenClaw pueda evitar cargar ese entorno de ejecución de Plugin hasta que la herramienta se incluya explícitamente en la lista de permitidos. 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 principales (los conflictos se omiten)
Las herramientas con objetos de registro mal formados, incluida la falta de parameters, se omiten y se reportan en los diagnósticos del Plugin en lugar de interrumpir las ejecuciones del agente
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

Registrar comandos de CLI

Los plugins pueden agregar grupos de comandos raíz de openclaw con api.registerCli. Proporciona descriptors para cada raíz de comando de nivel superior para que OpenClaw pueda mostrar y enrutar el comando sin cargar ansiosamente cada entorno de ejecución de Plugin.

register(api) {
  api.registerCli(
    ({ program }) => {
      const demo = program
        .command("demo-plugin")
        .description("Run demo plugin commands");

      demo
        .command("ping")
        .description("Check that the plugin CLI is executable")
        .action(() => {
          console.log("demo-plugin:pong");
        });
    },
    {
      descriptors: [
        {
          name: "demo-plugin",
          description: "Run demo plugin commands",
          hasSubcommands: true,
        },
      ],
    },
  );
}

Después de instalar, verifica el registro del entorno de ejecución y ejecuta el comando:

openclaw plugins inspect demo-plugin --runtime --json
openclaw demo-plugin ping

Convenciones de importación

Importa siempre desde rutas enfocadas openclaw/plugin-sdk/<subpath>:

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

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";

Para la referencia completa de subrutas, consulta Descripción general 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 de SDK. Para plugins de proveedor, mantén los helpers específicos del proveedor en esos barrels de la raíz del paquete salvo que la interfaz sea verdaderamente genérica. Ejemplos incluidos actuales:

Anthropic: envoltorios de flujo de Claude y helpers de service_tier / beta
OpenAI: constructores de proveedor, helpers de modelo predeterminado, 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 de paquete en lugar de promoverlo a openclaw/plugin-sdk/*. Algunas interfaces helper generadas openclaw/plugin-sdk/<bundled-id> todavía existen para el mantenimiento de plugins incluidos cuando han rastreado uso del propietario. Trátalas como superficies reservadas, no como el patrón predeterminado para nuevos plugins de terceros.

Lista de verificació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 enfocadas 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

Vigila las etiquetas de lanzamiento de GitHub en openclaw/openclaw y suscríbete mediante Watch > Releases. Las etiquetas beta se ven como v2026.3.N-beta.1. También puedes activar las notificaciones de la cuenta oficial de OpenClaw en X @openclaw para anuncios de lanzamiento.
Prueba tu Plugin contra la etiqueta beta en cuanto aparezca. La ventana 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 con lo que se haya roto. Si aún no tienes un hilo, crea uno.
Si algo se rompe, abre o actualiza un issue titulado Beta blocker: <plugin-name> - <summary> y aplica la etiqueta beta-blocker. Pon el enlace del issue en tu hilo.
Abre un PR a main titulado fix(<plugin-id>): beta blocker - <summary> y enlaza el issue tanto en el PR como en tu hilo de Discord. Los contribuidores 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 uno podrían publicarse de todos modos. Los mantenedores vigilan estos hilos durante las pruebas beta.
El silencio significa que todo está en verde. Si pierdes la ventana, es probable que tu corrección llegue en el siguiente ciclo.

Próximos pasos

Plugins de canal

Crea un Plugin de canal de mensajería

Plugins de proveedor

Crea un Plugin de proveedor de modelos

Plugins de backend de CLI

Registra un backend local de CLI de IA

Descripción general del SDK

Mapa de importación y referencia de API de registro

Helpers de entorno de ejecución

TTS, búsqueda, subagente mediante api.runtime

Pruebas

Utilidades y patrones de prueba

Manifiesto de Plugin

Referencia completa del esquema del manifiesto

Relacionado

Arquitectura de Plugin - análisis profundo de la arquitectura interna
Descripción general del SDK - referencia del SDK de Plugin
Manifiesto - 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

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Creación de plugins

Requisitos previos

¿Qué tipo de plugin?

Plugin de canal

Plugin de proveedor

Plugin de backend de CLI

Plugin de herramienta / hook

Inicio rápido: plugin de herramienta

Capacidades del plugin

Registrar herramientas de agente

Registrar comandos de CLI

Convenciones de importación

Lista de verificación previa al envío

Pruebas de versiones beta

Próximos pasos

Plugins de canal

Plugins de proveedor

Plugins de backend de CLI

Descripción general del SDK

Helpers de entorno de ejecución

Pruebas

Manifiesto de Plugin

Relacionado

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Documentation Index

​Requisitos previos

​¿Qué tipo de plugin?

Plugin de canal

Plugin de proveedor

Plugin de backend de CLI

Plugin de herramienta / hook

​Inicio rápido: plugin de herramienta

​Capacidades del plugin

​Registrar herramientas de agente

​Registrar comandos de CLI

​Convenciones de importación

​Lista de verificación previa al envío

​Pruebas de versiones beta

​Próximos pasos

Plugins de canal

Plugins de proveedor

Plugins de backend de CLI

Descripción general del SDK

Helpers de entorno de ejecución

Pruebas

Manifiesto de Plugin

​Relacionado

Requisitos previos

¿Qué tipo de plugin?

Inicio rápido: plugin de herramienta

Capacidades del plugin

Registrar herramientas de agente

Registrar comandos de CLI

Convenciones de importación

Lista de verificación previa al envío

Pruebas de versiones beta

Próximos pasos

Relacionado