--- read_when: - Добавление или изменение поведения фонового выполнения команд - Отладка длительно выполняющихся задач exec summary: Фоновое выполнение команд и управление процессами title: Фоновое выполнение и инструмент управления процессами x-i18n: generated_at: "2026-07-13T19:45:49Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: b540455797df71dcdb18b0caa5f5088e81ef8823e0ec79364bebad8e6f060f12 source_path: gateway/background-process.md workflow: 16 --- OpenClaw выполняет команды оболочки с помощью инструмента `exec` и хранит длительно выполняющиеся задачи в памяти. Инструмент `process` управляет этими фоновыми сеансами. ## Инструмент exec Параметры: | Параметр | Описание | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `command` | Обязательный. Команда оболочки для выполнения. | | `workdir` | Рабочий каталог; не указывайте, чтобы использовать cwd по умолчанию. | | `env` | Дополнительные переменные окружения для команды. | | `yieldMs` | Время ожидания в миллисекундах перед переводом в фоновый режим (по умолчанию 10000). | | `background` | Немедленно запустить в фоновом режиме. | | `timeout` | Тайм-аут в секундах (по умолчанию `tools.exec.timeoutSec`); по истечении процесс завершается. Установите `timeout: 0`, чтобы отключить тайм-аут процесса exec для этого вызова. | | `pty` | Запустить в псевдотерминале, если он доступен (CLI, требующие TTY, агенты программирования). | | `elevated` | Запустить вне песочницы, если режим повышения привилегий включён/разрешён (`gateway` по умолчанию или `node`, если целью exec является `node`). | | `host` | Цель exec: `auto`, `sandbox`, `gateway` или `node`. | | `node` | Идентификатор/имя Node, используется с `host: "node"`. | Поведение: - Запуски на переднем плане возвращают вывод напрямую. - При переводе в фоновый режим (явно или по тайм-ауту `yieldMs`) инструмент возвращает `status: "running"` + `sessionId` и краткий фрагмент конца вывода. - Запуски в фоновом режиме и с `yieldMs` наследуют `tools.exec.timeoutSec`, если в вызове явно не передан `timeout`. - Вывод остаётся в памяти, пока сеанс не будет опрошен или очищен. - Если инструмент `process` запрещён, `exec` выполняется синхронно и игнорирует `yieldMs`/`background`. - Порождаемые команды exec получают `OPENCLAW_SHELL=exec` для контекстно-зависимых правил оболочки/профиля. - Для длительной работы, начинающейся сейчас: запустите её один раз и полагайтесь на автоматическое уведомление о завершении (если оно включено), когда команда выдаст вывод или завершится с ошибкой. - Если автоматическое уведомление о завершении недоступно или необходимо подтвердить успешное завершение команды без вывода, выполните опрос с помощью `process`. - Не имитируйте напоминания или отложенные последующие действия циклами `sleep` либо повторным опросом — для будущих задач используйте cron. ### Переопределения через переменные окружения | Переменная | Действие | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `OPENCLAW_BASH_YIELD_MS` | Время ожидания по умолчанию перед переводом в фоновый режим (мс). По умолчанию 10000, ограничено диапазоном 10-120000. | | `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 | То же, что `OPENCLAW_BASH_YIELD_MS`. | | `tools.exec.timeoutSec` | 1800 | Тайм-аут по умолчанию для каждого вызова. | | `tools.exec.cleanupMs` | 1800000 | То же, что `OPENCLAW_BASH_JOB_TTL_MS`. | | `tools.exec.notifyOnExit` | true | Поставить системное событие в очередь и запросить Heartbeat при завершении фонового exec. | | `tools.exec.notifyOnExitEmptySuccess` | false | Также ставить в очередь события завершения для успешно выполненных фоновых запусков без вывода. | ## Связывание дочерних процессов При порождении длительно выполняющихся дочерних процессов вне инструментов exec/process (перезапуски CLI, вспомогательные процессы Gateway) подключайте вспомогательный мост дочерних процессов, чтобы сигналы завершения перенаправлялись, а обработчики отсоединялись при выходе/ошибке. Это предотвращает появление осиротевших процессов в systemd и обеспечивает согласованное завершение работы на разных платформах. ## Инструмент process Действия: | Действие | Результат | | ----------- | ----------------------------------------------------------------------------- | | `list` | Выполняющиеся и завершённые сеансы. | | `poll` | Получить новый вывод сеанса (также сообщает статус завершения). | | `log` | Прочитать объединённый вывод и подсказки по восстановлению ввода. Поддерживает `offset` + `limit`. | | `write` | Отправить данные в stdin (`data`, необязательный `eof`). | | `send-keys` | Отправить явные токены клавиш или байты в сеанс на базе PTY. | | `submit` | Отправить Enter/возврат каретки в сеанс на базе PTY. | | `paste` | Отправить буквальный текст, при необходимости обёрнутый в режим bracketed paste. | | `kill` | Завершить фоновый сеанс. | | `clear` | Удалить завершённый сеанс из памяти. | | `remove` | Завершить принудительно, если сеанс выполняется, иначе очистить, если он завершён. | Примечания: - В списке сохраняются только фоновые сеансы — исключительно в памяти, не на диске. При перезапуске процесса сеансы теряются. - Активный фоновый сеанс блокирует совместное приостановление хоста и безопасный перезапуск Gateway, пока владелец процесса не подтвердит его фактическое завершение. - `process remove` может скрыть выполняющийся сеанс сразу после запроса завершения; приостановление и перезапуск остаются заблокированными до подтверждения выхода. - Журналы сеансов сохраняются в истории чата, только если выполнить `process poll`/`log` и результат инструмента будет записан. - `process` действует в рамках отдельного агента; он видит только сеансы, запущенные этим агентом. - Используйте `poll`/`log` для получения статуса, журналов или подтверждения завершения, когда автоматическое уведомление о завершении недоступно. - Перед восстановлением интерактивного CLI используйте `log`, чтобы одновременно видеть текущую расшифровку, состояние stdin и подсказку об ожидании ввода. - Используйте `write`/`send-keys`/`submit`/`paste`/`kill`, когда требуется ввод или вмешательство. - `process list` включает вычисляемое значение `name` (командный глагол + цель) для быстрого просмотра. - `process list`, `poll` и `log` сообщают `waitingForInput`, только когда stdin сеанса всё ещё доступен для записи и сеанс бездействует дольше порога ожидания ввода (по умолчанию 15000 мс, `OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS`). - `process log` использует построчные `offset`/`limit`. Если оба параметра не указаны, возвращаются последние 200 строк с подсказкой по постраничному просмотру. Если задан `offset`, а `limit` — нет, возвращаются строки от `offset` до конца (без ограничения в 200 строк). - `timeout` в `poll` ожидает до указанного количества миллисекунд перед возвратом; значения свыше 30000 ограничиваются до 30000. - Опрос предназначен для получения статуса по запросу, а не для планирования циклов ожидания. Если работа должна выполняться позднее, используйте cron. ## Примеры Запустить длительную задачу и опросить её позднее: ```json { "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 } ``` ```json { "tool": "process", "action": "poll", "sessionId": "" } ``` Проверить интерактивный сеанс перед отправкой ввода: ```json { "tool": "process", "action": "log", "sessionId": "" } ``` Немедленно запустить в фоновом режиме: ```json { "tool": "exec", "command": "npm run build", "background": true } ``` Отправить данные в stdin: ```json { "tool": "process", "action": "write", "sessionId": "", "data": "y\n" } ``` Отправить клавиши PTY: ```json { "tool": "process", "action": "send-keys", "sessionId": "", "keys": ["C-c"] } ``` Отправить текущую строку: ```json { "tool": "process", "action": "submit", "sessionId": "" } ``` Вставить буквальный текст: ```json { "tool": "process", "action": "paste", "sessionId": "", "text": "line1\nline2\n" } ``` ## Связанные материалы - [Инструмент Exec](/ru/tools/exec) - [Подтверждения Exec](/ru/tools/exec-approvals)