Hintergrundausführung und Prozesstool

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

Parameter:

Verhalten:

• Ausführungen im Vordergrund geben die Ausgabe direkt zurück.
• Bei Ausführung im Hintergrund (explizit oder durch Zeitüberschreitung von yieldMs) gibt das Tool status: "running" + sessionId und einen kurzen Ausschnitt vom Ende der Ausgabe zurück.
• Ausführungen im Hintergrund und mit yieldMs übernehmen tools.exec.timeoutSeconds, sofern der Aufruf nicht ausdrücklich timeout übergibt.
• Die Ausgabe bleibt im Speicher, bis die Sitzung abgefragt oder gelöscht wird.
• Wenn das Tool process nicht zulässig ist, werden exec-Ausführungen synchron ausgeführt und yieldMs/background ignoriert.
• Gestartete exec-Befehle erhalten OPENCLAW_SHELL=exec für kontextabhängige Shell-/Profilregeln.
• Für lang laufende Arbeiten, die jetzt beginnen: Starten Sie sie einmal und verlassen Sie sich, sofern aktiviert, auf die automatische Benachrichtigung bei Abschluss, sobald der Befehl eine Ausgabe erzeugt oder fehlschlägt.
• Wenn die automatische Benachrichtigung bei Abschluss nicht verfügbar ist oder Sie den stillen Erfolg eines Befehls bestätigen müssen, der ohne Ausgabe ordnungsgemäß beendet wird, fragen Sie mit process ab.
• Simulieren Sie Erinnerungen oder verzögerte Folgeaktionen nicht mit sleep-Schleifen oder wiederholten Abfragen – verwenden Sie Cron für zukünftige Arbeiten.

Umgebungsüberschreibungen

Konfiguration (gegenüber Umgebungsüberschreibungen bevorzugt)

Überbrückung von Kindprozessen

Wenn lang laufende Kindprozesse außerhalb der exec-/process-Tools gestartet werden (CLI-Neustarts, Gateway-Hilfsprozesse), binden Sie den Hilfsmechanismus zur Überbrückung von Kindprozessen ein, damit Beendigungssignale weitergeleitet und Listener beim Beenden/bei Fehlern entfernt werden. Dies verhindert verwaiste Prozesse unter systemd und gewährleistet ein plattformübergreifend konsistentes Herunterfahren.

process-Tool

Aktionen:

Hinweise:

• Nur Hintergrundsitzungen werden aufgelistet/gespeichert – ausschließlich im Speicher, nicht auf dem Datenträger. Sitzungen gehen bei einem Prozessneustart verloren.
• Eine aktive Hintergrundsitzung verhindert die kooperative Suspendierung des Hosts und einen sicheren Neustart des Gateways, bis der Prozesseigentümer das tatsächliche Ende bestätigt.
• process remove kann eine laufende Sitzung unmittelbar nach dem Anfordern der Beendigung ausblenden; Suspendierung und Neustart bleiben bis zur Bestätigung des Endes blockiert.
• Sitzungsprotokolle werden nur im Chatverlauf gespeichert, wenn Sie process poll/log ausführen und das Tool-Ergebnis aufgezeichnet wird.
• process ist auf den jeweiligen Agenten beschränkt; es sieht nur Sitzungen, die von diesem Agenten gestartet wurden.
• Verwenden Sie poll/log für Status, Protokolle oder die Bestätigung des Abschlusses, wenn die automatische Benachrichtigung bei Abschluss nicht verfügbar ist.
• Verwenden Sie log, bevor Sie eine interaktive CLI wiederaufnehmen, damit das aktuelle Transkript, der stdin-Status und der Hinweis zum Warten auf Eingabe gemeinsam sichtbar sind.
• Verwenden Sie write/send-keys/submit/paste/kill, wenn Eingaben oder ein Eingriff erforderlich sind.
• process list enthält für eine schnelle Übersicht eine abgeleitete Angabe name (Befehlsverb + Ziel).
• process list, poll und log melden waitingForInput nur, wenn die Sitzung weiterhin über beschreibbares stdin verfügt und länger als der Schwellenwert für das Warten auf Eingabe inaktiv war (Standardwert: 15000 ms, OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS).
• process log verwendet zeilenbasierte Angaben für offset/limit. Wenn beide weggelassen werden, werden die letzten 200 Zeilen mit einem Hinweis zur Seitennavigation zurückgegeben. Wenn offset festgelegt ist und limit nicht, wird der Bereich von offset bis zum Ende zurückgegeben (nicht auf 200 begrenzt).
• polls timeout wartet vor der Rückgabe bis zu der angegebenen Anzahl von Millisekunden; Werte über 30000 werden auf 30000 begrenzt.
• Abfragen dienen dem bedarfsgesteuerten Statusabruf, nicht der Planung von Warteschleifen. Wenn die Arbeit später stattfinden soll, verwenden Sie Cron.

Beispiele

Eine lang laufende Aufgabe ausführen und später abfragen:

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

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

Eine interaktive Sitzung vor dem Senden einer Eingabe prüfen:

{ "tool": "process", "action": "log", "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" }

PTY-Tasten senden:

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

Aktuelle Zeile absenden:

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

Literaltext einfügen:

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

Verwandte Themen

• Exec-Tool
• Exec-Genehmigungen