Расширенные настройки подтверждений выполнения команд

Расширенные темы подтверждения выполнения: быстрый путь safeBins, привязка интерпретатора/среды выполнения и пересылка запросов подтверждения в каналы чата (включая нативную доставку). Основную политику и процесс подтверждения см. в разделе Подтверждения выполнения.

Безопасные команды (только stdin)

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

Безопасные команды по умолчанию:

cut, uniq, head, tail, tr, wc

grep и sort не входят в список по умолчанию. Если вы включите их, сохраняйте явные записи в списке разрешений для сценариев, не использующих stdin. Для grep в режиме безопасной команды передавайте шаблон через -e/--regexp; позиционная форма шаблона отклоняется, чтобы файловые операнды нельзя было скрыть среди неоднозначных позиционных аргументов.

Проверка argv и запрещённые флаги

Проверка выполняется детерминированно только по структуре argv (без проверки существования объектов в файловой системе хоста), что предотвращает использование различий между разрешением и запретом как оракула существования файлов. Ориентированные на файлы параметры запрещены для безопасных команд по умолчанию; длинные параметры проверяются с отказом по умолчанию (неизвестные флаги и неоднозначные сокращения отклоняются). Распознанные логические флаги только для чтения команд по умолчанию (например, wc -l, tr -d, uniq -c) принимаются, а нераспознанные короткие флаги по-прежнему отклоняются по умолчанию и требуют ручного подтверждения.

Запрещённые флаги по профилям безопасных команд:

• grep: --dereference-recursive, --directories, --exclude-from, --file, --recursive, -R, -d, -f, -r
• jq: --argfile, --from-file, --library-path, --rawfile, --slurpfile, -L, -f
• sort: --compress-program, --files0-from, --output, --random-source, --temporary-directory, -T, -o
• tail: --follow, --retry, -F, -f
• wc: --files0-from

Безопасные команды также требуют, чтобы при выполнении токены argv обрабатывались как буквальный текст (без раскрытия шаблонов и без раскрытия $VARS) для сегментов, работающих только со stdin, поэтому шаблоны вроде * или $HOME/... нельзя использовать для скрытого чтения файлов. awk, sed и jq всегда запрещены в качестве безопасных команд, поскольку невозможно гарантировать, что их семантика ограничивается stdin: jq может читать данные окружения и загружать код jq из модулей или файлов запуска. Для этих инструментов вместо safeBins используйте явную запись в списке разрешений или запрос подтверждения.

Доверенные каталоги исполняемых файлов

Безопасные команды должны разрешаться из доверенных каталогов исполняемых файлов (системных каталогов по умолчанию и необязательных каталогов tools.exec.safeBinTrustedDirs). Записи PATH никогда не считаются доверенными автоматически. Список доверенных каталогов по умолчанию намеренно минимален: /bin, /usr/bin. Если исполняемый файл безопасной команды находится в каталогах менеджера пакетов или пользователя (например, /opt/homebrew/bin, /usr/local/bin, /opt/local/bin, /snap/bin), явно добавьте их в tools.exec.safeBinTrustedDirs.

Цепочки оболочки, обёртки и мультиплексоры

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

