English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Tools

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

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

Параметри

commandstringrequired

Команда shell для виконання.

workdirstring

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

envobject

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

yieldMsnumber

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

backgroundboolean

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

timeoutnumber

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

ptyboolean

Запускати в псевдотерміналі, коли він доступний. Використовуйте для CLI, що потребують TTY, агентів кодування та термінальних UI.

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

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

security'deny' | 'allowlist' | 'full'

Режим примусового застосування для виконання gateway / node.

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

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

nodestring

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

elevatedboolean

Запитати підвищений режим — вийти з пісочниці на налаштований шлях хоста. 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 (супровідного застосунку або безголового хоста Node).
  • Якщо доступно кілька Node, задайте exec.node або tools.exec.node, щоб вибрати один.
  • exec host=node — єдиний шлях виконання shell для Node; застарілу обгортку nodes.run видалено.
  • timeout застосовується до виконання на передньому плані, у фоні, yieldMs, gateway, sandbox і node system.run. Якщо пропущено, 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/profile могли виявляти контекст інструмента exec.
  • openclaw channels login блокується з exec, бо це інтерактивний потік авторизації каналу; запускайте його в терміналі на хості gateway або використовуйте нативний для каналу інструмент входу з чату, якщо він існує.
  • Важливо: пісочниця вимкнена за замовчуванням. Якщо пісочницю вимкнено, неявний host=auto визначається як gateway. Явний host=sandbox усе одно завершується закрито з помилкою, а не тихо виконується на хості gateway. Увімкніть пісочницю або використовуйте host=gateway зі схваленнями.
  • Попередні перевірки скриптів (для типових помилок shell-синтаксису Python/Node) перевіряють лише файли всередині ефективної межі workdir. Якщо шлях скрипта визначається поза workdir, попередня перевірка для цього файла пропускається.
  • Для тривалої роботи, яка починається зараз, запустіть її один раз і покладайтеся на автоматичне пробудження після завершення, коли його ввімкнено й команда виводить дані або завершується з помилкою. Використовуйте process для журналів, статусу, введення або втручання; не імітуйте планування циклами sleep, циклами timeout або повторним опитуванням.
  • Для роботи, яка має відбутися пізніше або за розкладом, використовуйте cron замість шаблонів sleep/delay з 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 для sandbox, 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, форми inline 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. Докладну поведінку див. у Безпечні бінарні файли.
  • 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 відхиляються для виконання на хості. Сам 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 на початок після завантаження профілю через внутрішню змінну середовища (без shell-інтерполяції); tools.exec.pathPrepend також застосовується тут.
  • host=node: до Node надсилаються лише незаблоковані перевизначення env, які ви передаєте. Перевизначення 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"

Control UI: вкладка Nodes містить невелику панель "Прив’язка Exec node" для тих самих налаштувань.

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

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

Приклад:

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

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

/exec враховується лише для авторизованих відправників (allowlists/спарювання каналів плюс 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 зіставляє glob-шаблони визначених шляхів бінарних файлів і голих назв команд. Голі назви зіставляються лише з командами, викликаними через 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 для користувацьких безпечних бінарних файлів.
  • allowlist: явна довіра до шляхів виконуваних файлів.

Не розглядайте safeBins як загальний список дозволених і не додавайте бінарні файли інтерпретаторів/середовищ виконання (наприклад, python3, node, ruby, bash). Якщо вони вам потрібні, використовуйте явні записи списку дозволених і залишайте запити на затвердження ввімкненими. openclaw security audit попереджає, коли записи інтерпретаторів/середовищ виконання в safeBins не мають явних профілів, а openclaw doctor --fix може створити каркас відсутніх власних записів safeBinProfiles. openclaw security audit і openclaw doctor також попереджають, коли ви явно додаєте бінарні файли з широкою поведінкою, такі як jq, назад до safeBins. Якщо ви явно додаєте інтерпретатори до списку дозволених, увімкніть 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 для структурованого редагування кількох файлів. Він увімкнений за замовчуванням для моделей 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 записував/видаляв файли поза каталогом робочої області.

Пов’язане