> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# „Background Exec und Process Tool“

# Hintergrundausführung + Prozess-Tool

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

## exec-Tool

Wichtige Parameter:

* `command` (erforderlich)
* `yieldMs` (Standard 10000): automatisches Verschieben in den Hintergrund nach dieser Verzögerung
* `background` (bool): sofort im Hintergrund starten
* `timeout` (Sekunden, Standard 1800): beendet den Prozess nach diesem Timeout
* `elevated` (bool): auf dem Host ausführen, wenn der erhöhte Modus aktiviert/erlaubt ist
* Benötigen Sie ein echtes TTY? Setzen Sie `pty: true`.
* `workdir`, `env`

Verhalten:

* Vordergrundausführungen geben die Ausgabe direkt zurück.
* Bei Ausführung im Hintergrund (explizit oder durch 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.
* Wenn das Tool `process` nicht erlaubt ist, läuft `exec` synchron und ignoriert `yieldMs`/`background`.

## Child-Process-Bridging

Beim Starten lang laufender Child-Prozesse außerhalb der Exec-/Process-Tools (zum Beispiel bei CLI-Neustarts oder Gateway-Hilfsprozessen) sollten Sie den Child-Process-Bridge-Helper anhängen, damit Beendigungssignale weitergeleitet und Listener bei Exit/Fehler getrennt werden. Dies vermeidet verwaiste Prozesse unter systemd und sorgt für konsistentes Shutdown-Verhalten über alle Plattformen hinweg.

Umgebungs-Overrides:

* `PI_BASH_YIELD_MS`: Standard-Yield (ms)
* `PI_BASH_MAX_OUTPUT_CHARS`: In-Memory-Ausgabegrenze (Zeichen)
* `OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS`: Grenze für ausstehende stdout/stderr pro Stream (Zeichen)
* `PI_BASH_JOB_TTL_MS`: TTL für abgeschlossene Sitzungen (ms, begrenzt auf 1 Min.–3 Std.)

Konfiguration (bevorzugt):

* `tools.exec.backgroundMs` (Standard 10000)
* `tools.exec.timeoutSec` (Standard 1800)
* `tools.exec.cleanupMs` (Standard 1800000)
* `tools.exec.notifyOnExit` (Standard true): stellt beim Beenden einer im Hintergrund ausgeführten Exec einen System-Event in die Warteschlange und fordert einen Heartbeat an.
* `tools.exec.notifyOnExitEmptySuccess` (Standard false): wenn true, werden auch Completion-Events für erfolgreiche Hintergrundausführungen ohne Ausgabe eingereiht.

## process tool

Aktionen:

* `list`: laufende + abgeschlossene Sitzungen
* `poll`: neue Ausgabe für eine Sitzung abziehen (meldet auch den Exit-Status)
* `log`: aggregierte Ausgabe lesen (unterstützt `offset` + `limit`)
* `write`: stdin senden (`data`, optional `eof`)
* `kill`: eine Hintergrundsitzung beenden
* `clear`: eine abgeschlossene Sitzung aus dem Speicher entfernen
* `remove`: beenden, wenn laufend, andernfalls löschen, wenn abgeschlossen

Hinweise:

* Nur im Hintergrund ausgeführte Sitzungen werden aufgelistet bzw. im Speicher gehalten.
* Sitzungen gehen bei einem Prozessneustart verloren (keine Persistenz auf Datenträger).
* Sitzungsprotokolle werden nur im Chat-Verlauf gespeichert, wenn Sie `process poll/log` ausführen und das Tool-Ergebnis aufgezeichnet wird.
* `process` ist pro Agent begrenzt; es sieht nur Sitzungen, die von diesem Agent gestartet wurden.
* `process list` enthält ein abgeleitetes `name` (Befehlsverb + Ziel) für schnelle Übersichten.
* `process log` verwendet zeilenbasiertes `offset`/`limit` (lassen Sie `offset` weg, um die letzten N Zeilen zu erhalten).
* Wenn sowohl `offset` als auch `limit` weggelassen werden, werden die letzten 200 Zeilen zurückgegeben und ein Paging-Hinweis eingefügt.
* Wenn `offset` angegeben und `limit` weggelassen wird, wird von `offset` bis zum Ende zurückgegeben (nicht auf 200 begrenzt).

## Beispiele

Eine lange Aufgabe ausführen und später abfragen:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
```

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "poll", "sessionId": "<id>" }
```

Sofort im Hintergrund starten:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "npm run build", "background": true }
```

stdin senden:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
```