Solicitações de permissão do Plugin

As solicitações de permissão de plugins permitem que o código do plugin pause uma chamada de ferramenta ou uma operação pertencente ao plugin até que um usuário a aprove ou negue. Elas usam o fluxo plugin.approval.* do Gateway e as mesmas superfícies de interface de aprovação que processam botões de aprovação no chat e comandos /approve.

Use solicitações de permissão de plugins para permissões de plugins/aplicativos. Elas não substituem aprovações de execução no host, listas de permissões opcionais de ferramentas nem a análise de permissões nativa do Codex.

Escolha o controle correto

Escolha o controle correspondente ao ponto de decisão necessário:

As ferramentas opcionais são um controle no momento da descoberta. As solicitações de permissão de plugins são um controle por chamada. Use ambos quando uma ferramenta sensível precisar de consentimento explícito antes de o modelo poder vê-la e de aprovação antes de a ação ser executada.

Solicite aprovação antes de uma chamada de ferramenta

A maioria das solicitações criadas por plugins deve começar em um hook before_tool_call. O hook é executado após o modelo selecionar uma ferramenta e antes de o OpenClaw executá-la:

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

Escreva o texto da solicitação para a pessoa que aprovará a ação:

• Mantenha title curto e focado na ação; o Gateway limita seu tamanho a 80 caracteres.
• Mantenha description específico e delimitado; o Gateway limita seu tamanho a 512 caracteres.
• Inclua a ação, o destino e o risco. Não inclua segredos, tokens nem cargas privadas que não devam aparecer nas superfícies de aprovação do chat.
• Quando omitido, severity usa "warning" como padrão. Use "critical" somente para ações nas quais uma decisão incorreta possa causar danos à produção ou perda de dados.
• Quando omitido, allowedDecisions usa ["allow-once", "allow-always", "deny"] como padrão. Passe ["allow-once", "deny"] quando a confiança persistente não for segura para essa ação.
• timeoutMs usa 120000 (2 minutos) como padrão e é limitado a 600000 (10 minutos), independentemente do valor solicitado.

Comportamento das decisões

O OpenClaw cria uma aprovação pendente com um ID plugin:, envia-a às superfícies de aprovação disponíveis e aguarda uma decisão.

Somente as decisões exatas allow-once e allow-always permitidas pela solicitação autorizam a execução. Decisões desconhecidas, malformadas, incompatíveis, ausentes ou com tempo limite esgotado causam uma falha fechada. O campo legado timeoutBehavior continua sendo aceito para compatibilidade com plugins, mas está obsoleto e é ignorado; não o defina em novos hooks.

allow-always só é durável quando o plugin ou runtime solicitante implementa essa persistência. Para hooks comuns before_tool_call.requireApproval, o OpenClaw trata allow-once e allow-always como decisões de aprovação para a chamada atual e repassa o valor resolvido para onResolution. Se o seu plugin oferecer allow-always, documente e implemente exatamente quais chamadas futuras ele considera confiáveis.

Se o hook também retornar params, o OpenClaw aplicará essas alterações de parâmetros somente depois que a aprovação for bem-sucedida. Um hook de prioridade mais baixa ainda poderá bloquear a ação após um hook de prioridade mais alta solicitar aprovação.

allowedDecisions limita os botões e comandos exibidos ao usuário. O Gateway rejeita qualquer tentativa de resolução com uma decisão que não tenha sido oferecida pela solicitação.

Encaminhe solicitações de aprovação

As solicitações de aprovação podem ser resolvidas em superfícies de interface locais ou em canais de chat compatíveis com o tratamento de aprovações. Para encaminhar solicitações de aprovação de plugins a destinos explícitos de chat, configure approvals.plugin:

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

approvals.plugin é independente de approvals.exec. Habilitar o encaminhamento de aprovações de execução não encaminha solicitações de aprovação de plugins, e habilitar o encaminhamento de aprovações de plugins não altera a política de execução do host.

Quando uma solicitação incluir texto de aprovação manual, resolva-a com uma das decisões oferecidas:

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

Consulte Aprovações avançadas de execução para ver o modelo completo de encaminhamento, o comportamento de aprovação no mesmo chat, a entrega nativa por canais e as regras de aprovadores específicas de cada canal.

Permissões nativas do Codex

As solicitações de permissão nativas do Codex também podem passar por aprovações de plugins, mas têm uma propriedade diferente dos hooks criados por plugins.

• As solicitações de aprovação do servidor de aplicativos do Codex são encaminhadas pelo OpenClaw após a análise do Codex.
• O retransmissor do hook nativo permission_request pode solicitar autorização por meio de plugin.approval.request quando esse retransmissor está habilitado.
• As solicitações de aprovação de ferramentas MCP são encaminhadas pelas aprovações de plugins quando o Codex marca _meta.codex_approval_kind como "mcp_tool_call".

Consulte Runtime do harness do Codex para ver o comportamento específico do Codex e as regras de fallback.

Solução de problemas

A ferramenta informa que as aprovações de plugins não estão disponíveis. Nenhuma interface de aprovação nem rota de aprovação configurada aceitou a solicitação. Conecte um cliente compatível com aprovações, use um canal compatível com /approve no mesmo chat ou configure approvals.plugin.

allow-always aparece, mas a chamada seguinte solicita aprovação novamente. O fluxo genérico de aprovação de plugins não persiste automaticamente a confiança para hooks arbitrários. Persista no seu plugin a confiança pertencente ao plugin após onResolution("allow-always") ou ofereça somente allow-once e deny.

/approve rejeita a decisão. A solicitação restringiu allowedDecisions. Use uma das decisões exibidas na solicitação.

Uma solicitação do Discord, Matrix, Slack ou Telegram é encaminhada de modo diferente das aprovações de execução. As aprovações de plugins e as aprovações de execução usam configurações separadas e podem usar verificações de autorização diferentes. Verifique approvals.plugin e a compatibilidade do canal com aprovações de plugins, em vez de verificar somente approvals.exec.

Relacionados

• Hooks de plugins
• Criação de plugins
• Aprovações avançadas de execução
• Protocolo do Gateway
• Runtime do harness do Codex