--- read_when: - Потрібен хук або інструмент плагіна, щоб запитувати підтвердження перед виконанням дії з побічним ефектом - Потрібно налаштувати, куди надсилатимуться запити на схвалення плагінів - Ви обираєте між необов’язковими інструментами, схваленнями виконання команд і схваленнями плагінів sidebarTitle: Permission requests summary: Просіть користувачів схвалювати виклики інструментів плагінів і запити дозволів від плагінів title: Запити дозволів Plugin x-i18n: generated_at: "2026-07-16T18:17:05Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 675534212e70cc7b2e7bdc801955929c6a8156b08d620483edf0133afc3bfdaa source_path: plugins/plugin-permission-requests.md workflow: 16 --- Запити дозволів 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 його виконає: ```typescript 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`: ```json5 { approvals: { plugin: { enabled: true, mode: "targets", agentFilter: ["main"], targets: [{ channel: "slack", to: "U12345678" }], }, }, } ``` `approvals.plugin` не залежить від `approvals.exec`. Увімкнення пересилання схвалень виконання не маршрутизує запити схвалення Plugin, а ввімкнення пересилання схвалень Plugin не змінює політику виконання на хості. Якщо запит містить текст для ручного схвалення, опрацюйте його за допомогою одного із запропонованих рішень: ```text /approve allow-once /approve allow-always /approve deny ``` Повну модель пересилання, поведінку схвалень у тому самому чаті, вбудовану доставку каналами та правила для уповноважених осіб у конкретних каналах див. у розділі [Розширені схвалення виконання](/uk/tools/exec-approvals-advanced#plugin-approval-forwarding). ## Вбудовані дозволи 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](/uk/plugins/codex-harness-runtime#native-permissions-and-mcp-elicitations). ## Усунення несправностей **Інструмент повідомляє, що схвалення 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](/uk/plugins/hooks#tool-call-policy) - [Створення плагінів](/uk/plugins/building-plugins#registering-tools) - [Розширені схвалення виконання](/uk/tools/exec-approvals-advanced#plugin-approval-forwarding) - [Протокол Gateway](/uk/gateway/protocol) - [Середовище виконання Codex harness](/uk/plugins/codex-harness-runtime#native-permissions-and-mcp-elicitations)