Hintergrund-Exec + Prozess-Tool

OpenClaw führt Shell-Befehle über das exec-Tool aus und hält lang laufende Aufgaben im Speicher. Das process-Tool verwaltet diese Hintergrundsitzungen.

exec-Tool

Wichtige Parameter:

command (erforderlich)
yieldMs (Standard 10000): automatisches Hintergrundversetzen nach dieser Verzögerung
background (bool): sofort in den Hintergrund versetzen
timeout (Sekunden, Standard 1800): Prozess nach diesem Timeout beenden
elevated (bool): auf dem Host ausführen, wenn Elevated-Modus aktiviert/erlaubt ist
Echtes TTY erforderlich? Setze pty: true.
workdir, env

Verhalten:

Vordergrund-Ausführungen geben die Ausgabe direkt zurück.
Bei Hintergrundversetzung (explizit oder Timeout) gibt das Tool status: "running" + sessionId sowie einen kurzen Tail zurück.
Die Ausgabe wird im Speicher gehalten, bis die Sitzung abgefragt oder gelöscht wird.
Falls das process-Tool nicht erlaubt ist, läuft exec synchron und ignoriert yieldMs/background.
Gestartete exec-Befehle erhalten OPENCLAW_SHELL=exec für kontextsensitive Shell-/Profil-Regeln.

Child-Process-Bridging

Wenn lang laufende Kindprozesse außerhalb der exec/process-Tools gestartet werden (z. B. CLI-Neustarts oder Gateway-Helper), hänge den Child-Process-Bridge-Helper an, damit Beendigungssignale weitergeleitet und Listener bei Exit/Fehler getrennt werden. Das verhindert verwaiste Prozesse unter systemd und sorgt für ein konsistentes Shutdown-Verhalten über alle Plattformen hinweg.

Umgebungsvariablen-Overrides:

PI_BASH_YIELD_MS: Standard-Yield (ms)
PI_BASH_MAX_OUTPUT_CHARS: Ausgabe-Cap im Speicher (Zeichen)
OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: Cap für wartende stdout/stderr pro Stream (Zeichen)
PI_BASH_JOB_TTL_MS: TTL für beendete Sitzungen (ms, begrenzt auf 1m–3h)

Konfiguration (bevorzugt):

tools.exec.backgroundMs (Standard 10000)
tools.exec.timeoutSec (Standard 1800)
tools.exec.cleanupMs (Standard 1800000)
tools.exec.notifyOnExit (Standard true): System-Event in die Warteschlange stellen + Heartbeat anfordern, wenn ein im Hintergrund laufender exec-Prozess beendet wird.
tools.exec.notifyOnExitEmptySuccess (Standard false): wenn true, werden auch Abschluss-Events für erfolgreiche Hintergrund-Läufe ohne Ausgabe in die Warteschlange gestellt.

process-Tool

Aktionen:

list: laufende + beendete Sitzungen
poll: neue Ausgabe einer Sitzung abrufen (meldet auch den Exit-Status)
log: aggregierte Ausgabe lesen (unterstützt offset + limit)
write: stdin senden (data, optional eof)
kill: Hintergrundsitzung beenden
clear: beendete Sitzung aus dem Speicher entfernen
remove: falls laufend beenden, ansonsten beendete Sitzung löschen

Hinweise:

Nur Hintergrundsitzungen werden im Speicher aufgelistet/gehalten.
Sitzungen gehen bei Prozessneustart verloren (keine Festplatten-Persistenz).
Sitzungsprotokolle werden nur dann in den Chatverlauf geschrieben, wenn du process poll/log ausführst und das Tool-Ergebnis aufgezeichnet wird.
process ist pro Agent isoliert; es zeigt nur Sitzungen an, die von diesem Agenten gestartet wurden.
process list enthält einen abgeleiteten name (Befehlsverb + Ziel) zum schnellen Überblick.
process log verwendet zeilenbasiertes offset/limit.
Wenn sowohl offset als auch limit weggelassen werden, werden die letzten 200 Zeilen zurückgegeben, inklusive eines Paging-Hinweises.
Wenn offset angegeben und limit weggelassen wird, wird ab offset bis zum Ende zurückgegeben (nicht auf 200 begrenzt).

Beispiele

Einen lang laufenden Task starten und später abfragen:

{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

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

Sofort im Hintergrund starten:

{ "tool": "exec", "command": "npm run build", "background": true }

stdin senden:

{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }