Plugins de herramientas

defineToolPlugin crea un plugin que solo añade herramientas invocables por el agente: sin canal, proveedor de modelos, hook, servicio ni backend de configuración. Genera los metadatos del manifiesto que OpenClaw necesita para descubrir herramientas sin cargar el código de ejecución del plugin.

Para plugins de proveedor, canal, hook, servicio o capacidades mixtas, se debe comenzar con Creación de plugins, Plugins de canal o Plugins de proveedor.

Requisitos

• Node 22.22.3+, Node 24.15+ o Node 25.9+.
• Salida de paquete ESM de TypeScript.
• typebox en dependencies (no solo devDependencies; el plugin generado lo importa durante la ejecución).
• openclaw >=2026.5.17, la primera versión que exporta openclaw/plugin-sdk/tool-plugin.
• Una raíz de paquete que distribuya dist/, openclaw.plugin.json y package.json.

Inicio rápido

openclaw plugins init stock-quotes --name "Stock Quotes"cd stock-quotesnpm installnpm run plugin:buildnpm run plugin:validatenpm test

plugins init genera la estructura de:

npm run plugin:build ejecuta npm run build (tsc) y después openclaw plugins build --entry ./dist/index.js. npm run plugin:validate vuelve a compilar y ejecuta openclaw plugins validate --entry ./dist/index.js. Una validación correcta muestra:

El plugin stock-quotes es válido.

Opciones de openclaw plugins init <id>:

Escribir una herramienta

defineToolPlugin recibe la identidad del plugin, un esquema de configuración opcional y una lista estática de herramientas. Los tipos de parámetros y configuración se infieren de los esquemas de TypeBox.

  export default defineToolPlugin({  id: "stock-quotes",  name: "Cotizaciones bursátiles",  description: "Obtiene instantáneas de cotizaciones bursátiles.",  configSchema: Type.Object({    apiKey: Type.Optional(Type.String({ description: "Clave de la API de cotizaciones." })),    baseUrl: Type.Optional(Type.String({ description: "URL base de la API de cotizaciones." })),  }),  tools: (tool) => [    tool({      name: "stock_quote",      label: "Cotización bursátil",      description: "Obtiene una instantánea de una cotización bursátil.",      parameters: Type.Object({        symbol: Type.String({ description: "Símbolo bursátil, por ejemplo OPEN." }),      }),      outputSchema: Type.Object(        {          symbol: Type.String(),          configured: Type.Boolean(),          baseUrl: Type.String(),        },        { additionalProperties: false },      ),      async execute({ symbol }, config, context) {        context.signal?.throwIfAborted();        return {          symbol: symbol.toUpperCase(),          configured: Boolean(config.apiKey),          baseUrl: config.baseUrl ?? "https://api.example.com",        };      },    }),  ],});

Los nombres de herramientas son la API estable. Se deben elegir nombres únicos, en minúsculas y lo bastante específicos para evitar colisiones con las herramientas del núcleo u otros plugins.

Herramientas opcionales y de fábrica

Se debe establecer optional: true cuando los usuarios deban incluir explícitamente la herramienta en la lista de permitidas antes de enviarla a un modelo. openclaw plugins build escribe la entrada de manifiesto toolMetadata.<tool>.optional correspondiente, para que OpenClaw pueda determinar que la herramienta es opcional sin cargar el código de ejecución del plugin.

tool({  name: "workflow_run",  description: "Ejecuta un flujo de trabajo externo.",  parameters: Type.Object({ goal: Type.String() }),  optional: true,  execute: ({ goal }) => ({ queued: true, goal }),});

Se debe usar factory cuando una herramienta necesite el contexto de herramientas de ejecución antes de poder crearse: para excluirla de una ejecución específica, inspeccionar el estado del entorno aislado o vincular utilidades de ejecución. Los metadatos permanecen estáticos aunque la herramienta concreta se cree durante la ejecución.

tool({  name: "local_workflow",  description: "Ejecuta un flujo de trabajo local fuera de las sesiones aisladas.",  parameters: Type.Object({ goal: Type.String() }),  optional: true,  factory({ api, toolContext }) {    if (toolContext.sandboxed) {      return null;    }    return createLocalWorkflowTool(api);  },});

Las fábricas siguen declarando por adelantado un nombre de herramienta fijo. Se debe usar definePluginEntry directamente cuando el plugin calcule los nombres de las herramientas de forma dinámica o combine herramientas con hooks, servicios, proveedores o comandos.

Valores devueltos

defineToolPlugin encapsula los valores devueltos simples en el formato de resultado de herramientas de OpenClaw:

• Se debe devolver una cadena cuando el modelo deba ver exactamente ese texto.
• Se debe devolver un valor compatible con JSON cuando se quiera que el modelo vea JSON con formato y que OpenClaw conserve el valor original en details.

