OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Building plugins

Creación de plugins

Los plugins amplían OpenClaw sin modificar el núcleo. Un plugin puede añadir un canal de mensajería, un proveedor de modelos, un backend de CLI local, una herramienta del agente, un hook, un proveedor multimedia u otra capacidad propia del plugin.

No es necesario añadir un plugin externo al repositorio de OpenClaw. Publique el paquete en ClawHub y los usuarios podrán instalarlo con:

bash
openclaw plugins install clawhub:<package-name>

Las especificaciones de paquetes sin prefijo siguen instalándose desde npm durante la transición del lanzamiento. Use el prefijo clawhub: cuando quiera que la resolución se realice mediante ClawHub.

Requisitos

  • Node 22.22.3+, Node 24.15+ o Node 25.9+, y npm o pnpm.
  • Módulos ESM de TypeScript.
  • Para trabajar con plugins incluidos en el repositorio, clone el repositorio y ejecute pnpm install. El desarrollo de plugins desde una copia del código fuente solo admite pnpm porque OpenClaw descubre los plugins incluidos en los paquetes del espacio de trabajo extensions/*.

Elegir la estructura del plugin

Plugin de canal

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

Añada un proveedor de modelos, contenido multimedia, búsqueda, obtención de datos, voz o tiempo real.
Plugin de backend de CLI

Ejecute una CLI de IA local mediante la alternativa de modelos de OpenClaw.
Plugin de herramientas

Registre herramientas del agente.

Inicio rápido

Cree un plugin de herramientas mínimo registrando una herramienta obligatoria del agente. Esta es la estructura de plugin útil más sencilla y abarca el paquete, el manifiesto, el punto de entrada y la verificación local.

  • Crear los 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 dirigir las entradas de ejecución a archivos JavaScript compilados. Consulte Puntos de entrada del SDK para conocer el contrato completo de los puntos de entrada.

    Todos los plugins necesitan un manifiesto, incluso si no tienen configuración. Las herramientas de ejecución deben aparecer en contracts.tools para que OpenClaw pueda descubrir su propietario sin cargar de forma anticipada la ejecución de cada plugin. Configure activation.onStartup deliberadamente; este ejemplo se carga al iniciar el Gateway.

    Las superficies de plugins en las que confía el host también están condicionadas por el manifiesto y requieren una declaración explícita para los plugins instalados: api.registerAgentToolResultMiddleware(...) necesita que cada ejecución de destino figure en contracts.agentToolResultMiddleware, y api.registerTrustedToolPolicy(...) necesita cada identificador de política en contracts.trustedToolPolicies. Estas declaraciones mantienen alineadas la inspección durante la instalación y el registro en tiempo de ejecución.

    Para consultar todos los campos del manifiesto, consulte Manifiesto del 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}` }],        };      },    });  },});

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

  • Probar la ejecución

    Para un plugin instalado o externo, inspeccione la ejecución cargada:

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

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

    Para un plugin incluido en este repositorio, OpenClaw descubre los paquetes de plugins de la copia del código fuente en el espacio de trabajo extensions/*. Ejecute 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, pruebe la misma modalidad de instalación que recibirán los usuarios. Primero añada un paso de compilación, dirija las entradas de ejecución como openclaw.extensions al JavaScript compilado, como ./dist/index.js, y asegúrese de que npm pack incluya esa salida dist/. Las entradas de código fuente de TypeScript son únicamente para copias del código fuente y rutas de desarrollo local.

    Después, empaquete el plugin e instale el archivo tar 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 por plugin administrado por OpenClaw, por lo que detecta errores en las dependencias de ejecución que las pruebas desde una copia del código fuente pueden ocultar. Esto verifica la estructura del paquete y sus dependencias, no la confianza oficial vinculada al catálogo. Las importaciones de ejecución deben estar en dependencies o optionalDependencies; las dependencias que solo estén en devDependencies no se instalarán en el proyecto de ejecución administrado.

    No utilice una instalación directa desde un archivo o una ruta como verificación final del comportamiento oficial o privilegiado del plugin. El código fuente directo resulta útil para la depuración local, pero no verifica la misma ruta de dependencias que las instalaciones desde npm o ClawHub. Si el plugin depende del estado de confianza de los plugins oficiales, añada una segunda verificación mediante una instalación oficial respaldada por el catálogo o una ruta de paquete publicado que registre la confianza oficial. Consulte Resolución de dependencias de plugins para conocer los detalles de la raíz de instalación y la propiedad de las dependencias.

  • Publicar

    Valide el paquete antes de publicarlo:

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

    Los fragmentos canónicos de paquetes de ClawHub se encuentran en docs/snippets/plugin-publish/.

  • Instalar

    Instale 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 la ejecución del plugin propietario.

    Las fábricas de herramientas reciben un contexto de ejecución de confianza, incluidos deliveryContext, nativeChannelId para la conversación activa de la plataforma cuando esté disponible, y requesterSenderId.

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

    Todas las herramientas registradas con api.registerTool(...) también deben declararse en el manifiesto del plugin:

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

    Los usuarios las habilitan 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. Use solicitudes de permisos de plugins cuando una herramienta o un hook deban solicitar aprobación después de que el modelo los seleccione y antes de que se ejecute la acción.

    Use herramientas opcionales para efectos secundarios, binarios poco habituales o capacidades que no deban exponerse de forma predeterminada. Los nombres de las herramientas no deben entrar en conflicto con los nombres de las herramientas del núcleo; los conflictos se omiten y se notifican en el diagnóstico del plugin. Los registros mal formados se omiten y se notifican de la misma manera: un name no vacío ausente, un execute que no sea una función o un descriptor de herramienta sin un objeto parameters.

    Las fábricas de herramientas reciben un objeto de contexto proporcionado por el entorno de ejecución. Use ctx.activeModel cuando una herramienta necesite registrar, mostrar o adaptarse al modelo activo durante el turno actual; puede incluir provider, modelId y modelRef. Trátelo como metadatos informativos del entorno de ejecución, no como una frontera de seguridad frente al operador local, el código de plugins instalado o un entorno de ejecución de OpenClaw modificado. Las herramientas locales sensibles deben seguir requiriendo la habilitación explícita del plugin o del operador y denegar la operación de forma predeterminada cuando falten los metadatos del modelo activo o no sean adecuados.

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

    Convenciones de importación

    Importe desde subrutas específicas del SDK:

    typescript

    No importe desde el barrel raíz obsoleto:

    typescript

    Dentro del paquete del plugin, use archivos barrel locales como api.ts y runtime-api.ts para las importaciones internas. No importe el propio plugin mediante una ruta del SDK. Los auxiliares específicos de un proveedor deben permanecer en el paquete del proveedor, salvo que la interfaz sea verdaderamente genérica.

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

    Para consultar el mapa completo de importaciones, consulte Descripción general del SDK de plugins.

    Lista de comprobación previa al envío

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json contiene los 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 de plugin-sdk/<subpath> OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page