Перейти до основного вмісту

​
Фоновий 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.

​
Приклади

Запустити довге завдання й опитати пізніше: 
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

{ "tool": "process", "action": "poll", "sessionId": "<id>" }
Негайний запуск у фоні: 
{ "tool": "exec", "command": "npm run build", "background": true }
Надіслати stdin: 
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
Надіслати клавіші PTY: 
{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }
Підтвердити поточний рядок: 
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
Вставити буквальний текст: 
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }