Конфигурация и операции

Фоновый 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 получают OPENCLAW_SHELL=exec для контекстно-зависимых правил shell/профиля.

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

При запуске долгоиграющих дочерних процессов вне инструментов exec/process (например, CLI respawns или помощники шлюза) подключите вспомогательный мост для дочерних процессов, чтобы сигналы завершения передавались, а слушатели отключались при выходе/ошибке. Это позволяет избежать появления процессов-сирот в 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 завершится.
  • 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, и 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" }

Блокировка шлюзаНесколько шлюзов