OpenClaw Exec Tool: Shell-Befehle sicher im Workspace steuer

Kennst du das Problem? Du arbeitest an einem Projekt und musst ständig Shell-Befehle in verschiedenen Umgebungen ausführen, ohne den Kontext zu verlieren. Manchmal brauchst du eine isolierte Sandbox, manchmal direkten Zugriff auf deinen Host oder einen entfernten Node. Das Exec-Tool löst genau das und gibt dir die Flexibilität, die du für deinen Workflow brauchst.

Hier erfährst du, wie du das Exec-Tool am besten einsetzt, um Befehle effizient im Workspace auszuführen.

Exec-Tool

Führe Shell-Befehle im Workspace aus. Unterstützt Vordergrund- und Hintergrundausführung via process. Wenn process nicht erlaubt ist, läuft exec synchron und ignoriert yieldMs sowie background. Hintergrund-Sessions sind pro Agent begrenzt; process sieht nur Sessions desselben Agenten.

Parameter

• command (erforderlich)
• workdir (Standard ist cwd)
• env (Key/Value Overrides)
• yieldMs (Standard 10000): Automatischer Wechsel in den Hintergrund nach Verzögerung
• background (bool): Sofort im Hintergrund ausführen
• timeout (Sekunden, Standard 1800): Beenden bei Ablauf
• pty (bool): Ausführung in einem Pseudo-Terminal, falls verfügbar (TTY-only CLIs, Coding-Agents, Terminal-UIs)
• host (auto | sandbox | gateway | node): Ort der Ausführung
• security (deny | allowlist | full): Erzwingungsmodus für gateway/node
• ask (off | on-miss | always): Genehmigungsaufforderungen für gateway/node
• node (String): Node-ID/Name für host=node
• elevated (bool): Fordert erhöhte Rechte an (Gateway-Host); security=full wird nur erzwungen, wenn elevated als full aufgelöst wird

Hinweise:

• host ist standardmäßig auto: Sandbox, wenn die Sandbox-Runtime für die Session aktiv ist, ansonsten Gateway.
• elevated erzwingt host=gateway; dies ist nur verfügbar, wenn der erhöhte Zugriff für die aktuelle Session oder den Provider aktiviert ist.
• Freigaben für gateway/node werden über ~/.openclaw/exec-approvals.json gesteuert.
• node erfordert einen gekoppelten Node (Companion App oder Headless Node Host).
• Falls mehrere Nodes verfügbar sind, setze exec.node oder tools.exec.node, um einen auszuwählen.
• exec host=node ist der einzige Pfad zur Shell-Ausführung für Nodes; der alte nodes.run Wrapper wurde entfernt.
• Auf Nicht-Windows-Hosts nutzt Exec SHELL, falls gesetzt. Wenn SHELL gleich fish ist, werden bash oder sh aus dem PATH bevorzugt, um inkompatible Skripte zu vermeiden.
• Auf Windows-Hosts bevorzugt Exec PowerShell 7 (pwsh) und sucht in Program Files, ProgramW6432 oder im PATH, bevor es auf Windows PowerShell 5.1 zurückfällt.
• Die Host-Ausführung (gateway/node) lehnt env.PATH und Loader-Overrides (LD_*/DYLD_*) ab, um Binary-Hijacking oder Code-Injektionen zu verhindern.
• OpenClaw setzt OPENCLAW_SHELL=exec in der Umgebung des gestarteten Befehls, damit Shell-Regeln den Kontext erkennen können.
• Wichtig: Sandboxing ist standardmäßig deaktiviert. Wenn Sandboxing aus ist, wird ein implizites host=auto zu gateway. Ein explizites host=sandbox schlägt fehl, statt heimlich auf dem Gateway zu laufen. Aktiviere Sandboxing oder nutze host=gateway mit Freigaben.
• Preflight-Checks für Skripte prüfen nur Dateien innerhalb der workdir-Grenzen. Wenn ein Pfad außerhalb liegt, wird der Check übersprungen.

Konfiguration

• tools.exec.notifyOnExit (Standard: true): Wenn true, senden Hintergrund-Sessions ein System-Event und fordern beim Beenden einen Heartbeat an.
• tools.exec.approvalRunningNoticeMs (Standard: 10000): Gibt eine “Running”-Meldung aus, wenn ein freigabepflichtiger Befehl länger als diesen Wert läuft (0 deaktiviert dies).
• tools.exec.host (Standard: auto; wird zu sandbox, wenn aktiv, sonst gateway).
• tools.exec.security (Standard: deny für Sandbox, allowlist für Gateway + Node, falls nicht gesetzt).
• tools.exec.ask (Standard: on-miss).
• tools.exec.node (Standard: nicht gesetzt).
• tools.exec.strictInlineEval (Standard: false): Wenn true, erfordern Inline-Evaluierungen wie python -c oder node -e immer eine explizite Freigabe.
• tools.exec.pathPrepend: Liste von Verzeichnissen, die dem PATH vorangestellt werden (nur Gateway + Sandbox).
• tools.exec.safeBins: Nur für Stdin sichere Binaries, die ohne explizite Allowlist laufen können. Details findest du unter Safe bins.
• tools.exec.safeBinTrustedDirs: Zusätzliche Verzeichnisse für safeBins. PATH-Einträge werden nie automatisch vertraut. Standards sind /bin und /usr/bin.
• tools.exec.safeBinProfiles: Optionale Custom-Policies pro Safe-Bin (z. B. allowedValueFlags).

