Запити дозволів Plugin

Запити дозволів Plugin дають змогу коду Plugin призупинити виклик інструмента або належну Plugin операцію, доки користувач не схвалить або не відхилить її. Вони використовують потік Gateway plugin.approval.* і ті самі інтерфейси схвалення, які обробляють кнопки схвалення в чаті та команди /approve. Використовуйте запити дозволів Plugin для дозволів Plugin/застосунку. Вони не замінюють схвалення виконання на хості, необов’язкові списки дозволених інструментів або вбудовану перевірку дозволів Codex.

Виберіть правильний механізм контролю

Виберіть механізм контролю, що відповідає потрібній точці ухвалення рішення:

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

Необов’язкові інструменти — це механізм контролю на етапі виявлення. Запити дозволів Plugin — це механізм контролю для кожного виклику. Використовуйте обидва, якщо чутливий інструмент має потребувати явної згоди, перш ніж модель зможе його побачити, і схвалення перед виконанням дії.

Запит схвалення перед викликом інструмента

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

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

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,
          onResolution(decision) {
            console.log(`deploy approval resolved: ${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`	Поточний виклик продовжується, а рішення передається Plugin.
`deny`	Виклик блокується з результатом інструмента «відмовлено».
Час очікування минув	Виклик блокується.
Скасування	Виклик блокується, коли виконання перервано.
Немає маршруту схвалення	Виклик блокується, оскільки жоден підключений інтерфейс схвалення не може його опрацювати.

Виконання дозволяють лише точні рішення allow-once і allow-always, дозволені запитом. Невідомі, некоректні, невідповідні, відсутні рішення та рішення, для яких минув час очікування, призводять до безпечної відмови. Застаріле поле timeoutBehavior і надалі приймається для сумісності Plugin, але є застарілим та ігнорується; не задавайте його в нових хуках. allow-always є постійним лише тоді, коли Plugin або середовище виконання, що надсилає запит, реалізує таке збереження. Для звичайних хуків before_tool_call.requireApproval OpenClaw розглядає allow-once і allow-always як рішення про схвалення для поточного виклику та передає отримане значення до onResolution. Якщо ваш Plugin пропонує allow-always, задокументуйте та реалізуйте, яким саме майбутнім викликам він довіряє. Якщо хук також повертає params, OpenClaw застосовує ці зміни параметрів лише після успішного схвалення. Хук із нижчим пріоритетом усе одно може заблокувати дію після того, як хук із вищим пріоритетом запитав схвалення. allowedDecisions обмежує кнопки та команди, показані користувачеві. Gateway відхиляє спробу вирішення з будь-яким рішенням, якого не було запропоновано в запиті.

Маршрутизація запитів схвалення

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

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

approvals.plugin не залежить від approvals.exec. Увімкнення пересилання схвалень виконання не маршрутизує запити схвалення Plugin, а ввімкнення пересилання схвалень Plugin не змінює політику виконання на хості. Якщо запит містить текст для ручного схвалення, опрацюйте його за допомогою одного із запропонованих рішень:

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

Повну модель пересилання, поведінку схвалень у тому самому чаті, вбудовану доставку каналами та правила для уповноважених осіб у конкретних каналах див. у розділі Розширені схвалення виконання.

Вбудовані дозволи Codex

Вбудовані запити дозволів Codex також можуть проходити через схвалення Plugin, але їхня належність відрізняється від хуків, створених у Plugin.

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

Специфічну для Codex поведінку та правила резервної обробки див. у розділі Середовище виконання Codex harness.

Усунення несправностей

Інструмент повідомляє, що схвалення Plugin недоступні. Жоден інтерфейс схвалення або налаштований маршрут схвалення не прийняв запит. Підключіть клієнт із підтримкою схвалень, використайте канал, що підтримує /approve у тому самому чаті, або налаштуйте approvals.plugin. З’являється allow-always, але наступний виклик знову запитує дозвіл. Загальний потік схвалення Plugin не зберігає автоматично довіру для довільних хуків. Збережіть належну Plugin довіру у своєму Plugin після onResolution("allow-always") або пропонуйте лише allow-once і deny. /approve відхиляє рішення. Запит обмежив allowedDecisions. Використайте одне з рішень, надрукованих у запиті. Запит Discord, Matrix, Slack або Telegram маршрутизується інакше, ніж схвалення виконання. Схвалення Plugin і схвалення виконання використовують окремі налаштування та можуть застосовувати різні перевірки авторизації. Перевірте approvals.plugin і підтримку схвалень Plugin у каналі, а не лише approvals.exec.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Запити дозволів Plugin

Виберіть правильний механізм контролю

Запит схвалення перед викликом інструмента

Поведінка рішень

Маршрутизація запитів схвалення

Вбудовані дозволи Codex

Усунення несправностей

Пов’язані матеріали

​Виберіть правильний механізм контролю

​Запит схвалення перед викликом інструмента

​Поведінка рішень

​Маршрутизація запитів схвалення

​Вбудовані дозволи Codex

​Усунення несправностей

​Пов’язані матеріали

Виберіть правильний механізм контролю

Запит схвалення перед викликом інструмента

Поведінка рішень

Маршрутизація запитів схвалення

Вбудовані дозволи Codex

Усунення несправностей

Пов’язані матеріали