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 de medios u otra capacidad propiedad 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 todavía se instalan desde npm durante la transición del lanzamiento. Utilice el prefijo clawhub: cuando quiera usar la resolución de ClawHub.

Requisitos

  • Node 22.22.3+, Node 24.15+ o Node 25.9+, y npm o pnpm.
  • Módulos ESM de TypeScript.
  • Para trabajar en 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, medios, búsqueda, obtención, 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 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 hacer que las entradas de ejecución apunten a archivos JavaScript compilados. Consulte Puntos de entrada del SDK para conocer el contrato completo de los puntos de entrada.

    Cada 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 propiedad sin cargar de forma anticipada 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 controladas 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 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 conocer 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() }),      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,        };      },    });  },});

    Utilice definePluginEntry para los plugins que no sean de canal. Los plugins de canal utilizan en su lugar 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 a partir del 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 forma de instalación que recibirán los usuarios. Primero añada un paso de compilación, haga que las entradas de ejecución como openclaw.extensions apunten 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.

    A continuación, 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: utiliza el proyecto npm administrado por OpenClaw para cada plugin, por lo que detecta errores en las dependencias de ejecución que las pruebas desde una copia del código fuente pueden ocultar. Demuestra la estructura del paquete y de sus dependencias, no la confianza oficial vinculada al catálogo. Las importaciones del entorno de ejecución deben estar en dependencies o optionalDependencies; las dependencias que solo figuren en devDependencies no se instalarán para el proyecto de entorno 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 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 su 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

    • Registrar herramientas

    Las herramientas pueden ser obligatorias u opcionales. Las herramientas obligatorias están siempre disponibles cuando el plugin está habilitado. Las herramientas opcionales requieren la aceptación explícita del usuario antes de que OpenClaw cargue el entorno de 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() }),      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 utilizado por 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 para 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. Utilice solicitudes de permisos de plugins cuando una herramienta o un hook deba solicitar aprobación después de que el modelo lo seleccione y antes de que se ejecute la acción.

    Utilice 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. Utilice 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 un límite 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 rechazar la ejecución cuando los metadatos del modelo activo falten o no sean adecuados.

    El manifiesto declara la propiedad y el descubrimiento; la ejecución sigue invocando la implementación de la herramienta registrada en vivo. 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, utilice archivos de barril locales como api.ts y runtime-api.ts para las importaciones internas. No importe su propio plugin mediante una ruta del SDK. Los auxiliares específicos del proveedor deben permanecer en el paquete del proveedor, salvo que el punto de integración sea verdaderamente genérico.

    Los métodos RPC personalizados del Gateway son un punto de entrada avanzado. Manténgalos en 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 declaran contracts.gatewayMethodDispatch: ["authenticated-request"].

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

    Los campos de compatibilidad del SDK de OpenClaw contienen 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