---
read_when:
    - Додавання або зміна поведінки фонового exec
    - Налагодження довготривалих завдань exec
summary: Фонове виконання exec і керування процесами
title: Фоновий Exec та інструмент Process
x-i18n:
    generated_at: "2026-04-05T18:02:45Z"
    model: gpt-5.4
    provider: openai
    source_hash: 4398e2850f6f050944f103ad637cd9f578e9cc7fb478bc5cd5d972c92289b831
    source_path: gateway/background-process.md
    workflow: 15
---

# Фоновий Exec + інструмент Process

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

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

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

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

Поведінка:

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

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

Під час запуску довготривалих дочірніх процесів поза інструментами exec/process (наприклад, для повторних запусків CLI або helper-процесів gateway) підключайте helper містка дочірніх процесів, щоб сигнали завершення передавалися далі, а слухачі від’єднувалися після виходу/помилки. Це запобігає осиротілим процесам у 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 / carriage return до сесії з підтримкою 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.

## Приклади

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

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

```json
{ "tool": "process", "action": "poll", "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" }
```
