Plugin Agent Tools: So erweiterst du deine KI-Agenten

Es ist frustrierend, wenn dein LLM zwar theoretisch alles weiß, aber praktisch nicht auf deine lokalen Daten oder Funktionen zugreifen kann. Meistens verbringst du mehr Zeit damit, die Schnittstellen zu definieren, als die eigentliche Logik zu schreiben.

Hier helfen Agent Tools. Sie erlauben es deinen Plugins, Funktionen direkt für das LLM bereitzustellen, damit dein Agent Aufgaben nicht nur plant, sondern auch ausführt.

Voraussetzungen

• Ein laufendes OpenClaw Setup
• @sinclair/typebox für die Schema-Definition
• Zugriff auf die tools Sektion deiner Config

Schnellstart

In nur 5 Minuten registrierst du dein erstes Tool. Du kannst Tools entweder als Standard-Tools (immer verfügbar) oder als optionale Tools (opt-in) anlegen.

1. Ein einfaches Tool registrieren

Verwende die api.registerTool Methode in deinem Plugin. Hier ist ein Beispiel für ein Tool, das Text zurückgibt:

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. Ein optionales Tool erstellen

Für Aktionen mit Seiteneffekten solltest du optional: true setzen. Diese Tools muss der Nutzer explizit aktivieren.

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. Tools in der Config freischalten

Damit ein Agent das optionale Tool nutzen kann, fügst du es der allow-Liste in deiner Config hinzu:

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          allow: [
            "workflow_tool", // Einzelner Tool-Name
            "workflow", // Plugin ID (schaltet alle Tools des Plugins frei)
            "group:plugins", // Alle Plugin-Tools
          ],
        },
      },
    ],
  },
}

Fehlerbehebung

• Tool wird nicht geladen: Prüfe, ob der Name mit einem Core-Tool kollidiert. Wenn das passiert, wird dein Tool automatisch übersprungen.
• Optionales Tool erscheint nicht: Diese Tools sind niemals automatisch aktiviert. Du musst sie zwingend in agents.list[].tools.allow oder der globalen tools.allow Liste eintragen.
• Plugin-ID Konflikte: Achte darauf, dass Plugin-IDs in der Allowlist nicht wie Core-Tools heißen.
• Sicherheits-Hinweis: Nutze optional: true für alle Tools, die externe Binaries oder Zugangsdaten benötigen.

Du suchst nach einer spezifischen Lösung für dein Setup? Frag den AI Setup Assistant.

Nächste Schritte

• tools.profile: Standard-Berechtigungen festlegen
• tools.byProvider: Provider-spezifische Regeln konfigurieren
• tools.sandbox.tools.*: Sandbox-Policies für Tools
• Plugin-IDs und Versionierung