Demandes d’autorisation des Plugins

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

Utilisez les demandes d’autorisation des Plugins pour les autorisations des Plugins et des applications. Elles ne remplacent pas les approbations d’exécution de l’hôte, les listes d’autorisation facultatives d’outils ni l’examen natif des autorisations de Codex.

Choisir le contrôle approprié

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

Les outils facultatifs constituent un contrôle au moment de la découverte. Les demandes d’autorisation des Plugins constituent un contrôle à chaque appel. Utilisez les deux lorsqu’un outil sensible doit nécessiter une adhésion explicite avant que le modèle puisse le voir, puis une approbation avant l’exécution de l’action.

Demander une approbation avant un appel d’outil

La plupart des invites créées par des Plugins 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,          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 le limite à 80 caractères.
• Gardez description précis et bien délimité ; le Gateway le limite à 512 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 interfaces d’approbation des conversations.
• severity vaut par défaut "warning" lorsqu’il est omis. Utilisez "critical" uniquement pour les actions où une mauvaise décision pourrait endommager la production ou entraîner une perte de données.
• allowedDecisions vaut par défaut ["allow-once", "allow-always", "deny"] lorsqu’il est omis. Transmettez ["allow-once", "deny"] lorsqu’une confiance persistante n’est pas sûre pour cette action.
• timeoutMs vaut par défaut 120000 (2 minutes) et est plafonné à 600000 (10 minutes), quelle que soit la valeur demandée.

Comportement des décisions

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

Seules les décisions exactes allow-once et allow-always autorisées par la demande permettent l’exécution. Les décisions inconnues, mal formées, non concordantes, manquantes ou arrivées après expiration du délai entraînent un refus par défaut. L’ancien champ timeoutBehavior reste accepté pour assurer la compatibilité des Plugins, mais il est obsolète et ignoré ; ne le définissez pas dans de nouveaux hooks.

allow-always n’est persistant que lorsque le Plugin ou l’environnement d’exécution demandeur met en œuvre cette persistance. Pour les hooks before_tool_call.requireApproval ordinaires, 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 précisément les futurs appels auxquels cette décision accorde sa confiance.

Si le hook renvoie également params, OpenClaw n’applique ces modifications de paramètres qu’après la réussite de l’approbation. Un hook de priorité inférieure peut encore bloquer l’appel après qu’un hook de priorité supérieure a demandé une approbation.

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

Acheminer les invites d’approbation

Les invites d’approbation peuvent être résolues dans des interfaces locales ou dans des canaux de conversation prenant en charge la gestion des approbations. Pour transférer les invites d’approbation de Plugins vers des cibles de conversation 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. L’activation du transfert des approbations d’exécution n’achemine pas les invites d’approbation des Plugins, et l’activation du transfert des approbations des Plugins ne modifie pas la politique d’exécution de l’hôte.

Lorsqu’une invite contient un texte d’approbation manuelle, résolvez-la avec l’une des décisions proposées :

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

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

Autorisations natives de Codex

Les invites d’autorisation natives de Codex peuvent également transiter par les approbations de Plugins, mais leur responsabilité diffère de celle des hooks créés par les Plugins.

• Les demandes d’approbation du serveur d’applications de Codex sont acheminées via OpenClaw après l’examen de Codex.
• Le relais du hook natif permission_request peut effectuer une demande via plugin.approval.request lorsque ce relais est activé.
• Les sollicitations d’approbation d’outils MCP sont acheminées via les approbations de Plugins lorsque Codex définit _meta.codex_approval_kind sur "mcp_tool_call".

Consultez Environnement d’exécution du harnais Codex pour le comportement propre à Codex et les règles de repli.

Résolution des problèmes

L’outil indique que les approbations de Plugins ne sont pas disponibles. Aucune interface d’approbation ni aucun canal d’approbation configuré n’a accepté la demande. Connectez un client capable de gérer les approbations, utilisez un canal prenant en charge /approve dans la même conversation ou configurez approvals.plugin.

allow-always apparaît, mais l’appel suivant demande à nouveau une approbation. Le flux générique d’approbation des Plugins ne conserve pas automatiquement la confiance pour les hooks arbitraires. Conservez la confiance appartenant au Plugin dans votre Plugin après onResolution("allow-always"), ou ne proposez que 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 Discord, Matrix, Slack ou Telegram est acheminée différemment des approbations d’exécution. Les approbations des Plugins et les approbations d’exécution utilisent des configurations distinctes et peuvent appliquer des contrôles d’autorisation différents. Vérifiez approvals.plugin et la prise en charge des approbations de Plugins par le canal au lieu de vérifier uniquement approvals.exec.

Pages connexes

• Hooks de Plugins
• Création de Plugins
• Approbations d’exécution avancées
• Protocole du Gateway
• Environnement d’exécution du harnais Codex