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

Creación de plugins

Plugins extiende OpenClaw sin cambiar 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 necesitas añadir 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 paquete sin prefijo todavía se instalan desde npm durante la transición de lanzamiento. Usa el prefijo clawhub: cuando quieras resolución de ClawHub.

Requisitos

  • Usa Node 22.19+, Node 23.11+ o Node 24+ y un gestor de paquetes como npm o pnpm.
  • Familiarízate con los módulos TypeScript ESM.
  • Para trabajar con Plugins incluidos en el repositorio, clona el repositorio y ejecuta pnpm install. El desarrollo de Plugins desde un checkout de código fuente solo admite pnpm porque OpenClaw carga los Plugins incluidos desde los paquetes de workspace extensions/*.

Elegir la forma del Plugin

Plugin de canal

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

Añade un proveedor de modelos, medios, búsqueda, fetch, 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 requerida. Esta es la forma de Plugin útil más corta y muestra 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 puntos de entrada.

    Todo Plugin necesita un manifiesto, incluso cuando no tiene configuración. Las herramientas de runtime deben aparecer en contracts.tools para que OpenClaw pueda descubrir la propiedad sin cargar con anticipación todos los runtimes de Plugins. Configura activation.onStartup de forma intencional. Este ejemplo se inicia al arrancar el Gateway.

    Las superficies de Plugin de confianza del host también están controladas por el manifiesto y requieren habilitación explícita para los Plugins instalados. Si un Plugin instalado registra api.registerAgentToolResultMiddleware(...), declara cada runtime de destino en contracts.agentToolResultMiddleware. Si registra api.registerTrustedToolPolicy(...), declara 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 son de canal. Los Plugins de canal usan defineChannelPluginEntry.

  • 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. Por ejemplo, un comando de demostración debería tener una prueba de ejecución como openclaw demo-plugin ping.

    Para un Plugin incluido en este repositorio, OpenClaw descubre paquetes de Plugins desde checkout de código fuente en el workspace extensions/*. Ejecuta la prueba dirigida 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 añade 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 checkouts de 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 OpenClaw por Plugin, por lo que detecta errores de dependencias de runtime que las pruebas desde checkout de código fuente pueden ocultar. Prueba la forma del paquete y sus 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 sin procesar desde archivo/ruta como prueba final para comportamiento de Plugins oficiales o privilegiados. Las fuentes sin procesar son útiles para depuración local, pero no prueban la misma ruta de dependencias que las instalaciones desde npm o ClawHub. Si tu Plugin depende de un estado de Plugin oficial de confianza, añade 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 Plugins para obtener detalles sobre 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 snippets canónicos 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 requeridas u opcionales. Las herramientas requeridas siempre están disponibles cuando el Plugin está habilitado. Las herramientas opcionales requieren que el usuario las habilite.

    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 la habilitan con tools.allow:

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

    Las herramientas opcionales controlan si una herramienta se expone al modelo. Usa solicitudes de permisos de Plugins 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 las herramientas principales; los conflictos se omiten y se informan en los diagnósticos del Plugin. Los registros malformados, incluidos descriptores de herramientas sin parameters, se omiten y se informan del mismo modo. Las herramientas registradas son funciones tipadas que el modelo puede llamar después de que pasen las comprobaciones de política y lista de permitidos.

    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. El objeto puede incluir provider, modelId y modelRef. Trátalo como metadatos informativos de runtime, no como una frontera de seguridad frente al operador local, el código de Plugins instalados o un runtime de OpenClaw modificado. Las herramientas locales sensibles aún deberían requerir la habilitación explícita del Plugin o del operador y fallar de forma cerrada cuando los metadatos del modelo activo falten o no sean adecuados.

    El manifiesto declara propiedad y descubrimiento; la ejecución todavía llama a la implementación registrada en vivo de la herramienta. 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 permitidos.

    Convenciones de importación

    Importa desde subrutas enfocadas 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 del proveedor salvo que la superficie sea verdaderamente genérica.

    Los métodos RPC personalizados de Gateway son un punto de entrada avanzado. Mantenlos bajo un prefijo específico del Plugin; los espacios de nombres de administración principal 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 Plugins que declaran contracts.gatewayMethodDispatch: ["authenticated-request"].

    Para ver el mapa completo de importaciones, consulta visión general del SDK de Plugins.

    Lista de verificació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 enfocadas plugin-sdk/<subpath> OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page