​

Creación de plugins

​

Requisitos previos

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

​

¿Qué tipo de plugin?

​

Inicio rápido: plugin de herramienta

{
  "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"
    }
  }
}

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

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

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

​

Capacidades del plugin

• before_tool_call: { block: true } es terminal y detiene los controladores de menor prioridad.
• before_tool_call: { block: false } se trata como si no hubiera 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 exec, 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 si no hubiera decisión.
• message_sending: { cancel: true } es terminal y detiene los controladores de menor prioridad.
• message_sending: { cancel: false } se trata como si no hubiera decisión.

​

Registrar herramientas de agente

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 añadirla 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 },
  );
}

{
  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 añadiendo el ID del plugin a tools.allow

​

Convenciones de importación

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";

• Anthropic: envoltorios de flujo de Claude y auxiliares service_tier / beta
• OpenAI: constructores de proveedor, auxiliares de modelo predeterminado, proveedores en tiempo real
• OpenRouter: constructor de proveedor más auxiliares de onboarding/configuración

​

Lista de comprobación previa al envío

​

Pruebas de versiones beta

1. Vigila las etiquetas de versiones de GitHub en openclaw/openclaw y suscríbete mediante Watch > Releases. Las etiquetas beta tienen un aspecto como v2026.3.N-beta.1. También puedes activar notificaciones para la cuenta oficial de OpenClaw en X @openclaw para anuncios de versiones.
2. Prueba tu plugin con la etiqueta beta en cuanto aparezca. El margen antes de la versión estable suele ser de solo unas horas.
3. Publica en el hilo de tu plugin en el canal plugin-forum de Discord después de probarlo con all good o con lo que se haya roto. Si todavía no tienes un hilo, crea uno.
4. Si algo se rompe, 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.
5. 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 PR, así que el título es la señal del lado del PR para mantenedores y automatización. Los bloqueos con PR se fusionan; los bloqueos sin PR podrían publicarse igualmente. Los mantenedores vigilan estos hilos durante las pruebas beta.
6. El silencio significa verde. Si pierdes la ventana, es probable que tu corrección llegue en el siguiente ciclo.

​

Siguientes pasos

​

Relacionado

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