---
read_when:
    - Добавление или изменение поведения фонового выполнения
    - Отладка длительных задач exec
summary: Фоновое выполнение exec и управление процессами
title: Фоновое выполнение и инструмент процессов
x-i18n:
    generated_at: "2026-06-28T22:54:41Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 5822c1e26b0144c5216ae6e59e279ccc506cf4c0a42b8cd6c386f535fe458bd3
    source_path: gateway/background-process.md
    workflow: 16
---

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.

## Примеры

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

```json
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
```

```json
{ "tool": "process", "action": "poll", "sessionId": "<id>" }
```

Проверить интерактивный сеанс перед отправкой ввода:

```json
{ "tool": "process", "action": "log", "sessionId": "<id>" }
```

Сразу запустить в фоне:

```json
{ "tool": "exec", "command": "npm run build", "background": true }
```

Отправить stdin:

```json
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
```

Отправить клавиши PTY:

```json
{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }
```

Отправить текущую строку:

```json
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
```

Вставить буквальный текст:

```json
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
```

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

- [Инструмент Exec](/ru/tools/exec)
- [Подтверждения Exec](/ru/tools/exec-approvals)