Перейти к основному содержанию

​
Фоновый Exec + инструмент Process

OpenClaw выполняет shell‑команды через инструмент exec и хранит длительно выполняющиеся задачи в памяти. Инструмент process управляет этими фоновыми сеансами.

​
Инструмент exec

Ключевые параметры:
  • command (обязательно)
  • yieldMs (по умолчанию 10000): автоматический перевод в фон по истечении этой задержки
  • background (bool): немедленно запустить в фоне
  • timeout (секунды, по умолчанию 1800): завершить процесс по истечении этого тайм‑аута
  • elevated (bool): запускать на хосте, если повышенный режим включён/разрешён
  • Нужен реальный TTY? Установите pty: true.
  • workdir, env
Поведение:
  • Запуски в переднем плане возвращают вывод напрямую.
  • При переводе в фон (явно или по тайм‑ауту) инструмент возвращает status: "running" + sessionId и короткий хвост вывода.
  • Вывод хранится в памяти, пока сеанс не будет опрошен или очищен.
  • Если инструмент process запрещён, exec выполняется синхронно и игнорирует yieldMs/background.

​
Связывание дочерних процессов

При запуске длительно работающих дочерних процессов вне инструментов exec/process (например, при перезапуске CLI или вспомогательных процессах шлюза) подключайте помощник моста дочерних процессов, чтобы сигналы завершения передавались, а слушатели отсоединялись при выходе/ошибке. Это предотвращает появление «осиротевших» процессов в 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): поставить в очередь системное событие + запросить сигнал keepalive, когда фоновый exec завершается.
  • tools.exec.notifyOnExitEmptySuccess (по умолчанию false): если true, также ставит в очередь события завершения для успешно выполненных фоновых задач без вывода.

​
Инструмент process

Действия:
  • list: выполняющиеся + завершённые сеансы
  • poll: слить новый вывод для сеанса (также сообщает статус завершения)
  • log: прочитать агрегированный вывод (поддерживает offset + limit)
  • write: отправить stdin (data, необязательно eof)
  • kill: завершить фоновый сеанс
  • clear: удалить завершённый сеанс из памяти
  • remove: завершить, если выполняется, иначе очистить, если завершён
Примечания:
  • В памяти перечисляются/сохраняются только фоновые сеансы.
  • Сеансы теряются при перезапуске процесса (нет сохранения на диск).
  • Логи сеансов сохраняются в истории чата только если вы запускаете process poll/log и результат инструмента записывается.
  • process имеет область видимости «для каждого агента»; он видит только сеансы, запущенные этим агентом.
  • process list включает производный name (глагол команды + цель) для быстрого просмотра.
  • process log использует построчные offset/limit (опустите offset, чтобы получить последние N строк).
  • Если оба параметра offset и limit опущены, возвращаются последние 200 строк и добавляется подсказка о пагинации.
  • Если указан offset, а limit опущен, возвращается вывод от offset до конца (без ограничения в 200 строк).

​
Примеры

Запустить длительную задачу и опросить позже: 
{ "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" }