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

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

Підтримує виконання на передньому й задньому плані через process. Якщо process заборонено, exec виконується синхронно та ігнорує yieldMs/background. Фонові сеанси обмежені областю окремого агента; process бачить лише сеанси того самого агента.

Параметри

Примітки:

• host приймає лише auto, sandbox, gateway або node. Це не засіб вибору за назвою хоста; значення, схожі на назви хостів, відхиляються до запуску команди.
• Значення host=node для окремого виклику дозволено з auto; значення host=gateway для окремого виклику дозволено лише тоді, коли середовище виконання пісочниці неактивне.
• Без додаткової конфігурації host=auto усе одно «просто працює»: за відсутності пісочниці воно визначається як gateway; за наявності активної пісочниці виконання залишається в ній.
• elevated виходить із пісочниці до налаштованого шляху хоста: типово gateway або node, коли tools.exec.host=node (або типовим значенням сеансу є host=node). Це доступно лише тоді, коли для поточного сеансу/постачальника ввімкнено привілейований доступ.
• Схвалення gateway/node контролюються файлом схвалень хоста.
• node потребує спареного Node (супровідної програми або безінтерфейсного хоста Node). Якщо доступно кілька Node, задайте exec.node або tools.exec.node, щоб вибрати один.
• exec host=node — єдиний шлях виконання команд оболонки для Node; застарілу обгортку nodes.run видалено.
• На хостах, відмінних від Windows, exec використовує SHELL, якщо його задано; якщо SHELL має значення fish, надається перевага bash (або sh) з PATH, щоб уникнути несумісних із fish конструкцій bash, а якщо жодного з них немає, використовується SHELL.
• На хостах Windows exec спочатку намагається знайти PowerShell 7 (pwsh) (у Program Files, ProgramW6432, а потім у PATH), після чого використовує Windows PowerShell 5.1.
• На gateway-хостах, відмінних від Windows, команди exec для bash і zsh використовують знімок запуску. OpenClaw отримує придатні для підключення псевдоніми/функції та невеликий безпечний набір змінних середовища з файлів запуску оболонки, зберігає їх у $OPENCLAW_STATE_DIR/cache/shell-snapshots/, а потім підключає цей знімок перед кожною командою 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, якщо канал надав ці ідентифікатори.
• exec не може запускати команди оболонки openclaw channels login або /approve: openclaw channels login — це інтерактивний потік автентифікації каналу, а /approve має проходити через обробник команд схвалення, а не через оболонку. Запускайте вхід до каналу в терміналі на хості Gateway або використовуйте агентський інструмент входу, призначений для конкретного каналу, якщо такий існує (наприклад, whatsapp_login).
• Важливо: пісочницю типово вимкнено. Якщо пісочницю вимкнено, неявне значення host=auto визначається як gateway. Явне значення host=sandbox усе одно безпечно завершується помилкою замість непомітного запуску на хості Gateway. Увімкніть пісочницю або використовуйте host=gateway зі схваленнями.
• Попередні перевірки скриптів (на поширені помилки синтаксису оболонки в Python/Node) перевіряють лише файли в межах ефективної області workdir. Якщо шлях до скрипту визначається за межами workdir, попередня перевірка цього файлу пропускається. Попередня перевірка також повністю пропускається, коли host=gateway, а ефективною політикою є security=full із ask=off.
• Для тривалої роботи, що починається зараз, запустіть її один раз і покладайтеся на автоматичне пробудження після завершення, якщо його ввімкнено й команда виводить дані або завершується помилкою. Використовуйте process для журналів, стану, введення або втручання; не імітуйте планування циклами сну, циклами очікування чи повторним опитуванням.
• Для роботи, яку потрібно виконати пізніше або за розкладом, використовуйте Cron замість шаблонів сну/затримки exec.

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

Виконання на хості без схвалення є типовим для Gateway і Node (security=full, ask=off) — це визначається стандартними параметрами політики хоста, а не host=auto. Щоб використовувати схвалення або список дозволів, посильте обмеження як у tools.exec.*, так і у файлі схвалень хоста; див. Схвалення виконання. Щоб примусово спрямовувати виконання через Gateway або Node незалежно від стану пісочниці, задайте tools.exec.host або використовуйте /exec host=....

Приклад:

{  tools: {    exec: {      pathPrepend: ["~/bin", "/opt/oss/bin"],    },  },}

Режими

tools.exec.mode — нормалізований параметр політики. Його встановлення визначає security/ask, і його не можна поєднувати з явно заданими tools.exec.security/tools.exec.ask.

ask/ask=always все одно щоразу запитує схвалення людини незалежно від режиму.

Схвалення автоматичним рецензентом одноразове. У Gateway OpenClaw надає рецензенту визначений шлях до виконуваного файла й прив’язує виконання до цього самого шляху. Команди, які неможливо звести до одного придатного до примусового застосування плану виконання, як-от heredoc, розгортання оболонки або непідтримуване оформлення лапок в обгортках, передаються на схвалення людині, навіть якщо модель в іншому разі дозволила б їх.

Схвалення команд сервера застосунку Codex, щодо яких ще немає рішення явної політики середовища виконання або вбудованої політики, передаються людині. OpenClaw не запускає налаштованого рецензента виконання для цих запитів, оскільки Codex не надає придатний до примусового застосування визначений виконуваний файл, який дає змогу прив’язати рішення рецензента до команди, яку запускає Codex.

Вбудоване обчислення (strictInlineEval)

