Інструмент виконання команд

Запускайте shell-команди в робочій області. exec — це змінювана shell-поверхня: команди можуть створювати, редагувати або видаляти файли всюди, де це дозволяє вибраний хост або файлова система пісочниці. Вимкнення файлових інструментів OpenClaw, як-от write, edit або apply_patch, не робить exec доступним лише для читання. Підтримує виконання на передньому плані та у фоні через process. Якщо process заборонено, exec виконується синхронно й ігнорує yieldMs/background. Фонові сесії обмежені окремим агентом; process бачить лише сесії того самого агента.

Параметри

command

string

обов'язково

Shell-команда для запуску.

workdir

string

за замовчуванням:"cwd"

Робочий каталог для команди.

env

object

Перевизначення середовища у форматі ключ/значення, об’єднані поверх успадкованого середовища.

yieldMs

number

за замовчуванням:"10000"

Автоматично перевести команду у фон після цієї затримки (мс).

background

boolean

за замовчуванням:"false"

Негайно перевести команду у фон замість очікування yieldMs.

timeout

number

за замовчуванням:"tools.exec.timeoutSec"

Перевизначити налаштований таймаут exec для цього виклику. Установлюйте timeout: 0 лише тоді, коли команда має виконуватися без таймауту процесу exec.

pty

boolean

за замовчуванням:"false"

Запустити в псевдотерміналі, коли доступно. Використовуйте для CLI лише з TTY, агентів кодування та термінальних інтерфейсів.

host

'auto' | 'sandbox' | 'gateway' | 'node'

за замовчуванням:"auto"

Де виконувати. auto визначається як sandbox, коли активне середовище виконання пісочниці, і як gateway в інших випадках.

security

'deny' | 'allowlist' | 'full'

Ігнорується для звичайних викликів інструментів. Безпека gateway / node керується tools.exec.security і ~/.openclaw/exec-approvals.json; розширений режим може примусово встановити security=full лише тоді, коли оператор явно надає розширений доступ.

ask

'off' | 'on-miss' | 'always'

Поведінка запиту схвалення для виконання gateway / node.

node

string

Ідентифікатор/ім’я Node, коли host=node.

elevated

boolean

за замовчуванням:"false"

Запросити розширений режим — вийти з пісочниці на налаштований шлях хоста. security=full примусово встановлюється лише тоді, коли elevated визначається як full.

Примітки:

host за замовчуванням має значення auto: пісочниця, коли середовище виконання пісочниці активне для сесії, інакше gateway.
host приймає лише auto, sandbox, gateway або node. Це не селектор імені хоста; значення, схожі на імена хостів, відхиляються до запуску команди.
auto — це стандартна стратегія маршрутизації, а не шаблон будь-якого значення. Окремий виклик host=node дозволено з auto; окремий виклик host=gateway дозволено лише коли середовище виконання пісочниці не активне.
Без додаткової конфігурації host=auto усе одно «просто працює»: якщо пісочниці немає, він визначається як gateway; якщо пісочниця активна, він залишається в пісочниці.
elevated виходить із пісочниці на налаштований шлях хоста: типово gateway або node, коли tools.exec.host=node (або стандарт сесії — host=node). Він доступний лише коли розширений доступ увімкнено для поточної сесії/провайдера.
Схвалення gateway/node керуються через ~/.openclaw/exec-approvals.json.
node потребує спареного Node (супровідної програми або headless-хоста Node).
Якщо доступно кілька Node, установіть exec.node або tools.exec.node, щоб вибрати один.
exec host=node — єдиний шлях shell-виконання для 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/node) відхиляє env.PATH і перевизначення завантажувача (LD_*/DYLD_*), щоб запобігти підміні бінарних файлів або впровадженню коду.
OpenClaw встановлює OPENCLAW_SHELL=exec у середовищі породженої команди (включно з виконанням у PTY і пісочниці), щоб правила shell/профілю могли виявляти контекст інструмента exec.
openclaw channels login заблоковано з exec, оскільки це інтерактивний потік авторизації каналу; запустіть його в терміналі на хості gateway або скористайтеся нативним для каналу інструментом входу з чату, якщо він існує.
Важливо: пісочниця типово вимкнена. Якщо пісочницю вимкнено, неявний host=auto визначається як gateway. Явний host=sandbox усе одно завершується закрито, замість тихого запуску на хості gateway. Увімкніть пісочницю або використовуйте host=gateway зі схваленнями.
Попередні перевірки скриптів (для поширених помилок shell-синтаксису Python/Node) перевіряють лише файли всередині ефективної межі workdir. Якщо шлях скрипта визначається поза workdir, попередня перевірка для цього файлу пропускається.
Для тривалої роботи, яка починається зараз, запустіть її один раз і покладайтеся на автоматичне пробудження після завершення, коли його ввімкнено і команда виводить дані або завершується помилкою. Використовуйте process для журналів, стану, вводу або втручання; не імітуйте планування через цикли sleep, цикли таймаутів або повторне опитування.
Для роботи, яка має відбутися пізніше або за розкладом, використовуйте cron замість шаблонів sleep/затримки в exec.