tool({  name: "echo_text",  description: "Repite el texto de entrada.",  parameters: Type.Object({    input: Type.String(),  }),  execute: ({ input }) => input,});

tool({  name: "echo_json",  description: "Repite la entrada como JSON estructurado.",  parameters: Type.Object({    input: Type.String(),  }),  execute: ({ input }) => ({ input, length: input.length }),});

Se debe usar una herramienta de fábrica cuando se necesite un AgentToolResult personalizado o se quiera reutilizar una implementación existente de api.registerTool.

Contratos de salida

Se debe añadir outputSchema cuando una herramienta devuelva datos estables compatibles con JSON. Describe el valor original almacenado en AgentToolResult.details, no el texto con formato de content:

tool({  name: "shipment_list",  description: "Enumera los envíos.",  parameters: Type.Object({    buyer: Type.Optional(Type.String()),  }),  outputSchema: Type.Array(    Type.Object(      {        id: Type.String(),        buyer: Type.String(),        paid: Type.Boolean(),        tons: Type.Number(),      },      { additionalProperties: false },    ),  ),  execute: ({ buyer }) => listShipments(buyer),});

Modo de código y Búsqueda de herramientas convierten este esquema en una indicación de salida acotada con estilo de TypeScript. Esto permite que un modelo invoque y transforme un resultado conocido en un solo programa, en lugar de emplear otro turno del modelo para observar su estructura.

OpenClaw compila el esquema antes de ejecutar una llamada al catálogo y después valida el valor final de details tras los hooks de herramientas, antes de devolverlo mediante el puente. Un esquema no válido impide ejecutar la herramienta; una discrepancia en el resultado hace que falle la llamada completada. Se deben incluir todas las variantes de resultados que no generen excepciones, incluidas las variantes de error estructuradas, u omitir el esquema cuando el resultado no sea estable. No se deben incluir secretos ni valores confidenciales en las descripciones del esquema, ya que los metadatos de salida de confianza pueden quedar visibles para el modelo. Se debe usar { additionalProperties: false } en las capas de objetos cuando se quiera una indicación de salida compacta y completa; los esquemas abiertos o truncados siguen estando disponibles mediante tools.describe(...), pero no se anuncian como contratos completos de índice rápido.

Las herramientas de fábrica declaran outputSchema en el AnyAgentTool concreto que devuelven. La declaración estática tool({ factory }) no acepta un esquema de salida independiente porque podría divergir de la herramienta de ejecución.

Configuración

configSchema es opcional. Si se omite, OpenClaw aplica un esquema estricto de objeto vacío; el manifiesto generado sigue incluyendo configSchema.

export default defineToolPlugin({  id: "no-config-tools",  name: "Herramientas sin configuración",  description: "Añade herramientas que no necesitan configuración.",  tools: () => [],});

Con un configSchema, el segundo argumento de execute se tipa a partir de él:

const configSchema = Type.Object({  apiKey: Type.String(),}); export default defineToolPlugin({  id: "configured-tools",  name: "Herramientas configuradas",  description: "Añade herramientas configuradas.",  configSchema,  tools: (tool) => [    tool({      name: "configured_ping",      description: "Comprueba si la configuración está disponible.",      parameters: Type.Object({}),      execute: (_params, config) => ({ hasKey: config.apiKey.length > 0 }),    }),  ],});

OpenClaw lee la configuración del plugin desde la entrada del plugin en la configuración del Gateway. No se deben codificar secretos directamente en el código fuente ni en los ejemplos de documentación; se debe usar la configuración, las variables de entorno o SecretRefs de acuerdo con el modelo de seguridad del plugin.

Metadatos generados

OpenClaw debe leer el manifiesto del plugin antes de importar el código de ejecución del plugin. defineToolPlugin expone metadatos estáticos para ello y openclaw plugins build los escribe en el paquete. Se debe volver a ejecutar el generador después de cambiar el id, el nombre, la descripción, el esquema de configuración, la activación o los nombres de las herramientas del plugin:

npm run buildopenclaw plugins build --entry ./dist/index.js

Manifiesto generado para un plugin con una herramienta:

{  "id": "stock-quotes",  "name": "Stock Quotes",  "description": "Fetch stock quote snapshots.",  "version": "0.1.0",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  },  "activation": {    "onStartup": true  },  "contracts": {    "tools": ["stock_quote"]  }}

contracts.tools es el contrato de descubrimiento importante: indica a OpenClaw qué plugin posee cada herramienta sin cargar el entorno de ejecución de todos los plugins instalados. Un manifiesto obsoleto puede hacer que una herramienta no aparezca en el descubrimiento o que un error de registro se atribuya al plugin equivocado.

Metadatos del paquete

openclaw plugins build también alinea package.json con la entrada de ejecución seleccionada:

