​

Інструмент exec

​

Параметри

• command (обов’язковий)
• workdir (типово: cwd)
• env (перевизначення key/value)
• yieldMs (типово 10000): автоматично переводить у фон після затримки
• background (bool): негайно запускати у фоновому режимі
• timeout (секунди, типово 1800): примусово завершує після спливу часу
• pty (bool): запуск у псевдотерміналі, якщо доступно (CLI лише з TTY, coding agents, terminal UI)
• host (auto | sandbox | gateway | node): де виконувати
• security (deny | allowlist | full): режим застосування політик для gateway/node
• ask (off | on-miss | always): запити на схвалення для gateway/node
• node (string): id/ім’я вузла для host=node
• elevated (bool): запросити підвищений режим (вихід із sandbox на налаштований шлях хоста); security=full примусово вмикається лише тоді, коли elevated розв’язується як full

• host типово має значення auto: sandbox, якщо для сесії активне sandbox-середовище, інакше gateway.
• auto — це типова стратегія маршрутизації, а не wildcard. Для окремого виклику дозволено host=node з auto; host=gateway для окремого виклику дозволено лише тоді, коли sandbox-середовище не активне.
• Без додаткового налаштування host=auto все одно «просто працює»: без sandbox він розв’язується в gateway; за активного sandbox залишається в sandbox.
• elevated виходить із sandbox на налаштований шлях хоста: типово gateway, або node, якщо tools.exec.host=node (або типовим для сесії є host=node). Доступно лише тоді, коли для поточної сесії/провайдера ввімкнено elevated access.
• Схвалення для gateway/node керуються через ~/.openclaw/exec-approvals.json.
• Для node потрібен спарений вузол (companion app або headless node host).
• Якщо доступно кілька вузлів, укажіть exec.node або tools.exec.node, щоб вибрати один.
• exec host=node — єдиний шлях виконання shell-команд для вузлів; застарілу обгортку nodes.run видалено.
• На хостах, відмінних від 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 та виконання в sandbox), щоб правила shell/profile могли визначати контекст exec tool.
• Важливо: sandboxing типово вимкнено. Якщо sandboxing вимкнено, неявний host=auto розв’язується в gateway. Явний host=sandbox у такому разі все одно завершується без виконання, а не тихо запускається на gateway host. Увімкніть sandboxing або використовуйте host=gateway зі схваленнями.
• Перевірки preflight для скриптів (щодо поширених синтаксичних помилок Python/Node у shell) аналізують лише файли в межах ефективної межі workdir. Якщо шлях до скрипта розв’язується поза workdir, preflight для цього файла пропускається.
• Для довготривалої роботи, яку потрібно почати зараз, запускайте її один раз і покладайтеся на автоматичне пробудження після завершення, якщо його ввімкнено і команда виводить результат або завершується з помилкою. Використовуйте process для логів, статусу, введення або втручання; не імітуйте планування через цикли sleep, цикли timeout або повторне опитування.
• Для роботи, яка має виконатися пізніше або за розкладом, використовуйте cron, а не шаблони sleep/delay в exec.

​

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

• tools.exec.notifyOnExit (типово: true): якщо true, фонові сесії exec ставлять системну подію в чергу та запитують Heartbeat після завершення.
• tools.exec.approvalRunningNoticeMs (типово: 10000): надсилає одне сповіщення «running», якщо exec, що потребує схвалення, виконується довше за цей час (0 вимикає).
• tools.exec.host (типово: auto; розв’язується в sandbox, якщо sandbox-середовище активне, і в gateway інакше)
• tools.exec.security (типово: deny для sandbox, full для gateway і node, якщо не задано)
• tools.exec.ask (типово: off)
• Виконання на хості без схвалення — типовий режим для 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 виконання на хості безпосередньо дотримується налаштованої політики; додаткового евристичного попереднього фільтра для обфускації команд або шару відхилення script-preflight немає.
• 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.pathPrepend: список каталогів, які потрібно додати на початок PATH для запусків exec (лише gateway + sandbox).
• tools.exec.safeBins: безпечні бінарні файли лише для stdin, які можуть запускатися без явних записів у allowlist. Докладніше див. у Safe bins.
• tools.exec.safeBinTrustedDirs: додаткові явно довірені каталоги для перевірок шляхів виконуваних файлів із safeBins. Записи PATH ніколи не вважаються довіреними автоматично. Вбудовані типові значення: /bin і /usr/bin.
• tools.exec.safeBinProfiles: необов’язкова користувацька політика argv для кожного safe bin (minPositional, maxPositional, allowedValueFlags, deniedFlags).

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

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

​

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

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

​

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

​

Схвалення exec (companion app / node host)

​

Allowlist + safe bins

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

​

Приклади

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

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

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

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

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

​

apply_patch

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

• Доступно лише для моделей OpenAI/OpenAI Codex.
• Політика інструментів усе одно застосовується; allow: ["write"] неявно дозволяє apply_patch.
• Конфігурація розташована в tools.exec.applyPatch.
• tools.exec.applyPatch.enabled типово має значення true; установіть false, щоб вимкнути інструмент для моделей OpenAI.
• tools.exec.applyPatch.workspaceOnly типово має значення true (обмежено робочим простором). Установлюйте false лише тоді, коли ви свідомо хочете, щоб apply_patch записував/видаляв файли поза каталогом робочого простору.

​

Пов’язане

• Схвалення exec — шлюзи схвалення для shell-команд
• Sandboxing — запуск команд у sandbox-середовищах
• Фоновий процес — довготривалий exec та інструмент process
• Безпека — політика інструментів і elevated access