---
read_when:
- Використання або змінення інструмента exec
- Налагодження поведінки stdin або TTY
summary: Використання інструмента exec, режими stdin і підтримка TTY
title: Інструмент виконання
x-i18n:
generated_at: "2026-06-27T18:24:49Z"
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`, не змінюються.
Ідентифікатор/назва Node, коли `host=node`.
Запитати підвищений режим — вийти з пісочниці на налаштований шлях хоста. `security=full` примусово встановлюється лише тоді, коли elevated розв'язується як `full`.
Примітки:
- `host` за замовчуванням має значення `auto`: пісочниця, коли середовище виконання пісочниці активне для сеансу, інакше Gateway.
- `host` приймає лише `auto`, `sandbox`, `gateway` або `node`. Це не селектор імені хоста; значення, схожі на імена хостів, відхиляються до запуску команди.
- `auto` — це стандартна стратегія маршрутизації, а не wildcard. `host=node` на рівні виклику дозволено з `auto`; `host=gateway` на рівні виклику дозволено лише тоді, коли не активне середовище виконання пісочниці.
- `tools.exec.mode` — це нормалізований регулятор політики. Значення: `deny`, `allowlist`, `ask`, `auto` і `full`. `auto` запускає детерміновані збіги списку дозволених/безпечних бінарних файлів напряму та маршрутизує всі решту випадків схвалення exec через нативного авторецензента OpenClaw перед запитом до людини. `ask` / `ask=always` все ще щоразу запитує людину.
- Без додаткової конфігурації `host=auto` все одно "просто працює": якщо пісочниці немає, він розв'язується як `gateway`; якщо пісочниця активна, він залишається в пісочниці.
- `elevated` виходить із пісочниці на налаштований шлях хоста: `gateway` за замовчуванням або `node`, коли `tools.exec.host=node` (або типовий сеанс має `host=node`). Це доступно лише тоді, коли підвищений доступ увімкнено для поточного сеансу/провайдера.
- Схвалення `gateway`/`node` керуються файлом схвалень хоста.
- `node` потребує спареного вузла (супровідного застосунку або безголового хоста вузла).
- Якщо доступно кілька вузлів, установіть `exec.node` або `tools.exec.node`, щоб вибрати один.
- `exec host=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.
- На Gateway-хостах не Windows команди 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`, коли канал надав ці ідентифікатори.
- `openclaw channels login` заблоковано з `exec`, оскільки це інтерактивний потік автентифікації каналу; запустіть його в терміналі на Gateway-хості або використайте нативний для каналу інструмент входу з чату, коли він існує.
- Важливо: пісочниця **вимкнена за замовчуванням**. Якщо пісочницю вимкнено, неявний `host=auto`
розв'язується як `gateway`. Явний `host=sandbox` все ще відмовляє закрито замість тихого
запуску на Gateway-хості. Увімкніть пісочницю або використовуйте `host=gateway` зі схваленнями.
- Попередні перевірки скриптів (для поширених помилок синтаксису оболонки Python/Node) перевіряють лише файли всередині
ефективної межі `workdir`. Якщо шлях скрипта розв'язується за межами `workdir`, попередня перевірка для
цього файла пропускається.
- Для довготривалої роботи, що починається зараз, запустіть її один раз і покладайтеся на автоматичне
пробудження після завершення, коли воно ввімкнене і команда виводить дані або завершується з помилкою.
Використовуйте `process` для журналів, стану, введення або втручання; не імітуйте
планування циклами sleep, циклами тайм-аутів або повторним опитуванням.
- Для роботи, яка має відбутися пізніше або за розкладом, використовуйте Cron замість
шаблонів sleep/затримки з `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. Якщо вам потрібна поведінка схвалень/списку дозволених, посильте і `tools.exec.*`, і файл схвалень хоста; див. [Схвалення exec](/uk/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` 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-only безпечні бінарні файли, які можуть запускатися без явних записів у списку дозволених. Докладніше про поведінку див. [Безпечні бінарні файли](/uk/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`
відхиляються для виконання на хості. Сам демон усе ще працює з мінімальним `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` на початок після підключення профілю через внутрішню змінну середовища (без інтерполяції оболонки);
`tools.exec.pathPrepend` також застосовується тут.
- `host=node`: на вузол надсилаються лише неблоковані перевизначення середовища, які ви передаєте. Перевизначення `env.PATH`
відхиляються для виконання на хості та ігноруються Node-хостами. Якщо вам потрібні додаткові записи PATH на вузлі,
налаштуйте середовище служби 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 містить невелику панель "Прив'язка Node exec" для тих самих налаштувань.
## Перевизначення сеансу (`/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](/uk/tools/exec-approvals) щодо політики, списку дозволених і потоку UI.
Коли потрібні схвалення, інструмент exec негайно повертає
`status: "approval-pending"` та id схвалення. Після схвалення (або відхилення / тайм-ауту)
Gateway надсилає системні події прогресу й завершення команди лише для схвалених запусків
(`Exec running` / `Exec finished`). Відхилені або прострочені схвалення є кінцевими й не
пробуджують сесію агента системною подією відхилення.
У каналах із нативними картками/кнопками схвалення агент має спершу покладатися на цей
нативний UI і додавати ручну команду `/approve` лише тоді, коли результат інструмента
явно повідомляє, що схвалення в чаті недоступні або ручне схвалення є
єдиним шляхом.
## Список дозволених + безпечні бінарні файли
Ручне застосування списку дозволених зіставляє globs розв’язаних шляхів до бінарних файлів і globs
простих імен команд. Прості імена збігаються лише з командами, викликаними через 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` також попереджають, коли ви явно додаєте назад до `safeBins` бінарні файли широкої поведінки, як-от `jq`.
Якщо ви явно додаєте інтерпретатори до списку дозволених, увімкніть `tools.exec.strictInlineEval`, щоб форми inline code-eval усе одно вимагали рецензента або явного схвалення.
Повні деталі політики та приклади див. у [Схвалення exec](/uk/tools/exec-approvals-advanced#safe-bins-stdin-only) і [Безпечні бінарні файли порівняно зі списком дозволених](/uk/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": "" }
```
Вставити (у дужках за замовчуванням):
```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](/uk/tools/exec-approvals) — ворота схвалення для команд shell
- [Пісочниця](/uk/gateway/sandboxing) — запуск команд у середовищах пісочниці
- [Фоновий процес](/uk/gateway/background-process) — довготривалі exec та інструмент process
- [Безпека](/uk/gateway/security) — політика інструментів і підвищений доступ