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

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

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

Параметри

Примітки:

• 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.
• 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 безпечні бінарні файли, які можуть запускатися без явних записів у списку дозволених. Докладніше про поведінку див. Безпечні бінарні файли.
• 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
    • Щоб запобігти перевизначенню пріоритетних шляхів конфігурацією оболонки користувача (як-от ~/.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 для кожного агента (використовуйте індекс списку агентів у конфігурації):

openclaw config get agents.listopenclaw 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 щодо політики, списку дозволених і потоку 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 і Безпечні бінарні файли порівняно зі списком дозволених.

Приклади

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

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