Фоновий exec та інструмент процесів

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Інструмент 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 для майбутньої роботи.

​

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

• 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 год)
• OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS: поріг простою виводу, після якого фонові сеанси з можливістю запису позначаються як такі, що ймовірно очікують введення (типово 15000 мс)

• 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 / повернення каретки до сеансу на базі PTY
• paste: надіслати буквальний текст, необов’язково обгорнутий у режим bracketed paste
• kill: завершити фоновий сеанс
• clear: видалити завершений сеанс із пам’яті
• remove: завершити, якщо запущений; інакше очистити, якщо завершений

• Лише фонові сеанси відображаються у списку/зберігаються в пам’яті.
• Сеанси втрачаються під час перезапуску процесу (без збереження на диск).
• Журнали сеансів зберігаються в історії чату лише якщо ви запускаєте process poll/log і результат інструмента записується.
• process має область дії на рівні агента; він бачить лише сеанси, запущені цим агентом.
• Використовуйте poll / log для статусу, журналів, підтвердження тихого успіху або підтвердження завершення, коли автоматичне пробудження після завершення недоступне.
• Використовуйте log перед відновленням інтерактивного CLI, щоб поточний transcript, стан stdin і підказка очікування введення були видимі разом.
• Використовуйте write / send-keys / submit / paste / kill, коли потрібне введення або втручання.
• process list містить похідне name (дієслово команди + ціль) для швидкого перегляду.
• process list, poll і log повідомляють waitingForInput лише коли сеанс усе ще має stdin з можливістю запису й простоює довше за поріг очікування введення.
• 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": "process", "action": "log", "sessionId": "<id>" }

{ "tool": "exec", "command": "npm run build", "background": true }

{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }

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

​

Пов’язане

• Інструмент Exec
• Затвердження Exec