{  "type": "module",  "files": ["dist", "openclaw.plugin.json", "README.md"],  "dependencies": {    "typebox": "^1.1.38"  },  "peerDependencies": {    "openclaw": ">=2026.5.17"  },  "openclaw": {    "extensions": ["./dist/index.js"]  }}

Se debe distribuir JavaScript compilado (./dist/index.js), no una entrada de código fuente TypeScript. Las entradas de código fuente solo funcionan para el desarrollo local en el espacio de trabajo.

Validación en CI

plugins build --check falla sin reescribir archivos cuando los metadatos generados están obsoletos:

npm run buildopenclaw plugins build --entry ./dist/index.js --checkopenclaw plugins validate --entry ./dist/index.jsnpm test

Los campos de compatibilidad del SDK de OpenClaw incluyen anotaciones @deprecated de TypeScript, que los editores muestran como advertencias de migración. Para aplicarlas en CI, se debe habilitar una regla con conocimiento de tipos como @typescript-eslint/no-deprecated. Oxlint no tiene conocimiento de tipos, por lo que no puede aplicar estas anotaciones. Por tanto, la estructura plugins init generada no añade una configuración de lint para elementos obsoletos.

plugins validate comprueba que:

• openclaw.plugin.json existe y pasa el cargador de manifiestos normal.
• La entrada actual exporta los metadatos de defineToolPlugin.
• Los campos del manifiesto generado coinciden con los metadatos de la entrada.
• contracts.tools coincide con los nombres de herramientas declarados.
• package.json dirige openclaw.extensions a la entrada de runtime seleccionada.

Instalar e inspeccionar localmente

Desde otro checkout de OpenClaw o una CLI instalada, instale la ruta del paquete:

openclaw plugins install ./stock-quotesopenclaw plugins inspect stock-quotes --runtime

Para realizar una prueba de humo del paquete, empaquételo primero e instale el archivo tar:

npm packopenclaw plugins install npm-pack:./openclaw-plugin-stock-quotes-0.1.0.tgzopenclaw plugins inspect stock-quotes --runtime --json

Después de la instalación, reinicie o recargue el Gateway y solicite al agente que use la herramienta. Si la herramienta no está visible, inspeccione el runtime del plugin y el catálogo efectivo de herramientas antes de cambiar el código (consulte Solución de problemas).

Publicar

Publique mediante ClawHub cuando el paquete esté listo. clawhub package publish acepta un origen: una carpeta local, un repositorio de GitHub (owner/repo[@ref]) o una URL de un archivo tar.

clawhub package publish ./stock-quotes --dry-runclawhub package publish ./stock-quotes

Instale con un localizador explícito de ClawHub:

openclaw plugins install clawhub:your-org/stock-quotes

Las especificaciones simples de paquetes npm siguen instalándose desde npm durante la transición del lanzamiento, pero ClawHub es la superficie preferida para descubrir y distribuir plugins de OpenClaw. Consulte Publicación en ClawHub para obtener información sobre el ámbito del propietario y la revisión de versiones.

Solución de problemas

plugin entry not found: ./dist/index.js

El archivo de entrada seleccionado no existe. Ejecute npm run build y, a continuación, vuelva a ejecutar openclaw plugins build --entry ./dist/index.js o openclaw plugins validate --entry ./dist/index.js.

plugin entry does not expose defineToolPlugin metadata

La entrada no exportó un valor creado por defineToolPlugin. Confirme que la exportación predeterminada del módulo sea el resultado de defineToolPlugin(...) o proporcione la entrada correcta mediante --entry.

openclaw.plugin.json generated metadata is stale

El manifiesto ya no coincide con los metadatos de la entrada. Ejecute:

npm run buildopenclaw plugins build --entry ./dist/index.js

Confirme los cambios de openclaw.plugin.json y package.json.

package.json openclaw.extensions must include ./dist/index.js

Los metadatos del paquete apuntan a una entrada de runtime diferente. Ejecute openclaw plugins build --entry ./dist/index.js para que el generador alinee los metadatos del paquete con la entrada que se pretende publicar.

Cannot find package 'typebox'

El plugin compilado importa typebox durante el runtime. Manténgalo en dependencies, vuelva a instalar, compile de nuevo y repita la validación.

La herramienta no aparece después de la instalación

Compruebe lo siguiente en orden:

1. openclaw plugins inspect <plugin-id> --runtime
2. openclaw plugins validate --root <plugin-root> --entry ./dist/index.js
3. openclaw.plugin.json tiene contracts.tools con los nombres de herramientas esperados.
4. package.json tiene openclaw.extensions: ["./dist/index.js"].
5. El Gateway se reinició o recargó después de instalar el plugin.

Véase también

• Compilación de plugins
• Puntos de entrada de plugins
• Subrutas del SDK de plugins
• Manifiesto del plugin
• CLI de plugins
• Publicación en ClawHub