Схвалення виконання команд

Схвалення exec — це запобіжник супутнього застосунку / Node-хоста, який дає пісочному агенту змогу запускати команди на реальному хості (gateway або node). Це захисне блокування: команди дозволені лише тоді, коли політика + allowlist + (необов’язкове) схвалення користувача всі збігаються. Схвалення exec накладаються поверх політики інструментів і elevated-гейтингу (якщо elevated не встановлено в full, що пропускає схвалення).

# Перевірка ефективної політики

Коли локальна область просить host=node, exec-policy show повідомляє, що ця область під час виконання керується Node, замість удавати, що локальний файл схвалень є джерелом істини.

Якщо UI супутнього застосунку недоступний, будь-який запит, який зазвичай показав би підказку, розв’язується через резервний режим ask (стандартно: deny).

# Де це застосовується

Схвалення exec застосовуються локально на хості виконання:

• Gateway-хост → процес openclaw на машині Gateway.
• Node-хост → Node-runner (супутній застосунок macOS або headless Node-хост).

# Модель довіри

• Виклики, автентифіковані Gateway, є довіреними операторами для цього Gateway.
• Спарені Node розширюють цю можливість довіреного оператора на Node-хост.
• Схвалення exec зменшують ризик випадкового виконання, але не є межею автентифікації для кожного користувача.
• Схвалені запуски на Node-хості прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env за наявності та закріплений шлях до виконуваного файла, коли це застосовно.
• Для shell-скриптів і прямих викликів файлів інтерпретатора/runtime OpenClaw також намагається прив’язати один конкретний локальний файловий операнд. Якщо цей прив’язаний файл змінюється після схвалення, але до виконання, запуск забороняється замість виконання зміненого вмісту.
• Прив’язка файлів навмисно є best-effort, не повною семантичною моделлю кожного шляху завантажувача інтерпретатора/runtime. Якщо режим схвалення не може визначити рівно один конкретний локальний файл для прив’язки, він відмовляється видавати запуск на основі схвалення замість удавати повне покриття.

# Розділення macOS

• Сервіс Node-хоста пересилає system.run до застосунку macOS через локальний IPC.
• Застосунок macOS застосовує схвалення та виконує команду в контексті UI.

# Налаштування та зберігання

Схвалення зберігаються в локальному JSON-файлі на хості виконання:

~/.openclaw/exec-approvals.json

Приклад схеми:

