---
read_when:
    - Додавання або змінення поведінки фонового виконання
    - Налагодження довготривалих завдань exec
summary: Фонове виконання exec і керування процесами
title: Фонове виконання і інструмент процесів
x-i18n:
    generated_at: "2026-06-27T17:30:18Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 5822c1e26b0144c5216ae6e59e279ccc506cf4c0a42b8cd6c386f535fe458bd3
    source_path: gateway/background-process.md
    workflow: 16
---

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
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
```

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

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

```json
{ "tool": "process", "action": "log", "sessionId": "<id>" }
```

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

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

Надіслати stdin:

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

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

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

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

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

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

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

## Повʼязане

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