Building plugins

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

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

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

Выберите правильный шлюз

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

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

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

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

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

typescript

 export default definePluginEntry({  id: "deploy-policy",  name: "Deploy Policy",  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: "Deploy service",          description: `Deploy service to ${environment}.`,          severity: environment === "production" ? "critical" : "warning",          allowedDecisions:            environment === "production"              ? ["allow-once", "deny"]              : ["allow-once", "allow-always", "deny"],          timeoutMs: 120_000,          timeoutBehavior: "deny",          onResolution(decision) {            console.log(`deploy approval resolved: ${decision}`);          },        },      };    });  },});

Пишите текст prompt для человека, который будет одобрять действие:

Делайте title коротким и ориентированным на действие. Gateway принимает до 80 символов.
Делайте description конкретным и ограниченным по смыслу. Gateway принимает до 256 символов.
Укажите действие, цель и риск. Не включайте секреты, токены или приватные payload, которые не должны отображаться на поверхностях одобрения в чате.
Используйте severity: "critical" только для действий, где неправильное решение может привести к ущербу в production или потере данных.
Используйте allowedDecisions: ["allow-once", "deny"], когда постоянное доверие небезопасно для этого действия.

Поведение решений

OpenClaw создает ожидающее одобрение с ID plugin:, доставляет его на доступные поверхности одобрения и ждет решения.

Решение	Результат
`allow-once`	Текущий вызов продолжается.
`allow-always`	Текущий вызов продолжается, а решение передается в Plugin.
`deny`	Вызов блокируется с результатом инструмента об отклонении.
Тайм-аут	Вызов блокируется, если `timeoutBehavior` не равно `"allow"`.
Отмена	Вызов блокируется, когда выполнение прерывается.
Нет маршрута одобрения	Вызов блокируется, потому что ни одна подключенная поверхность одобрения не может его разрешить.

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

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

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

Маршрутизируйте prompt одобрений

Prompt одобрений могут разрешаться в локальных поверхностях UI или в чат-каналах, которые поддерживают обработку одобрений. Чтобы пересылать prompt одобрений Plugin явным целям чата, настройте approvals.plugin:

json5

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

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

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

text

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

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

Нативные разрешения Codex

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

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

См. Среда выполнения harness Codex для поведения, специфичного для Codex, и правил fallback.

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

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

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

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

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

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

Was this useful?