Exec-Tool

Shell-Befehle im Workspace ausführen. Unterstützt Vordergrund- + Hintergrundausführung über process. Wenn process nicht erlaubt ist, läuft exec synchron und ignoriert yieldMs/background. Hintergrundsitzungen sind pro Agent begrenzt; process sieht nur Sitzungen des gleichen Agenten.

Parameter

command (erforderlich)
workdir (Standard: cwd)
env (Key/Value-Überschreibungen)
yieldMs (Standard 10000): nach Verzögerung automatisch in den Hintergrund
background (bool): sofort in den Hintergrund
timeout (Sekunden, Standard 1800): bei Ablauf beenden
pty (bool): in einem Pseudo-Terminal ausführen, wenn verfügbar (TTY-only CLIs, Coding-Agenten, Terminal-UIs)
host (sandbox | gateway | node): wo ausgeführt wird
security (deny | allowlist | full): Durchsetzungsmodus für gateway/node
ask (off | on-miss | always): Genehmigungsprompts 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 zu full aufgelöst wird

Hinweise:

host ist standardmäßig sandbox.
elevated wird ignoriert, wenn Sandboxing aus ist (Exec läuft bereits auf dem Host).
gateway/node-Genehmigungen werden durch ~/.openclaw/exec-approvals.json gesteuert.
node erfordert einen gepaarten Node (Companion App oder Headless Node Host).
Wenn mehrere Nodes verfügbar sind, setze exec.node oder tools.exec.node, um einen auszuwählen.
Auf Nicht-Windows-Hosts verwendet Exec SHELL, wenn gesetzt; wenn SHELL fish ist, bevorzugt es bash (oder sh) aus PATH, um fish-inkompatible Skripte zu vermeiden, und fällt dann auf SHELL zurück, wenn keines existiert.
Auf Windows-Hosts bevorzugt Exec PowerShell 7 (pwsh) Discovery (Program Files, ProgramW6432, dann PATH), dann Fallback auf Windows PowerShell 5.1.
Host-Ausführung (gateway/node) lehnt env.PATH und Loader-Überschreibungen (LD_*/DYLD_*) ab, um Binary-Hijacking oder injizierten Code zu verhindern.
OpenClaw setzt OPENCLAW_SHELL=exec in der Umgebung des gespawnten Befehls (einschließlich PTY- und Sandbox-Ausführung), damit Shell-/Profil-Regeln den Exec-Tool-Kontext erkennen können.
Wichtig: Sandboxing ist standardmäßig aus. Wenn Sandboxing aus ist und host=sandbox explizit konfiguriert/angefordert wird, schlägt Exec jetzt geschlossen fehl, anstatt stillschweigend auf dem Gateway-Host zu laufen. Aktiviere Sandboxing oder verwende host=gateway mit Genehmigungen.
Script-Preflight-Checks (für häufige Python/Node-Shell-Syntaxfehler) inspizieren nur Dateien innerhalb der effektiven workdir-Grenze. Wenn ein Script-Pfad außerhalb von workdir aufgelöst wird, wird der Preflight für diese Datei übersprungen.

Konfiguration

tools.exec.notifyOnExit (Standard: true): wenn true, reihen beendete Hintergrund-Exec-Sitzungen ein Systemereignis ein und fordern einen Heartbeat an.
tools.exec.approvalRunningNoticeMs (Standard: 10000): einmalige „running”-Benachrichtigung senden, wenn ein genehmigungsgesteuerter Exec länger als dies läuft (0 deaktiviert).
tools.exec.host (Standard: sandbox)
tools.exec.security (Standard: deny für Sandbox, allowlist für Gateway + Node wenn nicht gesetzt)
tools.exec.ask (Standard: on-miss)
tools.exec.node (Standard: nicht gesetzt)
tools.exec.pathPrepend: Liste von Verzeichnissen, die PATH für Exec-Läufe vorangestellt werden (nur Gateway + Sandbox).
tools.exec.safeBins: Stdin-only Safe Binaries, die ohne explizite Allowlist-Einträge laufen können. Für Verhaltensdetails siehe Safe Bins.
tools.exec.safeBinTrustedDirs: Zusätzliche explizite Verzeichnisse, die für safeBins-Pfadprüfungen als vertrauenswürdig gelten. PATH-Einträge werden nie automatisch als vertrauenswürdig eingestuft. Eingebaute Standards sind /bin und /usr/bin.
tools.exec.safeBinProfiles: Optionale benutzerdefinierte argv-Policy pro Safe Bin (minPositional, maxPositional, allowedValueFlags, deniedFlags).

Beispiel:

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

PATH-Behandlung

