Verzoeken om Plugin-machtigingen

Aanvragen om Plugin-machtigingen laten Plugincode een toolaanroep of een bewerking van de Plugin onderbreken totdat een gebruiker deze goedkeurt of weigert. Ze gebruiken de Gateway- plugin.approval.*-stroom en dezelfde goedkeuringsinterfaces die goedkeuringsknoppen in chats en /approve-opdrachten afhandelen.

Gebruik aanvragen om Plugin-machtigingen voor machtigingen van plugins/apps. Ze vervangen geen goedkeuringen voor uitvoering op de host, optionele tooltoelatingslijsten of de ingebouwde machtigingscontrole van Codex.

Kies de juiste poort

Kies de poort die overeenkomt met het benodigde beslismoment:

Optionele tools vormen een poort tijdens de detectie. Aanvragen om Plugin-machtigingen vormen een poort per aanroep. Gebruik beide wanneer een gevoelige tool expliciete aanmelding moet vereisen voordat het model deze kan zien en goedkeuring voordat de actie wordt uitgevoerd.

Vraag goedkeuring vóór een toolaanroep

De meeste door een Plugin gemaakte prompts moeten beginnen in een before_tool_call-hook. De hook wordt uitgevoerd nadat het model een tool selecteert en voordat OpenClaw deze uitvoert:

 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}`);          },        },      };    });  },});

Schrijf de prompttekst voor de persoon die de actie zal goedkeuren:

• Houd title kort en actiegericht; de Gateway beperkt deze tot 80 tekens.
• Houd description specifiek en afgebakend; de Gateway beperkt deze tot 512 tekens.
• Vermeld de actie, het doel en het risico. Vermeld geen geheimen, tokens of privépayloads die niet in interfaces voor chatgoedkeuring mogen verschijnen.
• severity wordt standaard ingesteld op "warning" wanneer het wordt weggelaten. Gebruik "critical" alleen voor acties waarbij een verkeerde beslissing productieschade of gegevensverlies kan veroorzaken.
• allowedDecisions wordt standaard ingesteld op ["allow-once", "allow-always", "deny"] wanneer het wordt weggelaten. Geef ["allow-once", "deny"] door wanneer permanent vertrouwen onveilig is voor die actie.
• timeoutMs wordt standaard ingesteld op 120000 (2 minuten) en is begrensd op 600000 (10 minuten), ongeacht de aangevraagde waarde.

Beslissingsgedrag

OpenClaw maakt een openstaande goedkeuring met een plugin:-ID, levert deze aan de beschikbare goedkeuringsinterfaces en wacht op een beslissing.

Alleen de exacte door het verzoek toegestane beslissingen allow-once en allow-always staan uitvoering toe. Onbekende, onjuist gevormde, niet-overeenkomende, ontbrekende en verlopen beslissingen worden standaard geweigerd. Het verouderde veld timeoutBehavior blijft geaccepteerd voor compatibiliteit met plugins, maar is afgeschaft en wordt genegeerd; stel het niet in nieuwe hooks in.

allow-always is alleen permanent wanneer de verzoekende Plugin of runtime die persistentie implementeert. Voor gewone before_tool_call.requireApproval-hooks behandelt OpenClaw allow-once en allow-always als goedkeuringsbeslissingen voor de huidige aanroep en geeft het de afgehandelde waarde door aan onResolution. Als je Plugin allow-always aanbiedt, documenteer en implementeer dan exact welke toekomstige aanroepen worden vertrouwd.

Als de hook ook params retourneert, past OpenClaw die parameterwijzigingen pas toe nadat de goedkeuring is geslaagd. Een hook met lagere prioriteit kan nog steeds blokkeren nadat een hook met hogere prioriteit om goedkeuring heeft gevraagd.

allowedDecisions beperkt de knoppen en opdrachten die aan de gebruiker worden getoond. De Gateway weigert een afhandelingspoging voor elke beslissing die niet door het verzoek werd aangeboden.

Routeer goedkeuringsprompts

Goedkeuringsprompts kunnen worden afgehandeld in lokale gebruikersinterfaces of in chatkanalen die goedkeuringsafhandeling ondersteunen. Configureer approvals.plugin om prompts voor Plugin-goedkeuring door te sturen naar expliciete chatdoelen:

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

approvals.plugin staat los van approvals.exec. Het inschakelen van doorsturen van uitvoeringsgoedkeuringen routeert geen prompts voor Plugin-goedkeuring, en het inschakelen van doorsturen van Plugin-goedkeuringen wijzigt het uitvoeringsbeleid van de host niet.

Wanneer een prompt handmatige goedkeuringstekst bevat, handel je deze af met een van de aangeboden beslissingen:

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

Zie Geavanceerde uitvoeringsgoedkeuringen voor het volledige doorstuurmodel, goedkeuringsgedrag binnen dezelfde chat, ingebouwde kanaallevering en kanaalspecifieke regels voor goedkeurders.

Ingebouwde Codex-machtigingen

Ingebouwde Codex-machtigingsprompts kunnen ook via Plugin-goedkeuringen worden verzonden, maar ze hebben een andere eigenaar dan door plugins gemaakte hooks.

• Goedkeuringsaanvragen van de Codex-app-server worden na Codex-controle via OpenClaw gerouteerd.
• De relay van de ingebouwde hook permission_request kan via plugin.approval.request toestemming vragen wanneer die relay is ingeschakeld.
• MCP-goedkeuringsverzoeken voor tools worden via Plugin-goedkeuringen gerouteerd wanneer Codex _meta.codex_approval_kind markeert als "mcp_tool_call".

Zie Codex-harnessruntime voor het Codex-specifieke gedrag en de terugvalregels.

Problemen oplossen

De tool meldt dat Plugin-goedkeuringen niet beschikbaar zijn. Geen goedkeuringsinterface of geconfigureerde goedkeuringsroute heeft het verzoek geaccepteerd. Verbind een client die goedkeuringen ondersteunt, gebruik een kanaal dat /approve binnen dezelfde chat ondersteunt of configureer approvals.plugin.

allow-always verschijnt, maar de volgende aanroep vraagt opnieuw om toestemming. De algemene Plugin-goedkeuringsstroom bewaart vertrouwen voor willekeurige hooks niet automatisch. Sla vertrouwen dat door de Plugin wordt beheerd op in je Plugin na onResolution("allow-always"), of bied alleen allow-once en deny aan.

/approve weigert de beslissing. Het verzoek beperkte allowedDecisions. Gebruik een van de beslissingen die in de prompt worden weergegeven.

Een prompt van Discord, Matrix, Slack of Telegram wordt anders gerouteerd dan uitvoeringsgoedkeuringen. Plugin-goedkeuringen en uitvoeringsgoedkeuringen gebruiken afzonderlijke configuraties en kunnen verschillende autorisatiecontroles gebruiken. Controleer approvals.plugin en de ondersteuning voor Plugin-goedkeuringen van het kanaal in plaats van alleen approvals.exec te controleren.

Gerelateerd

• Plugin-hooks
• Plugins bouwen
• Geavanceerde uitvoeringsgoedkeuringen
• Gateway-protocol
• Codex-harnessruntime