{
  "version": 1,
  "socket": {
    "path": "~/.openclaw/exec-approvals.sock",
    "token": "base64url-token"
  },
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "askFallback": "deny",
      "autoAllowSkills": true,
      "allowlist": [
        {
          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
          "pattern": "~/Projects/**/bin/rg",
          "source": "allow-always",
          "commandText": "rg -n TODO",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}

# Ручки політики

# exec.security

# exec.ask

# askFallback

# tools.exec.strictInlineEval

Приклади, які виявляє strict-режим:

• python -c
• node -e, node --eval, node -p
• ruby -e
• perl -e, perl -E
• php -r
• lua -e
• osascript -e

У strict-режимі ці команди все одно потребують явного схвалення, а allow-always не зберігає нові записи allowlist для них автоматично.

# Режим YOLO (без схвалення)

Якщо ви хочете, щоб host exec виконувався без запитів на схвалення, потрібно відкрити обидва шари політики — запитану політику exec у конфігурації OpenClaw (tools.exec.*) і хост-локальну політику схвалень у ~/.openclaw/exec-approvals.json.

YOLO є стандартною поведінкою хоста, якщо ви явно її не посилите:

Провайдери на основі CLI, які надають власний неінтерактивний режим дозволів, можуть дотримуватися цієї політики. Claude CLI додає --permission-mode bypassPermissions, коли запитана OpenClaw політика exec є YOLO. Перевизначте цю поведінку backend явними аргументами Claude у agents.defaults.cliBackends.claude-cli.args / resumeArgs — наприклад --permission-mode default, acceptEdits або bypassPermissions.

Якщо потрібне консервативніше налаштування, посильте будь-який шар назад до allowlist / on-miss або deny.

# Постійне налаштування Gateway-хоста «ніколи не питати»

openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw gateway restart

openclaw approvals set --stdin <<'EOF'
{
  version: 1,
  defaults: {
    security: "full",
    ask: "off",
    askFallback: "full"
  }
}
EOF

# Локальне скорочення

openclaw exec-policy preset yolo

Це локальне скорочення оновлює обидва:

• Локальні tools.exec.host/security/ask.
• Локальні стандартні значення ~/.openclaw/exec-approvals.json.

Воно навмисно лише локальне. Щоб змінити схвалення Gateway-хоста або Node-хоста віддалено, використовуйте openclaw approvals set --gateway або openclaw approvals set --node <id|name|ip>.

# Node-хост

Для Node-хоста застосуйте той самий файл схвалень на цьому Node:

openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
{
  version: 1,
  defaults: {
    security: "full",
    ask: "off",
    askFallback: "full"
  }
}
EOF

# Скорочення лише для сесії

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

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

# Allowlist (для кожного агента)

Allowlists є окремими для кожного агента. Якщо існує кілька агентів, перемкніть агента, якого редагуєте, у застосунку macOS. Patterns — це glob-збіги.

Patterns можуть бути glob для resolved binary path або bare command-name globs. Bare names збігаються лише з командами, викликаними через PATH, тому rg може збігатися з /opt/homebrew/bin/rg, коли команда — rg, але не з ./rg або /tmp/rg. Використовуйте path glob, коли хочете довіряти одному конкретному розташуванню binary.

Застарілі записи agents.default мігруються до agents.main під час завантаження. Shell chains на кшталт echo ok && pwd все одно потребують, щоб кожен top-level segment задовольняв правила allowlist.

Приклади:

• rg
• ~/Projects/**/bin/peekaboo
• ~/.local/bin/*
• /opt/homebrew/bin/rg

# Обмеження аргументів через argPattern

Додайте argPattern, коли запис allowlist має збігатися з binary і конкретною формою аргументів. OpenClaw оцінює регулярний вираз проти розібраних аргументів команди, не враховуючи токен виконуваного файла (argv[0]). Для записів, написаних вручну, аргументи об’єднуються одним пробілом, тому заякорюйте pattern, коли потрібен точний збіг.

{
  "version": 1,
  "agents": {
    "main": {
      "allowlist": [
        {
          "pattern": "python3",
          "argPattern": "^safe\\.py$"
        }
      ]
    }
  }
}

Цей запис дозволяє python3 safe.py; python3 other.py є allowlist miss. Якщо для того самого binary також присутній запис лише за шляхом, аргументи без збігу все ще можуть fallback до цього запису лише за шляхом. Пропустіть запис лише за шляхом, коли мета — обмежити binary заявленими аргументами.

Записи, збережені потоками схвалення, можуть використовувати внутрішній формат separator для точного зіставлення argv. Надавайте перевагу UI або потоку схвалення, щоб повторно згенерувати ці записи замість ручного редагування закодованого значення. Якщо OpenClaw не може розібрати argv для сегмента команди, записи з argPattern не збігаються.

Кожен запис allowlist підтримує:

# Автоматичний дозвіл для CLI Skills

Коли ввімкнено Автоматичний дозвіл для CLI Skills, виконувані файли, на які посилаються відомі Skills, вважаються доданими до allowlist на Node (macOS Node або headless хост Node). Для цього використовується skills.bins через Gateway RPC, щоб отримати список бінарних файлів Skills. Вимкніть це, якщо вам потрібні суворі ручні allowlist.

# Безпечні бінарні файли та пересилання схвалень

Про безпечні бінарні файли (швидкий шлях лише через stdin), деталі прив'язування інтерпретатора та те, як пересилати запити на схвалення до Slack/Discord/Telegram (або запускати їх як нативні клієнти схвалення), див. Exec approvals - advanced.

# Редагування Control UI

Використовуйте картку Control UI → Nodes → Exec approvals, щоб редагувати стандартні значення, перевизначення для окремих агентів і allowlist. Виберіть область дії (стандартні значення або агент), налаштуйте політику, додайте або видаліть шаблони allowlist, потім натисніть Save. UI показує метадані останнього використання для кожного шаблону, щоб ви могли підтримувати список у порядку.

Селектор цілі вибирає Gateway (локальні схвалення) або Node. Nodes мають оголошувати system.execApprovals.get/set (застосунок macOS або headless хост Node). Якщо Node ще не оголошує exec approvals, редагуйте його локальний ~/.openclaw/exec-approvals.json напряму.

CLI: openclaw approvals підтримує редагування Gateway або Node - див. Approvals CLI.

# Потік схвалення

Коли потрібен запит, gateway транслює exec.approval.requested клієнтам оператора. Control UI та застосунок macOS вирішують його через exec.approval.resolve, після чого gateway пересилає схвалений запит до хоста Node.

Для host=node запити на схвалення містять канонічне корисне навантаження systemRunPlan. Gateway використовує цей план як авторитетний контекст command/cwd/session під час пересилання схвалених запитів system.run.

Це важливо для затримки асинхронного схвалення:

• Шлях виконання Node заздалегідь готує один канонічний план.
• Запис схвалення зберігає цей план і його метадані прив'язування.
• Після схвалення фінальний пересланий виклик system.run повторно використовує збережений план замість того, щоб довіряти пізнішим змінам викликача.
• Якщо викликач змінює command, rawCommand, cwd, agentId або sessionKey після створення запиту на схвалення, Gateway відхиляє пересланий запуск як невідповідність схвалення.

# Системні події

Життєвий цикл Exec відображається як системні повідомлення:

• Exec running (лише якщо команда перевищує поріг сповіщення про виконання).
• Exec finished.
• Exec denied.

Вони публікуються в сесії агента після того, як Node повідомить про подію. Схвалення exec на хості Gateway випускають ті самі події життєвого циклу, коли команда завершується (і, за бажанням, коли виконується довше за поріг). Exec із вимогою схвалення повторно використовують id схвалення як runId у цих повідомленнях для легкої кореляції.

# Поведінка відхиленого схвалення

Коли асинхронне схвалення exec відхилено, OpenClaw не дає агенту повторно використати вивід з будь-якого попереднього запуску тієї самої команди в сесії. Причина відхилення передається з явною вказівкою, що вивід команди недоступний, що не дає агенту стверджувати, ніби є новий вивід, або повторювати відхилену команду зі застарілими результатами попереднього успішного запуску.

# Наслідки

• full потужний; за можливості віддавайте перевагу allowlist.
• ask залишає вас у циклі ухвалення рішень, водночас дозволяючи швидкі схвалення.
• Allowlist для окремих агентів запобігають потраплянню схвалень одного агента до інших.
• Схвалення застосовуються лише до запитів host exec від авторизованих відправників. Неавторизовані відправники не можуть виконувати /exec.
• /exec security=full — це зручність рівня сесії для авторизованих операторів, яка свідомо пропускає схвалення. Щоб жорстко заблокувати host exec, установіть безпеку схвалень у deny або забороніть інструмент exec через політику інструментів.

# Пов'язане