Встроенные инструменты

Exec Approvals

Exec approvals — это приложение-компаньон / ограничитель хоста узла, позволяющий агенту в песочнице выполнять команды на реальном хосте (gateway или node). Представьте это как предохранительную блокировку: команды разрешены только когда политика + список разрешений + (опциональное) подтверждение пользователя согласованы. Exec approvals работают в дополнение к политике инструментов и повышенному контролю (если только повышенный режим не установлен в full, что пропускает утверждения). Эффективная политика — это более строгая из tools.exec.* и значений по умолчанию утверждений; если поле утверждений опущено, используется значение tools.exec. Если пользовательский интерфейс приложения-компаньона недоступен, любой запрос, требующий подтверждения, разрешается с помощью резервного действия (по умолчанию: запрет).

Где применяется

Exec approvals применяются локально на хосте выполнения:

хост gateway → процесс openclaw на машине шлюза
хост узла → запускающий процесс узла (приложение-компаньон macOS или headless-хост узла)

Разделение на macOS:

служба хоста узла перенаправляет 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",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}

Параметры политики

Безопасность (exec.security)

deny: блокировать все запросы на выполнение на хосте.
allowlist: разрешать только команды из списка разрешений.
full: разрешать всё (эквивалентно elevated).

Запрос (exec.ask)

off: никогда не запрашивать подтверждение.
on-miss: запрашивать только при отсутствии совпадения в списке разрешений.
always: запрашивать для каждой команды.

Резервное действие (askFallback)

Если требуется подтверждение, но UI недоступен, резервное действие решает:

deny: заблокировать.
allowlist: разрешить только при совпадении со списком разрешений.
full: разрешить.

Список разрешений (на агента)

Списки разрешений создаются для каждого агента. Если существует несколько агентов, переключите, какого агента вы редактируете, в приложении macOS. Шаблоны — это регистронезависимые glob-совпадения. Шаблоны должны разрешаться в пути к бинарным файлам (записи только с именем файла игнорируются). Устаревшие записи agents.default мигрируют в agents.main при загрузке. Примеры:

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

Каждая запись в списке разрешений отслеживает:

id стабильный UUID, используемый для идентификации в UI (опционально)
время последнего использования (timestamp)
последняя использованная команда
последний разрешённый путь

Авторазрешение для CLI навыков

Когда опция Авторазрешение для CLI навыков включена, исполняемые файлы, на которые ссылаются известные навыки, рассматриваются как разрешённые на узлах (узел macOS или headless-хост узла). Для этого используется skills.bins через RPC шлюза для получения списка бинарных файлов навыков. Отключите эту опцию, если хотите использовать строгие ручные списки разрешений.

Безопасные бинарники (только stdin)

