Фоновый 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 завершается.

Инструмент 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 строк).

Примеры¶

Запустить длительную задачу и опросить позже:

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