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

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

Инструмент exec

Ключевые параметры:

  • command (обязательно)
  • yieldMs (по умолчанию 10000): авто-фон после этой задержки
  • background (bool): фон немедленно
  • timeout (секунды, по умолчанию 1800): завершить процесс после этого тайм-аута
  • elevated (bool): запуск на хосте, если включен/разрешен режим elevated
  • Нужен настоящий TTY? Установите pty: true.
  • workdir, env

Поведение:

  • Запуски на переднем плане возвращают вывод напрямую.
  • При переходе в фон (явно или по тайм-ауту), инструмент возвращает status: "running" + sessionId и короткий хвост.
  • Вывод сохраняется в памяти до тех пор, пока сессия не будет опрошена или очищена.
  • Если инструмент process запрещен, exec работает синхронно и игнорирует yieldMs/background.

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

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

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

  • PI_BASH_YIELD_MS: задержка по умолчанию (мс)
  • 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 завершается.

Инструмент 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"\}
← Назад к документации