Фонове виконання та інструмент процесів

OpenClaw запускає команди оболонки через інструмент exec і зберігає довготривалі завдання в пам’яті. Інструмент process керує цими фоновими сеансами.

# Інструмент exec

Ключові параметри:

• command (обов’язковий)
• yieldMs (типово 10000): автоматично переводити у фон після цієї затримки
• background (bool): одразу перевести у фон
• timeout (секунди, типово tools.exec.timeoutSec): завершити процес після цього тайм-ауту; установлюйте timeout: 0 лише щоб вимкнути тайм-аут процесу exec для цього виклику
• elevated (bool): запускати поза пісочницею, якщо підвищений режим увімкнено/дозволено (gateway типово або node, коли ціль exec — node)
• Потрібен справжній TTY? Установіть pty: true.
• workdir, env

Поведінка:

• Запуски на передньому плані повертають вивід напряму.
• Коли процес переведено у фон (явно або через тайм-аут), інструмент повертає status: "running" + sessionId і короткий хвіст виводу.
• Фонові запуски та запуски з yieldMs успадковують tools.exec.timeoutSec, якщо виклик не надає явний timeout.
• Вивід зберігається в пам’яті, доки сеанс не буде опитано або очищено.
• Якщо інструмент process заборонено, exec виконується синхронно та ігнорує yieldMs/background.
• Породжені команди exec отримують OPENCLAW_SHELL=exec для контекстно-залежних правил оболонки/профілю.
• Для довготривалої роботи, яка починається зараз, запустіть її один раз і покладайтеся на автоматичне пробудження після завершення, коли воно ввімкнене й команда видає вивід або завершується з помилкою.
• Якщо автоматичне пробудження після завершення недоступне або вам потрібне підтвердження тихого успіху для команди, яка завершилася чисто без виводу, використовуйте process для підтвердження завершення.
• Не емулюйте нагадування або відкладені подальші дії циклами sleep чи повторним опитуванням; використовуйте cron для майбутньої роботи.

# Міст до дочірніх процесів

Коли породжуєте довготривалі дочірні процеси поза інструментами exec/process (наприклад, перезапуски CLI або допоміжні процеси gateway), під’єднуйте допоміжний міст дочірнього процесу, щоб сигнали завершення пересилалися, а слухачі від’єднувалися під час виходу/помилки. Це запобігає осиротілим процесам у systemd і зберігає узгоджену поведінку завершення роботи на різних платформах.

Перевизначення середовища:

• PI_BASH_YIELD_MS: типова затримка yield (мс)
• PI_BASH_MAX_OUTPUT_CHARS: обмеження виводу в пам’яті (символів)
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: обмеження очікуваного stdout/stderr для кожного потоку (символів)
• PI_BASH_JOB_TTL_MS: TTL для завершених сеансів (мс, обмежено до 1 хв–3 год)

Конфігурація (бажано):

• tools.exec.backgroundMs (типово 10000)
• tools.exec.timeoutSec (типово 1800)
• tools.exec.cleanupMs (типово 1800000)
• tools.exec.notifyOnExit (типово true): ставити системну подію в чергу + запитувати heartbeat, коли фоновий exec завершується.
• tools.exec.notifyOnExitEmptySuccess (типово false): коли true, також ставити в чергу події завершення для успішних фонових запусків, які не створили виводу.

# Інструмент process

Дії:

• list: запущені + завершені сеанси
• poll: зчитати новий вивід для сеансу (також повідомляє статус виходу)
• log: прочитати агрегований вивід (підтримує offset + limit)
• write: надіслати stdin (data, необов’язковий eof)
• send-keys: надіслати явні клавішні токени або байти до сеансу на базі PTY
• submit: надіслати Enter / повернення каретки до сеансу на базі PTY
• paste: надіслати буквальний текст, необов’язково обгорнутий у режим bracketed paste
• kill: завершити фоновий сеанс
• clear: вилучити завершений сеанс із пам’яті
• remove: завершити, якщо запущено, інакше очистити, якщо завершено

Примітки:

• У списку відображаються та зберігаються в пам’яті лише фонові сеанси.
• Сеанси втрачаються після перезапуску процесу (без збереження на диск).
• Журнали сеансів зберігаються в історії чату лише якщо ви запускаєте process poll/log, а результат інструмента записується.
• process обмежений кожним агентом; він бачить лише сеанси, запущені цим агентом.
• Використовуйте poll / log для статусу, журналів, підтвердження тихого успіху або підтвердження завершення, коли автоматичне пробудження після завершення недоступне.
• Використовуйте write / send-keys / submit / paste / kill, коли потрібне введення або втручання.
• process list містить похідне name (дієслово команди + ціль) для швидкого перегляду.
• process log використовує рядкові offset/limit.
• Коли і offset, і limit пропущено, він повертає останні 200 рядків і містить підказку щодо пагінації.
• Коли вказано offset, а limit пропущено, він повертає від offset до кінця (без обмеження 200).
• Опитування призначене для статусу на вимогу, а не для планування циклів очікування. Якщо робота має відбутися пізніше, використовуйте cron натомість.

# Приклади

Запустити довге завдання й опитати пізніше:

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

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

Одразу запустити у фоні:

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

Надіслати stdin:

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

Надіслати клавіші PTY:

{ "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" }

# Пов’язане

• Інструмент Exec
• Схвалення Exec