Beispiel:

{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

PATH-Handling

• host=gateway: Mischt den PATH deiner Login-Shell in die Umgebung. env.PATH Overrides werden abgelehnt. Der Daemon selbst läuft mit einem minimalen Pfad:
  • macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
  • Linux: /usr/local/bin, /usr/bin, /bin, /sbin
• host=sandbox: Führt sh -lc im Container aus. OpenClaw stellt env.PATH nach dem Laden des Profils voran; tools.exec.pathPrepend gilt hier ebenfalls.
• host=node: Nur nicht blockierte Overrides werden gesendet. env.PATH wird ignoriert. Nutze für zusätzliche Pfade die Umgebung des Node-Host-Dienstes.

Node-Bindung pro Agent (nutze den Index der Agenten-Liste):

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

In der UI bietet der Nodes-Tab ein Panel für diese Einstellungen an.

Session-Overrides (/exec)

Nutze /exec, um pro Session Defaults für host, security, ask und node festzulegen. Ohne Argumente zeigt der Befehl die aktuellen Werte an.

Beispiel:

/exec host=auto security=allowlist ask=on-miss node=mac-1

Autorisierungsmodell

/exec wird nur für autorisierte Sender berücksichtigt. Es aktualisiert nur den Session-Status und schreibt keine Konfiguration. Um Exec hart zu deaktivieren, nutze die Tool-Policy (tools.deny: ["exec"]). Host-Freigaben gelten weiterhin, außer du setzt explizit security=full und ask=off.

Exec-Freigaben (Companion App / Node Host)

Agenten in der Sandbox können eine Freigabe pro Anfrage erfordern, bevor exec auf dem Gateway oder Node läuft. Details findest du unter Exec approvals.

Wenn eine Freigabe nötig ist, gibt das Tool sofort status: "approval-pending" zurück. Nach der Entscheidung sendet das Gateway Events wie Exec finished oder Exec denied.

Allowlist + Safe Bins

Die manuelle Allowlist prüft nur aufgelöste Binärpfade. Bei security=allowlist werden Befehle nur erlaubt, wenn jedes Segment der Pipeline in der Allowlist oder ein Safe-Bin ist. Verkettungen wie && oder || werden abgelehnt, wenn nicht alle Teile die Kriterien erfüllen.

Nutze die Steuerungen für unterschiedliche Aufgaben:

• tools.exec.safeBins: Kleine Filter, die nur Stdin nutzen.
• tools.exec.safeBinTrustedDirs: Explizite Verzeichnisse für Safe-Bins.
• tools.exec.safeBinProfiles: Regeln für Argumente bei Safe-Bins.
• Allowlist: Explizites Vertrauen für Pfade.

Behandle safeBins nicht als allgemeine Allowlist. Füge dort keine Interpreter wie python3 oder node hinzu. Nutze dafür die explizite Allowlist. openclaw security audit warnt dich bei riskanten Konfigurationen.

Beispiele

Vordergrund:

{ "tool": "exec", "command": "ls -la" }

Hintergrund + Poll:

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

Tasten senden (Tmux-Stil):

{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}

Absenden (nur CR senden):

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

Einfügen:

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

apply_patch

apply_patch ist ein Subtool von exec für strukturierte Bearbeitungen mehrerer Dateien. Es ist standardmäßig für OpenAI-Modelle aktiv.

{
  tools: {
    exec: {
      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.2"] },
    },
  },
}

Hinweise:

• Nur für OpenAI/OpenAI Codex Modelle verfügbar.
• Die Tool-Policy gilt weiterhin; allow: ["write"] erlaubt implizit apply_patch.
• tools.exec.applyPatch.enabled ist standardmäßig true.
• tools.exec.applyPatch.workspaceOnly ist standardmäßig true, um Schreibzugriffe auf den Workspace zu begrenzen.

Verwandte Themen

• Exec Approvals — Freigaben für Shell-Befehle
• Sandboxing — Befehle in isolierten Umgebungen ausführen
• Background Process — Langlaufende Prozesse verwalten
• Security — Tool-Policies und erweiterter Zugriff

Nächste Schritte

Hast du Fragen zur Einrichtung oder brauchst Hilfe bei der Konfiguration? Unser AI Setup Assistant hilft dir gerne direkt weiter.