Запросы разрешений плагина

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

Используйте запросы разрешений плагинов для разрешений плагинов и приложений. Они не заменяют одобрения выполнения команд на хосте, необязательные списки разрешённых инструментов или встроенную проверку разрешений Codex.

Выберите подходящий механизм контроля

Выберите механизм, соответствующий требуемой точке принятия решения:

Необязательные инструменты — это механизм контроля на этапе обнаружения. Запросы разрешений плагинов — механизм контроля для каждого вызова. Используйте оба механизма, если для конфиденциального инструмента требуется явное согласие до того, как модель сможет его увидеть, и одобрение до выполнения действия.

Запрашивайте одобрение перед вызовом инструмента

Большинство запросов, создаваемых плагинами, следует инициировать в хуке before_tool_call. Хук запускается после того, как модель выбрала инструмент, но до того, как OpenClaw выполнит его:

 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, допустимые в запросе. Неизвестные, некорректные, несоответствующие, отсутствующие и просроченные решения приводят к безопасному отказу. Устаревшее поле timeoutBehavior по-прежнему принимается для совместимости плагинов, но объявлено устаревшим и игнорируется; не задавайте его в новых хуках.

allow-always является постоянным только в том случае, если запрашивающий плагин или среда выполнения реализует такое сохранение. Для обычных хуков before_tool_call.requireApproval OpenClaw рассматривает allow-once и allow-always как решения об одобрении для текущего вызова и передаёт полученное значение в onResolution. Если ваш плагин предлагает allow-always, задокументируйте и реализуйте, каким именно будущим вызовам он доверяет.

Если хук также возвращает params, OpenClaw применяет эти изменения параметров только после успешного одобрения. Хук с более низким приоритетом всё ещё может заблокировать выполнение после того, как хук с более высоким приоритетом запросил одобрение.

allowedDecisions ограничивает кнопки и команды, отображаемые пользователю. Gateway отклоняет попытку разрешить запрос любым решением, которое не было предложено в запросе.

Маршрутизация запросов на одобрение

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

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

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

Если запрос содержит текст для ручного одобрения, разрешите его одним из предложенных решений:

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

Полное описание модели пересылки, одобрения в том же чате, встроенной доставки в каналах и правил для одобряющих лиц в отдельных каналах см. в разделе Расширенные одобрения выполнения команд.

Встроенные разрешения Codex

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

• Запросы одобрения сервера приложений Codex направляются через OpenClaw после проверки Codex.
• Ретранслятор встроенного хука permission_request может отправлять запрос через plugin.approval.request, если этот ретранслятор включён.
• Запросы одобрения инструментов MCP направляются через одобрения плагинов, когда Codex задаёт для _meta.codex_approval_kind значение "mcp_tool_call".

Специфичное для Codex поведение и правила резервного варианта см. в разделе Среда выполнения инфраструктуры Codex.

Устранение неполадок

Инструмент сообщает, что одобрения плагинов недоступны. Ни один интерфейс одобрения или настроенный маршрут одобрения не принял запрос. Подключите клиент с поддержкой одобрений, используйте канал, поддерживающий /approve в том же чате, или настройте approvals.plugin.

Появляется allow-always, но следующий вызов снова запрашивает одобрение. Общий поток одобрения плагинов не сохраняет доверие автоматически для произвольных хуков. Сохраняйте принадлежащее плагину доверие в своём плагине после onResolution("allow-always") или предлагайте только allow-once и deny.

/approve отклоняет решение. Запрос ограничил allowedDecisions. Используйте одно из решений, указанных в запросе.

Запрос в Discord, Matrix, Slack или Telegram маршрутизируется иначе, чем одобрения выполнения команд. Одобрения плагинов и одобрения выполнения команд используют отдельные настройки и могут применять разные проверки авторизации. Проверьте approvals.plugin и поддержку одобрений плагинов в канале, а не только approvals.exec.

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

• Хуки плагинов
• Создание плагинов
• Расширенные одобрения выполнения команд
• Протокол Gateway
• Среда выполнения инфраструктуры Codex