tools.exec.safeBins определяет небольшой список бинарников только для stdin (например, jq), которые могут выполняться в режиме allowlist без явных записей в списке разрешений. Безопасные бинарники отклоняют позиционные файловые аргументы и токены, похожие на пути, поэтому они могут работать только со входящим потоком. Проверка является детерминированной только на основе формы argv (без проверок существования файлов в файловой системе хоста), что предотвращает поведение оракула существования файлов из-за различий в разрешении/запрете. Файловые опции запрещены для безопасных бинарников по умолчанию (например, sort -o, sort --output, sort --files0-from, sort --compress-program, wc --files0-from, jq -f/--from-file, grep -f/--file). Безопасные бинарники также применяют явную политику флагов для каждого бинарника для опций, нарушающих поведение "только stdin" (например, sort -o/--output/--compress-program и рекурсивные флаги grep). Безопасные бинарники также заставляют токены argv обрабатываться как буквальный текст во время выполнения (без подстановки шаблонов и без раскрытия $VARS) для сегментов "только stdin", поэтому шаблоны вроде * или $HOME/... нельзя использовать для скрытого чтения файлов. Безопасные бинарники также должны разрешаться из доверенных каталогов бинарников (системные по умолчанию плюс PATH процесса шлюза при запуске). Это блокирует попытки подмены PATH в рамках запроса. Цепочки команд оболочки и перенаправления не разрешаются автоматически в режиме allowlist. Цепочки команд оболочки (&&, ||, ;) разрешены, когда каждый сегмент верхнего уровня удовлетворяет списку разрешений (включая безопасные бинарники или авторазрешение навыков). Перенаправления остаются неподдерживаемыми в режиме allowlist. Подстановка команд ($() / обратные кавычки) отклоняется при разборе списка разрешений, включая внутри двойных кавычек; используйте одинарные кавычки, если вам нужен буквальный текст $(). В утверждениях приложения-компаньона macOS необработанный текст оболочки, содержащий синтаксис управления или раскрытия оболочки (&&, ||, ;, |, ```, $, <, >, (, )), рассматривается как отсутствие в списке разрешений, если сам бинарник оболочки не добавлен в список. Безопасные бинарники по умолчанию: jq, cut, uniq, head, tail, tr, wc. grep и sort не входят в список по умолчанию. Если вы их добавите, сохраняйте явные записи в списке разрешений для их рабочих процессов, не связанных только с stdin. Для grep в режиме безопасного бинарника указывайте шаблон с помощью -e/--regexp; позиционная форма шаблона отклоняется, чтобы файловые операнды нельзя было подменить в виде неоднозначных позиционных аргументов.

Редактирование в Control UI

Используйте карточку Control UI → Nodes → Exec approvals для редактирования значений по умолчанию, переопределений для каждого агента и списков разрешений. Выберите область (Defaults или агент), измените политику, добавьте/удалите шаблоны списка разрешений, затем нажмите Save. UI показывает метаданные последнего использования для каждого шаблона, чтобы вы могли поддерживать список в порядке. Селектор цели выбирает Gateway (локальные утверждения) или Node. Узлы должны объявлять поддержку system.execApprovals.get/set (приложение macOS или headless-хост узла). Если узел ещё не объявляет поддержку exec approvals, отредактируйте его локальный файл ~/.openclaw/exec-approvals.json напрямую. CLI: openclaw approvals поддерживает редактирование для шлюза или узла (см. Approvals CLI).

Процесс утверждения

Когда требуется подтверждение, шлюз рассылает событие exec.approval.requested клиентам оператора. Control UI и приложение macOS разрешают его через exec.approval.resolve, затем шлюз перенаправляет утверждённый запрос на хост узла. Когда требуются утверждения, инструмент exec немедленно возвращает идентификатор утверждения. Используйте этот id для корреляции с последующими системными событиями (Exec finished / Exec denied). Если решение не поступает до истечения таймаута, запрос рассматривается как таймаут утверждения и указывается как причина отказа. Диалог подтверждения включает:

команда + аргументы
текущий рабочий каталог (cwd)
идентификатор агента
разрешённый путь к исполняемому файлу
хост + метаданные политики

Действия:

Разрешить один раз → выполнить сейчас
Разрешать всегда → добавить в список разрешений + выполнить
Запретить → заблокировать

Перенаправление запросов утверждения в чат-каналы

Вы можете перенаправлять запросы утверждения exec в любой чат-канал (включая плагинные каналы) и утверждать их с помощью /approve. Для этого используется обычный конвейер исходящей доставки. Конфигурация:

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session", // "session" | "targets" | "both"
      agentFilter: ["main"],
      sessionFilter: ["discord"], // подстрока или regex
      targets: [
        { channel: "slack", to: "U12345678" },
        { channel: "telegram", to: "123456789" },
      ],
    },
  },
}

Ответ в чате:

/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny

Процесс IPC на macOS

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + approvals + system.run)

Примечания по безопасности:

Режим Unix-сокета 0600, токен хранится в exec-approvals.json.
Проверка соответствия UID.
Challenge/response (nonce + HMAC токен + хэш запроса) + короткий TTL.

Системные события

Жизненный цикл выполнения отображается как системные сообщения:

Exec running (только если команда превышает порог уведомления о запуске)
Exec finished
Exec denied

Они публикуются в сессии агента после того, как узел сообщит о событии. Утверждения exec на хосте шлюза генерируют те же события жизненного цикла, когда команда завершается (и опционально при работе дольше порога). Выполнения, требующие утверждения, повторно используют идентификатор утверждения как runId в этих сообщениях для лёгкой корреляции.

Последствия

full — мощный режим; по возможности предпочитайте списки разрешений.
ask держит вас в курсе, позволяя при этом быстрое утверждение.
Списки разрешений на агента предотвращают утечку утверждений одного агента к другим.
Утверждения применяются только к запросам на выполнение на хосте от авторизованных отправителей. Неавторизованные отправители не могут выполнить /exec.
/exec security=full — это удобство на уровне сессии для авторизованных операторов и по замыслу пропускает утверждения. Чтобы жёстко заблокировать выполнение на хосте, установите безопасность утверждений в deny или запретите инструмент exec через политику инструментов.

Связанные темы:

Exec Tool Firecrawl