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

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

Використовуйте запити дозволів Plugin для дозволів Plugin/застосунку. Вони не замінюють схвалення виконання на хості, необов’язкові списки дозволених інструментів або вбудовану перевірку дозволів Codex.

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

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

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

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

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

 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, дозволені запитом. Невідомі, некоректні, невідповідні, відсутні рішення та рішення, для яких минув час очікування, призводять до безпечної відмови. Застаріле поле 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.

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

• Хуки Plugin
• Створення плагінів
• Розширені схвалення виконання
• Протокол Gateway
• Середовище виконання Codex harness