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, ohne Shell-Aufrufe, und der Agent sollte direkt auf sie zugreifen.

Tools deaktivieren

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

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

Hinweise:

• Groß-/Kleinschreibung wird ignoriert.
• * 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 setzt eine Basis-Tool-Allowlist vor tools.allow/tools.deny. 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, erlaube zusätzlich Slack + Discord Tools):

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

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

{
  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

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

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

Beispiel (behalte globales Coding-Profil, 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 (Abkürzungen)

Tool-Policies (global, Agent, Sandbox) unterstützen group:* Einträge, die sich zu mehreren Tools erweitern. Nutze 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 (erlaube nur Datei-Tools + Browser):

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

Plugins + Tools

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

Optionale Plugin-Tools:

• Lobster: typisierte Workflow-Runtime mit fortsetzbaren Freigaben (benötigt die Lobster CLI auf dem Gateway-Host).
• LLM Task: JSON-only LLM-Schritt für strukturierte Workflow-Ausgabe (optionale Schema-Validierung).

Tool-Inventar

apply_patch

Wendet strukturierte Patches über eine oder mehrere Dateien an. Nutze dies für Multi-Hunk-Edits. Experimentell: aktiviere über tools.exec.applyPatch.enabled (nur OpenAI-Modelle).

exec

Führt Shell-Befehle im Workspace aus.

Kern-Parameter:

• command (erforderlich)
• yieldMs (Auto-Background nach Timeout, Standard 10000)
• background (sofortiger Background)
• timeout (Sekunden; beendet den Prozess bei Überschreitung, Standard 1800)
• elevated (bool; läuft auf Host, wenn Elevated-Modus aktiviert/erlaubt ist; ändert nur Verhalten, wenn der Agent in der Sandbox läuft)
• 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.
• Nutze process, um Background-Sessions zu pollen/loggen/schreiben/beenden/löschen.
• Wenn process nicht erlaubt ist, läuft exec synchron und ignoriert yieldMs/background.
• elevated wird durch tools.elevated plus jeden agents.list[].tools.elevated Override gesteuert (beide müssen erlauben) und ist ein Alias für host=gateway + security=full.
• elevated ändert nur Verhalten, wenn der Agent in der Sandbox läuft (sonst ist es ein No-Op).
• host=node kann eine macOS Companion-App oder einen Headless-Node-Host (openclaw node run) ansprechen.
• Gateway/Node-Freigaben und Allowlists: Exec-Freigaben.

process

Verwaltet Background-Exec-Sessions.

Kern-Aktionen:

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

Hinweise:

• poll gibt neue Ausgabe und Exit-Status zurück, wenn abgeschlossen.
• log unterstützt zeilenbasiertes offset/limit (lasse offset weg, um die letzten N Zeilen zu holen).
• process ist pro Agent begrenzt; Sessions von anderen Agents sind nicht sichtbar.

web_search

Durchsucht das Web mit der Brave Search API.

Kern-Parameter:

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

Hinweise:

• Benötigt einen Brave API Key (empfohlen: openclaw configure --section web, oder setze BRAVE_API_KEY).
• Aktiviere über tools.web.search.enabled.
• Antworten werden gecacht (Standard 15 Min).
• Siehe Web-Tools für Setup.

web_fetch

Holt und extrahiert lesbaren Inhalt von einer URL (HTML → Markdown/Text).

Kern-Parameter:

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

Hinweise:

• Aktiviere über tools.web.fetch.enabled.
• Antworten werden gecacht (Standard 15 Min).
• Für JS-lastige Sites nutze lieber das Browser-Tool.
• Siehe Web-Tools für Setup.
• Siehe Firecrawl für das optionale Anti-Bot-Fallback.

browser

Steuert den dedizierten OpenClaw-verwalteten Browser.

Kern-Aktionen:

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

Profil-Verwaltung:

• profiles — listet alle Browser-Profile mit Status auf
• create-profile — erstellt neues Profil mit auto-zugewiesenem Port (oder cdpUrl)
• delete-profile — stoppt Browser, löscht User-Daten, entfernt aus Config (nur lokal)
• reset-profile — beendet verwaisten Prozess auf dem Port des Profils (nur lokal)

Häufige Parameter:

• profile (optional; Standard ist browser.defaultProfile)
• target (sandbox | host | node)
• node (optional; wählt eine bestimmte Node-ID/Name)

Hinweise:

• Benötigt browser.enabled=true (Standard ist true; setze false zum Deaktivieren).
• Alle Aktionen akzeptieren optionalen profile Parameter für Multi-Instanz-Support.
• Wenn profile weggelassen wird, nutzt es browser.defaultProfile (Standard ist “chrome”).
• Profilnamen: nur Kleinbuchstaben, alphanumerisch + Bindestriche (max 64 Zeichen).
• Port-Bereich: 18800-18899 (~100 Profile max).
• Remote-Profile sind nur Attach-Only (kein start/stop/reset).
• Wenn eine browser-fähige Node verbunden ist, kann das Tool automatisch dorthin routen (außer du pinnst target).
• snapshot nutzt standardmäßig ai, wenn Playwright installiert ist; nutze aria für den Accessibility-Tree.
• snapshot unterstützt auch Role-Snapshot-Optionen (interactive, compact, depth, selector), die Refs wie e12 zurückgeben.
• act benötigt ref von snapshot (numerisch 12 von AI-Snapshots, oder e12 von Role-Snapshots); nutze evaluate für seltene CSS-Selektor-Bedürfnisse.
• Vermeide act → wait standardmäßig; nutze es nur in Ausnahmefällen (kein zuverlässiger UI-Status zum Warten).
• upload kann optional eine ref übergeben, um nach dem Arming automatisch zu klicken.
• upload unterstützt auch inputRef (aria ref) oder element (CSS-Selektor), um <input type="file"> direkt zu setzen.

canvas

Steuert die Node-Canvas (present, eval, snapshot, A2UI).

Kern-Aktionen:

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

Hinweise:

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

nodes

Entdeckt und spricht gepaarte Nodes an; sendet Benachrichtigungen; erfasst Kamera/Bildschirm.

Kern-Aktionen:

• status, describe
• pending, approve, reject (Pairing)
• notify (macOS system.notify)
• run (macOS system.run)
• camera_snap, camera_clip, screen_record
• location_get

Hinweise:

• Kamera/Bildschirm-Befehle benötigen die Node-App im Vordergrund.
• Bilder geben Image-Blocks + 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

Analysiert ein Bild mit dem konfigurierten Image-Modell.

Kern-Parameter:

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

Hinweise:

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

message

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

Kern-Aktionen:

• 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 Channels 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, sind Sends auf das Ziel dieser Session beschränkt, um Cross-Context-Leaks zu vermeiden.

cron

Verwaltet Gateway-Cron-Jobs und Wakeups.

Kern-Aktionen:

• status, list
• add, update, remove, run, runs
• wake (reiht System-Event ein + optionaler sofortiger Heartbeat)

Hinweise:

• add erwartet ein vollständiges Cron-Job-Objekt (gleiches Schema wie cron.add RPC).
• update nutzt { id, patch }.

gateway

Startet den laufenden Gateway-Prozess neu oder wendet Updates an (in-place).

Kern-Aktionen:

• restart (autorisiert + sendet SIGUSR1 für In-Process-Neustart; openclaw gateway restart in-place)
• config.get / config.schema
• config.apply (validiere + schreibe Config + Neustart + Wake)
• config.patch (merge partielles Update + Neustart + Wake)
• update.run (führe Update aus + Neustart + Wake)

Hinweise:

• Nutze delayMs (Standard 2000), um eine laufende Antwort nicht zu unterbrechen.
• restart ist standardmäßig deaktiviert; aktiviere mit commands.restart: true.

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

Listet Sessions auf, inspiziert Transkript-Historie oder sendet an eine andere Session.

Kern-Parameter:

• 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?, agentId?, model?, runTimeoutSeconds?, cleanup?
• session_status: sessionKey? (Standard aktuell; akzeptiert sessionId), model? (default löscht Override)

Hinweise:

• main ist der kanonische Direct-Chat-Key; global/unknown sind versteckt.
• messageLimit > 0 holt die letzten N Nachrichten pro Session (Tool-Nachrichten gefiltert).
• sessions_send wartet auf finale Fertigstellung, wenn timeoutSeconds > 0.
• Zustellung/Ankündigung erfolgt nach Fertigstellung und ist Best-Effort; status: "ok" bestätigt, dass der Agent-Run beendet ist, nicht dass die Ankündigung zugestellt wurde.
• sessions_spawn startet einen Sub-Agent-Run und postet eine Ankündigungs-Antwort zurück zum Anfrage-Chat.
• sessions_spawn ist nicht-blockierend und gibt sofort status: "accepted" zurück.
• sessions_send führt ein Reply-Back-Ping-Pong aus (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.

agents_list

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

Hinweise:

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

Parameter (häufig)

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

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

Browser-Tool:

• profile (optional; Standard ist browser.defaultProfile)
• target (sandbox | host | node)
• node (optional; pinne eine bestimmte Node-ID/Name)

Empfohlene Agent-Flows

Browser-Automatisierung:

1. browser → status / start
2. snapshot (ai oder aria)
3. act (click/type/press)
4. screenshot, wenn du visuelle Bestätigung brauchst

Canvas-Render:

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

Node-Targeting:

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

Sicherheit

• Vermeide direktes system.run; nutze nodes → run nur mit expliziter User-Zustimmung.
• Respektiere User-Zustimmung für Kamera/Bildschirm-Erfassung.
• Nutze status/describe, um Berechtigungen sicherzustellen, bevor du Medien-Befehle aufrufst.

Wie Tools dem Agent präsentiert werden

Tools werden in zwei parallelen Kanälen bereitgestellt:

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

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