Solicitudes de permisos de Plugins

Las solicitudes de permisos de Plugin permiten que el código de un plugin pause una llamada a una herramienta o una operación propiedad del plugin hasta que un usuario la apruebe o deniegue. Utilizan el flujo de Gateway plugin.approval.* y las mismas superficies de interfaz de aprobación que gestionan los botones de aprobación del chat y los comandos /approve.

Utilice las solicitudes de permisos de Plugin para los permisos de plugins y aplicaciones. No sustituyen las aprobaciones de ejecución del host, las listas opcionales de herramientas permitidas ni la revisión de permisos nativa de Codex.

Elegir el control adecuado

Elija el control que corresponda al punto de decisión necesario:

Las herramientas opcionales constituyen un control durante el descubrimiento. Las solicitudes de permisos de Plugin constituyen un control por llamada. Utilice ambos cuando una herramienta sensible deba requerir una habilitación explícita antes de que el modelo pueda verla y una aprobación antes de ejecutar la acción.

Solicitar aprobación antes de una llamada a una herramienta

La mayoría de las solicitudes creadas por plugins deben iniciarse en un hook before_tool_call. El hook se ejecuta después de que el modelo selecciona una herramienta y antes de que OpenClaw la ejecute:

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

Redacte el texto de la solicitud para la persona que aprobará la acción:

• Mantenga title breve y centrado en la acción; el Gateway lo limita a 80 caracteres.
• Mantenga description específico y acotado; el Gateway lo limita a 512 caracteres.
• Incluya la acción, el objetivo y el riesgo. No incluya secretos, tokens ni cargas privadas que no deban aparecer en las superficies de aprobación del chat.
• severity utiliza "warning" de forma predeterminada cuando se omite. Utilice "critical" solo para acciones en las que una decisión equivocada pueda causar daños en producción o pérdida de datos.
• allowedDecisions utiliza ["allow-once", "allow-always", "deny"] de forma predeterminada cuando se omite. Pase ["allow-once", "deny"] cuando la confianza persistente no sea segura para esa acción.
• timeoutMs utiliza de forma predeterminada 120000 (2 minutos) y tiene un límite de 600000 (10 minutos), independientemente del valor solicitado.

Comportamiento de las decisiones

OpenClaw crea una aprobación pendiente con un ID plugin:, la entrega a las superficies de aprobación disponibles y espera una decisión.

Solo las decisiones exactas allow-once y allow-always permitidas por la solicitud autorizan la ejecución. Las decisiones desconocidas, mal formadas, no coincidentes, ausentes o que hayan agotado el tiempo de espera se rechazan de forma segura. El campo heredado timeoutBehavior sigue aceptándose por compatibilidad con plugins, pero está obsoleto y se ignora; no lo establezca en hooks nuevos.

allow-always solo es duradero cuando el plugin o el entorno de ejecución solicitante implementa esa persistencia. Para los hooks before_tool_call.requireApproval ordinarios, OpenClaw trata allow-once y allow-always como decisiones de aprobación para la llamada actual y pasa el valor resuelto a onResolution. Si el plugin ofrece allow-always, documente e implemente exactamente qué llamadas futuras considera de confianza.

Si el hook también devuelve params, OpenClaw aplica esos cambios de parámetros solo después de que la aprobación se complete correctamente. Un hook de menor prioridad aún puede bloquear la acción después de que uno de mayor prioridad haya solicitado aprobación.

allowedDecisions limita los botones y comandos que se muestran al usuario. El Gateway rechaza los intentos de resolución con cualquier decisión que la solicitud no haya ofrecido.

Encaminar las solicitudes de aprobación

Las solicitudes de aprobación pueden resolverse en superficies de interfaz locales o en canales de chat compatibles con la gestión de aprobaciones. Para reenviar solicitudes de aprobación de plugins a destinos de chat explícitos, configure approvals.plugin:

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

approvals.plugin es independiente de approvals.exec. Habilitar el reenvío de aprobaciones de ejecución no encamina las solicitudes de aprobación de plugins, y habilitar el reenvío de aprobaciones de plugins no cambia la política de ejecución del host.

Cuando una solicitud incluya texto de aprobación manual, resuélvala con una de las decisiones ofrecidas:

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

Consulte Aprobaciones de ejecución avanzadas para conocer el modelo completo de reenvío, el comportamiento de aprobación en el mismo chat, la entrega nativa del canal y las reglas de aprobación específicas de cada canal.

Permisos nativos de Codex

Las solicitudes de permisos nativas de Codex también pueden transmitirse mediante aprobaciones de plugins, pero tienen una propiedad diferente de la de los hooks creados por plugins.

• Las solicitudes de aprobación del servidor de aplicaciones de Codex se encaminan mediante OpenClaw después de la revisión de Codex.
• El relé del hook nativo permission_request puede solicitar aprobación mediante plugin.approval.request cuando dicho relé está habilitado.
• Las solicitudes de aprobación de herramientas MCP se encaminan mediante aprobaciones de plugins cuando Codex marca _meta.codex_approval_kind como "mcp_tool_call".

Consulte Entorno de ejecución del arnés de Codex para conocer el comportamiento específico de Codex y las reglas de respaldo.

Solución de problemas

La herramienta indica que las aprobaciones de plugins no están disponibles. Ninguna interfaz de aprobación ni ruta de aprobación configurada aceptó la solicitud. Conecte un cliente capaz de gestionar aprobaciones, utilice un canal compatible con /approve en el mismo chat o configure approvals.plugin.

Aparece allow-always, pero la siguiente llamada vuelve a solicitar aprobación. El flujo genérico de aprobación de plugins no conserva automáticamente la confianza para hooks arbitrarios. Conserve la confianza propiedad del plugin en el propio plugin después de onResolution("allow-always"), u ofrezca únicamente allow-once y deny.

/approve rechaza la decisión. La solicitud restringió allowedDecisions. Utilice una de las decisiones mostradas en la solicitud.

Una solicitud de Discord, Matrix, Slack o Telegram se encamina de forma diferente a las aprobaciones de ejecución. Las aprobaciones de plugins y las aprobaciones de ejecución utilizan configuraciones distintas y pueden aplicar comprobaciones de autorización diferentes. Verifique approvals.plugin y la compatibilidad del canal con las aprobaciones de plugins, en lugar de comprobar únicamente approvals.exec.

Contenido relacionado

• Hooks de plugins
• Creación de plugins
• Aprobaciones de ejecución avanzadas
• Protocolo del Gateway
• Entorno de ejecución del arnés de Codex