При подтверждении через приложение-компаньон macOS необработанный текст оболочки, содержащий синтаксис управления или подстановки оболочки (&&, ||, ;, |, `, $, <, >, (, )), считается не соответствующим списку разрешений, если сам исполняемый файл оболочки не добавлен в него.

Для обёрток оболочки (bash|sh|zsh ... -c/-lc) переопределения переменных окружения в рамках запроса ограничиваются небольшим явным списком разрешений (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).

При решениях allow-always в режиме списка разрешений прозрачные диспетчеризующие обёртки (например, env, flock, nice, nohup, stdbuf, timeout) сохраняют путь к внутреннему исполняемому файлу, а не путь к обёртке. Мультиплексоры оболочки (busybox, toybox) для апплетов оболочки (sh, ash и т. д.) разворачиваются таким же образом. Если обёртку или мультиплексор нельзя безопасно развернуть, запись в списке разрешений не сохраняется автоматически.

Если вы добавляете в список разрешений интерпретаторы вроде python3 или node, предпочтительно используйте tools.exec.strictInlineEval=true, чтобы встроенное вычисление кода по-прежнему требовало явного подтверждения. В строгом режиме allow-always всё ещё может сохранять безопасные вызовы интерпретаторов и сценариев, но носители встроенного вычисления не сохраняются автоматически.

Безопасные команды и список разрешений

Расположение конфигурации:

• safeBins берётся из конфигурации (tools.exec.safeBins или индивидуального agents.list[].tools.exec.safeBins агента).
• safeBinTrustedDirs берётся из конфигурации (tools.exec.safeBinTrustedDirs или индивидуального agents.list[].tools.exec.safeBinTrustedDirs агента).
• safeBinProfiles берётся из конфигурации (tools.exec.safeBinProfiles или индивидуального agents.list[].tools.exec.safeBinProfiles агента). Ключи профиля агента переопределяют глобальные ключи.
• записи списка разрешений хранятся в локальном для хоста файле подтверждений в agents.<id>.allowlist (или управляются через Control UI / openclaw approvals allowlist ...).
• openclaw security audit выводит предупреждение tools.exec.safe_bins_interpreter_unprofiled, если исполняемые файлы интерпретаторов/сред выполнения указаны в safeBins без явных профилей.
• openclaw doctor --fix может создать заготовки отсутствующих пользовательских записей safeBinProfiles.<bin> как {} (после этого проверьте и ужесточите их). Заготовки для исполняемых файлов интерпретаторов/сред выполнения автоматически не создаются.

Пример пользовательского профиля:

{  tools: {    exec: {      safeBins: ["myfilter"],      safeBinProfiles: {        myfilter: {          minPositional: 0,          maxPositional: 0,          allowedValueFlags: ["-n", "--limit"],          deniedFlags: ["-f", "--file", "-c", "--command"],        },      },    },  },}

Команды интерпретаторов и сред выполнения

Запуски интерпретаторов и сред выполнения с подтверждением намеренно обрабатываются консервативно:

• Всегда привязывается точный контекст argv/cwd/env.
• Прямые формы сценариев оболочки и файлов среды выполнения по возможности привязываются к одному конкретному локальному снимку файла.
• Распространённые формы обёрток менеджеров пакетов, которые всё ещё разрешаются в один непосредственный локальный файл (например, pnpm exec, pnpm node, npm exec, npx), разворачиваются перед привязкой.
• Если OpenClaw не может определить ровно один конкретный локальный файл для команды интерпретатора или среды выполнения (например, для сценариев пакетов, форм вычисления, цепочек загрузчиков конкретной среды выполнения или неоднозначных форм с несколькими файлами), выполнение с подтверждением запрещается, вместо того чтобы заявлять о семантическом охвате, которого фактически нет.
• Для таких рабочих процессов предпочтительно использовать песочницу, отдельную границу хоста или явный доверенный список разрешений/полный рабочий процесс, в котором оператор принимает более широкую семантику среды выполнения.

Когда требуется подтверждение, инструмент выполнения немедленно возвращает идентификатор подтверждения. Используйте его, чтобы сопоставить последующие системные события подтверждённого запуска (Exec finished и Exec running, если настроено). Если решение не поступит до истечения времени ожидания, запрос считается просроченным при ожидании подтверждения и отображается как окончательный запрет команды хоста. Для асинхронных подтверждений основного агента с исходным сеансом OpenClaw также возобновляет этот сеанс внутренним продолжением, чтобы агент увидел, что команда не была запущена, а не пытался позднее восстановить отсутствующий результат. По умолчанию ожидающие подтверждения выполнения истекают через 30 минут.

Поведение доставки продолжения

После завершения подтверждённого асинхронного выполнения OpenClaw отправляет продолжение agent в тот же сеанс. Для отклонённых асинхронных подтверждений используется тот же путь продолжения основного сеанса для передачи статуса отказа, но они не регистрируют передачу управления среде выполнения с повышенными правами и не запускают команду. Отказы без возобновляемого основного сеанса либо подавляются, либо передаются по безопасному прямому маршруту, если он существует.

• Если существует действительная внешняя цель доставки (канал с поддержкой доставки и цель to), продолжение доставляется через этот канал.
• В потоках только веб-чата или внутренних сеансов без внешней цели доставка продолжения остаётся только в сеансе (deliver: false).
• Если вызывающая сторона явно требует строгой внешней доставки, но подходящий внешний канал определить невозможно, запрос завершается ошибкой INVALID_REQUEST.
• Если включён bestEffortDeliver и определить внешний канал невозможно, вместо ошибки доставка понижается до режима только в сеансе.

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

Запросы подтверждения выполнения можно пересылать в любой канал чата (включая каналы плагинов) и подтверждать их с помощью /approve. При этом используется обычный конвейер исходящей доставки.

Конфигурация:

{  approvals: {    exec: {      enabled: true,      mode: "session", // "session" | "targets" | "both"      agentFilter: ["main"],      sessionFilter: ["discord"], // substring or regex      targets: [        { channel: "slack", to: "U12345678" },        { channel: "telegram", to: "123456789" },      ],    },  },}

Ответ в чате:

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

Команда /approve обрабатывает как подтверждения выполнения команд, так и подтверждения плагинов. Если идентификатор не соответствует ожидающему подтверждению выполнения команды, она автоматически проверяет подтверждения плагинов. Этот резервный переход ограничен ошибками «подтверждение не найдено»; фактический отказ или ошибка подтверждения выполнения команды не приводит к незаметной повторной попытке в качестве подтверждения плагина.

Перенаправление подтверждений плагинов

Перенаправление подтверждений плагинов использует тот же конвейер доставки, что и подтверждения выполнения команд, но имеет собственную независимую конфигурацию в approvals.plugin. Включение или отключение одного механизма не влияет на другой. Поведение при разработке плагинов, поля запросов и семантику решений см. в разделе Запросы разрешений плагинов.

{  approvals: {    plugin: {      enabled: true,      mode: "targets",      agentFilter: ["main"],      targets: [        { channel: "slack", to: "U12345678" },        { channel: "telegram", to: "123456789" },      ],    },  },}

Структура конфигурации идентична approvals.exec: enabled, mode, agentFilter, sessionFilter и targets работают так же.

Каналы, поддерживающие общие интерактивные ответы, отображают одинаковые кнопки подтверждения как для выполнения команд, так и для плагинов. Каналы без общего интерактивного интерфейса используют обычный текст с инструкциями /approve. Запросы подтверждения плагинов могут ограничивать доступные решения: интерфейсы подтверждения используют набор решений, объявленный в запросе, а Gateway отклоняет попытки отправить решение, которое не было предложено.

Подтверждения в том же чате на любом канале

Когда запрос подтверждения выполнения команды или плагина поступает из чата с поддержкой доставки, по умолчанию его можно подтвердить в том же чате с помощью /approve. Это относится к Slack, Matrix, Microsoft Teams и аналогичным чатам с поддержкой доставки, в дополнение к существующим сценариям веб-интерфейса и терминального интерфейса, с использованием обычной модели авторизации канала для этого диалога. Если исходный чат уже может отправлять команды и получать ответы, запросам подтверждения больше не требуется отдельный нативный адаптер доставки только для того, чтобы оставаться в состоянии ожидания.

Discord, Telegram и QQ bot также поддерживают /approve в том же чате, но эти каналы по-прежнему используют сформированный список подтверждающих пользователей для авторизации, даже если нативная доставка подтверждений отключена.

Нативная доставка подтверждений

Некоторые каналы также могут выступать в роли нативных клиентов подтверждения: Discord, Slack, Telegram, Matrix и QQ bot. Нативные клиенты добавляют личные сообщения подтверждающим пользователям, рассылку в исходный чат и интерактивный интерфейс подтверждения, специфичный для канала, поверх общего процесса /approve в том же чате.

Если доступны нативные карточки или кнопки подтверждения, этот нативный интерфейс является основным способом взаимодействия с агентом. Агент не должен дополнительно дублировать в обычном чате команду /approve, если только результат инструмента не указывает, что подтверждения в чате недоступны или ручное подтверждение является единственным оставшимся способом.

Если нативный клиент подтверждения настроен, но для исходного канала не активна нативная среда выполнения, OpenClaw оставляет видимым локальное детерминированное приглашение /approve. Если нативная среда выполнения активна и пытается выполнить доставку, но ни одна цель не получает карточку, OpenClaw отправляет в тот же чат резервное уведомление с точной командой /approve <id> <decision>, чтобы запрос всё ещё можно было обработать.

Общая модель:

• политика выполнения команд на узле по-прежнему определяет, требуется ли подтверждение выполнения команды
• approvals.exec управляет перенаправлением запросов подтверждения в другие чаты
• channels.<channel>.execApprovals определяет, включены ли Discord, Slack, Telegram, QQ bot и аналогичные нативные клиенты отдельных каналов
• подтверждения плагинов Slack могут использовать нативный клиент подтверждения Slack, когда запрос поступает из Slack и удаётся определить подтверждающих пользователей плагина Slack; approvals.plugin также может направлять подтверждения плагинов в сеансы или цели Slack, даже если подтверждения выполнения команд Slack отключены
• нативные карточки подтверждения Google Chat обрабатывают подтверждения выполнения команд и плагинов, поступившие из пространств или веток Google Chat, когда стабильные подтверждающие пользователи users/<id> определяются из dm.allowFrom или defaultTo; события реакций не используются для принятия решений
• доставка подтверждений с помощью реакций в WhatsApp и Signal управляется параметрами approvals.exec и approvals.plugin; у них нет блоков channels.<channel>.execApprovals

Нативные клиенты автоматически включают доставку сначала в личные сообщения, если выполняются все следующие условия:

• канал поддерживает нативную доставку подтверждений
• подтверждающих пользователей можно определить из явного значения execApprovals.approvers или идентификатора владельца, например commands.ownerAllowFrom
• channels.<channel>.execApprovals.enabled не задано или имеет значение "auto"

Задайте enabled: false, чтобы явно отключить нативный клиент подтверждения. Задайте enabled: true, чтобы принудительно включить его, когда удаётся определить подтверждающих пользователей. Публичная доставка в исходный чат явно настраивается через channels.<channel>.execApprovals.target. Когда нативный параметр target включает доставку в исходный чат, запросы подтверждения содержат текст команды.

Часто задаваемый вопрос: Почему для подтверждений выполнения команд в чатах существуют две конфигурации?

• Discord: channels.discord.execApprovals.*
• Slack: channels.slack.execApprovals.*
• Telegram: channels.telegram.execApprovals.*
• QQ bot: channels.qqbot.execApprovals.*
• Google Chat: настройте стабильных подтверждающих пользователей с помощью channels.googlechat.dm.allowFrom или channels.googlechat.defaultTo; блок execApprovals не требуется
• WhatsApp: используйте approvals.exec и approvals.plugin, чтобы направлять запросы подтверждения в WhatsApp
• Signal: используйте approvals.exec и approvals.plugin, чтобы направлять запросы подтверждения в Signal

Маршрутизация для отдельных нативных клиентов:

• по умолчанию Telegram отправляет запросы в личные сообщения подтверждающим пользователям (target: "dm"). Переключитесь на channel или both, чтобы также показывать запросы подтверждения в исходном чате или теме Telegram. Для тем форумов Telegram OpenClaw сохраняет тему для запроса подтверждения и последующего сообщения после подтверждения.
• подтверждающие пользователи Discord и Telegram могут задаваться явно (execApprovals.approvers) или определяться из commands.ownerAllowFrom; подтвердить или отклонить запрос могут только определённые подтверждающие пользователи.
• подтверждающие пользователи Slack могут задаваться явно (execApprovals.approvers) или определяться из commands.ownerAllowFrom. Личные сообщения для подтверждения плагинов Slack используют подтверждающих пользователей плагинов Slack из allowFrom и маршрутизацию учётной записи по умолчанию, а не подтверждающих пользователей выполнения команд Slack. Нативные кнопки Slack сохраняют тип идентификатора подтверждения, поэтому идентификаторы plugin: могут обрабатывать подтверждения плагинов без второго локального резервного слоя Slack.
• нативные карточки Google Chat сохраняют ручной резервный вариант /approve в тексте сообщения, но обратные вызовы кнопок карточки передают только непрозрачные токены действий; идентификатор подтверждения и решение восстанавливаются из ожидающего состояния на стороне сервера.
• подтверждения с помощью эмодзи WhatsApp обрабатывают запросы выполнения команд и плагинов, когда соответствующее семейство перенаправления верхнего уровня направляет их в WhatsApp. Запросы, исходящие из нативного клиента, привязываются напрямую; при общей доставке в режиме целей те же типизированные метаданные подтверждения привязываются к квитанции принятого сообщения WhatsApp.
• подтверждения с помощью реакций Signal обрабатывают запросы выполнения команд и плагинов только тогда, когда соответствующее семейство перенаправления верхнего уровня включено и направляет их в Signal. Прямые подтверждения выполнения команд Signal в том же чате могут скрывать локальный резервный вариант /approve без явных подтверждающих пользователей; для обработки реакций Signal всё равно требуются явно заданные подтверждающие пользователи Signal из channels.signal.allowFrom или defaultTo.
• нативная маршрутизация Matrix в личные сообщения или каналы и быстрые действия с помощью реакций обрабатывают подтверждения выполнения команд и плагинов; авторизация плагинов по-прежнему определяется из channels.matrix.dm.allowFrom. Нативные запросы Matrix включают содержимое пользовательского события com.openclaw.approval в первое событие запроса, чтобы клиенты Matrix с поддержкой OpenClaw могли считывать структурированное состояние подтверждения, а стандартные клиенты сохраняли обычный текстовый резервный вариант /approve.
• нативные кнопки подтверждения Discord и Telegram передают явный тип владельца — выполнение команды или плагин — в закрытых транспортных данных обратного вызова и обрабатывают только этого владельца. Старые элементы управления /approve, у которых нет типа, остаются ограниченным путём совместимости: они проверяют только те типы владельцев, которые пользователь может подтверждать, продолжают обработку только после результата «подтверждение не найдено» и никогда не определяют владельца по идентификатору подтверждения.
• пользователю, отправившему запрос, не обязательно быть подтверждающим пользователем.
• если ни операторский интерфейс, ни настроенный клиент подтверждения не могут принять запрос, используется резервное приглашение askFallback.

Конфиденциальные групповые команды, доступные только владельцу, такие как /diagnostics и /export-trajectory, используют закрытую маршрутизацию владельца для запросов подтверждения и окончательных результатов. Сначала OpenClaw пытается использовать закрытый маршрут в том же интерфейсе, где владелец запустил команду. Если в этом интерфейсе нет закрытого маршрута владельца, используется первый доступный маршрут владельца из commands.ownerAllowFrom, поэтому групповая команда Discord всё равно может отправить подтверждение и результат в личные сообщения владельца в Telegram, когда Telegram настроен как основной закрытый интерфейс. Групповой чат получает только краткое уведомление.

См. также:

• Discord
• Telegram
• QQ bot

Официальные мобильные приложения оператора

Официальные приложения для iOS и Android также могут просматривать принадлежащие Gateway ожидающие подтверждения выполнения команд, когда используется подключение operator.admin или когда запрос явно адресован сопряжённому устройству operator.approvals. Они считывают ту же очищенную постоянную запись, которую использует интерфейс управления, отправляют решение с учётом типа и отображают канонический результат Gateway по первому ответу. Apple Watch отображает эти запросы подтверждения через сопряжённый iPhone и предоставляет действия однократного разрешения и отказа. В режиме прямого подключения Watch к Gateway просмотр подтверждений недоступен.

Потеря подтверждения обработки не делает отправленный выбор окончательным: приложение отключает элементы управления и повторно считывает запись. Если другой интерфейс ответил первым, приложение показывает записанное решение. Ожидающие запросы остаются привязанными к выдавшему их Gateway, поэтому переключение активного Gateway не может перенаправить старый идентификатор подтверждения.

Процесс IPC в macOS

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

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

• режим сокета Unix 0600, токен хранится в exec-approvals.json.
• проверка одноимённого UID узла.
• запрос и ответ (одноразовое значение + токен HMAC + хеш запроса) + короткий TTL.

Часто задаваемые вопросы

Когда accountId и threadId используются для цели подтверждения?

Используйте accountId, когда для канала настроено несколько идентификаторов и запрос подтверждения должен отправляться через конкретную учётную запись. Используйте threadId, когда место назначения поддерживает темы или ветки и запрос должен оставаться в этой ветке, а не в чате верхнего уровня.

Конкретный пример для Telegram — операционная супергруппа с темами форума и двумя учётными записями ботов Telegram. Значение to указывает супергруппу, accountId выбирает учётную запись бота, а threadId выбирает тему форума:

{  approvals: {    exec: {      enabled: true,      mode: "targets",      targets: [        {          channel: "telegram",          to: "-1001234567890",          accountId: "ops-bot",          threadId: "77",        },      ],    },  },  channels: {    telegram: {      accounts: {        default: {          name: "Primary bot",          botToken: "env:TELEGRAM_PRIMARY_BOT_TOKEN",        },        "ops-bot": {          name: "Operations bot",          botToken: "env:TELEGRAM_OPS_BOT_TOKEN",        },      },    },  },}

При такой настройке перенаправленные запросы на подтверждение выполнения публикуются аккаунтом Telegram ops-bot в теме 77 чата -1001234567890. Для целевого назначения без accountId используется аккаунт канала по умолчанию, а для целевого назначения без threadId публикация выполняется в назначение верхнего уровня.

Если запросы на подтверждение отправляются в сеанс, может ли их подтвердить любой участник этого сеанса?

Нет. Доставка в сеанс определяет только место отображения запроса. Сама по себе она не дает каждому участнику этого чата право подтверждать его.

Для универсальных запросов /approve в том же чате отправитель уже должен иметь право выполнять команды в этом сеансе канала. Если канал явно задает пользователей, уполномоченных подтверждать запросы, они могут разрешить действие /approve, даже если в этом сеансе у них нет иных прав на выполнение команд.

В некоторых каналах действуют более строгие правила. Нативные личные сообщения с запросами на подтверждение в Discord, Telegram, Matrix и Slack, а также аналогичные нативные клиенты подтверждения используют определенные для них списки уполномоченных пользователей для авторизации подтверждений. Например, запрос на подтверждение в теме форума Telegram может быть виден всем участникам темы, но подтвердить или отклонить его могут только пользователи с числовыми идентификаторами Telegram, определенными из channels.telegram.execApprovals.approvers или commands.ownerAllowFrom.

Связанные материалы

• Подтверждения выполнения — основная политика и процесс подтверждения
• Инструмент выполнения
• Режим повышенных привилегий
• Skills — автоматическое разрешение на основе навыков