Background Exec + Process Tool

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

exec Tool

Wichtige Parameter:

  • command (erforderlich)
  • yieldMs (Standard 10000): nach dieser Verzögerung automatisch in den Hintergrund verschieben
  • background (bool): sofort im Hintergrund starten
  • timeout (Sekunden, Standard 1800): Prozess nach diesem Timeout beenden
  • elevated (bool): auf dem Host ausführen, wenn der Elevated-Modus aktiviert/erlaubt ist
  • Brauchst du ein echtes TTY? Setze pty: true.
  • workdir, env

Verhalten:

  • Vordergrund-Ausführungen geben die Ausgabe direkt zurück.
  • Im Hintergrund (explizit oder durch Timeout) gibt das Tool status: "running" + sessionId und einen kurzen Tail zurück.
  • Die Ausgabe bleibt im Speicher, bis die Session abgefragt oder gelöscht wird.
  • Wenn das process Tool nicht erlaubt ist, läuft exec synchron und ignoriert yieldMs/background.

Child Process Bridging

Wenn du lang laufende Child-Prozesse außerhalb der exec/process Tools startest (zum Beispiel CLI-Respawns oder Gateway-Helfer), verwende den Child-Process-Bridge-Helper. So werden Terminierungssignale weitergeleitet und Listener bei Exit/Error entfernt. Das verhindert verwaiste Prozesse auf systemd und sorgt für konsistentes Shutdown-Verhalten auf allen Plattformen.

Umgebungsvariablen:

  • PI_BASH_YIELD_MS: Standard-Yield (ms)
  • PI_BASH_MAX_OUTPUT_CHARS: Ausgabe-Limit im Speicher (Zeichen)
  • OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: Limit für ausstehende stdout/stderr pro Stream (Zeichen)
  • PI_BASH_JOB_TTL_MS: TTL für beendete Sessions (ms, begrenzt auf 1 Min.–3 Std.)

Config (bevorzugt):

  • tools.exec.backgroundMs (Standard 10000)
  • tools.exec.timeoutSec (Standard 1800)
  • tools.exec.cleanupMs (Standard 1800000)
  • tools.exec.notifyOnExit (Standard true): System-Event einreihen + Heartbeat anfordern, wenn ein Hintergrund-Exec beendet wird.

process Tool

Aktionen:

  • list: laufende + beendete Sessions anzeigen
  • poll: neue Ausgabe einer Session abrufen (meldet auch Exit-Status)
  • log: aggregierte Ausgabe lesen (unterstützt offset + limit)
  • write: stdin senden (data, optional eof)
  • kill: Hintergrund-Session beenden
  • clear: beendete Session aus dem Speicher entfernen
  • remove: beenden falls laufend, sonst löschen falls beendet

Hinweise:

  • Nur Hintergrund-Sessions werden im Speicher aufgelistet/gespeichert.
  • Sessions gehen bei Prozess-Neustart verloren (keine Persistenz auf der Festplatte).
  • Session-Logs werden nur im Chat-Verlauf gespeichert, wenn du process poll/log ausführst und das Tool-Ergebnis aufgezeichnet wird.
  • process ist pro Agent begrenzt; es sieht nur Sessions, die von diesem Agent gestartet wurden.
  • process list enthält einen abgeleiteten name (Befehlsverb + Ziel) für schnelles Scannen.
  • process log verwendet zeilenbasiertes offset/limit (lass offset weg, um die letzten N Zeilen zu holen).

Beispiele

Einen langen 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" }