---
read_when:
    - Додавання або зміна поведінки фонового exec შესრულения
    - Додавання або зміна поведінки фонового виконання exec
summary: Фонове виконання exec і керування процесами
title: Фоновий exec та інструмент process
x-i18n:
    generated_at: "2026-04-23T20:52:18Z"
    model: gpt-5.4
    provider: openai
    source_hash: 4b66a236f930f34314ffb98addecff292ca9fdc01e7e0842cd1f0c9ad01bb2bc
    source_path: gateway/background-process.md
    workflow: 15
---

# Фоновий exec + інструмент process

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

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

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

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

Поведінка:

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

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

Під час запуску довготривалих дочірніх процесів поза інструментами exec/process (наприклад, при повторних запусках CLI або допоміжних процесах 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`: надіслати явні key tokens або байти в сесію з 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" }
```
