Tools (OpenClaw)

OpenClaw stellt erstklassige Agent-Tools für Browser, Canvas, Nodes und Cron bereit. Diese ersetzen die alten openclaw-* Skills: Die Tools sind typisiert, kein Shelling nötig, und der Agent sollte sie direkt verwenden.

Tools deaktivieren

Du kannst Tools global über tools.allow / tools.deny in openclaw.json erlauben oder sperren (Deny gewinnt). Das verhindert, dass gesperrte Tools an Model-Provider gesendet werden.

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

Hinweise:

  • Matching ist case-insensitive.
  • *-Wildcards werden unterstützt ("*" bedeutet alle Tools).
  • Wenn tools.allow nur unbekannte oder nicht geladene Plugin-Tool-Namen referenziert, loggt OpenClaw eine Warnung und ignoriert die Allowlist, damit Core-Tools verfügbar bleiben.

Tool-Profile (Basis-Allowlist)

tools.profile legt eine Basis-Tool-Allowlist fest, bevor tools.allow/tools.deny greifen. Pro-Agent-Override: agents.list[].tools.profile.

Profile:

  • 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änkung (wie nicht gesetzt)

Beispiel (standardmäßig nur Messaging, zusätzlich Slack + Discord erlaubt):

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

Beispiel (Coding-Profil, aber exec/process überall sperren):

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

Beispiel (globales Coding-Profil, Messaging-only Support-Agent):

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

Provider-spezifische Tool-Policy

Verwende tools.byProvider, um Tools für bestimmte Provider (oder ein einzelnes provider/model) weiter einzuschränken, ohne deine globalen Defaults zu ändern. Pro-Agent-Override: agents.list[].tools.byProvider.

Dies wird nach dem Basis-Tool-Profil und vor den Allow/Deny-Listen angewendet, kann also nur das Tool-Set verkleinern. Provider-Keys akzeptieren entweder provider (z.B. google-antigravity) oder provider/model (z.B. openai/gpt-5.2).

Beispiel (globales Coding-Profil beibehalten, aber minimale Tools für Google Antigravity):

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

Beispiel (provider/model-spezifische Allowlist für einen instabilen Endpoint):

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

Beispiel (agent-spezifischer Override für einen einzelnen Provider):

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

Tool-Gruppen (Kurzformen)

Tool-Policies (global, Agent, Sandbox) unterstützen group:*-Einträge, die sich zu mehreren Tools auflösen. Verwende diese in tools.allow / tools.deny.

Verfügbare 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 eingebauten OpenClaw-Tools (ohne Provider-Plugins)

Beispiel (nur Datei-Tools + Browser erlauben):

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

Plugins + Tools

Plugins können über den Core-Satz hinaus zusätzliche Tools (und CLI-Befehle) registrieren. Siehe Plugins für Installation + Konfiguration und Skills für die Art, wie Tool-Nutzungshinweise in Prompts injiziert werden. Einige Plugins liefern eigene Skills zusammen mit Tools (zum Beispiel das Voice-Call-Plugin).

Optionale Plugin-Tools:

  • Lobster: typisierte Workflow-Runtime mit fortsetzbaren Genehmigungen (erfordert die Lobster CLI auf dem Gateway-Host).
  • LLM Task: JSON-only LLM-Schritt für strukturierte Workflow-Ausgabe (optionale Schema-Validierung).
  • Diffs: schreibgeschützter Diff-Viewer und PNG- oder PDF-Datei-Renderer für Vorher/Nachher-Texte oder Unified Patches.

Tool-Inventar

apply_patch

Strukturierte Patches über eine oder mehrere Dateien anwenden. Verwende dies für Multi-Hunk-Edits. Experimentell: aktivieren über tools.exec.applyPatch.enabled (nur OpenAI-Modelle). tools.exec.applyPatch.workspaceOnly ist standardmäßig true (auf den Workspace beschränkt). Setze es nur auf false, wenn du apply_patch absichtlich außerhalb des Workspace-Verzeichnisses schreiben/löschen lassen willst.

exec

Shell-Befehle im Workspace ausführen.

Kernparameter:

  • command (erforderlich)
  • yieldMs (nach Timeout automatisch in den Hintergrund, Standard 10000)
  • background (sofort in den Hintergrund)
  • timeout (Sekunden; beendet den Prozess bei Überschreitung, Standard 1800)
  • elevated (bool; auf dem Host ausführen, wenn der Elevated-Modus aktiviert/erlaubt ist; ändert das Verhalten nur, wenn der Agent gesandboxt ist)
  • host (sandbox | gateway | node)
  • security (deny | allowlist | full)
  • ask (off | on-miss | always)
  • node (Node-ID/Name für host=node)
  • Brauchst du ein echtes TTY? Setze pty: true.

