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

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 і зберігає узгоджену поведінку завершення роботи на різних платформах.

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

• OPENCLAW_BASH_YIELD_MS: типове очікування (мс)
• OPENCLAW_BASH_MAX_OUTPUT_CHARS: обмеження виводу в памʼяті (символи)
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: обмеження очікуваних stdout/stderr на потік (символи)
• OPENCLAW_BASH_JOB_TTL_MS: TTL для завершених сеансів (мс, обмежено 1 хв–3 год)
• OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS: поріг простою виводу, після якого фонові сеанси з можливістю запису позначаються як такі, що ймовірно очікують введення (типово 15000 мс)

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

• 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 для статусу, журналів, підтвердження успішного завершення без виводу або підтвердження завершення, коли автоматичне пробудження після завершення недоступне.
• Використовуйте log перед відновленням інтерактивного CLI, щоб поточний транскрипт, стан stdin і підказка очікування введення були видимі разом.
• Використовуйте write / send-keys / submit / paste / kill, коли потрібне введення або втручання.
• process list містить похідне name (дієслово команди + ціль) для швидкого перегляду.
• process list, poll і log повідомляють waitingForInput лише коли сеанс досі має stdin з можливістю запису й простоював довше за поріг очікування введення.
• 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": "process", "action": "log", "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