--- read_when: - Потрібен хук або інструмент Plugin, який запитуватиме перед виконанням побічного ефекту - Потрібно налаштувати, куди доставляються запити на схвалення Plugin - Ви обираєте між необов’язковими інструментами, схваленнями виконання та схваленнями Plugin sidebarTitle: Permission requests summary: Попросіть користувачів схвалювати виклики інструментів Plugin і запити дозволів, що належать Plugin title: Запити дозволів Plugin x-i18n: generated_at: "2026-06-27T17:56:01Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 72b860e9f8ddef80c70e943ec05353cbc0a917577382289649432a58c3ce6bd0 source_path: plugins/plugin-permission-requests.md workflow: 16 --- Запити дозволів Plugin дають коду Plugin змогу призупинити виклик інструмента або операцію, якою володіє Plugin, доки користувач не схвалить або не відхилить її. Вони використовують потік Gateway `plugin.approval.*` і ті самі поверхні UI схвалення, що обробляють кнопки схвалення в чаті та команди `/approve`. Використовуйте запити дозволів Plugin для дозволів Plugin/застосунків. Вони не замінюють схвалення виконання команд хоста, необов’язкові списки дозволених інструментів або нативний перегляд дозволів Codex. ## Виберіть правильний шлюз Виберіть шлюз, що відповідає потрібній точці ухвалення рішення: | Шлюз | Коли використовувати | Що він контролює | | -------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | Необов’язкові інструменти | Інструмент не має бути видимим для моделі, доки користувач не погодиться. | Видимість інструментів через `tools.allow`. | | Запити дозволів Plugin | Хук Plugin або операція, якою володіє Plugin, має запитати дозвіл перед виконанням однієї дії. | Схвалення під час виконання через `plugin.approval.*`. | | Схвалення exec | Команда хоста або shell-подібний інструмент потребує схвалення оператора. | Політика exec хоста та сталі списки дозволів exec. | | Нативні запити дозволів Codex | Codex запитує дозвіл перед нативними діями shell, файлами, MCP або app-server. | Обробка схвалення app-server 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, timeoutBehavior: "deny", onResolution(decision) { console.log(`deploy approval resolved: ${decision}`); }, }, }; }); }, }); ``` Пишіть текст запиту для людини, яка схвалюватиме дію: - Тримайте `title` коротким і зосередженим на дії. Gateway приймає до 80 символів. - Тримайте `description` конкретним і обмеженим. Gateway приймає до 256 символів. - Додайте дію, ціль і ризик. Не додавайте секрети, токени або приватні корисні дані, які не мають з’являтися в чат-поверхнях схвалення. - Використовуйте `severity: "critical"` лише для дій, де неправильне рішення може спричинити пошкодження production або втрату даних. - Використовуйте `allowedDecisions: ["allow-once", "deny"]`, коли стала довіра є небезпечною для цієї дії. ## Поведінка рішень OpenClaw створює очікуване схвалення з ID `plugin:`, доставляє його до доступних поверхонь схвалення та чекає на рішення. | Рішення | Результат | | ----------------- | ------------------------------------------------------------------------- | | `allow-once` | Поточний виклик продовжується. | | `allow-always` | Поточний виклик продовжується, а рішення передається до Plugin. | | `deny` | Виклик блокується з результатом інструмента про відмову. | | Тайм-аут | Виклик блокується, якщо `timeoutBehavior` не дорівнює `"allow"`. | | Скасування | Виклик блокується, коли запуск перервано. | | Немає маршруту схвалення | Виклик блокується, бо жодна підключена поверхня схвалення не може його розв’язати. | `allow-always` є сталим лише тоді, коли Plugin або runtime, що запитує, реалізує таке збереження. Для звичайних хуків `before_tool_call.requireApproval` OpenClaw розглядає `allow-once` і `allow-always` як рішення схвалення для поточного виклику та передає розв’язане значення до `onResolution`. Якщо ваш Plugin пропонує `allow-always`, задокументуйте й реалізуйте точно, яким майбутнім викликам він довіряє. Якщо хук також повертає `params`, OpenClaw застосовує ці зміни параметрів лише після успішного схвалення. Хук із нижчим пріоритетом усе ще може заблокувати після того, як хук із вищим пріоритетом запросив схвалення. `allowedDecisions` обмежує кнопки та команди, показані користувачу. Gateway відхиляє спробу розв’язання для будь-якого рішення, якого запит не пропонував. ## Маршрутизуйте запити схвалення Запити схвалення можуть розв’язуватися в локальних поверхнях UI або в чат-каналах, що підтримують обробку схвалень. Щоб пересилати запити схвалення Plugin до явних чат-цілей, налаштуйте `approvals.plugin`: ```json5 { approvals: { plugin: { enabled: true, mode: "targets", agentFilter: ["main"], targets: [{ channel: "slack", to: "U12345678" }], }, }, } ``` `approvals.plugin` не залежить від `approvals.exec`. Увімкнення пересилання схвалень exec не маршрутизує запити схвалення Plugin, а ввімкнення пересилання схвалень Plugin не змінює політику exec хоста. Коли запит містить текст ручного схвалення, розв’яжіть його одним із запропонованих рішень: ```text /approve allow-once /approve allow-always /approve deny ``` Див. [Розширені схвалення exec](/uk/tools/exec-approvals-advanced#plugin-approval-forwarding) для повної моделі пересилання, поведінки схвалення в тому самому чаті, нативної доставки каналом і правил схвалювачів, специфічних для каналу. ## Нативні дозволи Codex Нативні запити дозволів Codex також можуть проходити через схвалення Plugin, але вони мають інше володіння, ніж хуки, створені Plugin. - Запити схвалення app-server Codex маршрутизуються через OpenClaw після перегляду Codex. - Ретранслятор нативного хука `permission_request` може запитувати через `plugin.approval.request`, коли цей ретранслятор увімкнено. - Запити схвалення інструментів MCP маршрутизуються через схвалення Plugin, коли Codex позначає `_meta.codex_approval_kind` як `"mcp_tool_call"`. Див. [Runtime Codex harness](/uk/plugins/codex-harness-runtime#native-permissions-and-mcp-elicitations) для поведінки, специфічної для Codex, і правил fallback. ## Усунення несправностей **Інструмент повідомляє, що схвалення Plugin недоступні.** Жоден UI схвалення або налаштований маршрут схвалення не прийняв запит. Підключіть клієнт, здатний до схвалення, використайте канал, що підтримує `/approve` у тому самому чаті, або налаштуйте `approvals.plugin`. **`allow-always` з’являється, але наступний виклик знову показує запит.** Загальний потік схвалення Plugin не зберігає довіру автоматично для довільних хуків. Зберігайте довіру, якою володіє Plugin, у вашому Plugin після `onResolution("allow-always")`, або пропонуйте лише `allow-once` і `deny`. **`/approve` відхиляє рішення.** Запит обмежив `allowedDecisions`. Використайте одне з рішень, надрукованих у запиті. **Запит Slack, Discord, Telegram або Matrix маршрутизується інакше, ніж схвалення exec.** Схвалення Plugin і схвалення exec використовують окрему конфігурацію та можуть застосовувати різні перевірки авторизації. Перевірте `approvals.plugin` і підтримку схвалень Plugin каналом, а не лише `approvals.exec`. ## Пов’язане - [Хуки Plugin](/uk/plugins/hooks#tool-call-policy) - [Створення plugins](/uk/plugins/building-plugins#registering-agent-tools) - [Розширені схвалення exec](/uk/tools/exec-approvals-advanced#plugin-approval-forwarding) - [Протокол Gateway](/uk/gateway/protocol) - [Runtime Codex harness](/uk/plugins/codex-harness-runtime#native-permissions-and-mcp-elicitations)