Exec Tool

Führe Shell-Befehle in der Workspace aus. Unterstützt Vordergrund- und Hintergrundausführung über process. Wenn process nicht erlaubt ist, läuft exec synchron und ignoriert yieldMs/background. Hintergrund-Sessions sind pro Agent isoliert; process sieht nur Sessions vom selben Agent.

Parameter

command (erforderlich)
workdir (Standard: aktuelles Verzeichnis)
env (Key/Value-Überschreibungen)
yieldMs (Standard: 10000): automatisch in den Hintergrund nach Verzögerung
background (bool): sofort in den Hintergrund
timeout (Sekunden, Standard: 1800): Prozess beenden bei Ablauf
pty (bool): in einem Pseudo-Terminal ausführen, wenn verfügbar (für TTY-only CLIs, Coding-Agents, Terminal-UIs)
host (sandbox | gateway | node): wo der Befehl ausgeführt wird
security (deny | allowlist | full): Sicherheitsmodus für gateway/node
ask (off | on-miss | always): Freigabe-Prompts für gateway/node
node (string): Node-ID/Name für host=node
elevated (bool): erhöhte Rechte 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 deaktiviert ist (exec läuft dann bereits auf dem Host).
gateway/node-Freigaben werden über ~/.openclaw/exec-approvals.json gesteuert.
node benötigt einen gepaarten Node (Companion-App oder Headless-Node-Host).
Bei mehreren verfügbaren Nodes setze exec.node oder tools.exec.node, um einen auszuwählen.
Auf Nicht-Windows-Hosts nutzt exec SHELL, wenn gesetzt; bei SHELL=fish bevorzugt es bash (oder sh) aus PATH, um fish-inkompatible Skripte zu vermeiden, und fällt auf SHELL zurück, wenn keines existiert.
Host-Ausführung (gateway/node) lehnt env.PATH und Loader-Überschreibungen (LD_*/DYLD_*) ab, um Binary-Hijacking oder injizierten Code zu verhindern.
Wichtig: Sandboxing ist standardmäßig deaktiviert. Wenn Sandboxing aus ist, läuft host=sandbox direkt auf dem Gateway-Host (kein Container) und benötigt keine Freigaben. Um Freigaben zu erzwingen, nutze host=gateway und konfiguriere Exec-Freigaben (oder aktiviere Sandboxing).

Config

tools.exec.notifyOnExit (Standard: true): wenn true, reihen Hintergrund-Exec-Sessions ein System-Event ein und fordern einen Heartbeat beim Beenden an.
tools.exec.approvalRunningNoticeMs (Standard: 10000): gibt eine einzelne “running”-Benachrichtigung aus, wenn ein freigabepflichtiger Exec länger als diese Zeit 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 dem PATH für Exec-Läufe vorangestellt werden.
tools.exec.safeBins: stdin-only sichere Binaries, die ohne explizite Allowlist-Einträge laufen können.

Beispiel:

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

PATH-Handling

host=gateway: merged deinen 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 den PATH zurücksetzen kann. OpenClaw stellt env.PATH nach dem Profile-Sourcing über eine interne Umgebungsvariable 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. Headless-Node-Hosts akzeptieren PATH nur, wenn es dem Node-Host- PATH vorangestellt wird (kein Ersetzen). macOS-Nodes verwerfen PATH-Überschreibungen komplett.

Per-Agent-Node-Binding (nutze den Agent-List-Index in der Config):

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.

Session-Overrides (`/exec`)

Nutze /exec, um pro Session 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

Authorization-Model

/exec wird nur für autorisierte Absender berücksichtigt (Channel-Allowlists/Pairing plus commands.useAccessGroups). Es aktualisiert nur den Session-State und schreibt keine Config. Um exec komplett zu deaktivieren, verbiete es über Tool- Policy (tools.deny: ["exec"] oder per Agent). Host-Freigaben gelten weiterhin, außer du setzt explizit security=full und ask=off.

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

Sandboxed Agents können eine Freigabe pro Request verlangen, bevor exec auf dem Gateway oder Node-Host läuft. Siehe Exec-Freigaben für Policy, Allowlist und UI-Flow.

Wenn Freigaben erforderlich sind, gibt das Exec-Tool sofort status: "approval-pending" und eine Approval-ID zurück. Nach Freigabe (oder Ablehnung / Timeout) sendet das Gateway System-Events (Exec finished / Exec denied). Wenn der Befehl nach tools.exec.approvalRunningNoticeMs noch läuft, wird eine einzelne Exec running-Benachrichtigung ausgegeben.

Allowlist + Safe Bins

Allowlist-Enforcement matcht nur aufgelöste Binary-Pfade (keine Basename-Matches). Bei security=allowlist werden Shell-Befehle nur automatisch erlaubt, wenn jedes Pipeline-Segment auf der Allowlist steht oder ein Safe Bin ist. Chaining (;, &&, ||) und Redirections 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>"}

Keys 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 geklammert):

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

apply_patch (experimentell)

apply_patch ist ein Subtool von exec für strukturierte Multi-File-Edits. Aktiviere es explizit:

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