host=gateway: mergt dein Login-Shell-PATH in die Exec-Umgebung. env.PATH-Überschreibungen werden für Host-Ausführung abgelehnt. Der Daemon selbst läuft mit minimalem PATH:
- macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
- Linux: /usr/local/bin, /usr/bin, /bin
host=sandbox: führt sh -lc (Login-Shell) im Container aus, sodass /etc/profile PATH zurücksetzen kann. OpenClaw stellt env.PATH nach Profile-Sourcing über eine interne Env-Variable voran (keine Shell-Interpolation); tools.exec.pathPrepend gilt hier ebenfalls.
host=node: nur nicht-blockierte Env-Überschreibungen, die du übergibst, werden an den Node gesendet. env.PATH-Überschreibungen werden für Host-Ausführung abgelehnt und von Node Hosts ignoriert. Wenn du zusätzliche PATH-Einträge auf einem Node benötigst, konfiguriere die Node-Host-Service-Umgebung (systemd/launchd) oder installiere Tools an Standard-Orten.

Pro-Agent Node-Bindung (verwende den Agent-Listen-Index in der Konfiguration):

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 die gleichen Einstellungen.

Sitzungsüberschreibungen (`/exec`)

Verwende /exec, um pro-Sitzungs-Standardwerte für host, security, ask und node zu setzen. Sende /exec ohne Argumente, um die aktuellen Werte anzuzeigen.

Beispiel:

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

Autorisierungsmodell

/exec wird nur für autorisierte Absender berücksichtigt (Kanal-Allowlists/Pairing plus commands.useAccessGroups). Es aktualisiert nur den Sitzungsstatus und schreibt keine Konfiguration. Um Exec hart zu deaktivieren, verweigere es über Tool- Policy (tools.deny: ["exec"] oder pro-Agent). Host-Genehmigungen gelten weiterhin, es sei denn, du setzt explizit security=full und ask=off.

Exec-Genehmigungen (Companion App / Node Host)

Gesandboxte Agenten können eine pro-Anfrage-Genehmigung erfordern, bevor exec auf dem Gateway- oder Node-Host läuft. Siehe Exec-Genehmigungen für die Policy, Allowlist und den UI-Flow.

Wenn Genehmigungen erforderlich sind, kehrt das Exec-Tool sofort mit status: "approval-pending" und einer Genehmigungs-ID zurück. Nach Genehmigung (oder Ablehnung / Timeout) sendet das Gateway Systemereignisse (Exec finished / Exec denied). Wenn der Befehl noch nach tools.exec.approvalRunningNoticeMs läuft, wird eine einmalige Exec running-Benachrichtigung gesendet.

Allowlist + Safe Bins

Manuelle Allowlist-Durchsetzung matcht nur aufgelöste Binary-Pfade (keine Basename-Matches). Wenn security=allowlist, werden Shell-Befehle nur automatisch erlaubt, wenn jedes Pipeline-Segment allowlisted oder ein Safe Bin ist. Verkettung (;, &&, ||) und Umleitungen werden im Allowlist-Modus abgelehnt, es sei denn, jedes Top-Level-Segment erfüllt die Allowlist (einschließlich Safe Bins). Umleitungen bleiben nicht unterstützt.

autoAllowSkills ist ein separater Komfortpfad in Exec-Genehmigungen. Er ist nicht dasselbe wie manuelle Pfad-Allowlist-Einträge. Für striktes explizites Vertrauen halte autoAllowSkills deaktiviert.

Verwende die beiden Steuerungen für verschiedene Aufgaben:

tools.exec.safeBins: kleine, stdin-only Stream-Filter.
tools.exec.safeBinTrustedDirs: explizite zusätzliche vertrauenswürdige Verzeichnisse für Safe-Bin-Executable-Pfade.
tools.exec.safeBinProfiles: explizite argv-Policy für benutzerdefinierte Safe Bins.
Allowlist: explizites Vertrauen für Executable-Pfade.

Behandle safeBins nicht als generische Allowlist und füge keine Interpreter/Runtime-Binaries hinzu (zum Beispiel python3, node, ruby, bash). Wenn du diese brauchst, verwende explizite Allowlist-Einträge und halte Genehmigungsprompts aktiviert. openclaw security audit warnt, wenn Interpreter/Runtime-safeBins-Einträge ohne explizite Profile vorhanden sind, und openclaw doctor --fix kann fehlende benutzerdefinierte safeBinProfiles-Einträge scaffolden.

Für vollständige Policy-Details und Beispiele siehe Exec-Genehmigungen und Safe Bins versus Allowlist.

Beispiele

Vordergrund:

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

Hintergrund + Polling:

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

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

Submit (nur CR senden):

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

Einfügen (standardmäßig mit Bracket):

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

apply_patch (experimentell)

apply_patch ist ein Untertool von exec für strukturierte Multi-Datei-Bearbeitungen. Explizit aktivieren:

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