Plugin-Agent-Tools

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

Agent-Tools werden unter tools in der Hauptkonfiguration oder pro Agent unter agents.list[].tools konfiguriert. Die Allowlist-/Denylist-Richtlinie 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. Benutzer 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 tools.allow):

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

Weitere Konfigurationsoptionen, die die Tool-Verfügbarkeit beeinflussen:

• Allowlists, die nur Plugin-Tools benennen, werden als Plugin-Opt-ins behandelt; Core-Tools bleiben aktiviert, es sei denn 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-spezifisches Allow/Deny)
• tools.sandbox.tools.* (Sandbox-Tool-Richtlinie bei Sandboxing)

Regeln und 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.
• Bevorzuge optional: true für Tools, die Seiteneffekte auslösen oder zusätzliche Binärdateien/Zugangsdaten erfordern.