Конфігурація

tools.exec.notifyOnExit (типово: true): коли true, фонові сесії exec ставлять у чергу системну подію й запитують Heartbeat після завершення.
tools.exec.approvalRunningNoticeMs (типово: 10000): надсилати одне сповіщення “running”, коли 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.*, і хостовий ~/.openclaw/exec-approvals.json; див. схвалення Exec.
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, форми вбудованого eval інтерпретатора, як-от python -c, node -e, ruby -e, perl -e, php -r, lua -e і osascript -e, завжди потребують явного схвалення. allow-always усе ще може зберігати доброякісні виклики інтерпретатора/скриптів, але форми inline-eval усе одно запитують щоразу.
tools.exec.commandHighlighting (типово: false): коли true, запити схвалення можуть підсвічувати отримані парсером ділянки команд у тексті команди. Установіть true глобально або для окремого агента, щоб увімкнути підсвічування тексту команд без зміни політики схвалення exec.
tools.exec.pathPrepend: список каталогів, які потрібно додати на початок PATH для запусків exec (лише gateway + пісочниця).
tools.exec.safeBins: безпечні бінарні файли лише для stdin, які можуть виконуватися без явних записів allowlist. Подробиці поведінки див. у безпечних бінарних файлах.
tools.exec.safeBinTrustedDirs: додаткові явні каталоги, довірені для перевірок шляху safeBins. Записи PATH ніколи автоматично не вважаються довіреними. Вбудовані стандарти — /bin і /usr/bin.
tools.exec.safeBinProfiles: необов’язкова власна політика argv для кожного безпечного бінарного файла (minPositional, maxPositional, allowedValueFlags, deniedFlags).

Приклад:

