---
read_when:
    - Додавання або змінення поведінки фонового виконання
    - Налагодження довготривалих завдань exec
summary: Фонове виконання exec і керування процесами
title: Фоновий exec та інструмент процесів
x-i18n:
    generated_at: "2026-05-11T20:35:17Z"
    model: gpt-5.5
    provider: openai
    source_hash: 95fb986cf0c07ef3d054189ce2838b441ae24f07703f8edc1ddb8aca3a58b300
    source_path: gateway/background-process.md
    workflow: 16
---

OpenClaw запускає shell-команди через інструмент `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` для контекстно-залежних правил shell/профілю.
- Для довготривалої роботи, яка починається зараз, запустіть її один раз і покладайтеся на автоматичне
  пробудження після завершення, коли воно ввімкнене й команда видає вивід або завершується з помилкою.
- Якщо автоматичне пробудження після завершення недоступне або потрібне підтвердження тихого успіху
  для команди, яка коректно завершилася без виводу, використовуйте `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 год)
- `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, щоб поточний transcript,
  стан 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)