​

Background Exec + Process Tool

​

exec-Tool

• command (erforderlich)
• yieldMs (Standard 10000): nach dieser Verzögerung automatisch in den Hintergrund verschieben
• background (bool): sofort in den Hintergrund verschieben
• timeout (Sekunden, Standard 1800): den Prozess nach diesem Timeout beenden
• elevated (bool): außerhalb der Sandbox ausführen, wenn der erhöhte Modus aktiviert/erlaubt ist (standardmäßig gateway oder node, wenn das exec-Ziel node ist)
• Benötigen Sie ein echtes TTY? Setzen Sie pty: true.
• workdir, env

• Ausführungen im Vordergrund geben die Ausgabe direkt zurück.
• Wenn sie in den Hintergrund verschoben werden (explizit oder per Timeout), gibt das Tool status: "running" + sessionId und einen kurzen Tail zurück.
• Die Ausgabe bleibt im Speicher, bis die Sitzung abgefragt oder gelöscht wird.
• Wenn das Tool process nicht erlaubt ist, läuft exec synchron und ignoriert yieldMs/background.
• Von exec gestartete Befehle erhalten OPENCLAW_SHELL=exec für kontextabhängige Shell-/Profilregeln.
• Für lang laufende Arbeit, die jetzt beginnt, starten Sie sie einmal und verlassen Sie sich auf das automatische Completion-Wake, wenn es aktiviert ist und der Befehl Ausgabe erzeugt oder fehlschlägt.
• Wenn automatisches Completion-Wake nicht verfügbar ist oder Sie eine stille Erfolgs- Bestätigung für einen Befehl benötigen, der sauber ohne Ausgabe beendet wurde, verwenden Sie process, um den Abschluss zu bestätigen.
• Emulieren Sie Erinnerungen oder verzögerte Nachverfolgungen nicht mit sleep-Schleifen oder wiederholtem Polling; verwenden Sie cron für zukünftige Arbeit.

​

Bridging von Kindprozessen

• PI_BASH_YIELD_MS: Standard-Yield (ms)
• PI_BASH_MAX_OUTPUT_CHARS: In-Memory-Ausgabeobergrenze (Zeichen)
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: Obergrenze für ausstehendes stdout/stderr pro Stream (Zeichen)
• PI_BASH_JOB_TTL_MS: TTL für beendete Sitzungen (ms, begrenzt auf 1 Min.–3 Std.)

• tools.exec.backgroundMs (Standard 10000)
• tools.exec.timeoutSec (Standard 1800)
• tools.exec.cleanupMs (Standard 1800000)
• tools.exec.notifyOnExit (Standard true): ein Systemereignis in die Warteschlange stellen + Heartbeat anfordern, wenn ein im Hintergrund ausgeführter exec beendet wird.
• tools.exec.notifyOnExitEmptySuccess (Standard false): wenn true, auch Completion-Ereignisse für erfolgreiche Hintergrundläufe ohne Ausgabe in die Warteschlange stellen.

​

process-Tool

• list: laufende + beendete Sitzungen
• poll: neue Ausgabe für eine Sitzung abrufen (meldet auch den Exit-Status)
• log: die aggregierte Ausgabe lesen (unterstützt offset + limit)
• write: stdin senden (data, optional eof)
• send-keys: explizite Schlüsseltoken oder Bytes an eine PTY-gestützte Sitzung senden
• submit: Enter / Wagenrücklauf an eine PTY-gestützte Sitzung senden
• paste: Literaltext senden, optional mit bracketed paste mode
• kill: eine Hintergrundsitzung beenden
• clear: eine beendete Sitzung aus dem Speicher entfernen
• remove: falls laufend beenden, andernfalls falls beendet löschen

• Nur Hintergrundsitzungen werden im Speicher aufgelistet/gespeichert.
• Sitzungen gehen bei einem Prozessneustart verloren (keine Persistenz auf Festplatte).
• Sitzungslogs werden nur im Chatverlauf 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 Agenten gestartet wurden.
• Verwenden Sie poll / log für Status, Logs, stille Erfolgsbestätigung oder Abschlussbestätigung, wenn automatisches Completion-Wake nicht verfügbar ist.
• Verwenden Sie write / send-keys / submit / paste / kill, wenn Sie Eingaben oder Eingriffe benötigen.
• process list enthält einen abgeleiteten name (Befehlsverb + Ziel) für schnelle Übersichten.
• process log verwendet zeilenbasiertes offset/limit.
• Wenn sowohl offset als auch limit fehlen, werden die letzten 200 Zeilen zurückgegeben und ein Paging-Hinweis eingeschlossen.
• Wenn offset angegeben ist und limit fehlt, wird von offset bis zum Ende zurückgegeben (nicht auf 200 begrenzt).
• Polling ist für Status bei Bedarf gedacht, nicht für Scheduling mit Warteschleifen. Wenn die Arbeit später stattfinden soll, verwenden Sie stattdessen cron.

​

Beispiele

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

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

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

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

{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }

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

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