---
read_when:
- Использование или изменение инструмента exec
- Отладка поведения stdin или TTY
summary: Использование инструмента Exec, режимы stdin и поддержка TTY
title: Инструмент Exec
x-i18n:
generated_at: "2026-06-28T23:52:06Z"
model: gpt-5.5
postprocess_version: locale-links-v1
provider: openai
source_hash: d2831d9e66b25ce251f90e59a41b25234e22106d865466e61b878e3999e849dc
source_path: tools/exec.md
workflow: 16
---
Выполняйте команды оболочки в рабочей области. `exec` — изменяющая поверхность оболочки: команды могут создавать, редактировать или удалять файлы везде, где это разрешает выбранный хост или файловая система песочницы. Отключение файловых инструментов OpenClaw, таких как `write`, `edit` или `apply_patch`, не делает `exec` доступным только для чтения.
Поддерживает выполнение на переднем плане и в фоне через `process`. Если `process` запрещен, `exec` выполняется синхронно и игнорирует `yieldMs`/`background`.
Фоновые сеансы ограничены областью агента; `process` видит только сеансы того же агента.
## Параметры
Команда оболочки для выполнения.
Рабочий каталог для команды.
Переопределения окружения в виде ключ/значение, объединяемые поверх унаследованного окружения.
Автоматически перевести команду в фон после этой задержки (мс).
Сразу перевести команду в фон вместо ожидания `yieldMs`.
Переопределить настроенный тайм-аут exec для этого вызова. Устанавливайте `timeout: 0` только когда команда должна выполняться без тайм-аута процесса exec.
Запускать в псевдотерминале, когда он доступен. Используйте для CLI, требующих TTY, кодирующих агентов и терминальных UI.
Где выполнять. `auto` разрешается в `sandbox`, когда активна среда выполнения песочницы, и в `gateway` в остальных случаях.
Игнорируется для обычных вызовов инструментов. Безопасность `gateway` / `node` управляется
`tools.exec.security` и файлом одобрений хоста; повышенный режим может
принудительно установить `security=full` только когда оператор явно предоставляет повышенный доступ.
Базовый режим запроса берется из `tools.exec.ask` и одобрений хоста.
Для вызовов модели, пришедших из канала, `ask` для отдельного вызова игнорируется, когда
эффективный запрос хоста равен `off`; иначе он может только усилиться до более строгого
режима. Доверенные внутренние/API вызывающие стороны, которые создают инструменты exec с
явным значением `ask`, не меняются.
ID/имя Node, когда `host=node`.
Запросить повышенный режим — выйти из песочницы на настроенный путь хоста. `security=full` принудительно устанавливается только когда elevated разрешается в `full`.
Примечания:
- `host` по умолчанию равен `auto`: песочница, когда для сеанса активна среда выполнения песочницы, иначе gateway.
- `host` принимает только `auto`, `sandbox`, `gateway` или `node`. Это не селектор имени хоста; значения, похожие на имена хостов, отклоняются до запуска команды.
- `auto` — стратегия маршрутизации по умолчанию, а не подстановочный шаблон. `host=node` для отдельного вызова разрешен из `auto`; `host=gateway` для отдельного вызова разрешен только когда среда выполнения песочницы не активна.
- `tools.exec.mode` — нормализованный переключатель политики. Значения: `deny`, `allowlist`, `ask`, `auto` и `full`. `auto` напрямую запускает детерминированные совпадения allowlist/safe-bin и направляет каждый оставшийся случай одобрения exec через нативного авторецензента OpenClaw перед запросом человека. `ask` / `ask=always` по-прежнему каждый раз спрашивает человека.
- Без дополнительной конфигурации `host=auto` все равно «просто работает»: если песочницы нет, он разрешается в `gateway`; если песочница активна, он остается в песочнице.
- `elevated` выходит из песочницы на настроенный путь хоста: `gateway` по умолчанию или `node`, когда `tools.exec.host=node` (или значение сеанса по умолчанию — `host=node`). Доступно только когда повышенный доступ включен для текущего сеанса/провайдера.
- Одобрения `gateway`/`node` управляются файлом одобрений хоста.
- `node` требует сопряженный Node (сопутствующее приложение или headless-хост Node).
- Если доступно несколько Node, задайте `exec.node` или `tools.exec.node`, чтобы выбрать один.
- `exec host=node` — единственный путь выполнения команд оболочки для Node; устаревшая обертка `nodes.run` удалена.
- `timeout` применяется к выполнению на переднем плане, в фоне, `yieldMs`, gateway, песочнице и `system.run` на Node. Если опущен, OpenClaw использует `tools.exec.timeoutSec`; явный `timeout: 0` отключает тайм-аут процесса exec для этого вызова.
- На не-Windows хостах exec использует `SHELL`, если он задан; если `SHELL` — `fish`, он предпочитает `bash` (или `sh`)
из `PATH`, чтобы избежать скриптов, несовместимых с fish, затем откатывается к `SHELL`, если ни один не найден.
- На Windows хостах exec предпочитает обнаружение PowerShell 7 (`pwsh`) (Program Files, ProgramW6432, затем PATH),
затем откатывается к Windows PowerShell 5.1.
- На не-Windows gateway-хостах команды exec bash и zsh используют стартовый снимок. OpenClaw захватывает пригодные для source
псевдонимы/функции и небольшой безопасный набор окружения из стартовых файлов оболочки в
`$OPENCLAW_STATE_DIR/cache/shell-snapshots/`, затем выполняет source этого снимка перед каждой командой exec.
Переменные, похожие на секреты, исключаются; exec в песочнице и Node не используют этот снимок. Задайте
`OPENCLAW_EXEC_SHELL_SNAPSHOT=0` в окружении процесса Gateway, чтобы отключить этот путь снимков.
- Выполнение на хосте (`gateway`/`node`) отклоняет `env.PATH` и переопределения загрузчика (`LD_*`/`DYLD_*`), чтобы
предотвратить подмену бинарных файлов или внедренный код.
- OpenClaw задает `OPENCLAW_SHELL=exec` в окружении порожденной команды (включая выполнение в PTY и песочнице), чтобы правила оболочки/профиля могли определить контекст инструмента exec.
- Для запусков из каналов OpenClaw также предоставляет узкую JSON-полезную нагрузку с идентичностью отправителя/чата в
`OPENCLAW_CHANNEL_CONTEXT`, когда канал предоставил эти ID.
- `openclaw channels login` заблокирован из `exec`, потому что это интерактивный поток авторизации канала; запускайте его в терминале на gateway-хосте или используйте нативный для канала инструмент входа из чата, когда он существует.
- Важно: песочница **по умолчанию отключена**. Если песочница отключена, неявный `host=auto`
разрешается в `gateway`. Явный `host=sandbox` все равно закрыто завершается ошибкой вместо тихого
запуска на gateway-хосте. Включите песочницу или используйте `host=gateway` с одобрениями.
- Предварительные проверки скриптов (для распространенных ошибок синтаксиса оболочки Python/Node) проверяют только файлы внутри
эффективной границы `workdir`. Если путь скрипта разрешается за пределами `workdir`, предварительная проверка для
этого файла пропускается.
- Для длительной работы, которая начинается сейчас, запустите ее один раз и полагайтесь на автоматическое
пробуждение по завершению, когда оно включено и команда выводит данные или завершается ошибкой.
Используйте `process` для логов, статуса, ввода или вмешательства; не имитируйте
планирование циклами sleep, циклами тайм-аутов или повторным опросом.
- Для работы, которая должна произойти позже или по расписанию, используйте cron вместо
шаблонов sleep/delay в `exec`.
## Конфигурация
- `tools.exec.notifyOnExit` (по умолчанию: true): когда true, фоновые сеансы exec ставят системное событие в очередь и запрашивают Heartbeat при выходе.
- `tools.exec.approvalRunningNoticeMs` (по умолчанию: 10000): выдать одно уведомление «выполняется», когда exec, ограниченный одобрением, работает дольше этого времени (0 отключает).
- `tools.exec.timeoutSec` (по умолчанию: 1800): тайм-аут exec по умолчанию для каждой команды в секундах. `timeout` для отдельного вызова переопределяет его; `timeout: 0` для отдельного вызова отключает тайм-аут процесса exec.
- `tools.exec.host` (по умолчанию: `auto`; разрешается в `sandbox`, когда среда выполнения песочницы активна, иначе в `gateway`)
- `tools.exec.security` (по умолчанию: `deny` для песочницы, `full` для gateway + node, когда не задано)
- `tools.exec.ask` (по умолчанию: `off`)
- Выполнение exec на хосте без одобрений является настройкой по умолчанию для gateway + node. Если нужно поведение с одобрениями/allowlist, ужесточите и `tools.exec.*`, и файл одобрений хоста; см. [Одобрения exec](/ru/tools/exec-approvals#yolo-mode-no-approval).
- YOLO берется из значений политики хоста по умолчанию (`security=full`, `ask=off`), а не из `host=auto`. Если нужно принудительно маршрутизировать в gateway или node, задайте `tools.exec.host` или используйте `/exec host=...`.
- В режиме `security=full` плюс `ask=off` host exec напрямую следует настроенной политике; дополнительного эвристического префильтра обфускации команд или слоя отклонения предварительной проверки скриптов нет.
- `tools.exec.node` (по умолчанию: не задано)
- `tools.exec.strictInlineEval` (по умолчанию: false): когда true, формы inline eval интерпретаторов, такие как `python -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `lua -e` и `osascript -e`, требуют рецензента или явного одобрения. В `mode=auto` обычный путь одобрения exec может позволить нативному авторецензенту разрешить явно низкорисковую разовую команду; прямые вызовы `system.run` на node-хосте все равно требуют явного одобрения, потому что они не могут передать команду в маршрут человеческого одобрения. Если рецензент запрашивает, запрос отправляется человеку. `allow-always` все еще может сохранять безвредные вызовы интерпретаторов/скриптов, но формы inline-eval не становятся долговременными правилами разрешения.
- `tools.exec.commandHighlighting` (по умолчанию: false): когда true, запросы одобрения могут подсвечивать полученные парсером фрагменты команд в тексте команды. Задайте `true` глобально или для отдельного агента, чтобы включить подсветку текста команд без изменения политики одобрения exec.
- `tools.exec.pathPrepend`: список каталогов для добавления в начало `PATH` при запусках exec (только gateway + песочница).
- `tools.exec.safeBins`: безопасные бинарные файлы только со stdin, которые могут запускаться без явных записей allowlist. Подробнее о поведении см. [Безопасные бинарные файлы](/ru/tools/exec-approvals-advanced#safe-bins-stdin-only).
- `tools.exec.safeBinTrustedDirs`: дополнительные явные каталоги, доверенные для проверок путей `safeBins`. Записи `PATH` никогда не считаются доверенными автоматически. Встроенные значения по умолчанию: `/bin` и `/usr/bin`.
- `tools.exec.safeBinProfiles`: необязательная пользовательская политика argv для каждого безопасного бинарного файла (`minPositional`, `maxPositional`, `allowedValueFlags`, `deniedFlags`).
Пример:
```json5
{
tools: {
exec: {
pathPrepend: ["~/bin", "/opt/oss/bin"],
},
},
}
```
### Обработка PATH
- `host=gateway`: объединяет `PATH` вашей login-shell в окружение exec. Переопределения `env.PATH`
отклоняются для выполнения на хосте. Сам daemon по-прежнему запускается с минимальным `PATH`:
- macOS: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`
- Linux: `/usr/local/bin`, `/usr/bin`, `/bin`
- Чтобы предотвратить переопределение приоритетных путей пользовательской конфигурацией оболочки (например, `~/.zshenv` или `/etc/zshenv`) во время запуска, записи `tools.exec.pathPrepend` безопасно добавляются в начало финального `PATH` внутри команды оболочки прямо перед выполнением.
- `host=sandbox`: запускает `sh -lc` (login shell) внутри контейнера, поэтому `/etc/profile` может сбросить `PATH`.
OpenClaw добавляет `env.PATH` после source профиля через внутреннюю переменную окружения (без интерполяции оболочки);
`tools.exec.pathPrepend` применяется и здесь.
- `host=node`: на Node отправляются только переданные вами незаблокированные переопределения окружения. Переопределения `env.PATH`
отклоняются для выполнения на хосте и игнорируются node-хостами. Если нужны дополнительные записи PATH на Node,
настройте окружение службы node-хоста (systemd/launchd) или установите инструменты в стандартные расположения.
Привязка Node для отдельного агента (используйте индекс агента в списке в конфигурации):
```bash
openclaw config get agents.list
openclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"
```
Control UI: вкладка Nodes содержит небольшую панель «Привязка exec-Node» для тех же настроек.
## Переопределения сеанса (`/exec`)
Используйте `/exec`, чтобы задать значения по умолчанию **для отдельного сеанса** для `host`, `security`, `ask` и `node`.
Отправьте `/exec` без аргументов, чтобы показать текущие значения.
Пример:
```
/exec host=auto security=allowlist ask=on-miss node=mac-1
```
## Модель авторизации
`/exec` учитывается только для **авторизованных отправителей** (списки разрешений/сопряжение каналов плюс `commands.useAccessGroups`).
Он обновляет **только состояние сеанса** и не записывает конфигурацию. Авторизованные отправители внешних каналов могут
задавать эти значения сеанса по умолчанию. Внутренним клиентам Gateway/webchat нужен `operator.admin`, чтобы сохранять их.
Чтобы жестко отключить exec, запретите его через политику инструментов (`tools.deny: ["exec"]` или для отдельного агента). Одобрения хоста
по-прежнему применяются, если вы явно не зададите `security=full` и `ask=off`.
## Одобрения exec (сопутствующее приложение / хост Node)
Агенты в песочнице могут требовать одобрение для каждого запроса перед запуском `exec` на Gateway или хосте Node.
См. [Одобрения exec](/ru/tools/exec-approvals) для политики, списка разрешений и UI-потока.
Когда требуются одобрения, инструмент exec сразу возвращает
`status: "approval-pending"` и идентификатор одобрения. После одобрения (или отказа / истечения времени ожидания)
Gateway отправляет системные события хода и завершения команды только для одобренных запусков
(`Exec running` / `Exec finished`). Отклоненные или просроченные одобрения являются конечными и не
пробуждают сеанс агента системным событием об отказе.
В каналах с нативными карточками/кнопками одобрения агент должен сначала полагаться на этот
нативный UI и включать ручную команду `/approve` только когда результат инструмента
явно сообщает, что одобрения в чате недоступны или ручное одобрение является
единственным путем.
## Список разрешений + безопасные исполняемые файлы
Ручное применение списка разрешений сопоставляет glob-шаблоны разрешенных путей исполняемых файлов и
glob-шаблоны простых имен команд. Простые имена совпадают только с командами, вызванными через PATH, поэтому `rg` может соответствовать
`/opt/homebrew/bin/rg`, когда команда — `rg`, но не `./rg` или `/tmp/rg`.
Когда `security=allowlist`, shell-команды автоматически разрешаются только если каждый сегмент конвейера
есть в списке разрешений или является безопасным исполняемым файлом. Связывание команд (`;`, `&&`, `||`) и перенаправления
отклоняются в режиме списка разрешений, если каждый сегмент верхнего уровня не удовлетворяет
списку разрешений (включая безопасные исполняемые файлы). Перенаправления остаются неподдерживаемыми.
Долговременное доверие `allow-always` не обходит это правило: связанная команда по-прежнему требует, чтобы каждый
сегмент верхнего уровня совпадал.
`autoAllowSkills` — это отдельный удобный путь в одобрениях exec. Это не то же самое, что
ручные записи списка разрешенных путей. Для строгого явного доверия оставляйте `autoAllowSkills` отключенным.
Используйте два элемента управления для разных задач:
- `tools.exec.safeBins`: небольшие потоковые фильтры только для stdin.
- `tools.exec.safeBinTrustedDirs`: явные дополнительные доверенные каталоги для путей безопасных исполняемых файлов.
- `tools.exec.safeBinProfiles`: явная политика argv для пользовательских безопасных исполняемых файлов.
- список разрешений: явное доверие к путям исполняемых файлов.
Не рассматривайте `safeBins` как универсальный список разрешений и не добавляйте исполняемые файлы интерпретаторов/рантаймов (например, `python3`, `node`, `ruby`, `bash`). Если они нужны, используйте явные записи списка разрешений и оставляйте запросы одобрения включенными.
`openclaw security audit` предупреждает, когда записи `safeBins` для интерпретаторов/рантаймов не имеют явных профилей, а `openclaw doctor --fix` может создать каркас отсутствующих пользовательских записей `safeBinProfiles`.
`openclaw security audit` и `openclaw doctor` также предупреждают, когда вы явно добавляете исполняемые файлы с широким поведением, такие как `jq`, обратно в `safeBins`.
Если вы явно разрешаете интерпретаторы, включите `tools.exec.strictInlineEval`, чтобы формы встроенной оценки кода по-прежнему требовали проверки рецензентом или явного одобрения.
Полные сведения о политике и примеры см. в [Одобрения exec](/ru/tools/exec-approvals-advanced#safe-bins-stdin-only) и [Безопасные исполняемые файлы и список разрешений](/ru/tools/exec-approvals-advanced#safe-bins-versus-allowlist).
## Примеры
Передний план:
```json
{ "tool": "exec", "command": "ls -la" }
```
Фоновый режим + опрос:
```json
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":""}
```
Опрос предназначен для статуса по запросу, а не для циклов ожидания. Если автоматическое пробуждение по завершению
включено, команда может разбудить сеанс, когда выводит данные или завершается с ошибкой.
Отправка клавиш (в стиле tmux):
```json
{"tool":"process","action":"send-keys","sessionId":"","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"","keys":["Up","Up","Enter"]}
```
Отправка (только CR):
```json
{ "tool": "process", "action": "submit", "sessionId": "" }
```
Вставка (по умолчанию bracketed):
```json
{ "tool": "process", "action": "paste", "sessionId": "", "text": "line1\nline2\n" }
```
## apply_patch
`apply_patch` — это подинструмент `exec` для структурированных многофайловых правок.
Он включен по умолчанию для моделей OpenAI и OpenAI Codex. Используйте конфигурацию только
когда хотите отключить его или ограничить конкретными моделями:
```json5
{
tools: {
exec: {
applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.5"] },
},
},
}
```
Примечания:
- Доступно только для моделей OpenAI/OpenAI Codex.
- Политика инструментов по-прежнему применяется; `allow: ["write"]` неявно разрешает `apply_patch`.
- `deny: ["write"]` не запрещает `apply_patch`; запретите `apply_patch` явно или используйте `deny: ["group:fs"]`, когда записи патчей также должны блокироваться.
- Конфигурация находится в `tools.exec.applyPatch`.
- `tools.exec.applyPatch.enabled` по умолчанию равно `true`; задайте `false`, чтобы отключить инструмент для моделей OpenAI.
- `tools.exec.applyPatch.workspaceOnly` по умолчанию равно `true` (только внутри рабочей области). Задавайте `false` только если намеренно хотите, чтобы `apply_patch` записывал/удалял файлы за пределами каталога рабочей области.
## Связанные разделы
- [Одобрения exec](/ru/tools/exec-approvals) — шлюзы одобрения для shell-команд
- [Песочница](/ru/gateway/sandboxing) — запуск команд в изолированных окружениях
- [Фоновый процесс](/ru/gateway/background-process) — длительно выполняющиеся exec и инструмент process
- [Безопасность](/ru/gateway/security) — политика инструментов и повышенный доступ