Construyendo complementos

Los complementos extienden OpenClaw sin cambiar el núcleo. Un complemento puede agregar un canal de mensajería, proveedor de modelos, backend local de CLI, herramienta de agente, enlace, proveedor de medios u otra capacidad propiedad del complemento.

No es necesario agregar un complemento externo al repositorio de OpenClaw. Publica el paquete en ClawHub y los usuarios lo instalan con:

openclaw plugins install clawhub:<package-name>

Las especificaciones de paquete básicas todavía se instalan desde npm durante la transición de lanzamiento. Usa el prefijo clawhub: cuando quieras la resolución de ClawHub.

Requisitos

Usa Node 22.19 o más reciente y un gestor de paquetes como npm o pnpm.
Estar familiarizado con los módulos ESM de TypeScript.
Para el trabajo de complementos agrupados en el repositorio, clona el repositorio y ejecuta pnpm install. El desarrollo de complementos con código fuente es exclusivo de pnpm porque OpenClaw carga los complementos agrupados desde paquetes del espacio de trabajo extensions/*.

Elige el tipo de complemento

Complemento de canal

Conecta OpenClaw a una plataforma de mensajería.

Complemento de proveedor

Agrega un proveedor de modelos, medios, búsqueda, recuperación, voz o tiempo real.

Complemento de backend de CLI

Ejecuta una CLI de IA local a través del respaldo de modelos de OpenClaw.

Complemento de herramienta

Registra herramientas de agente.

Inicio rápido

Cree un complemento de herramienta mínimo registrando una herramienta de agente obligatoria. Esta es la forma de complemento útil más corta y muestra el paquete, el manifiesto, el punto de entrada y la prueba local.

Crear metadatos del paquete

{
  "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",
  "contracts": {
    "tools": ["my_tool"]
  },
  "activation": {
    "onStartup": true
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

Los complementos externos publicados deben apuntar las entradas de tiempo de ejecución a archivos JavaScript construidos. Consulte Puntos de entrada del SDK para ver el contrato completo del punto de entrada.

Cada complemento necesita un manifiesto, incluso cuando no tiene configuración. Las herramientas de tiempo de ejecución deben aparecer en contracts.tools para que OpenClaw pueda descubrir la propiedad sin cargar ansiosamente todos los tiempos de ejecución de complementos. Configure activation.onStartup intencionalmente. Este ejemplo se inicia al iniciar Gateway.

Para cada campo de manifiesto, consulte Manifiesto del complemento.

Registrar la herramienta

import { Type } from "typebox";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

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

Use definePluginEntry para complementos que no sean de canal. Los complementos de canal usan defineChannelPluginEntry.

Probar el tiempo de ejecución
Para un complemento instalado o externo, inspeccione el tiempo de ejecución cargado:
Ventana de terminal
```
openclaw plugins inspect my-plugin --runtime --json
```
Si el complemento registra un comando CLI, ejecute ese comando también. Por ejemplo, un comando de demostración debe tener una prueba de ejecución como openclaw demo-plugin ping.

Para un complemento incluido en este repositorio, OpenClaw descubre paquetes de complementos de fuente extraída del espacio de trabajo extensions/*. Ejecute la prueba dirigida más cercana:
Ventana de terminal
```
pnpm test -- extensions/my-plugin/
pnpm check
```
Publicar
Valide el paquete antes de publicarlo:
Ventana de terminal
```
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
```
Los fragmentos canónicos de ClawHub viven en docs/snippets/plugin-publish/.
Instalar
Instale el paquete publicado a través de ClawHub:
Ventana de terminal
```
openclaw plugins install clawhub:your-org/your-plugin
```

Registro de herramientas

Las herramientas pueden ser obligatorias u opcionales. Las herramientas obligatorias siempre están disponibles cuando el complemento está habilitado. Las herramientas opcionales requieren la aceptación explícita del usuario.

register(api) {
  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 },
  );
}

Cada herramienta registrada con api.registerTool(...) también debe declararse en el manifiesto del complemento:

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

Los usuarios aceptan con tools.allow:

{
  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for all tools from one plugin
}

Use herramientas opcionales para efectos secundarios, binarios inusuales o capacidades que no deben exponerse de forma predeterminada. Los nombres de las herramientas no deben entrar en conflicto con las herramientas principales; los conflictos se omiten y se informan en los diagnósticos del complemento. Los registros con formato incorrecto, incluidos los descriptores de herramientas sin parameters, se omiten y se informan de la misma manera. Las herramientas registradas son funciones tipificadas que el modelo puede llamar después de pasar las comprobaciones de política y lista de permitidos.

Las fábricas de herramientas reciben un objeto de contexto proporcionado por el tiempo de ejecución. Use 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átelo como metadatos informativos del tiempo de ejecución, no como un límite de seguridad contra el operador local, el código del complemento instalado o un tiempo de ejecución de OpenClaw modificado. Las herramientas locales sensibles aún deben requerir una aceptación explícita del complemento o del operador y deben fallar de forma cerrada cuando faltan o no son adecuados los metadatos del modelo activo.

El manifiesto declara la propiedad y el descubrimiento; la ejecución aún llama a la implementación de la herramienta registrada en vivo. Mantenga `toolMetadata.

.optional: truealineado conapi.registerTool(…, { optional: true })` para que OpenClaw pueda evitar cargar ese tiempo de ejecución del complemento hasta que la herramienta se haya agregado explícitamente a la lista de permitidos.

Convenciones de importación

Importe desde subrutas enfocadas del SDK:

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

No importe desde el barril raíz en desuso:

import { definePluginEntry } from "openclaw/plugin-sdk";

Dentro de su paquete de complementos, use archivos barril locales como api.ts y runtime-api.ts para importaciones internas. No importe su propio complemento a través de una ruta del SDK. Los asistentes específicos del proveedor deben permanecer en el paquete del proveedor a menos que la unión sea verdaderamente genérica.

Los métodos RPC de Gateway personalizados son un punto de entrada avanzado. Manténgalos en un prefijo específico del complemento; los espacios de nombres de administración principal como config.*, exec.approvals.*, operator.admin.*, wizard.* y update.* permanecen reservados y resuelven a operator.admin. El puente openclaw/plugin-sdk/gateway-method-runtime está reservado para las rutas HTTP de complementos que declaran contracts.gatewayMethodDispatch: ["authenticated-request"].

Para ver el mapa de importación completo, consulte Plugin SDK overview.

Lista de verificación previa al envío

Probar contra versiones 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 anuncios de lanzamiento.
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 con 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. Abre una PR a maintituladafix(

): beta blocker -

` y vincula la incidencia tanto en la PR como en tu hilo de Discord. Los colaboradores no pueden etiquetar las PR, por lo que el título es la señal del lado de la PR para los mantenedores y la automatización. Los bloqueos con una PR se fusionan; los bloqueos sin una podrían lanzarse de todos modos. Los mantenedores supervisan estos hilos durante las pruebas beta. 6. El silencio significa luz verde. Si pierdes la ventana, tu corrección probablemente se incluirá en el siguiente ciclo.