Plugin Agent-Tools

OpenClaw Plugins können Agent-Tools (JSON-Schema-Funktionen) registrieren, die dem LLM während Agent-Läufen zur Verfügung stehen. Tools können required (immer verfügbar) oder optional (opt-in) sein.

Agent-Tools werden unter tools in der Hauptkonfiguration konfiguriert, oder pro Agent unter agents.list[].tools. Die Allowlist/Denylist-Policy steuert, welche Tools der Agent aufrufen kann.

Einfaches Tool

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

Optionales Tool (opt-in)

Optionale Tools werden nie automatisch aktiviert. Nutzer müssen sie zu einer Agent-Allowlist hinzufügen.

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

Aktiviere optionale Tools in agents.list[].tools.allow (oder global in tools.allow):

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          allow: [
            "workflow_tool", // spezifischer Tool-Name
            "workflow", // Plugin-ID (aktiviert alle Tools aus diesem Plugin)
            "group:plugins", // alle Plugin-Tools
          ],
        },
      },
    ],
  },
}

Weitere Config-Optionen, die die Tool-Verfügbarkeit beeinflussen:

• Allowlists, die nur Plugin-Tools nennen, werden als Plugin-Opt-ins behandelt; Core-Tools bleiben aktiviert, außer du nimmst auch Core-Tools oder Gruppen in die Allowlist auf.
• tools.profile / agents.list[].tools.profile (Basis-Allowlist)
• tools.byProvider / agents.list[].tools.byProvider (Provider-spezifische Allow/Deny)
• tools.sandbox.tools.* (Sandbox-Tool-Policy im Sandbox-Modus)

Regeln + Tipps

• Tool-Namen dürfen nicht mit Core-Tool-Namen kollidieren; kollidierende Tools werden übersprungen.
• Plugin-IDs in Allowlists dürfen nicht mit Core-Tool-Namen kollidieren.
• Nutze optional: true für Tools, die Seiteneffekte auslösen oder zusätzliche Binaries/Credentials benötigen.