OpenClaw Tools richtig konfigurieren

Kennst du das? Du versuchst, deinem Agent neue Fähigkeiten beizubringen, landest aber in einem Chaos aus externen Skripten und Shell-Befehlen. Die Verwaltung von Berechtigungen wird schnell unübersichtlich, wenn du nicht genau steuern kannst, worauf der Agent Zugriff hat und welche Befehle er wirklich ausführen darf.

OpenClaw löst das mit nativen Tools für Browser, Canvas, Nodes und Cron. Diese ersetzen die alten openclaw-* Skills. Die neuen Tools sind typisiert, benötigen kein Shelling und werden vom Agent direkt angesprochen.

Voraussetzungen

• Eine openclaw.json Konfigurationsdatei
• Installierte OpenClaw-Umgebung

Schnellstart

In 5 Minuten hast du deine Tool-Berechtigungen im Griff. Du steuerst den Zugriff global über tools.allow und tools.deny in deiner openclaw.json. Dabei gilt: deny gewinnt immer.

1. Tools deaktivieren: Wenn du den Browser-Zugriff global verbieten willst, füge dies deiner Konfiguration hinzu:

   {
     tools: { deny: ["browser"] },
   }

2. Profile nutzen: Statt jedes Tool einzeln aufzulisten, nutzt du tools.profile. Das setzt eine Basis-Allowlist.

   Beispiel für ein Messaging-Setup, das zusätzlich Slack und Discord erlaubt:

   {
     tools: {
       profile: "messaging",
       allow: ["slack", "discord"],
     },
   }

Tool-Profile im Detail

Profile helfen dir, schnell passende Berechtigungen zu setzen. Du kannst sie global oder pro Agent unter agents.list[].tools.profile definieren.

• minimal: Nur session_status
• coding: group:fs, group:runtime, group:sessions, group:memory, image
• messaging: group:messaging, sessions_list, sessions_history, sessions_send, session_status
• full: Keine Einschränkungen (entspricht dem Standardwert)

Hier siehst du, wie du ein globales Coding-Profil setzt, aber für einen spezifischen Support-Agent auf Messaging umstellst:

{
  tools: { profile: "coding" },
  agents: {
    list: [
      {
        id: "support",
        tools: { profile: "messaging", allow: ["slack"] },
      },
    ],
  },
}

Fehlerbehebung

• Warnung bei unbekannten Plugins: Wenn du in tools.allow nur Namen verwendest, die OpenClaw nicht kennt oder die nicht geladen wurden, loggt das System eine Warnung. Die Allowlist wird dann ignoriert, damit die Core-Tools verfügbar bleiben.
• Wildcards: Du kannst * als Wildcard nutzen. "*" erlaubt oder verbietet alle Tools.
• Groß- und Kleinschreibung: Das Matching der Tool-Namen ist Case-Insensitive.
• Runtime sperren: Wenn du das coding Profil nutzt, aber Ausführungsrechte unterbinden willst, kombiniere es mit deny:

  {
    tools: {
      profile: "coding",
      deny: ["group:runtime"],
    },
  }

Hast du Fragen zur Einrichtung? Nutze den AI Setup Assistant.

Nächste Schritte

• Agent-Konfiguration vertiefen
• Eigene Plugins erstellen

Kennst du das? Du hast ein Toolset gebaut, das mit den meisten Modellen super funktioniert. Aber dann gibt es diesen einen Provider oder ein spezielles Modell, das bei bestimmten API-Aufrufen ständig halluziniert oder bei komplexen Tools überfordert ist. Es ist frustrierend, wenn du dein gesamtes Setup für alle Modelle herabstufen musst, nur weil ein einzelner Endpoint nicht mitspielt.

Anstatt den kleinsten gemeinsamen Nenner für alle zu suchen, solltest du die Kontrolle pro Provider übernehmen. So bleibt dein System flexibel und stabil.

Voraussetzungen

• Eine Konfigurationsdatei mit tools-Definitionen
• Zugriff auf die agents.list, falls du Overrides pro Agent brauchst

Schnellstart

