English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Building plugins

Crear plugins

Plugins extienden OpenClaw sin cambiar el núcleo. Un plugin puede agregar un canal de mensajería, proveedor de modelos, backend de CLI local, herramienta de agente, hook, proveedor multimedia u otra capacidad propiedad del plugin.

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

bash
openclaw plugins install clawhub:<package-name>

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

Requisitos

  • Node 22.19+, Node 23.11+ o Node 24+, y npm o pnpm.
  • Módulos ESM de TypeScript.
  • Para el trabajo en plugins incluidos en el repositorio, clona el repositorio y ejecuta pnpm install. El desarrollo de plugins desde una copia del código fuente solo usa pnpm porque OpenClaw descubre plugins incluidos desde paquetes de espacio de trabajo extensions/*.

Elige la forma del plugin

Plugin de canal

Conecta OpenClaw a una plataforma de mensajería.
Plugin de proveedor

Agrega un proveedor de modelos, multimedia, búsqueda, obtención, voz o tiempo real.
Plugin de backend de CLI

Ejecuta una CLI de IA local mediante la reserva de modelos de OpenClaw.
Plugin de herramienta

Registra herramientas de agente.

Inicio rápido

Crea un plugin de herramienta mínimo registrando una herramienta de agente obligatoria. Esta es la forma de plugin útil más breve y cubre el paquete, el manifiesto, el punto de entrada y la prueba local.

  • Crear metadatos del paquete

    package.json
    {"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"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"}}}
    openclaw.plugin.json
    {"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 plugins externos publicados deben apuntar las entradas de runtime a archivos JavaScript compilados. Consulta puntos de entrada del SDK para ver el contrato completo de punto de entrada.

    Todo plugin necesita un manifiesto, incluso sin configuración. Las herramientas de runtime deben aparecer en contracts.tools para que OpenClaw pueda descubrir la propiedad sin cargar con antelación el runtime de todos los plugins. Define activation.onStartup de forma intencionada; este ejemplo se carga al iniciar el Gateway.

    Las superficies de plugin en las que confía el host también están controladas por manifiesto y requieren una declaración explícita para los plugins instalados: api.registerAgentToolResultMiddleware(...) necesita que cada runtime objetivo esté listado en contracts.agentToolResultMiddleware, y api.registerTrustedToolPolicy(...) necesita cada id de política en contracts.trustedToolPolicies. Estas declaraciones mantienen alineadas la inspección en el momento de instalación y el registro en runtime.

    Para cada campo del manifiesto, consulta manifiesto de Plugin.

  • Registrar la herramienta

    index.ts
    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}` }],        };      },    });  },});

    Usa definePluginEntry para plugins que no sean de canal. Los plugins de canal usan defineChannelPluginEntry desde openclaw/plugin-sdk/core en su lugar.

  • Probar el runtime

    Para un plugin instalado o externo, inspecciona el runtime cargado:

    bash
    openclaw plugins inspect my-plugin --runtime --json

    Si el plugin registra un comando de CLI, ejecuta también ese comando y confirma la salida, por ejemplo openclaw demo-plugin ping.

    Para un plugin incluido en este repositorio, OpenClaw descubre los paquetes de plugin de la copia del código fuente desde el espacio de trabajo extensions/*. Ejecuta la prueba específica más cercana:

    bash
    pnpm test extensions/my-plugin/pnpm check

  • Probar la instalación del paquete

    Antes de publicar un plugin listo para empaquetar, prueba la misma forma de instalación que recibirán los usuarios. Primero agrega un paso de compilación, apunta entradas de runtime como openclaw.extensions a JavaScript compilado como ./dist/index.js, y asegúrate de que npm pack incluya esa salida dist/. Las entradas de código fuente TypeScript son solo para copias del código fuente y rutas de desarrollo local.

    Luego empaqueta el plugin e instala el tarball con npm-pack::

    bash
    npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

    npm-pack: usa el proyecto npm administrado por plugin de OpenClaw, por lo que detecta errores de dependencias de runtime que las pruebas desde una copia del código fuente pueden ocultar. Prueba la forma del paquete y las dependencias, no la confianza oficial vinculada al catálogo. Las importaciones de runtime deben estar en dependencies u optionalDependencies; las dependencias que queden solo en devDependencies no se instalarán para el proyecto de runtime administrado.

    No uses una instalación directa de archivo/ruta como prueba final para comportamiento de plugin oficial o privilegiado. Las fuentes directas son útiles para la depuración local, pero no prueban la misma ruta de dependencias que las instalaciones desde npm o ClawHub. Si tu plugin depende del estado de plugin oficial de confianza, agrega una segunda prueba mediante una instalación oficial respaldada por catálogo o una ruta de paquete publicado que registre la confianza oficial. Consulta resolución de dependencias de Plugin para detalles de raíz de instalación y propiedad de dependencias.

  • Publicar

    Valida el paquete antes de publicar:

    bash
    clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

    Los fragmentos canónicos de paquetes de ClawHub están en docs/snippets/plugin-publish/.

  • Instalar

    Instala el paquete publicado mediante ClawHub:

    bash
    openclaw plugins install clawhub:your-org/your-plugin

    • Registrar herramientas

    Las herramientas pueden ser obligatorias u opcionales. Las herramientas obligatorias siempre están disponibles cuando el plugin está habilitado. Las herramientas opcionales necesitan la aceptación explícita del usuario antes de que OpenClaw cargue el runtime del plugin propietario.

    typescript
    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 },  );}

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

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

    Los usuarios aceptan con tools.allow:

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

    Las herramientas opcionales controlan si una herramienta se expone al modelo. Usa solicitudes de permisos de plugin cuando una herramienta o hook deba pedir aprobación después de que el modelo la seleccione y antes de que se ejecute la acción.

    Usa herramientas opcionales para efectos secundarios, binarios inusuales o capacidades que no deberían exponerse de forma predeterminada. Los nombres de herramientas no deben entrar en conflicto con los nombres de herramientas del núcleo; los conflictos se omiten y se informan en los diagnósticos del plugin. Los registros mal formados se omiten y se informan del mismo modo: un name no vacío faltante, un execute que no sea función o un descriptor de herramienta sin un objeto parameters.

    Las fábricas de herramientas reciben un objeto de contexto suministrado por el runtime. Usa ctx.activeModel cuando una herramienta necesite registrar, mostrar o adaptarse al modelo activo para el turno actual; puede incluir provider, modelId y modelRef. Trátalo como metadatos informativos de runtime, no como un límite de seguridad frente al operador local, el código de plugin instalado o un runtime de OpenClaw modificado. Las herramientas locales sensibles aun así deben requerir una aceptación explícita del plugin u operador y fallar de forma cerrada cuando los metadatos del modelo activo falten o no sean adecuados.

    El manifiesto declara la propiedad y el descubrimiento; la ejecución sigue llamando a la implementación registrada de la herramienta en vivo. Mantén toolMetadata.<tool>.optional: true alineado con api.registerTool(..., { optional: true }) para que OpenClaw pueda evitar cargar ese runtime de plugin hasta que la herramienta se incluya explícitamente en la lista de permitidas.

    Convenciones de importación

    Importa desde subrutas específicas del SDK:

    typescript

    No importes desde el barrel raíz obsoleto:

    typescript

    Dentro de tu paquete de plugin, usa archivos barrel locales como api.ts y runtime-api.ts para importaciones internas. No importes tu propio plugin mediante una ruta del SDK. Los helpers específicos de proveedor deben permanecer en el paquete de proveedor a menos que la unión sea realmente genérica.

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

    Para el mapa completo de importaciones, consulta descripción general del SDK de Plugin.

    Lista de verificación previa al envío

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json tiene metadatos openclaw correctos OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s El manifiesto openclaw.plugin.json está presente y es válido OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s El punto de entrada usa defineChannelPluginEntry o definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Todas las importaciones usan rutas específicas plugin-sdk/<subpath> OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page