Żądania uprawnień Pluginu

Żądania uprawnień Pluginu umożliwiają kodowi Pluginu wstrzymanie wywołania narzędzia lub operacji należącej do Pluginu do czasu jej zatwierdzenia albo odrzucenia przez użytkownika. Korzystają z przepływu Gateway plugin.approval.* oraz tych samych interfejsów zatwierdzania, które obsługują przyciski zatwierdzania na czacie i polecenia /approve.

Żądań uprawnień Pluginu należy używać do uprawnień Pluginu/aplikacji. Nie zastępują one zatwierdzeń wykonywania poleceń na hoście, opcjonalnych list dozwolonych narzędzi ani natywnej weryfikacji uprawnień przez Codex.

Wybór właściwej bramy

Należy wybrać bramę odpowiadającą wymaganemu punktowi decyzyjnemu:

Opcjonalne narzędzia stanowią bramę na etapie wykrywania. Żądania uprawnień Pluginu stanowią bramę dla każdego wywołania. Należy użyć obu, gdy wrażliwe narzędzie powinno wymagać jawnego włączenia, zanim model będzie mógł je zobaczyć, oraz zatwierdzenia przed wykonaniem działania.

Żądanie zatwierdzenia przed wywołaniem narzędzia

Większość monitów tworzonych przez Plugin powinna rozpoczynać się w hooku before_tool_call. Hook jest uruchamiany po wybraniu narzędzia przez model, ale przed jego wykonaniem przez 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}`);          },        },      };    });  },});

Tekst monitu należy napisać z myślą o osobie, która będzie zatwierdzać działanie:

• Pole title powinno być krótkie i skoncentrowane na działaniu; Gateway ogranicza je do 80 znaków.
• Pole description powinno być konkretne i precyzyjnie ograniczone; Gateway ogranicza je do 512 znaków.
• Należy uwzględnić działanie, cel i ryzyko. Nie należy podawać sekretów, tokenów ani prywatnych ładunków, które nie powinny pojawiać się w interfejsach zatwierdzania na czacie.
• Jeśli pominięto severity, domyślnie przyjmuje ono wartość "warning". Wartości "critical" należy używać wyłącznie w przypadku działań, przy których błędna decyzja może spowodować szkody w środowisku produkcyjnym lub utratę danych.
• Jeśli pominięto allowedDecisions, domyślnie przyjmuje ono wartość ["allow-once", "allow-always", "deny"]. Wartość ["allow-once", "deny"] należy przekazać, gdy trwałe zaufanie jest niebezpieczne dla danego działania.
• Domyślna wartość timeoutMs wynosi 120000 (2 minuty), a maksymalna 600000 (10 minut), niezależnie od żądanej wartości.

Sposób obsługi decyzji

OpenClaw tworzy oczekujące zatwierdzenie z identyfikatorem plugin:, przekazuje je do dostępnych interfejsów zatwierdzania i oczekuje na decyzję.

Na wykonanie zezwalają wyłącznie dokładne decyzje allow-once i allow-always dozwolone przez żądanie. Decyzje nieznane, nieprawidłowe, niedopasowane, brakujące oraz otrzymane po przekroczeniu limitu czasu powodują bezpieczną odmowę. Starsze pole timeoutBehavior pozostaje akceptowane ze względu na zgodność Pluginów, ale jest przestarzałe i ignorowane; nie należy go ustawiać w nowych hookach.

Wartość allow-always jest trwała tylko wtedy, gdy żądający Plugin lub środowisko wykonawcze implementuje taką trwałość. W przypadku zwykłych hooków before_tool_call.requireApproval OpenClaw traktuje allow-once i allow-always jako decyzje zatwierdzające dla bieżącego wywołania i przekazuje rozstrzygniętą wartość do onResolution. Jeśli Plugin oferuje allow-always, należy udokumentować i zaimplementować dokładny zakres przyszłych wywołań, którym ufa.

Jeśli hook zwraca również params, OpenClaw stosuje te zmiany parametrów dopiero po pomyślnym zatwierdzeniu. Hook o niższym priorytecie może nadal zablokować działanie po tym, jak hook o wyższym priorytecie zażądał zatwierdzenia.

allowedDecisions ogranicza przyciski i polecenia wyświetlane użytkownikowi. Gateway odrzuca próbę rozstrzygnięcia przy użyciu decyzji, której nie oferowało żądanie.

Kierowanie monitów zatwierdzania

Monity zatwierdzania mogą być rozstrzygane w lokalnych interfejsach użytkownika lub w kanałach czatu obsługujących zatwierdzanie. Aby przekazywać monity zatwierdzania Pluginu do określonych celów czatu, należy skonfigurować approvals.plugin:

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

approvals.plugin jest niezależne od approvals.exec. Włączenie przekazywania zatwierdzeń wykonywania nie kieruje monitów zatwierdzania Pluginu, a włączenie przekazywania zatwierdzeń Pluginu nie zmienia zasad wykonywania na hoście.

Gdy monit zawiera tekst do ręcznego zatwierdzenia, należy rozstrzygnąć go przy użyciu jednej z oferowanych decyzji:

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

Pełny model przekazywania, zatwierdzanie na tym samym czacie, natywne dostarczanie do kanałów oraz reguły osób zatwierdzających specyficzne dla kanałów opisano w sekcji Zaawansowane zatwierdzenia wykonywania.

Natywne uprawnienia Codex

Natywne monity o uprawnienia Codex mogą być również przekazywane przez zatwierdzenia Pluginu, ale mają innego właściciela niż hooki tworzone przez Plugin.

• Żądania zatwierdzenia serwera aplikacji Codex są kierowane przez OpenClaw po weryfikacji przez Codex.
• Przekaźnik natywnego hooka permission_request może wysyłać żądania przez plugin.approval.request, gdy ten przekaźnik jest włączony.
• Żądania zatwierdzenia narzędzi MCP są kierowane przez zatwierdzenia Pluginu, gdy Codex oznaczy _meta.codex_approval_kind jako "mcp_tool_call".

Zachowanie specyficzne dla Codex i reguły awaryjne opisano w sekcji Środowisko wykonawcze uprzęży Codex.

Rozwiązywanie problemów

Narzędzie informuje, że zatwierdzenia Pluginu są niedostępne. Żaden interfejs zatwierdzania ani skonfigurowana trasa zatwierdzania nie przyjęły żądania. Należy podłączyć klienta obsługującego zatwierdzanie, użyć kanału obsługującego /approve na tym samym czacie albo skonfigurować approvals.plugin.

Pojawia się allow-always, ale kolejne wywołanie ponownie wyświetla monit. Ogólny przepływ zatwierdzania Pluginu nie utrwala automatycznie zaufania dla dowolnych hooków. Zaufanie należące do Pluginu należy utrwalić w Pluginie po onResolution("allow-always") albo oferować wyłącznie allow-once i deny.

/approve odrzuca decyzję. Żądanie ograniczyło allowedDecisions. Należy użyć jednej z decyzji wyświetlonych w monicie.

Monit Discord, Matrix, Slack lub Telegram jest kierowany inaczej niż zatwierdzenia wykonywania. Zatwierdzenia Pluginu i zatwierdzenia wykonywania korzystają z oddzielnych konfiguracji i mogą stosować różne mechanizmy autoryzacji. Zamiast sprawdzać wyłącznie approvals.exec, należy zweryfikować approvals.plugin oraz obsługę zatwierdzeń Pluginu przez dany kanał.

Powiązane

• Hooki Pluginu
• Tworzenie Pluginów
• Zaawansowane zatwierdzenia wykonywania
• Protokół Gateway
• Środowisko wykonawcze uprzęży Codex