Nutze tools.byProvider, um Tools für spezifische Provider (oder eine provider/model-Kombination) weiter einzuschränken. Deine globalen Defaults bleiben dabei unberührt. Du kannst diese Regel auch pro Agent überschreiben: agents.list[].tools.byProvider.

Wichtig für die Logik: Diese Regel wird nach dem Basis-Tool-Profil und vor den Allow/Deny-Listen angewendet. Das bedeutet, du kannst das Toolset damit nur verkleinern (narrow), nicht erweitern.

Als Keys akzeptiert das System entweder den Provider (z. B. google-antigravity) oder die Kombination provider/model (z. B. openai/gpt-5.2).

Beispiel: Globales Profil mit Ausnahme

Hier behältst du das globale coding-Profil bei, schränkst Google Antigravity aber auf ein Minimum ein:

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

Beispiel: Spezifische Allowlist für instabile Endpoints

Wenn ein Modell bei bestimmten Tools Probleme macht, kannst du eine gezielte Allowlist definieren:

{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

Beispiel: Agent-spezifischer Override

Du kannst die Einschränkung auch direkt in der Konfiguration eines bestimmten Agents festlegen:

{
  agents: {
    list: [
      {
        id: "support",
        tools: {
          byProvider: {
            "google-antigravity": { allow: ["message", "sessions_list"] },
          },
        },
      },
    ],
  },
}

Fehlerbehebung

Ein Modell nutzt Tools, die es nicht nutzen sollte Prüfe die Reihenfolge deiner Konfiguration. Da byProvider nach dem Profil angewendet wird, stelle sicher, dass du das Profil korrekt benannt hast. Falls das Modell immer noch zu viele Tools sieht, nutze eine explizite allow-Liste innerhalb von byProvider.

Ein Endpoint ist unzuverlässig (flaky endpoint) Falls ein Modell bei bestimmten Tool-Gruppen Fehler produziert, nutze die provider/model-Syntax, um genau diesen Endpoint auf eine sicherere Liste an Tools zu begrenzen.

Du hast Fragen zu deinem speziellen Setup? Der AI Setup Assistant hilft dir direkt weiter.

Nächste Schritte

• Tool Profiles Übersicht
• Agent Configuration Guide

Es ist immer das Gleiche: Du baust einen Agenten und musst mühsam jedes einzelne Tool freischalten. Eine lange Liste von Berechtigungen wird schnell unübersichtlich und führt dazu, dass du den Überblick über die Sicherheit verlierst.

Statt jedes Tool einzeln aufzuführen, kannst du Shorthands nutzen. Das spart Zeit und macht deine Konfiguration deutlich sauberer.

Voraussetzungen

• Tool-Policies (global, agent oder sandbox)
• Zugriff auf die Konfiguration von tools.allow oder tools.deny

Schnellstart

Tool-Policies unterstützen group:* Einträge, die automatisch zu mehreren Tools expandieren. Du kannst diese Gruppen direkt in deinen tools.allow oder tools.deny Listen verwenden.

Hier sind die verfügbaren Gruppen:

• group:runtime: exec, bash, process
• group:fs: read, write, edit, apply_patch
• group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
• group:memory: memory_search, memory_get
• group:web: web_search, web_fetch
• group:ui: browser, canvas
• group:automation: cron, gateway
• group:messaging: message
• group:nodes: nodes
• group:openclaw: Alle integrierten OpenClaw-Tools (exklusive Provider-Plugins)

Hier ist ein Beispiel, wie du nur Dateisystem-Tools und den Browser erlaubst:

{
  tools: {
    allow: ["group:fs", "browser"],
  },
}

Plugins und zusätzliche Tools

Plugins können über das Core-Set hinaus weitere Tools und CLI-Befehle registrieren. Informationen zur Installation findest du unter Plugins. Wie Tool-Anleitungen in Prompts eingefügt werden, erfährst du unter Skills. Einige Plugins, wie das für Voice-Calls, liefern ihre eigenen Skills direkt mit.

Es gibt zudem optionale Plugin-Tools:

• Lobster: Eine Runtime für getypte Workflows mit approvals (erfordert die Lobster CLI auf dem Gateway-Host).
• LLM Task: Ein reiner JSON-LLM-Schritt für strukturierten Workflow-Output (optional mit Schema-Validierung).

Fehlerbehebung

• Tool wird nicht gefunden: Wenn du ein Tool aus einem Plugin nutzt, prüfe unter Plugins, ob die Installation und Config korrekt sind.
• Lobster-Fehler: Stelle sicher, dass die Lobster CLI tatsächlich auf dem Gateway-Host installiert ist, da das Tool sonst nicht ausgeführt werden kann.

Frag unseren AI Setup Assistant, falls du Hilfe bei der Einrichtung brauchst.

Nächste Schritte

• Plugins
• Skills
• Lobster
• LLM Task

Du kennst das Problem: Dein Agent hat einen Plan, aber ihm fehlen die Hände, um ihn umzusetzen. Er weiß, was im Code geändert werden muss, kann aber die Datei nicht speichern oder die Shell nicht bedienen, um die Tests zu starten.

Meistens verbringst du mehr Zeit damit, Berechtigungen zu fixen oder APIs zu verbinden, als am eigentlichen Prompt zu arbeiten. OpenClaw löst das mit einem fertigen Set an Tools, die deinem Agenten direkten Zugriff auf das System und das Web geben.

Voraussetzungen

Bevor du die Tools nutzt, stelle sicher, dass folgende Voraussetzungen erfüllt sind (je nach Tool):

• OpenAI Modelle (erforderlich für apply_patch)
• Ein Brave API Key (für web_search, konfigurierbar via openclaw configure --section web)
• Installiertes Playwright (für browser Snapshots)
• Konfiguriertes agents.defaults.imageModel (für das image Tool)
• Gateway Zugriff für cron oder gateway Aktionen

Schnellstart

In 5 Minuten hast du die wichtigsten Tools einsatzbereit:

1. Shell-Zugriff: Nutze exec, um Befehle in der Sandbox auszuführen.

   {
     "command": "ls -la",
     "host": "sandbox"
   }

2. Web-Suche: Aktiviere Brave Search, indem du deinen API Key in der Config hinterlegst. Dein Agent kann dann mit web_search das Internet durchforsten.
3. Browser-Steuerung: Wenn browser.enabled auf true steht, kann dein Agent direkt Chrome-Instanzen starten und UI-Aktionen ausführen.

---

Tool Übersicht

apply_patch

Wende strukturierte Patches auf eine oder mehrere Dateien an. Ideal für Änderungen über mehrere Code-Blöcke hinweg. Hinweis: Aktuell experimentell und nur für OpenAI Modelle über tools.exec.applyPatch.enabled verfügbar.

exec

Führt Shell-Befehle im Workspace aus.

Parameter:

• command (erforderlich)
• yieldMs: Automatischer Hintergrundmodus nach Zeitablauf (Standard: 10000).
• background: Sofortiger Hintergrundmodus.
• timeout: Killt den Prozess nach X Sekunden (Standard: 1800).
• elevated: Führt den Befehl auf dem Host aus, falls der Modus erlaubt ist.
• host: sandbox | gateway | node
• security: deny | allowlist | full
• ask: off | on-miss | always
• node: ID/Name für host=node.
• pty: Auf true setzen, wenn ein echtes TTY benötigt wird.

Details:

• Gibt status: "running" mit einer sessionId zurück, wenn der Prozess im Hintergrund läuft.
• Nutze process, um Hintergrund-Sessions zu steuern.
• elevated ist ein Alias für host=gateway + security=full und wird durch tools.elevated und agents.list[].tools.elevated gesteuert.

process

Verwalte deine Hintergrund-Sessions von exec. Aktionen: list, poll, log, write, kill, clear, remove. Hinweis: poll liefert neuen Output und den Exit-Status. log unterstützt offset und limit für zeilenbasiertes Auslesen.

web_search

Suche im Web über die Brave Search API. Parameter: query (erforderlich), count (1–10). Setup: Benötigt einen Brave API Key (openclaw configure --section web) und tools.web.search.enabled.

web_fetch

Extrahiert lesbaren Inhalt von einer URL (HTML zu Markdown oder Text). Parameter: url (erforderlich), extractMode (markdown | text), maxChars. Hinweis: Ergebnisse werden 15 Minuten gecached. Bei Seiten mit viel JavaScript solltest du das browser Tool vorziehen. Details findest du unter Web tools und Firecrawl.

browser

Steuert einen dedizierten, von OpenClaw verwalteten Browser.

Kern-Aktionen:

• status, start, stop, tabs, open, focus, close
• snapshot (aria/ai)
• screenshot (liefert Image-Block + MEDIA:<path>)
• act: UI-Aktionen wie click, type, press, hover, drag, select, fill, resize, wait, evaluate.
• navigate, console, pdf, upload, dialog

Profil-Management:

• profiles: Liste alle Profile.
• create-profile: Neues Profil mit Port-Allokation.
• delete-profile: Löscht User-Daten (nur lokal).

Wichtige Infos:

• Port-Bereich: 18800-18899.
• snapshot nutzt standardmäßig ai, wenn Playwright installiert ist.
• act benötigt eine ref aus einem snapshot.
• Vermeide wait in act, außer es gibt keinen stabilen UI-Status, auf den gewartet werden kann.

canvas

Steuert den Node Canvas (Präsentationen, Evaluation, Snapshots). Aktionen: present, hide, navigate, eval, snapshot, a2ui_push, a2ui_reset. Hinweis: A2UI ist nur in v0.8 verfügbar. Die CLI lehnt v0.9 JSONL ab.

nodes

Entdecke verbundene Nodes, sende Benachrichtigungen oder nutze Kamera und Screen-Recording. Aktionen: status, describe, pending, approve, reject, notify, run, camera_snap, camera_clip, screen_record, location_get.

Beispiel (run):

{
  "action": "run",
  "node": "office-mac",
  "command": ["echo", "Hello"],
  "env": ["FOO=bar"],
  "commandTimeoutMs": 12000,
  "invokeTimeoutMs": 45000,
  "needsScreenRecording": false
}

image

Analysiere Bilder mit dem konfigurierten Image-Modell. Parameter: image (Pfad oder URL), prompt, model, maxBytesMb. Hinweis: Funktioniert nur, wenn agents.defaults.imageModel gesetzt ist.

message

Sende Nachrichten über Kanäle wie Discord, Slack, Telegram, WhatsApp oder MS Teams. Aktionen: send, poll, react, thread-create, search, channel-list, etc. Hinweis: WhatsApp-Nachrichten werden über das Gateway geroutet.

cron

Verwalte Gateway Cron-Jobs. Aktionen: status, list, add, update, remove, run, wake.

gateway

Startet den Gateway-Prozess neu oder wendet Konfigurationsänderungen an. Aktionen: restart, config.get, config.apply, config.patch, update.run. Hinweis: Nutze delayMs, um laufende Antworten nicht zu unterbrechen.

sessions_*

Verwalte Sessions und starte Sub-Agenten.

• sessions_list: Zeigt aktive Sessions.
• sessions_history: Inspiziert den Verlauf.
• sessions_send: Sendet Nachrichten an andere Sessions.
• sessions_spawn: Startet einen Sub-Agenten (nicht-blockierend).
• session_status: Prüft den Status oder setzt Modell-Overrides zurück.

agents_list

Listet Agenten-IDs auf, die für sessions_spawn genutzt werden können. Dies ist durch agents.list[].subagents.allowAgents eingeschränkt.

---

Fehlerbehebung

• exec hängt: Wenn process in den Einstellungen deaktiviert ist, läuft exec synchron. Das bedeutet, yieldMs und background werden ignoriert.
• Browser-Fehler: Remote-Profile sind “attach-only”. Du kannst sie nicht über das Tool starten oder stoppen.
• Canvas-Probleme: Wenn du v0.9 JSONL nutzt, wird die CLI dies mit Fehlern ablehnen. Bleib für A2UI bei v0.8.
• Web-Suche schlägt fehl: Prüfe, ob dein Brave API Key korrekt über openclaw configure gesetzt wurde.

Noch Fragen zur Einrichtung? Der AI Setup Assistant hilft dir direkt weiter.

Nächste Schritte

• Exec approvals
• Web tools
• Firecrawl Setup

Kennst du das? Du versuchst, eine Verbindung zu einem Service aufzubauen, aber die Authentifizierung schlägt fehl, weil irgendwo im Hintergrund eine Umgebungsvariable nicht richtig weitergereicht wurde. Oder dein Agent versucht, Aktionen auszuführen, ohne vorher den Status der Umgebung zu prüfen, was zu unnötigen Fehlermeldungen führt.

Diese kleinen Reibungspunkte kosten Zeit und Nerven. Eine klare Struktur bei den Parametern sorgt dafür, dass deine Tools genau das tun, was sie sollen, ohne dass du dich durch kryptische Logs wühlen musst. Wir schauen uns jetzt an, wie du die Konfiguration sauber aufsetzt.

Voraussetzungen

• Gateway-backed tools (canvas, nodes, cron)
• Browser tool Zugriff
• Aktive Model API Verbindung
• Nutzer-Berechtigungen für Medienzugriffe

Schnellstart

In weniger als fünf Minuten hast du die Basis-Konfiguration für deine Tools stehen. Hier sind die wichtigsten Parameter und Abläufe.

Gateway-Konfiguration

Wenn du Tools wie canvas, nodes oder cron nutzt, sind diese Parameter entscheidend:

1. gatewayUrl: Die Adresse deines Gateways (Standard ist ws://127.0.0.1:18789).
2. gatewayToken: Dein Token, falls die Authentifizierung aktiviert ist.
3. timeoutMs: Zeitlimit für Anfragen in Millisekunden.
4. Explizite Credentials: Tools erben keine Konfigurationen oder Umgebungsvariablen. Wenn du eine gatewayUrl setzt, musst du den gatewayToken immer explizit angeben.

Browser-Parameter

Für das Browser tool stehen dir folgende Optionen zur Verfügung:

1. profile: Optional, nutzt standardmäßig browser.defaultProfile.
2. target: Bestimme die Umgebung (sandbox, host oder node).
3. node: Pinne das Tool an eine spezifische Node ID oder einen Namen.
4. Defaults: Ohne Angabe werden die Standardwerte der Umgebung genutzt.

Empfohlene Agent-Flows

Browser-Automatisierung:

• browser → status / start
• snapshot (ai oder aria)
• act (click/type/press)
• screenshot für die visuelle Bestätigung

Canvas Rendering:

• canvas → present
• a2ui_push (optional)
• snapshot
• Visuelle Verifizierung der UI-Elemente

Node Targeting:

• nodes → status
• describe auf dem gewählten Node
• notify / run / camera_snap / screen_record
• Prüfung der Medien-Berechtigungen

Sicherheit und Darstellung

Vermeide direktes system.run. Nutze stattdessen nodes → run und hol dir immer die explizite Zustimmung des Nutzers ein. Respektiere die Privatsphäre bei Kamera- oder Bildschirmaufnahmen und nutze status/describe, um Berechtigungen vorab zu prüfen.

Tools werden dem Agent über zwei Kanäle präsentiert:

1. System prompt text: Eine für Menschen lesbare Liste mit Anleitungen.
2. Tool schema: Strukturierte Funktionsdefinitionen für die Model API.

Fehlerbehebung

• Fehler: Authentication Error trotz gesetzter Umgebungsvariablen Tools erben keine Credentials für Overrides. Wenn du gatewayUrl manuell konfigurierst, musst du den gatewayToken zwingend explizit im Tool-Aufruf angeben. Fehlende explizite Credentials führen zu einem Fehler.
• Problem: Agent findet oder erkennt ein Tool nicht Damit ein Model ein Tool aufrufen kann, muss es sowohl im System Prompt als auch im Tool Schema definiert sein. Fehlt es in einem der beiden Kanäle, ist das Tool für den Agent unsichtbar.

Du hast Fragen zu einem spezifischen Setup? Der AI Setup Assistant hilft dir direkt weiter.

Nächste Schritte

• Gateway Deep Dive
• Browser Tool Reference
• Node Management Guide
• Safety Best Practices