Hinweise:

  • Gibt status: "running" mit einer sessionId zurück, wenn im Hintergrund.
  • Verwende process zum Abfragen/Loggen/Schreiben/Beenden/Bereinigen von Hintergrund-Sessions.
  • Wenn process gesperrt ist, läuft exec synchron und ignoriert yieldMs/background.
  • elevated wird durch tools.elevated plus agents.list[].tools.elevated-Override gesteuert (beide müssen erlauben) und ist ein Alias für host=gateway + security=full.
  • elevated ändert das Verhalten nur, wenn der Agent gesandboxt ist (sonst ein No-Op).
  • host=node kann eine macOS-Companion-App oder einen Headless-Node-Host (openclaw node run) ansprechen.
  • Gateway/Node-Genehmigungen und Allowlists: Exec-Genehmigungen.

process

Hintergrund-Exec-Sessions verwalten.

Kernaktionen:

  • list, poll, log, write, kill, clear, remove

Hinweise:

  • poll gibt neue Ausgabe und den Exit-Status bei Abschluss zurück.
  • log unterstützt zeilenbasiertes offset/limit (lass offset weg, um die letzten N Zeilen zu holen).
  • process ist pro Agent beschränkt; Sessions anderer Agents sind nicht sichtbar.

loop-detection (Tool-Call-Loop-Schutzmaßnahmen)

OpenClaw verfolgt die letzte Tool-Call-History und blockiert oder warnt, wenn es repetitive No-Progress-Loops erkennt. Aktivieren mit tools.loopDetection.enabled: true (Standard ist false).

