Przejdź do głównej treści

​
Exec w tle + narzędzie procesów

OpenClaw uruchamia polecenia powłoki za pomocą narzędzia exec i przechowuje długotrwałe zadania w pamięci. Narzędzie process zarządza tymi sesjami w tle.

​
narzędzie exec

Kluczowe parametry:
  • command (wymagane)
  • yieldMs (domyślnie 10000): automatyczne przejście do tła po tym opóźnieniu
  • background (bool): natychmiastowe uruchomienie w tle
  • timeout (sekundy, domyślnie 1800): zabicie procesu po tym czasie
  • elevated (bool): uruchomienie na hoście, jeśli tryb podwyższonych uprawnień jest włączony/dozwolony
  • Potrzebujesz prawdziwego TTY? Ustaw pty: true.
  • workdir, env
Zachowanie:
  • Uruchomienia na pierwszym planie zwracają wyjście bezpośrednio.
  • Po uruchomieniu w tle (jawnie lub po przekroczeniu limitu czasu) narzędzie zwraca status: "running" + sessionId oraz krótki fragment końcówki.
  • Wyjście jest przechowywane w pamięci do momentu odpytywania lub wyczyszczenia sesji.
  • Jeśli narzędzie process jest niedozwolone, exec działa synchronicznie i ignoruje yieldMs/background.

​
Mostkowanie procesów potomnych

Podczas uruchamiania długotrwałych procesów potomnych poza narzędziami exec/process (na przykład przy ponownych uruchomieniach CLI lub pomocnikach Gateway), dołącz pomocnik mostkowania procesów potomnych, aby sygnały zakończenia były przekazywane, a nasłuchiwacze odłączane przy wyjściu/błędzie. Zapobiega to osieroconym procesom w systemd i zapewnia spójne zachowanie zamykania na różnych platformach. Nadpisania środowiska:
  • PI_BASH_YIELD_MS: domyślne yield (ms)
  • PI_BASH_MAX_OUTPUT_CHARS: limit wyjścia w pamięci (znaki)
  • OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: limit oczekującego stdout/stderr na strumień (znaki)
  • PI_BASH_JOB_TTL_MS: TTL dla zakończonych sesji (ms, ograniczone do 1m–3h)
Konfiguracja (zalecane):
  • tools.exec.backgroundMs (domyślnie 10000)
  • tools.exec.timeoutSec (domyślnie 1800)
  • tools.exec.cleanupMs (domyślnie 1800000)
  • tools.exec.notifyOnExit (domyślnie true): dodaj zdarzenie systemowe do kolejki + zażądaj heartbeat, gdy exec uruchomiony w tle zakończy się.
  • tools.exec.notifyOnExitEmptySuccess (domyślnie false): gdy ustawione na true, dodaje również zdarzenia zakończenia dla pomyślnych uruchomień w tle, które nie wygenerowały wyjścia.

​
narzędzie process

Akcje:
  • list: sesje uruchomione + zakończone
  • poll: opróżnij nowe wyjście dla sesji (raportuje także status zakończenia)
  • log: odczytaj zagregowane wyjście (obsługuje offset + limit)
  • write: wyślij stdin (data, opcjonalnie eof)
  • kill: zakończ sesję w tle
  • clear: usuń zakończoną sesję z pamięci
  • remove: zabij, jeśli działa; w przeciwnym razie wyczyść, jeśli zakończona
Uwagi:
  • Tylko sesje uruchomione w tle są wyświetlane i utrwalane w pamięci.
  • Sesje są tracone po ponownym uruchomieniu procesu (brak utrwalania na dysku).
  • Dzienniki sesji są zapisywane do historii czatu tylko wtedy, gdy uruchomisz process poll/log i wynik narzędzia zostanie zarejestrowany.
  • process jest ograniczone do agenta; widzi wyłącznie sesje uruchomione przez tego agenta.
  • process list zawiera pochodny name (czasownik polecenia + cel) do szybkich przeglądów.
  • process log używa opartego na liniach offset/limit (pomiń offset, aby pobrać ostatnie N linii).
  • Gdy pominięto zarówno offset, jak i limit, zwraca ostatnie 200 linii i zawiera wskazówkę dotyczącą stronicowania.
  • Gdy podano offset, a limit pominięto, zwraca dane od offset do końca (bez ograniczenia do 200).

​
Przykłady

Uruchom długie zadanie i odpytaj później: 
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

{ "tool": "process", "action": "poll", "sessionId": "<id>" }
Uruchom natychmiast w tle: 
{ "tool": "exec", "command": "npm run build", "background": true }
Wyślij stdin: 
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }