Cómo registrar agent tools en tus plugins de OpenClaw

¿Alguna vez has sentido que tu agente es muy inteligente pero está “atrapado” sin poder interactuar con el mundo real? Es frustrante cuando el modelo sabe exactamente qué debe hacer, pero no tiene las herramientas para ejecutar un script local o consultar una API específica.

Para solucionar esto, puedes usar los plugins de OpenClaw para registrar agent tools. Estas herramientas son funciones basadas en JSON-schema que el LLM puede detectar y llamar durante su ejecución.

Requisitos previos

• Una instancia de OpenClaw funcionando.
• Un plugin básico donde registrarás tus funciones.

Inicio rápido

Puedes definir herramientas que estén siempre disponibles o herramientas opcionales que el usuario debe habilitar manualmente. Mi recomendación es usar optional: true para cualquier acción que tenga efectos secundarios o requiera credenciales extra.

1. Registrar una herramienta básica

Usa api.registerTool dentro de tu plugin. Este es el camino más rápido para exponer una función:

import { Type } from "@sinclair/typebox";

export default function (api) {
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({
      input: Type.String(),
    }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });
}

2. Crear una herramienta opcional (Opt-in)

Las herramientas opcionales no se activan solas. Esto es ideal para flujos de trabajo locales que no quieres que cualquier agente use por defecto.

export default function (api) {
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a local workflow",
      parameters: {
        type: "object",
        properties: {
          pipeline: { type: "string" },
        },
        required: ["pipeline"],
      },
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

3. Habilitar herramientas en la configuración

Para que tu agente pueda ver las herramientas opcionales, debes agregarlas al allowlist en tu archivo de configuración, ya sea de forma global o por agente:

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          allow: [
            "workflow_tool", // nombre específico de la herramienta
            "workflow", // ID del plugin (habilita todas sus herramientas)
            "group:plugins", // todas las herramientas de plugins
          ],
        },
      },
    ],
  },
}

Ten en cuenta que si el allowlist solo menciona herramientas de plugins, las herramientas del core seguirán activas a menos que las restrinjas explícitamente. También puedes usar tools.byProvider para un control más fino por proveedor o tools.sandbox si trabajas en entornos aislados.

Solución de problemas

• Conflictos de nombres: Si el nombre de tu tool coincide con una core tool del sistema, OpenClaw la ignorará. Asegúrate de usar nombres únicos.
• IDs de plugins: Evita que el ID de tu plugin choque con los nombres de las herramientas integradas, ya que esto causará problemas en el allowlist.

¿Necesitas ayuda para configurar el entorno? Prueba el AI Setup Assistant.

Próximos pasos

• Configuración avanzada de tools.profile.
• Uso de tools.byProvider para límites específicos.