Exec-Tool

Shell-Befehle ausführen. Mit Vorsicht nutzen. Shell-Befehle im Workspace ausführen. Unterstützt Vorder- und Hintergrund-Ausführung über process. Ist process verboten, läuft exec synchron und ignoriert yieldMs/background. Hintergrund-Sitzungen sind pro Agent; process sieht nur Sitzungen desselben Agenten.

Parameter

command (erforderlich)
workdir (Standard: cwd)
env (Key/Value-Überschreibungen)
yieldMs (Standard 10000): Auto-Hintergrund nach Verzögerung
background (bool): sofort im Hintergrund
timeout (Sekunden, Standard 1800): bei Ablauf beenden
pty (bool): in Pseudoterminal ausführen, wenn verfügbar (TTY-only-CLIs, Coding-Agenten, Terminal-UIs)
host (sandbox | gateway | node): wo ausführen
security (deny | allowlist | full): Durchsetzungsmodus für gateway/node
ask (off | on-miss | always): Freigabe-Abfragen für gateway/node
node (string): Node-ID/Name für host=node
elevated (bool): Elevated-Modus anfordern (Gateway-Host); security=full wird nur erzwungen, wenn elevated auf full aufgelöst wird

Hinweise:

host standardmäßig sandbox.
elevated wird ignoriert, wenn Sandboxing aus ist (exec läuft dann bereits auf dem Host).
Gateway-/Node-Freigaben werden in ~/.clawdbot/exec-approvals.json gesteuert.
node erfordert einen gepaarten Node (Companion-App oder Headless-Node-Host).
Bei mehreren Nodes exec.node oder tools.exec.node setzen, um einen auszuwählen.
Auf Nicht-Windows-Hosts nutzt exec SHELL, wenn gesetzt; ist SHELL fish, wird bevorzugt bash (oder sh) aus PATH genutzt (fish-inkompatible Skripte), sonst Fallback auf SHELL.
Wichtig: Sandboxing ist standardmäßig aus. Bei ausgeschaltetem Sandboxing läuft host=sandbox direkt auf dem Gateway-Host (kein Container) und erfordert keine Freigaben. Für Freigaben mit host=gateway laufen und Exec-Freigaben konfigurieren (oder Sandboxing aktivieren).

Config

tools.exec.notifyOnExit (Standard: true): bei true legen Hintergrund-Exec-Sitzungen ein System-Event in die Warteschlange und fordern beim Beenden einen Heartbeat an.
tools.exec.approvalRunningNoticeMs (Standard: 10000): einmalige „running“-Meldung, wenn ein freigabe-pflichtiger Exec länger läuft (0 deaktiviert).
tools.exec.host (Standard: sandbox)
tools.exec.security (Standard: deny für Sandbox, allowlist für Gateway + Node wenn ungesetzt)
tools.exec.ask (Standard: on-miss)
tools.exec.node (Standard: ungesetzt)
tools.exec.pathPrepend: Verzeichnisliste, die dem PATH für Exec-Läufe vorangestellt wird.
tools.exec.safeBins: Nur-stdin-sichere Binaries, die ohne explizite Allowlist-Einträge laufen dürfen.

Beispiel:


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

PATH-Behandlung

host=gateway: dein Login-Shell-PATH wird in die Exec-Umgebung übernommen (außer der Exec-Aufruf setzt bereits env.PATH). Der Daemon selbst läuft weiter mit minimalem PATH:
- macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
- Linux: /usr/local/bin, /usr/bin, /bin
host=sandbox: läuft sh -lc (Login-Shell) im Container, /etc/profile kann PATH zurücksetzen. OpenClaw hängt env.PATH nach dem Profile-Sourcing per interner Env-Var an (keine Shell-Interpolation); tools.exec.pathPrepend gilt hier ebenfalls.
host=node: nur die von dir übergebenen Env-Überschreibungen werden an den Node gesendet. tools.exec.pathPrepend gilt nur, wenn der Exec-Aufruf bereits env.PATH setzt. Headless-Node-Hosts akzeptieren PATH nur, wenn er den Node-Host-PATH voranstellt (kein Ersetzen). macOS-Nodes verwerfen PATH-Überschreibungen komplett.

Pro-Agent-Node-Bindung (Agent-Listen-Index in der Config nutzen):


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

Control UI: Der Nodes-Tab enthält ein kleines „Exec node binding“-Panel für dieselben Einstellungen.

Sitzungs-Überschreibungen (`/exec`)

/exec setzt pro Sitzung Defaults für host, security, ask und node. /exec ohne Argumente senden, um die aktuellen Werte anzuzeigen. Beispiel:


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

Autorisierungsmodell

/exec gilt nur für autorisiertes Sender (Kanal-Allowlists/Pairing plus commands.useAccessGroups). Es aktualisiert nur den Sitzungsstate und schreibt nicht in die Config. Exec hart deaktivieren: per Tool-Richtlinie verweigern (tools.deny: ["exec"] oder pro Agent). Host-Freigaben gelten weiterhin, außer du setzt explizit security=full und ask=off.

Exec-Freigaben (Companion-App / Node-Host)

Sandboxed Agenten können pro-Anfrage-Freigabe verlangen, bevor exec auf dem Gateway oder Node-Host läuft. Siehe Exec-Freigaben für Richtlinie, Allowlist und UI-Ablauf. Bei erforderlichen Freigaben gibt das Exec-Tool sofort mit status: "approval-pending" und einer Approval-ID zurück. Nach Freigabe (oder Ablehnung/Timeout) sendet das Gateway System-Events (Exec finished / Exec denied). Läuft der Befehl nach tools.exec.approvalRunningNoticeMs noch, wird einmalig Exec running gemeldet.

Allowlist + Safe Bins

Allowlist-Prüfung matcht nur aufgelöste Binary-Pfade (keine Basename-Matches). Bei security=allowlist werden Shell-Befehle nur automatisch erlaubt, wenn jedes Pipeline-Segment allowlistet oder eine Safe-Bin ist. Verkettung (;, &&, ||) und Umleitungen werden im Allowlist-Modus abgelehnt.

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-Style):


{"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"]}

Submit (nur CR senden):


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

Paste (standardmäßig in Klammern):


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

apply_patch (experimentell)

apply_patch ist ein Sub-Tool von exec für strukturierte Mehrdatei-Bearbeitungen. Explizit aktivieren:


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