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 de agente, un hook, un proveedor multimedia u otra capacidad perteneciente al 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 desee 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 a partir de 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, voz o tiempo real.
Plugin de backend de CLI

Ejecute una CLI de IA local mediante el mecanismo alternativo de modelos de OpenClaw.
Plugin de herramientas

Registre herramientas de agente.

Inicio rápido

Cree un Plugin de herramientas mínimo registrando una herramienta de agente obligatoria. Esta es la estructura de Plugin útil más breve 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.

    Todo Plugin necesita un manifiesto, incluso si no tiene configuración. Las herramientas de ejecución deben aparecer en contracts.tools para que OpenClaw pueda descubrir su propietario sin cargar anticipadamente el entorno de ejecución de cada Plugin. Defina activation.onStartup deliberadamente; este ejemplo se carga al iniciar el Gateway.

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

    Para consultar todos los campos del manifiesto, consulte Manifiesto de Plugins.

  • 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() }),      outputSchema: Type.Object(        { input: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        const details = { input: params.input };        return {          content: [{ type: "text", text: `Got: ${params.input}` }],          details,        };      },    });  },});

    Use definePluginEntry para los Plugins que no sean de canal. En su lugar, los Plugins de canal usan defineChannelPluginEntry de openclaw/plugin-sdk/core.

  • Probar el entorno de ejecución

    Para un Plugin instalado o externo, inspeccione el entorno de ejecución cargado:

    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 a JavaScript compilado como ./dist/index.js y asegúrese 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.

    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 administrado por OpenClaw para cada Plugin, por lo que detecta errores de dependencias de ejecución que las pruebas en una copia del código fuente pueden ocultar. Demuestra la estructura del paquete y de las 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 para el proyecto de ejecución administrado.

    No use una instalación directa desde un archivo o una ruta como verificación final del comportamiento oficial o privilegiado de un Plugin. El código fuente directo resulta útil para la depuración local, pero no demuestra la misma ruta de dependencias que las instalaciones desde npm o ClawHub. Si el Plugin depende del estado de Plugin oficial de confianza, 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 obtener detalles sobre 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

    • Registro de herramientas

    Las herramientas pueden ser obligatorias u opcionales. Las herramientas obligatorias siempre están disponibles cuando el Plugin está habilitado. Las herramientas opcionales requieren que el usuario acepte explícitamente su uso antes de que OpenClaw cargue el entorno de ejecución del Plugin propietario.

    Las fábricas de herramientas reciben 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() }),      outputSchema: Type.Object(        { pipeline: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        return {          content: [{ type: "text", text: params.pipeline }],          details: { pipeline: params.pipeline },        };      },    },    { optional: true },  );}

    outputSchema es opcional. Describe el valor estructurado details que usan Modo de código y Búsqueda de herramientas. Las llamadas al catálogo rechazan los esquemas no válidos antes de la ejecución y validan el valor final después de los hooks de herramientas. Omítalo en las herramientas que no tengan un resultado JSON estable. Consulte Plugins de herramientas para conocer el contrato completo.

    Cada 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 su uso mediante 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 los diagnósticos de Plugins. Los registros con formato incorrecto 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 del turno actual; puede incluir provider, modelId y modelRef. Trátelo como metadatos informativos del entorno de ejecución, no como una barrera 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 aceptación explícita del Plugin o del operador y cerrarse de forma segura cuando falten los metadatos del modelo activo o estos 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 el entorno de 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

    Dentro del paquete del Plugin, use archivos de barril 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 el límite sea verdaderamente genérico.

    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 rutas HTTP de Plugins que declaren contracts.gatewayMethodDispatch: ["authenticated-request"].

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

    Los campos de compatibilidad del SDK de OpenClaw incluyen anotaciones @deprecated de TypeScript, que los editores muestran como advertencias de migración. Para aplicarlas durante la compilación, habilite una regla que tenga en cuenta los tipos, como @typescript-eslint/no-deprecated. Oxlint no tiene en cuenta los tipos, por lo que no puede aplicar estas anotaciones.

    Lista de comprobación previa al envío

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json tiene 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 plugin-sdk/<subpath> específicas OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page