Construcción de complementos

Los complementos amplían OpenClaw con nuevas capacidades: canales, proveedores de modelos, voz, generación de imágenes, búsqueda web, herramientas de agente, o cualquier combinación.

No es necesario añadir su complemento al repositorio de OpenClaw. Publíquelo en ClawHub o npm y los usuarios lo instalan con openclaw plugins install <package-name>. OpenClaw intenta con ClawHub primero y recurre a npm automáticamente.

Requisitos previos

Node >= 22 y un gestor de paquetes (npm o pnpm)
Familiaridad con TypeScript (ESM)
Para complementos en el repositorio: repositorio clonado y pnpm install realizado

¿Qué tipo de complemento?

Complemento de canal

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

Complemento de proveedor

Añada un proveedor de modelos (LLM, proxy o endpoint personalizado)

Complemento de herramienta / gancho

Registre herramientas de agente, ganchos de eventos o servicios — continúe abajo

Inicio rápido: complemento de herramienta

Este tutorial crea un complemento mínimo que registra una herramienta de agente. Los complementos de canal y proveedor tienen guías dedicadas vinculadas anteriormente.

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

{
  "id": "my-plugin",
  "name": "My Plugin",
  "description": "Adds a custom tool to OpenClaw",
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

Cada complemento necesita un manifiesto, incluso sin configuración. Vea Manifiesto para el esquema completo. Los snippets canónicos de publicación en ClawHub viven en docs/snippets/plugin-publish/.

Escribir el punto de entrada

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 complementos que no son de canal. Para canales, use defineChannelPluginEntry — vea Complementos de canal. Para todas las opciones de puntos de entrada, vea Puntos de entrada.

Probar y publicar
Complementos externos: valide y publique con ClawHub, luego instale:
Ventana de terminal
```
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 verifica ClawHub antes que npm para especificaciones de paquetes simples como @myorg/openclaw-my-plugin.

Complementos en el repositorio: colóquelos bajo el árbol del espacio de trabajo del complemento incluido — detectados automáticamente.
Ventana de terminal
```
pnpm test --
```
/my-plugin/ ```

Capacidades de los complementos

Un único complemento puede registrar cualquier número de capacidades a través del objeto api:

Capacidad	Método de registro	Guía detallada
Inferencia de texto (LLM)	`api.registerProvider(...)`	Complementos de proveedor
Backend de inferencia de CLI	`api.registerCliBackend(...)`	Backends de CLI
Canal / mensajería	`api.registerChannel(...)`	Complementos de canal
Voz (TTS/STT)	`api.registerSpeechProvider(...)`	Complementos de proveedor
Comprensión de medios	`api.registerMediaUnderstandingProvider(...)`	Complementos de proveedor
Generación de imágenes	`api.registerImageGenerationProvider(...)`	Complementos de proveedor
Búsqueda web	`api.registerWebSearchProvider(...)`	Complementos de proveedor
Herramientas de agente	`api.registerTool(...)`	A continuación
Comandos personalizados	`api.registerCommand(...)`	Puntos de entrada
Ganchos de eventos	`api.registerHook(...)`	Puntos de entrada
Rutas HTTP	`api.registerHttpRoute(...)`	Aspectos internos
Subcomandos de CLI	`api.registerCli(...)`	Puntos de entrada

Para conocer la API de registro completa, consulte Descripción general del SDK.

Semántica de guardia de gancho 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 sin decisión.
before_tool_call: { requireApproval: true } pausa la ejecución del agente y solicita al usuario aprobación a través de 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 sin decisión.
message_sending: { cancel: true } es terminal y detiene los controladores de menor prioridad.
message_sending: { cancel: false } se trata como ninguna decisión.

El comando /approve maneja tanto las aprobaciones de ejecución como las de complementos con conmutación por error automática. El reenvío de aprobaciones de complementos se puede configurar de forma independiente a través de approvals.plugin en la configuración.

Consulte semántica de decisión de enlace de descripción general del SDK para obtener más detalles.

Registrar herramientas de agente

Las herramientas son funciones tipificadas que el LLM puede llamar. Pueden ser obligatorias (siempre disponibles) u opcionales (opción del 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 },
  );
}

Los usuarios habilitan las herramientas opcionales en la configuración:

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

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

Convenciones de importación

Siempre importe desde rutas `openclaw/plugin-sdk/

` enfocadas:

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 obtener la referencia completa de subrutas, consulte Descripción general del SDK.

Dentro de su complemento, use archivos barrel locales (api.ts, runtime-api.ts) para importaciones internas; nunca importe su propio complemento a través de su ruta SDK.

Lista de verificación previa al envío

Pruebas de lanzamiento beta

Esté atento a las etiquetas de lanzamiento de GitHub en openclaw/openclaw y suscríbase a través de Watch > Releases. Las etiquetas beta se parecen a v2026.3.N-beta.1. También puede activar las notificaciones para la cuenta oficial de OpenClaw X @openclaw para recibir anuncios de lanzamientos.
Pruebe su complemento contra la etiqueta beta tan pronto como aparezca. La ventana antes de la versión estable suele ser de solo unas pocas horas.
Publique en el hilo de su complemento en el canal de Discord plugin-forum después de probar con all good o lo que se rompió. Si aún no tiene un hilo, cree uno.
Si algo se rompe, abra o actualice un problema titulado `Beta blocker:

y aplique la etiquetabeta-blocker. Ponga el enlace del problema en su hilo. 5. Abra un PR a maintituladofix(

): beta blocker -

` y vincule el problema tanto en el PR como en su hilo de Discord. Los colaboradores no pueden etiquetar los PR, por lo que el título es la señal del lado del PR para los mantenedores y la automatización. Los bloqueadores con un PR se fusionan; los bloqueadores sin uno pueden publicarse de todos modos. Los mantenedores vigilan estos hilos durante las pruebas beta. 6. El silencio significa verde (que está bien). Si pierde la ventana, su corrección probablemente se incluirá en el próximo ciclo.