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
}

Las herramientas opcionales controlan si una herramienta está expuesta al modelo. Use solicitudes de permiso de complementos cuando una herramienta o hook deba solicitar aprobación después de que el modelo la seleccione y antes de que se ejecute la acción.

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 el diagnóstico del complemento. Los registros malformados, 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 que se aprueben las verificaciones de políticas y listas 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 de tiempo de ejecución informativos, 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 opción explícita del complemento u operador y fallar cerradas cuando falten los metadatos del modelo activo o no sean adecuados.

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 agregue explícitamente a la lista de permitidos.

Convenciones de importación

Importe desde subrutas centradas 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 complemento, 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 se resuelven en 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 Descripción general del SDK de complementos.

Lista de verificación previa al envío

Probar con versiones beta

Esté atento a las etiquetas de lanzamiento de GitHub en openclaw/openclaw y suscríbase mediante Watch > Releases. Las etiquetas beta se parecen a v2026.3.N-beta.1. También puede activar las notificaciones para la cuenta oficial de X de OpenClaw @openclaw para recibir anuncios de lanzamiento.
Pruebe su complemento con 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 falló. Si aún no tiene un hilo, cree uno.
Si algo falla, abra o actualice un problema titulado `Beta blocker:

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

): beta blocker -

` y vincula el problema tanto en el PR como en tu 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 podrían enviarse de todos modos. Los mantenedores observan estos hilos durante las pruebas beta. 6. El silencio significa que está bien (verde). Si pierdes la ventana, tu corrección probablemente se incluirá en el siguiente ciclo.