Коли tools.exec.strictInlineEval має значення true, вбудовані форми обчислення інтерпретатором потребують схвалення рецензента або явного схвалення: python -c, node -e, ruby -e, perl -e, php -r, lua -e, osascript -e та подібні форми в інших підтримуваних інтерпретаторах і засобах передавання команд (awk, find -exec, make, sed, xargs тощо). У mode=auto звичайний шлях схвалення виконання може дозволити вбудованому автоматичному рецензенту схвалити явно низькоризикову одноразову команду; безпосередні виклики system.run на хості Node все одно потребують явного схвалення, оскільки вони не можуть передати команду на схвалення людині. Якщо рецензент запитує схвалення, запит передається людині. allow-always усе ще може зберігати безпечні виклики інтерпретатора або сценарію, але вбудовані форми обчислення не перетворюються на постійні правила дозволу.

Обробка PATH

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

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

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

Інтерфейс керування: сторінка Пристрої містить невелику панель «Прив’язування Node для виконання» з тими самими параметрами.

Перевизначення сеансу (/exec)

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

Приклад:

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

/exec враховується лише для авторизованих відправників (списки дозволів каналів/спарювання разом із commands.useAccessGroups). Він оновлює лише стан сеансу й не записує конфігурацію. Авторизовані відправники із зовнішніх каналів можуть установлювати ці стандартні значення сеансу. Внутрішнім клієнтам Gateway/вебчату для їх збереження потрібен operator.admin.

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

Схвалення виконання (супровідний застосунок / хост Node)

Агенти в пісочниці можуть вимагати схвалення кожного запиту перед запуском exec у Gateway або на хості Node. Політику, список дозволів і порядок дій в інтерфейсі описано в розділі Схвалення виконання.

Коли потрібне схвалення людини, потоки хоста Node і невбудовані потоки Gateway негайно повертають status: "approval-pending" та ідентифікатор схвалення. Вбудований чат і потоки Gateway у вебінтерфейсі натомість можуть очікувати в поточному запиті та повернути остаточний результат команди після схвалення. Результат approval-pending означає, що команда не запускалася, тому попередження про резервний перехід до виконання на передньому плані з’являються лише тоді, коли схвалена команда справді виконується в поточному запиті. Схвалені асинхронні запуски створюють системні події перебігу та завершення команди (Exec running / Exec finished); відхилені запити та запити, час очікування схвалення яких минув, є остаточними й не активують сеанс агента системною подією про відмову.

У каналах із нативними картками/кнопками схвалення агент має насамперед покладатися на цей нативний інтерфейс і додавати ручну команду /approve лише тоді, коли результат інструмента прямо вказує, що схвалення в чаті недоступні або ручне схвалення є єдиним шляхом.

Список дозволеного + безпечні виконувані файли

Ручне застосування списку дозволеного зіставляє глоб-шаблони розпізнаних шляхів до бінарних файлів і глоб-шаблони простих назв команд. Прості назви відповідають лише командам, викликаним через PATH, тому rg може відповідати /opt/homebrew/bin/rg, коли команда — rg, але не ./rg чи /tmp/rg.

Коли security=allowlist, команди оболонки автоматично дозволяються, лише якщо кожен сегмент конвеєра є в списку дозволеного або є безпечним виконуваним файлом. Ланцюжки (;, &&, ||) і переспрямування відхиляються в режимі списку дозволеного, якщо кожен сегмент верхнього рівня не відповідає списку дозволеного (включно з безпечними виконуваними файлами). Переспрямування й надалі не підтримуються. Постійна довіра 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 (jq може читати дані середовища та завантажувати код jq із модулів або файлів запуску, тому натомість віддавайте перевагу явним записам у списку дозволеного або запускам, що потребують схвалення). jq заборонено як безпечний виконуваний файл, навіть якщо його явно внесено до списку. Якщо ви явно додаєте інтерпретатори до списку дозволеного, увімкніть tools.exec.strictInlineEval, щоб форми вбудованого обчислення коду й надалі вимагали перевірки рецензентом або явного схвалення.

Повний опис політики та приклади див. у розділах Схвалення exec і Безпечні виконувані файли порівняно зі списком дозволеного.

Приклади

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

{ "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"]}

Надсилання (лише CR):

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

Вставлення (типово в дужковому режимі):

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

apply_patch

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

{  tools: {    exec: {      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.6-sol"] },    },  },}

Примітки:

• Політика інструментів усе одно застосовується; allow: ["write"] неявно дозволяє apply_patch.
• deny: ["write"] не забороняє apply_patch; явно забороніть apply_patch або використовуйте deny: ["group:fs"], якщо записування виправлень також потрібно заблокувати.
• Конфігурація міститься в tools.exec.applyPatch.
• Типове значення tools.exec.applyPatch.enabled — true; установіть false, щоб вимкнути інструмент.
• Типове значення tools.exec.applyPatch.workspaceOnly — true (у межах робочого простору). Установіть false лише тоді, коли навмисно хочете дозволити apply_patch записувати/видаляти поза каталогом робочого простору.
• tools.exec.applyPatch.allowModels — це необов’язковий список дозволених ідентифікаторів моделей (коротких, як-от gpt-5.4, або повних, як-от openai/gpt-5.4). Якщо його задано, інструмент отримують лише відповідні моделі; якщо не задано — усі моделі.

Пов’язані матеріали

• Схвалення exec — шлюзи схвалення для команд оболонки
• Ізоляція в пісочниці — виконання команд в ізольованих середовищах
• Фоновий процес — довготривале виконання exec та інструмент process
• Безпека — політика інструментів і розширений доступ