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

Запити дозволів Plugin дають коду Plugin змогу призупинити виклик інструмента або операцію, якою володіє Plugin, доки користувач не схвалить або не відхилить її. Вони використовують потік Gateway plugin.approval.* і ті самі поверхні UI схвалення, що обробляють кнопки схвалення в чаті та команди /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,          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-always є сталим лише тоді, коли Plugin або runtime, що запитує, реалізує таке збереження. Для звичайних хуків before_tool_call.requireApproval OpenClaw розглядає allow-once і allow-always як рішення схвалення для поточного виклику та передає розв’язане значення до onResolution. Якщо ваш Plugin пропонує allow-always, задокументуйте й реалізуйте точно, яким майбутнім викликам він довіряє.

Якщо хук також повертає params, OpenClaw застосовує ці зміни параметрів лише після успішного схвалення. Хук із нижчим пріоритетом усе ще може заблокувати після того, як хук із вищим пріоритетом запросив схвалення.

allowedDecisions обмежує кнопки та команди, показані користувачу. Gateway відхиляє спробу розв’язання для будь-якого рішення, якого запит не пропонував.

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

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

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

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

Коли запит містить текст ручного схвалення, розв’яжіть його одним із запропонованих рішень:

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

Див. Розширені схвалення exec для повної моделі пересилання, поведінки схвалення в тому самому чаті, нативної доставки каналом і правил схвалювачів, специфічних для каналу.

Нативні дозволи 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 для поведінки, специфічної для 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
• Створення plugins
• Розширені схвалення exec
• Протокол Gateway
• Runtime Codex harness