--- read_when: - Вам нужен хук или инструмент плагина, который запрашивает подтверждение перед выполнением действия с побочным эффектом - Необходимо настроить, куда будут отправляться запросы на одобрение плагинов - Вы выбираете между необязательными инструментами, подтверждениями выполнения команд и подтверждениями плагинов sidebarTitle: Permission requests summary: Запрашивать у пользователей подтверждение вызовов инструментов плагина и запросов разрешений, принадлежащих плагину title: Запросы разрешений плагина x-i18n: generated_at: "2026-07-13T20:04:10Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 675534212e70cc7b2e7bdc801955929c6a8156b08d620483edf0133afc3bfdaa source_path: plugins/plugin-permission-requests.md workflow: 16 --- Запросы разрешений плагинов позволяют приостановить вызов инструмента или принадлежащую плагину операцию, пока пользователь не одобрит или не отклонит её. Они используют поток Gateway `plugin.approval.*` и те же интерфейсы одобрения, которые обрабатывают кнопки одобрения в чате и команды `/approve`. Используйте запросы разрешений плагинов для разрешений плагинов и приложений. Они не заменяют одобрения выполнения команд на хосте, необязательные списки разрешённых инструментов или встроенную проверку разрешений Codex. ## Выберите подходящий механизм контроля Выберите механизм, соответствующий требуемой точке принятия решения: | Механизм контроля | Когда использовать | Что он контролирует | | -------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | Необязательные инструменты | Инструмент не должен быть виден модели, пока пользователь явно не согласится. | Предоставление инструментов через `tools.allow`. | | Запросы разрешений плагинов | Хук плагина или принадлежащая плагину операция должны запрашивать разрешение перед выполнением действия. | Одобрение во время выполнения через `plugin.approval.*`. | | Одобрения выполнения команд | Команде хоста или инструменту, подобному оболочке, требуется одобрение оператора. | Политику выполнения команд на хосте и постоянные списки разрешённых команд. | | Встроенные запросы разрешений Codex | Codex запрашивает разрешение перед встроенными действиями с оболочкой, файлами, MCP или сервером приложений. | Обработку одобрений сервером приложений Codex или встроенным хуком, направляемую через одобрения плагинов, когда запросом управляет OpenClaw. | | Запросы одобрения MCP | Сервер MCP для Codex запрашивает одобрение вызова инструмента. | Ответы на запросы одобрения MCP, передаваемые через одобрения плагинов OpenClaw. | Необязательные инструменты — это механизм контроля на этапе обнаружения. Запросы разрешений плагинов — механизм контроля для каждого вызова. Используйте оба механизма, если для конфиденциального инструмента требуется явное согласие до того, как модель сможет его увидеть, и одобрение до выполнения действия. ## Запрашивайте одобрение перед вызовом инструмента Большинство запросов, создаваемых плагинами, следует инициировать в хуке `before_tool_call`. Хук запускается после того, как модель выбрала инструмент, но до того, как OpenClaw выполнит его: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({ id: "deploy-policy", name: "Политика развёртывания", register(api) { api.on("before_tool_call", async (event) => { if (event.toolName !== "deploy_service") { return; } const environment = typeof event.params.environment === "string" ? event.params.environment : "unknown"; return { requireApproval: { title: "Развернуть сервис", description: `Развернуть сервис в среде ${environment}.`, severity: environment === "production" ? "critical" : "warning", allowedDecisions: environment === "production" ? ["allow-once", "deny"] : ["allow-once", "allow-always", "deny"], timeoutMs: 120_000, onResolution(decision) { console.log(`одобрение развёртывания получено: ${decision}`); }, }, }; }); }, }); ``` Формулируйте текст запроса для человека, который будет одобрять действие: - Делайте `title` кратким и ориентированным на действие; Gateway ограничивает его длину 80 символами. - Делайте `description` конкретным и ограниченным по объёму; Gateway ограничивает его длину 512 символами. - Укажите действие, цель и риск. Не включайте секреты, токены или конфиденциальные данные, которые не должны отображаться в интерфейсах одобрения в чате. - Если `severity` не указан, по умолчанию используется `"warning"`. Используйте `"critical"` только для действий, ошибочное решение по которым может привести к ущербу в рабочей среде или потере данных. - Если `allowedDecisions` не указан, по умолчанию используется `["allow-once", "allow-always", "deny"]`. Передавайте `["allow-once", "deny"]`, если постоянное доверие небезопасно для этого действия. - Значение `timeoutMs` по умолчанию составляет 120000 (2 минуты) и ограничено 600000 (10 минутами) независимо от запрошенного значения. ## Обработка решений OpenClaw создаёт ожидающий одобрения запрос с идентификатором `plugin:`, доставляет его в доступные интерфейсы одобрения и ожидает решения. | Решение | Результат | | ----------------- | ------------------------------------------------------------------------- | | `allow-once` | Текущий вызов продолжается. | | `allow-always` | Текущий вызов продолжается, а решение передаётся плагину. | | `deny` | Вызов блокируется с результатом инструмента, указывающим на отказ. | | Истечение времени | Вызов блокируется. | | Отмена | Вызов блокируется при прерывании выполнения. | | Нет маршрута одобрения | Вызов блокируется, поскольку ни один подключённый интерфейс одобрения не может обработать запрос. | Выполнение разрешают только точные решения `allow-once` и `allow-always`, допустимые в запросе. Неизвестные, некорректные, несоответствующие, отсутствующие и просроченные решения приводят к безопасному отказу. Устаревшее поле `timeoutBehavior` по-прежнему принимается для совместимости плагинов, но объявлено устаревшим и игнорируется; не задавайте его в новых хуках. `allow-always` является постоянным только в том случае, если запрашивающий плагин или среда выполнения реализует такое сохранение. Для обычных хуков `before_tool_call.requireApproval` OpenClaw рассматривает `allow-once` и `allow-always` как решения об одобрении для текущего вызова и передаёт полученное значение в `onResolution`. Если ваш плагин предлагает `allow-always`, задокументируйте и реализуйте, каким именно будущим вызовам он доверяет. Если хук также возвращает `params`, OpenClaw применяет эти изменения параметров только после успешного одобрения. Хук с более низким приоритетом всё ещё может заблокировать выполнение после того, как хук с более высоким приоритетом запросил одобрение. `allowedDecisions` ограничивает кнопки и команды, отображаемые пользователю. Gateway отклоняет попытку разрешить запрос любым решением, которое не было предложено в запросе. ## Маршрутизация запросов на одобрение Запросы на одобрение могут обрабатываться в локальных интерфейсах или в каналах чата, поддерживающих обработку одобрений. Чтобы пересылать запросы на одобрение плагинов явно заданным целям чата, настройте `approvals.plugin`: ```json5 { approvals: { plugin: { enabled: true, mode: "targets", agentFilter: ["main"], targets: [{ channel: "slack", to: "U12345678" }], }, }, } ``` `approvals.plugin` не зависит от `approvals.exec`. Включение пересылки одобрений выполнения команд не маршрутизирует запросы на одобрение плагинов, а включение пересылки одобрений плагинов не изменяет политику выполнения команд на хосте. Если запрос содержит текст для ручного одобрения, разрешите его одним из предложенных решений: ```text /approve allow-once /approve allow-always /approve deny ``` Полное описание модели пересылки, одобрения в том же чате, встроенной доставки в каналах и правил для одобряющих лиц в отдельных каналах см. в разделе [Расширенные одобрения выполнения команд](/ru/tools/exec-approvals-advanced#plugin-approval-forwarding). ## Встроенные разрешения Codex Встроенные запросы разрешений Codex также могут передаваться через одобрения плагинов, но у них другой владелец, чем у хуков, создаваемых плагинами. - Запросы одобрения сервера приложений Codex направляются через OpenClaw после проверки Codex. - Ретранслятор встроенного хука `permission_request` может отправлять запрос через `plugin.approval.request`, если этот ретранслятор включён. - Запросы одобрения инструментов MCP направляются через одобрения плагинов, когда Codex задаёт для `_meta.codex_approval_kind` значение `"mcp_tool_call"`. Специфичное для Codex поведение и правила резервного варианта см. в разделе [Среда выполнения инфраструктуры Codex](/ru/plugins/codex-harness-runtime#native-permissions-and-mcp-elicitations). ## Устранение неполадок **Инструмент сообщает, что одобрения плагинов недоступны.** Ни один интерфейс одобрения или настроенный маршрут одобрения не принял запрос. Подключите клиент с поддержкой одобрений, используйте канал, поддерживающий `/approve` в том же чате, или настройте `approvals.plugin`. **Появляется `allow-always`, но следующий вызов снова запрашивает одобрение.** Общий поток одобрения плагинов не сохраняет доверие автоматически для произвольных хуков. Сохраняйте принадлежащее плагину доверие в своём плагине после `onResolution("allow-always")` или предлагайте только `allow-once` и `deny`. **`/approve` отклоняет решение.** Запрос ограничил `allowedDecisions`. Используйте одно из решений, указанных в запросе. **Запрос в Discord, Matrix, Slack или Telegram маршрутизируется иначе, чем одобрения выполнения команд.** Одобрения плагинов и одобрения выполнения команд используют отдельные настройки и могут применять разные проверки авторизации. Проверьте `approvals.plugin` и поддержку одобрений плагинов в канале, а не только `approvals.exec`. ## Связанные материалы - [Хуки плагинов](/ru/plugins/hooks#tool-call-policy) - [Создание плагинов](/ru/plugins/building-plugins#registering-tools) - [Расширенные одобрения выполнения команд](/ru/tools/exec-approvals-advanced#plugin-approval-forwarding) - [Протокол Gateway](/ru/gateway/protocol) - [Среда выполнения инфраструктуры Codex](/ru/plugins/codex-harness-runtime#native-permissions-and-mcp-elicitations)