> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
```

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "poll", "sessionId": "<id>" }
```

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "log", "sessionId": "<id>" }
```

Немедленно запустить в фоновом режиме:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "npm run build", "background": true }
```

Отправить данные в stdin:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
```

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

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

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
```

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
```

## Связанные материалы

* [Инструмент Exec](https://docs2.openclaw.ai/ru/tools/exec.md)
* [Подтверждения Exec](https://docs2.openclaw.ai/ru/tools/exec-approvals.md)