Demandes d’autorisation de Plugin

Les demandes d'autorisation de Plugin permettent au code du Plugin de suspendre un appel d'outil ou une opération appartenant au Plugin jusqu'à ce qu'un utilisateur l'approuve ou le refuse. Elles utilisent le flux Gateway plugin.approval.* et les mêmes surfaces d'interface d'approbation qui gèrent les boutons d'approbation dans le chat et les commandes /approve.

Utilisez les demandes d'autorisation de Plugin pour les autorisations de Plugin/application. Elles ne remplacent pas les approbations d'exécution de l'hôte, les listes d'autorisation d'outils facultatives ni la revue d'autorisation native de Codex.

Choisir le bon point de contrôle

Choisissez le point de contrôle qui correspond au point de décision dont vous avez besoin :

Les outils facultatifs sont un point de contrôle au moment de la découverte. Les demandes d'autorisation de Plugin sont un point de contrôle par appel. Utilisez les deux lorsqu'un outil sensible doit nécessiter une adhésion explicite avant que le modèle puisse le voir et une approbation avant l'exécution de l'action.

Demander l'approbation avant un appel d'outil

La plupart des invites rédigées par un Plugin doivent commencer dans un hook before_tool_call. Le hook s'exécute après que le modèle a sélectionné un outil et avant qu'OpenClaw ne l'exécute :

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

Rédigez le texte de l'invite pour la personne qui approuvera l'action :

• Gardez title court et centré sur l'action. Le Gateway accepte jusqu'à 80 caractères.
• Gardez description précise et bornée. Le Gateway accepte jusqu'à 256 caractères.
• Incluez l'action, la cible et le risque. N'incluez pas de secrets, de jetons ni de charges utiles privées qui ne doivent pas apparaître dans les surfaces d'approbation du chat.
• Utilisez severity: "critical" uniquement pour les actions où une mauvaise décision pourrait causer des dommages en production ou une perte de données.
• Utilisez allowedDecisions: ["allow-once", "deny"] lorsque la confiance persistante est dangereuse pour cette action.

Comportement des décisions

OpenClaw crée une approbation en attente avec un ID plugin:, la transmet aux surfaces d'approbation disponibles et attend une décision.

allow-always n'est durable que lorsque le Plugin ou le runtime demandeur implémente cette persistance. Pour les hooks ordinaires before_tool_call.requireApproval, OpenClaw traite allow-once et allow-always comme des décisions d'approbation pour l'appel actuel et transmet la valeur résolue à onResolution. Si votre Plugin propose allow-always, documentez et implémentez exactement les futurs appels auxquels il accorde sa confiance.

Si le hook renvoie aussi params, OpenClaw applique ces changements de paramètres uniquement après la réussite de l'approbation. Un hook de priorité inférieure peut toujours bloquer après qu'un hook de priorité supérieure a demandé l'approbation.

allowedDecisions limite les boutons et les commandes affichés à l'utilisateur. Le Gateway rejette toute tentative de résolution pour une décision que la demande ne proposait pas.

Acheminer les invites d'approbation

Les invites d'approbation peuvent être résolues dans des surfaces d'interface locales ou dans des canaux de chat qui prennent en charge la gestion des approbations. Pour transférer les invites d'approbation de Plugin vers des cibles de chat explicites, configurez approvals.plugin :

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

approvals.plugin est indépendant de approvals.exec. Activer le transfert des approbations exec n'achemine pas les invites d'approbation de Plugin, et activer le transfert des approbations de Plugin ne modifie pas la politique d'exécution de l'hôte.

Lorsqu'une invite inclut un texte d'approbation manuel, résolvez-la avec l'une des décisions proposées :

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

Consultez Approbations exec avancées pour le modèle complet de transfert, le comportement d'approbation dans le même chat, la livraison native par canal et les règles d'approbateur propres à chaque canal.

Autorisations natives Codex

Les invites d'autorisation natives Codex peuvent aussi passer par les approbations de Plugin, mais leur propriété diffère de celle des hooks rédigés par un Plugin.

• Les demandes d'approbation du serveur d'application Codex sont acheminées via OpenClaw après la revue Codex.
• Le relais de hook natif permission_request peut demander via plugin.approval.request lorsque ce relais est activé.
• Les sollicitations d'approbation d'outil MCP sont acheminées via les approbations de Plugin lorsque Codex marque _meta.codex_approval_kind comme "mcp_tool_call".

Consultez Runtime du harnais Codex pour le comportement propre à Codex et les règles de repli.

Dépannage

L'outil indique que les approbations de Plugin ne sont pas disponibles. Aucune interface d'approbation ou route d'approbation configurée n'a accepté la demande. Connectez un client capable d'approuver, utilisez un canal qui prend en charge /approve dans le même chat, ou configurez approvals.plugin.

allow-always apparaît, mais l'appel suivant redemande une approbation. Le flux générique d'approbation de Plugin ne persiste pas automatiquement la confiance pour des hooks arbitraires. Persistez la confiance appartenant au Plugin dans votre Plugin après onResolution("allow-always"), ou proposez uniquement allow-once et deny.

/approve rejette la décision. La demande a restreint allowedDecisions. Utilisez l'une des décisions affichées dans l'invite.

Une invite Slack, Discord, Telegram ou Matrix est acheminée différemment des approbations exec. Les approbations de Plugin et les approbations exec utilisent une configuration séparée et peuvent utiliser des vérifications d'autorisation différentes. Vérifiez approvals.plugin et la prise en charge des approbations de Plugin par le canal au lieu de vérifier seulement approvals.exec.

Connexe

• Hooks de Plugin
• Créer des Plugins
• Approbations exec avancées
• Protocole Gateway
• Runtime du harnais Codex