Фоновое выполнение и инструмент процессов

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

Инструмент 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 для правил оболочки/профиля, учитывающих контекст.
• Для длительной работы, которая начинается сейчас, запустите ее один раз и полагайтесь на автоматическое пробуждение при завершении, когда оно включено и команда выводит данные или завершается с ошибкой.
• Если автоматическое пробуждение при завершении недоступно или нужно подтвердить тихий успешный результат для команды, которая завершилась без ошибок и без вывода, используйте process для подтверждения завершения.
• Не имитируйте напоминания или отложенные повторные действия циклами sleep или повторным опросом; используйте cron для будущей работы.

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

При запуске длительных дочерних процессов вне инструментов exec/process (например, перезапуски CLI или вспомогательные процессы gateway) подключайте вспомогательную связку дочернего процесса, чтобы сигналы завершения пересылались, а слушатели отсоединялись при выходе/ошибке. Это предотвращает осиротевшие процессы в systemd и сохраняет единое поведение завершения работы на разных платформах.

Переопределения окружения:

• OPENCLAW_BASH_YIELD_MS: задержка yield по умолчанию (мс)
• OPENCLAW_BASH_MAX_OUTPUT_CHARS: лимит вывода в памяти (символы)
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: лимит ожидающих stdout/stderr для каждого потока (символы)
• OPENCLAW_BASH_JOB_TTL_MS: TTL для завершенных сеансов (мс, ограничено 1m–3h)
• 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 }

Отправить 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" }

Связанные разделы

• Инструмент Exec
• Подтверждения Exec