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

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

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

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

Механизм контроля	Когда использовать	Что он контролирует
Необязательные инструменты	Инструмент не должен быть виден модели, пока пользователь явно не согласится.	Предоставление инструментов через `tools.allow`.
Запросы разрешений плагинов	Хук плагина или принадлежащая плагину операция должны запрашивать разрешение перед выполнением действия.	Одобрение во время выполнения через `plugin.approval.*`.
Одобрения выполнения команд	Команде хоста или инструменту, подобному оболочке, требуется одобрение оператора.	Политику выполнения команд на хосте и постоянные списки разрешённых команд.
Встроенные запросы разрешений Codex	Codex запрашивает разрешение перед встроенными действиями с оболочкой, файлами, MCP или сервером приложений.	Обработку одобрений сервером приложений Codex или встроенным хуком, направляемую через одобрения плагинов, когда запросом управляет OpenClaw.
Запросы одобрения MCP	Сервер MCP для Codex запрашивает одобрение вызова инструмента.	Ответы на запросы одобрения MCP, передаваемые через одобрения плагинов OpenClaw.

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

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

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

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:

{
  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.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

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

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

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

Обработка решений

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

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

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

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

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

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

​Обработка решений

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

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

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

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

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

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

Обработка решений

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

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

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

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