Herramientas de agente en plugins

Los plugins de OpenClaw pueden registrar herramientas de agente (funciones con esquema JSON) que se exponen al LLM durante las ejecuciones del agente. Las herramientas pueden ser requeridas (siempre disponibles) u opcionales (activación manual).

Las herramientas de agente se configuran bajo tools en la configuración principal, o por agente bajo agents.list[].tools. La política de allowlist/denylist controla qué herramientas puede llamar el agente.

Herramienta básica

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 }] };
    },
  });
}

Herramienta opcional (activación manual)

Las herramientas opcionales nunca se habilitan automáticamente. Los usuarios deben agregarlas a una allowlist del agente.

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 },
  );
}

Habilita herramientas opcionales en agents.list[].tools.allow (o tools.allow global):

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

Otros ajustes de configuración que afectan la disponibilidad de herramientas:

• Las allowlists que solo nombran herramientas de plugins se tratan como activaciones de plugins; las herramientas core permanecen habilitadas a menos que también incluyas herramientas o grupos core en la allowlist.
• tools.profile / agents.list[].tools.profile (allowlist base)
• tools.byProvider / agents.list[].tools.byProvider (allow/deny específico por proveedor)
• tools.sandbox.tools.* (política de herramientas en sandbox cuando está sandboxeado)

Reglas y consejos

• Los nombres de herramientas no deben coincidir con nombres de herramientas core; las herramientas en conflicto se omiten.
• Los ids de plugin usados en allowlists no deben coincidir con nombres de herramientas core.
• Prefiere optional: true para herramientas que desencadenan efectos secundarios o requieren binarios/credenciales adicionales.