{
  tools: {
    loopDetection: {
      enabled: true,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      historySize: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}
  • genericRepeat: wiederholte gleiche Tool + gleiche Parameter Aufrufmuster.
  • knownPollNoProgress: wiederholte Poll-ähnliche Tools mit identischen Ausgaben.
  • pingPong: alternierende A/B/A/B No-Progress-Muster.
  • Pro-Agent-Override: agents.list[].tools.loopDetection.

Das Web mit Perplexity, Brave, Gemini, Grok oder Kimi durchsuchen.

Kernparameter:

  • query (erforderlich)
  • count (1–10; Standard von tools.web.search.maxResults)

Hinweise:

  • Benötigt einen API-Key für den gewählten Provider (empfohlen: openclaw configure --section web).
  • Aktivieren über tools.web.search.enabled.
  • Antworten werden gecacht (Standard 15 Min).
  • Siehe Web-Tools für die Einrichtung.

web_fetch

Lesbaren Inhalt von einer URL abrufen und extrahieren (HTML → Markdown/Text).

Kernparameter:

  • url (erforderlich)
  • extractMode (markdown | text)
  • maxChars (lange Seiten kürzen)

Hinweise:

  • Aktivieren über tools.web.fetch.enabled.
  • maxChars wird durch tools.web.fetch.maxCharsCap begrenzt (Standard 50000).
  • Antworten werden gecacht (Standard 15 Min).
  • Für JS-lastige Seiten bevorzuge das Browser-Tool.
  • Siehe Web-Tools für die Einrichtung.
  • Siehe Firecrawl für den optionalen Anti-Bot-Fallback.

browser

Den dedizierten OpenClaw-verwalteten Browser steuern.

Kernaktionen:

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

Profilverwaltung:

  • profiles — alle Browserprofile mit Status auflisten
  • create-profile — neues Profil mit automatisch zugewiesenem Port erstellen (oder cdpUrl)
  • delete-profile — Browser stoppen, Benutzerdaten löschen, aus der Konfiguration entfernen (nur lokal)
  • reset-profile — verwaisten Prozess auf dem Port des Profils beenden (nur lokal)

Allgemeine Parameter:

  • profile (optional; Standard ist browser.defaultProfile)
  • target (sandbox | host | node)
  • node (optional; bestimmte Node-ID/Name auswählen) Hinweise:
  • Erfordert browser.enabled=true (Standard ist true; auf false setzen zum Deaktivieren).
  • Alle Aktionen akzeptieren den optionalen profile-Parameter für Multi-Instanz-Unterstützung.
  • Wenn profile weggelassen wird, wird browser.defaultProfile verwendet (Standard “chrome”).
  • Profilnamen: nur Kleinbuchstaben, Ziffern + Bindestriche (max. 64 Zeichen).
  • Port-Bereich: 18800-18899 (~100 Profile max.).
  • Remote-Profile sind nur zum Anhängen (kein Start/Stop/Reset).
  • Wenn ein browserfähiger Node verbunden ist, kann das Tool automatisch dorthin routen (außer du fixierst target).
  • snapshot verwendet standardmäßig ai, wenn Playwright installiert ist; verwende aria für den Accessibility Tree.
  • snapshot unterstützt auch Role-Snapshot-Optionen (interactive, compact, depth, selector), die Refs wie e12 zurückgeben.
  • act erfordert ref von snapshot (numerisch 12 von AI-Snapshots oder e12 von Role-Snapshots); verwende evaluate für seltene CSS-Selektor-Anforderungen.
  • Vermeide act → wait standardmäßig; verwende es nur in Ausnahmefällen (kein zuverlässiger UI-Zustand zum Warten).
  • upload kann optional eine ref übergeben, um nach dem Aktivieren automatisch zu klicken.
  • upload unterstützt auch inputRef (Aria-Ref) oder element (CSS-Selektor), um <input type="file"> direkt zu setzen.

canvas

Den Node-Canvas steuern (Präsentieren, Auswerten, Snapshot, A2UI).

Kernaktionen:

  • present, hide, navigate, eval
  • snapshot (gibt Bild-Block + MEDIA:<path> zurück)
  • a2ui_push, a2ui_reset

Hinweise:

  • Verwendet unter der Haube Gateway node.invoke.
  • Wenn kein node angegeben ist, wählt das Tool einen Standard (einzelner verbundener Node oder lokaler Mac-Node).
  • A2UI ist nur v0.8 (kein createSurface); die CLI lehnt v0.9 JSONL mit Zeilenfehlern ab.
  • Schnelltest: openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI".

nodes

Gepaarte Nodes erkennen und ansprechen; Benachrichtigungen senden; Kamera/Bildschirm aufnehmen.

Kernaktionen:

  • status, describe
  • pending, approve, reject (Pairing)
  • notify (macOS system.notify)
  • run (macOS system.run)
  • camera_list, camera_snap, camera_clip, screen_record
  • location_get, notifications_list, notifications_action
  • device_status, device_info, device_permissions, device_health

Hinweise:

  • Kamera-/Bildschirm-Befehle erfordern, dass die Node-App im Vordergrund ist.
  • Bilder geben Bild-Blöcke + MEDIA:<path> zurück.
  • Videos geben FILE:<path> (mp4) zurück.
  • Location gibt ein JSON-Payload zurück (lat/lon/accuracy/timestamp).
  • run-Parameter: command argv-Array; optional cwd, env (KEY=VAL), commandTimeoutMs, invokeTimeoutMs, needsScreenRecording.

Beispiel (run):

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

image

Ein Bild mit dem konfigurierten Bildmodell analysieren.

Kernparameter:

  • image (erforderlicher Pfad oder URL)
  • prompt (optional; Standard ist “Describe the image.”)
  • model (optionaler Override)
  • maxBytesMb (optionale Größenbegrenzung)

Hinweise:

  • Nur verfügbar, wenn agents.defaults.imageModel konfiguriert ist (primär oder Fallbacks), oder wenn ein implizites Bildmodell aus deinem Standardmodell + konfigurierter Auth abgeleitet werden kann (Best-Effort-Zuordnung).
  • Verwendet das Bildmodell direkt (unabhängig vom Haupt-Chat-Modell).

pdf

Ein oder mehrere PDF-Dokumente analysieren.

Für vollständiges Verhalten, Limits, Konfiguration und Beispiele siehe PDF-Tool.

message

Nachrichten und Channel-Aktionen über Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams senden.

Kernaktionen:

  • send (Text + optionale Medien; MS Teams unterstützt auch card für Adaptive Cards)
  • poll (WhatsApp/Discord/MS Teams-Umfragen)
  • react / reactions / read / edit / delete
  • pin / unpin / list-pins
  • permissions
  • thread-create / thread-list / thread-reply
  • search
  • sticker
  • member-info / role-info
  • emoji-list / emoji-upload / sticker-upload
  • role-add / role-remove
  • channel-info / channel-list
  • voice-status
  • event-list / event-create
  • timeout / kick / ban

Hinweise:

  • send routet WhatsApp über das Gateway; andere Kanäle gehen direkt.
  • poll nutzt das Gateway für WhatsApp und MS Teams; Discord-Umfragen gehen direkt.
  • Wenn ein Message-Tool-Call an eine aktive Chat-Session gebunden ist, werden Sends auf das Ziel dieser Session beschränkt, um Cross-Context-Leaks zu vermeiden.

cron

Gateway-Cron-Jobs und Wakeups verwalten.

Kernaktionen:

  • status, list
  • add, update, remove, run, runs
  • wake (System-Event in die Warteschlange stellen + optionaler sofortiger Heartbeat)

Hinweise:

  • add erwartet ein vollständiges Cron-Job-Objekt (gleiche Schema wie cron.add RPC).
  • update verwendet { jobId, patch } (id wird aus Kompatibilitätsgründen akzeptiert).

gateway

Den laufenden Gateway-Prozess neu starten oder Updates anwenden (In-Place).

Kernaktionen:

  • restart (autorisiert + sendet SIGUSR1 für In-Process-Neustart; openclaw gateway In-Place-Neustart)
  • config.schema.lookup (einen Config-Pfad gleichzeitig prüfen, ohne das vollständige Schema in den Prompt-Kontext zu laden)
  • config.get
  • config.apply (validieren + Config schreiben + Neustart + Wake)
  • config.patch (partielles Update mergen + Neustart + Wake)
  • update.run (Update ausführen + Neustart + Wake)

Hinweise:

  • config.schema.lookup erwartet einen gezielten Config-Pfad wie gateway.auth oder agents.list.*.heartbeat.
  • Pfade können Slash-getrennte Plugin-IDs enthalten, wenn sie plugins.entries.<id> adressieren, zum Beispiel plugins.entries.pack/one.config.
  • Verwende delayMs (Standard 2000), um laufende Antworten nicht zu unterbrechen.
  • config.schema bleibt für interne Control-UI-Flows verfügbar und wird nicht über das Agent-gateway-Tool exponiert.
  • restart ist standardmäßig aktiviert; setze commands.restart: false zum Deaktivieren.

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

Sessions auflisten, Transkript-History einsehen oder an eine andere Session senden.

Kernparameter:

  • sessions_list: kinds?, limit?, activeMinutes?, messageLimit? (0 = keine)
  • sessions_history: sessionKey (oder sessionId), limit?, includeTools?
  • sessions_send: sessionKey (oder sessionId), message, timeoutSeconds? (0 = Fire-and-Forget)
  • sessions_spawn: task, label?, runtime?, agentId?, model?, thinking?, cwd?, runTimeoutSeconds?, thread?, mode?, cleanup?, sandbox?, streamTo?, attachments?, attachAs?
  • session_status: sessionKey? (Standard aktuell; akzeptiert sessionId), model? (default setzt Override zurück)

Hinweise:

  • main ist der kanonische Direkt-Chat-Key; global/unknown sind ausgeblendet.
  • messageLimit > 0 ruft die letzten N Nachrichten pro Session ab (Tool-Nachrichten gefiltert).
  • Session-Targeting wird durch tools.sessions.visibility gesteuert (Standard tree: aktuelle Session + gespawnte Subagent-Sessions). Wenn du einen gemeinsamen Agent für mehrere Benutzer betreibst, erwäge tools.sessions.visibility: "self" zu setzen, um Cross-Session-Browsing zu verhindern.
  • sessions_send wartet auf die endgültige Fertigstellung, wenn timeoutSeconds > 0.
  • Zustellung/Announce erfolgt nach Abschluss und ist Best-Effort; status: "ok" bestätigt, dass der Agent-Run beendet ist, nicht dass das Announce zugestellt wurde.
  • sessions_spawn unterstützt runtime: "subagent" | "acp" (Standard subagent). Für ACP-Runtime-Verhalten siehe ACP Agents.
  • Für ACP-Runtime routet streamTo: "parent" Fortschritts-Zusammenfassungen des Initial-Runs zurück an die anfragende Session als System-Events statt direkter Kind-Zustellung.
  • sessions_spawn startet einen Sub-Agent-Run und postet eine Announce-Antwort zurück in den anfragenden Chat.
    • Unterstützt One-Shot-Modus (mode: "run") und persistenten Thread-gebundenen Modus (mode: "session" mit thread: true).
    • Wenn thread: true und mode weggelassen wird, ist der Standardmodus session.
    • mode: "session" erfordert thread: true.
    • Wenn runTimeoutSeconds weggelassen wird, verwendet OpenClaw agents.defaults.subagents.runTimeoutSeconds falls gesetzt; ansonsten ist der Standard-Timeout 0 (kein Timeout).
    • Discord Thread-gebundene Flows hängen von session.threadBindings.* und channels.discord.threadBindings.* ab.
    • Das Antwortformat enthält Status, Result und kompakte Stats.
    • Result ist der Assistant-Completion-Text; fehlt er, wird das letzte toolResult als Fallback verwendet.
  • Manuelle Completion-Mode-Spawns senden zuerst direkt, mit Queue-Fallback und Retry bei transienten Fehlern (status: "ok" bedeutet, der Run ist beendet, nicht dass das Announce zugestellt wurde).
  • sessions_spawn unterstützt Inline-Dateianhänge nur für die Subagent-Runtime (ACP lehnt sie ab). Jeder Anhang hat name, content und optionale encoding (utf8 oder base64) und mimeType. Dateien werden im Kind-Workspace unter .openclaw/attachments/<uuid>/ mit einer .manifest.json-Metadatendatei materialisiert. Das Tool gibt eine Quittung mit count, totalBytes, pro Datei sha256 und relDir zurück. Anhangsinhalte werden automatisch aus der Transkript-Persistierung redigiert.
    • Limits konfigurieren über tools.sessions_spawn.attachments (enabled, maxTotalBytes, maxFiles, maxFileBytes, retainOnSessionKeep).
    • attachAs.mountPath ist ein reservierter Hinweis für zukünftige Mount-Implementierungen.
  • sessions_spawn ist nicht-blockierend und gibt sofort status: "accepted" zurück.
  • ACP streamTo: "parent"-Antworten können streamLogPath (session-bezogenes *.acp-stream.jsonl) zum Verfolgen der Fortschritts-History enthalten.
  • sessions_send führt ein Reply-Back-Ping-Pong durch (antworte REPLY_SKIP zum Stoppen; max. Turns über session.agentToAgent.maxPingPongTurns, 0–5).
  • Nach dem Ping-Pong führt der Ziel-Agent einen Announce-Schritt aus; antworte ANNOUNCE_SKIP, um die Ankündigung zu unterdrücken.
  • Sandbox-Clamp: Wenn die aktuelle Session gesandboxt ist und agents.defaults.sandbox.sessionToolsVisibility: "spawned", klemmt OpenClaw tools.sessions.visibility auf tree.

agents_list

Agent-IDs auflisten, die die aktuelle Session mit sessions_spawn ansprechen kann.

Hinweise:

  • Das Ergebnis wird durch Pro-Agent-Allowlists (agents.list[].subagents.allowAgents) eingeschränkt.
  • Wenn ["*"] konfiguriert ist, enthält das Tool alle konfigurierten Agents und markiert allowAny: true.

Parameter (allgemein)

Gateway-gestützte Tools (canvas, nodes, cron):

  • gatewayUrl (Standard ws://127.0.0.1:18789)
  • gatewayToken (wenn Auth aktiviert)
  • timeoutMs

Hinweis: Wenn gatewayUrl gesetzt ist, gib gatewayToken explizit an. Tools erben weder Config- noch Umgebungs-Credentials für Overrides, und fehlende explizite Credentials sind ein Fehler.

Browser-Tool:

Empfohlene Agent-Abläufe

Browser-Automatisierung:

  1. browser → status / start
  2. snapshot (ai oder aria)
  3. act (click/type/press)
  4. screenshot bei Bedarf zur visuellen Bestätigung

Canvas-Rendering:

  1. canvas → present
  2. a2ui_push (optional)
  3. snapshot

Node-Targeting:

  1. nodes → status
  2. describe auf dem gewählten Node
  3. notify / run / camera_snap / screen_record

Sicherheit

  • Vermeide direktes system.run; verwende nodes → run nur mit expliziter Benutzer-Zustimmung.
  • Respektiere die Benutzer-Einwilligung für Kamera-/Bildschirmaufnahmen.
  • Verwende status/describe, um Berechtigungen zu prüfen, bevor du Medien-Befehle aufrufst.

Wie Tools dem Agent präsentiert werden

Tools werden über zwei parallele Kanäle exponiert:

  1. System-Prompt-Text: eine menschenlesbare Liste + Hinweise.
  2. Tool-Schema: die strukturierten Funktionsdefinitionen, die an die Model-API gesendet werden.

Das bedeutet, der Agent sieht sowohl “welche Tools existieren” als auch “wie man sie aufruft.” Wenn ein Tool weder im System-Prompt noch im Schema erscheint, kann das Modell es nicht aufrufen.

arrow_back
Zurück
Queue
Weiter
Apply Patch
arrow_forward