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

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

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 год)

Конфігурація (рекомендовано):

- `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" }
```

## Пов’язане

- [Інструмент Exec](/uk/tools/exec)
- [Погодження Exec](/uk/tools/exec-approvals)
