Одобрения exec

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

Если пользовательский интерфейс приложения-компаньона недоступен, любой запрос, требующий подсказки, разрешается запасным вариантом ask (по умолчанию: deny).

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

Одобрения exec применяются локально на хосте выполнения:

хост gateway → процесс openclaw на машине gateway
узел-хост → исполнитель узла (приложение-компаньон macOS или безголовый узел-хост)

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

сервис узла-хоста пересылает system.run в приложение macOS через локальный IPC.
Приложение macOS применяет одобрения + выполняет команду в контексте пользовательского интерфейса.

Настройки и хранение

Одобрения находятся в локальном 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"
        }
      ]
    }
  }
}

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

Security (exec.security)

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

Ask (exec.ask)

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

Ask fallback (askFallback)

Если требуется подсказка, но пользовательский интерфейс недоступен, fallback решает:

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

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

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

Примеры:

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

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

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

Автоматическое разрешение CLI навыков

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

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

tools.exec.safeBins определяет небольшой список бинарных файлов только для stdin (например, jq), которые могут работать в режиме списка разрешений без явных записей в списке разрешений. Безопасные бинарные файлы отклоняют позиционные аргументы файлов и токены, похожие на пути, поэтому они могут работать только с входящим потоком. Цепочка команд оболочки и перенаправления не разрешены автоматически в режиме списка разрешений.

Цепочка команд оболочки (&&, ||, ;) разрешена, когда каждый сегмент верхнего уровня удовлетворяет списку разрешений (включая безопасные бинарные файлы или автоматическое разрешение навыков). Перенаправления остаются неподдерживаемыми в режиме списка разрешений.

Безопасные бинарные файлы по умолчанию: jq, grep, cut, sort, uniq, head, tail, tr, wc.

Редактирование пользовательского интерфейса управления

Используйте карточку Control UI → Nodes → Exec approvals для редактирования значений по умолчанию, переопределений для каждого агента и списков разрешений. Выберите область (Defaults или агента), настройте политику, добавьте/удалите паттерны списка разрешений, затем Сохранить. Пользовательский интерфейс показывает метаданные последнего использования для каждого паттерна, чтобы вы могли поддерживать список в порядке.

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

CLI: openclaw approvals поддерживает редактирование gateway или узла (см. Approvals CLI).

Поток одобрения

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

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

Диалог подтверждения включает:

команда + аргументы
cwd
id агента
разрешенный путь исполняемого файла
метаданные хоста + политики

Действия:

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

Пересылка одобрения на каналы чата

Вы можете пересылать подсказки одобрения 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

Поток macOS IPC

Gateway -> Сервис узла (WS)
                 |  IPC (UDS + токен + HMAC + TTL)
                 v
             Приложение Mac (UI + одобрения + system.run)

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

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

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

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

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

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

Последствия

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

Связанное: