> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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.

## Приклади

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
```

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "poll", "sessionId": "<id>" }
```

Переглянути інтерактивний сеанс перед надсиланням введення:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "log", "sessionId": "<id>" }
```

Негайно запустити у фоні:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "npm run build", "background": true }
```

Надіслати stdin:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
```

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }
```

Надіслати поточний рядок:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
```

Вставити буквальний текст:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
```

## Повʼязане

* [Інструмент exec](/uk/tools/exec)
* [Схвалення exec](/uk/tools/exec-approvals)