--- read_when: - Додавання або змінення поведінки фонового виконання - Налагодження довготривалих завдань виконання summary: Фонове виконання команд і керування процесами title: Фонове виконання та інструмент керування процесами x-i18n: generated_at: "2026-07-12T13:10:51Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: b540455797df71dcdb18b0caa5f5088e81ef8823e0ec79364bebad8e6f060f12 source_path: gateway/background-process.md workflow: 16 --- OpenClaw виконує команди оболонки через інструмент `exec` і зберігає довготривалі завдання в пам’яті. Інструмент `process` керує цими фоновими сеансами. ## Інструмент exec Параметри: | Параметр | Опис | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `command` | Обов’язковий. Команда оболонки для виконання. | | `workdir` | Робочий каталог; не вказуйте, щоб використовувати стандартний поточний робочий каталог. | | `env` | Додаткові змінні середовища для команди. | | `yieldMs` | Кількість мілісекунд очікування перед переведенням у фоновий режим (стандартно 10000). | | `background` | Негайно виконувати у фоновому режимі. | | `timeout` | Час очікування в секундах (стандартно `tools.exec.timeoutSec`); після його завершення процес припиняється. Установіть `timeout: 0`, щоб вимкнути обмеження часу процесу exec для цього виклику. | | `pty` | Виконувати в псевдотерміналі, якщо він доступний (CLI, що потребують TTY, агенти програмування). | | `elevated` | Виконувати поза пісочницею, якщо привілейований режим увімкнено/дозволено (стандартно `gateway` або `node`, коли ціллю exec є `node`). | | `host` | Ціль exec: `auto`, `sandbox`, `gateway` або `node`. | | `node` | Ідентифікатор/назва Node, використовується з `host: "node"`. | Поведінка: - Виконання на передньому плані повертає вивід безпосередньо. - Після переведення у фоновий режим (явно або через завершення часу `yieldMs`) інструмент повертає `status: "running"` + `sessionId` і короткий фрагмент кінця виводу. - Фонові виконання та виконання з `yieldMs` успадковують `tools.exec.timeoutSec`, якщо у виклику явно не передано `timeout`. - Вивід залишається в пам’яті, доки не буде опитано або очищено сеанс. - Якщо інструмент `process` заборонено, `exec` виконується синхронно та ігнорує `yieldMs`/`background`. - Запущені команди exec отримують `OPENCLAW_SHELL=exec` для контекстно-залежних правил оболонки/профілю. - Для довготривалої роботи, яка починається зараз: запустіть її один раз і покладайтеся на автоматичне пробудження після завершення (якщо ввімкнено), щойно команда виведе дані або завершиться помилкою. - Якщо автоматичне пробудження після завершення недоступне або потрібне підтвердження тихого успішного виконання команди, яка завершується без виводу, опитуйте її за допомогою `process`. - Не імітуйте нагадування чи відкладені подальші дії циклами `sleep` або повторним опитуванням — для майбутньої роботи використовуйте Cron. ### Перевизначення через змінні середовища | Змінна | Вплив | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `OPENCLAW_BASH_YIELD_MS` | Стандартний час очікування перед переведенням у фоновий режим (мс). Стандартно 10000, обмежується діапазоном 10–120000. | | `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 | Те саме, що й `OPENCLAW_BASH_YIELD_MS`. | | `tools.exec.timeoutSec` | 1800 | Стандартний час очікування для кожного виклику. | | `tools.exec.cleanupMs` | 1800000 | Те саме, що й `OPENCLAW_BASH_JOB_TTL_MS`. | | `tools.exec.notifyOnExit` | true | Додає системну подію до черги та запитує Heartbeat після завершення фонового виконання exec. | | `tools.exec.notifyOnExitEmptySuccess` | false | Також додає до черги події завершення для успішних фонових виконань без виводу. | ## Міст для дочірніх процесів Під час запуску довготривалих дочірніх процесів поза інструментами exec/process (повторні запуски CLI, допоміжні засоби Gateway) підключайте допоміжний засіб мосту дочірніх процесів, щоб сигнали завершення передавалися далі, а обробники від’єднувалися після виходу/помилки. Це запобігає появі осиротілих процесів у systemd і забезпечує узгоджене завершення роботи на різних платформах. ## Інструмент process Дії: | Дія | Вплив | | ----------- | ---------------------------------------------------------------------------------------------------------- | | `list` | Активні та завершені сеанси. | | `poll` | Отримати новий вивід сеансу (також повідомляє стан завершення). | | `log` | Прочитати сукупний вивід і підказки щодо відновлення введення. Підтримує `offset` + `limit`. | | `write` | Надіслати дані до stdin (`data`, необов’язково `eof`). | | `send-keys` | Надіслати явні токени клавіш або байти до сеансу на основі PTY. | | `submit` | Надіслати Enter/повернення каретки до сеансу на основі PTY. | | `paste` | Надіслати буквальний текст, за потреби обгорнутий у режим вставлення в дужках. | | `kill` | Припинити фоновий сеанс. | | `clear` | Видалити завершений сеанс із пам’яті. | | `remove` | Припинити активний сеанс або очистити завершений. | Примітки: - У списку зберігаються лише фонові сеанси — тільки в пам’яті, не на диску. Після перезапуску процесу сеанси втрачаються. - Активний фоновий сеанс блокує узгоджене призупинення хоста та безпечний перезапуск Gateway, доки власник процесу не підтвердить його фактичне завершення. - `process 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 і неактивний довше за поріг очікування введення (стандартно 15000 мс, `OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS`). - `process log` використовує построкові `offset`/`limit`. Якщо обидва параметри не вказано, повертаються останні 200 рядків із підказкою щодо посторінкового перегляду. Якщо `offset` задано, а `limit` — ні, повертаються рядки від `offset` до кінця (без обмеження у 200 рядків). - `timeout` для `poll` очікує до вказаної кількості мілісекунд перед поверненням; значення понад 30000 обмежуються до 30000. - Опитування призначене для перевірки стану на вимогу, а не для планування циклів очікування. Якщо робота має виконатися пізніше, використовуйте Cron. ## Приклади Запустити довготривале завдання й опитати його пізніше: ```json { "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 } ``` ```json { "tool": "process", "action": "poll", "sessionId": "" } ``` Перевірити інтерактивний сеанс перед надсиланням введення: ```json { "tool": "process", "action": "log", "sessionId": "" } ``` Негайно запустити у фоновому режимі: ```json { "tool": "exec", "command": "npm run build", "background": true } ``` Надіслати дані до stdin: ```json { "tool": "process", "action": "write", "sessionId": "", "data": "y\n" } ``` Надіслати клавіші PTY: ```json { "tool": "process", "action": "send-keys", "sessionId": "", "keys": ["C-c"] } ``` Надіслати поточний рядок: ```json { "tool": "process", "action": "submit", "sessionId": "" } ``` Вставити буквальний текст: ```json { "tool": "process", "action": "paste", "sessionId": "", "text": "line1\nline2\n" } ``` ## Пов’язані матеріали - [Інструмент Exec](/uk/tools/exec) - [Схвалення Exec](/uk/tools/exec-approvals)