{
  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
host=sandbox: запускає sh -lc (login shell) усередині контейнера, тому /etc/profile може скинути PATH. OpenClaw додає env.PATH на початок після завантаження профілю через внутрішню змінну середовища (без shell-інтерполяції); tools.exec.pathPrepend також застосовується тут.
host=node: до Node надсилаються лише незаблоковані перевизначення середовища, які ви передаєте. Перевизначення env.PATH відхиляються для виконання на хості та ігноруються хостами Node. Якщо вам потрібні додаткові записи PATH на Node, налаштуйте середовище служби хоста Node (systemd/launchd) або встановіть інструменти у стандартні розташування.

Прив’язка Node для окремого агента (використовуйте індекс списку агентів у конфігурації):

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

Інтерфейс керування: вкладка Nodes містить невелику панель “Exec node binding” для тих самих налаштувань.

Перевизначення сесії (`/exec`)

Використовуйте /exec, щоб установити стандартні значення для окремої сесії для host, security, ask і node. Надішліть /exec без аргументів, щоб показати поточні значення. Приклад:

/exec host=auto security=allowlist ask=on-miss node=mac-1

Модель авторизації

/exec враховується лише для авторизованих відправників (allowlist/спарювання каналів плюс commands.useAccessGroups). Вона оновлює лише стан сесії і не записує конфігурацію. Щоб жорстко вимкнути exec, забороніть його через політику інструментів (tools.deny: ["exec"] або для окремого агента). Схвалення хоста все одно застосовуються, якщо ви явно не встановите security=full і ask=off.

Схвалення Exec (супровідна програма / хост Node)

Агенти в пісочниці можуть вимагати схвалення для кожного запиту перед запуском exec на хості gateway або Node. Див. схвалення Exec для політики, allowlist і потоку UI. Коли потрібні схвалення, інструмент exec негайно повертає status: "approval-pending" та ідентифікатор схвалення. Після схвалення (або відхилення / таймауту) Gateway надсилає системні події (Exec finished / Exec denied). Якщо команда все ще виконується після tools.exec.approvalRunningNoticeMs, надсилається одне сповіщення Exec running. У каналах із нативними картками/кнопками схвалення агент має спершу покладатися на цей нативний UI й включати ручну команду /approve лише тоді, коли результат інструмента явно каже, що схвалення в чаті недоступні або ручне схвалення є єдиним шляхом.

Allowlist + безпечні бінарні файли

Ручне застосування allowlist зіставляє globs визначених шляхів бінарних файлів і globs простих імен команд. Прості імена зіставляються лише з командами, викликаними через PATH, тому rg може відповідати /opt/homebrew/bin/rg, коли команда — rg, але не ./rg або /tmp/rg. Коли security=allowlist, shell-команди автоматично дозволяються лише якщо кожен сегмент pipeline є в allowlist або є безпечним бінарним файлом. Ланцюжки (;, &&, ||) і перенаправлення відхиляються в режимі allowlist, якщо кожен сегмент верхнього рівня не задовольняє allowlist (включно з безпечними бінарними файлами). Перенаправлення залишаються непідтримуваними. Стійка довіра allow-always не обходить це правило: ланцюжкова команда все одно потребує, щоб кожен сегмент верхнього рівня збігався. autoAllowSkills — це окремий зручний шлях у схваленнях exec. Це не те саме, що ручні записи allowlist шляхів. Для строгого явного довіряння залиште autoAllowSkills вимкненим. Використовуйте ці два елементи керування для різних завдань:

tools.exec.safeBins: малі фільтри потоків лише зі stdin.
tools.exec.safeBinTrustedDirs: явні додаткові довірені каталоги для шляхів виконуваних файлів safe-bin.
tools.exec.safeBinProfiles: явна політика argv для користувацьких safe bins.
список дозволених: явна довіра до шляхів виконуваних файлів.

Не розглядайте safeBins як загальний список дозволених і не додавайте бінарні файли інтерпретаторів/середовищ виконання (наприклад, python3, node, ruby, bash). Якщо вони вам потрібні, використовуйте явні записи списку дозволених і залишайте запити на схвалення ввімкненими. openclaw security audit попереджає, коли записи інтерпретаторів/середовищ виконання в safeBins не мають явних профілів, а openclaw doctor --fix може згенерувати каркас відсутніх користувацьких записів safeBinProfiles. openclaw security audit і openclaw doctor також попереджають, коли ви явно додаєте bins із широкою поведінкою, як-от jq, назад у safeBins. Якщо ви явно додаєте інтерпретатори до списку дозволених, увімкніть tools.exec.strictInlineEval, щоб форми inline code-eval і надалі вимагали нового схвалення. Повні відомості про політику та приклади див. у схваленнях Exec і Safe bins проти списку дозволених.

Приклади

Передній план:

{ "tool": "exec", "command": "ls -la" }

Фоновий режим + опитування:

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

Опитування призначене для статусу на вимогу, а не для циклів очікування. Якщо автоматичне пробудження після завершення ввімкнене, команда може пробудити сеанс, коли виводить дані або завершується з помилкою. Надсилання клавіш (у стилі tmux):

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

Submit (надсилати лише CR):

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

Вставлення (bracketed за замовчуванням):

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

apply_patch

apply_patch — це підінструмент exec для структурованих багатофайлових редагувань. Він увімкнений за замовчуванням для моделей OpenAI і OpenAI Codex. Використовуйте конфігурацію лише тоді, коли хочете вимкнути його або обмежити певними моделями:

{
  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 — шлюзи схвалення для команд оболонки
Пісочниця — запуск команд у ізольованих середовищах
Фоновий процес — довготривалий exec та інструмент process
Безпека — політика інструментів і підвищений доступ

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Інструмент виконання команд

Параметри

Конфігурація

Обробка PATH

Перевизначення сесії (`/exec`)

Модель авторизації

Схвалення Exec (супровідна програма / хост Node)

Allowlist + безпечні бінарні файли

Приклади

apply_patch

Пов’язане

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Documentation Index

​Параметри

​Конфігурація

​Обробка PATH

​Перевизначення сесії (/exec)

​Модель авторизації

​Схвалення Exec (супровідна програма / хост Node)

​Allowlist + безпечні бінарні файли

​Приклади

​apply_patch

​Пов’язане

Параметри

Конфігурація

Обробка PATH

Перевизначення сесії (`/exec`)

Модель авторизації

Схвалення Exec (супровідна програма / хост Node)

Allowlist + безпечні бінарні файли

Приклади

apply_patch

Пов’язане