Como configurar permissões e hooks no Claude Code

Resposta direta

Execute /permissions no Claude Code para ver e gerenciar regras de permissão. Para mantê-las, coloque allow, ask e deny em settings.json. Hooks usam os mesmos arquivos e executam formatação, testes ou verificações de segurança durante chamadas de ferramentas. A precedência é deny → ask → allow, portanto uma regra de allow não substitui uma regra de deny. Essas configurações controlam as ferramentas locais do seu computador. A BetterToken altera apenas Base URL, API Key e roteamento da API de modelos; ela não ignora permissões locais nem executa hooks por você.

Escolha permissões ou hooks

Necessidade	Use
Executar um comando específico sem perguntar	`permissions.allow`
Perguntar sempre antes de uma operação	`permissions.ask`
Bloquear leituras confidenciais ou comandos perigosos	`permissions.deny`
Formatar ou testar após uma alteração de arquivo	Hook `PostToolUse`
Verificar ou bloquear uma ação antes da execução	Hook `PreToolUse`
Explicar convenções da equipe ao modelo	`CLAUDE.md`, não uma regra de permissão

Escolha o escopo correto

Arquivo	Escopo	Versionar no repositório?
`~/.claude/settings.json`	Todos os projetos do usuário atual	Não
`.claude/settings.json`	Projeto e equipe atuais	Sim
`.claude/settings.local.json`	Projeto atual nesta máquina	Não

Coloque permissões, hooks e variáveis de ambiente em settings.json, não em ~/.claude.json. O segundo armazena estado do aplicativo e configurações da interface.

Configure regras mínimas de permissão

Examine as regras existentes com /permissions

No Claude Code, execute:

/permissions

A interface mostra regras allow, ask e deny com os arquivos de origem. Verifique regras de equipe ou gerenciadas antes de escolher uma configuração de usuário ou projeto.

Adicione regras restritas

Este exemplo de projeto permite testes e lint comuns, pergunta antes de cada git push e bloqueia leituras de .env:

{
  "permissions": {
    "allow": [
      "Bash(npm run lint *)",
      "Bash(npm test *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Substitua os comandos por scripts existentes no projeto. Não ative bypassPermissions apenas para remover confirmações; a documentação oficial limita esse modo a contêineres ou VMs isoladas.

Verifique em /permissions

Salve o arquivo e execute /permissions novamente. Confirme que cada regra aparece com a origem esperada e acione um caso de allow, ask e deny para verificar o comportamento.

Adicione um hook de formatação copiável

Este exemplo executa o formatador do projeto depois de o Claude Code usar Edit ou Write:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run format"
          }
        ]
      }
    ]
  }
}

Se o arquivo já tiver permissions, combine hooks no mesmo objeto JSON de nível superior. Não crie um .claude/hooks.json separado. Execute primeiro npm run format manualmente para confirmar que funciona.

Hooks de comando são executados com as permissões do usuário do sistema. Use apenas scripts revisados e nunca imprima API Keys, tokens, conteúdo de .env ou outros segredos em um hook.

Verifique o hook

Execute /hooks no Claude Code.
Abra PostToolUse e confirme que aparecem Edit|Write e npm run format.
Peça ao Claude que altere um arquivo de teste.
Confira a saída do hook e a formatação do arquivo e confirme que ele foi executado uma vez sem erros.

O Claude Code normalmente recarrega as mudanças de configuração automaticamente. Se isso não ocorrer, saia da sessão e reinicie o Claude Code.

Erros comuns

Sintoma	Causa	Correção
Regras de permissão não são aplicadas	Estão em `~/.claude.json` ou no diretório errado	Mova-as para `~/.claude/settings.json`, `.claude/settings.json` ou `.claude/settings.local.json`
Uma ação permitida continua bloqueada	Ela corresponde a uma regra deny ou gerenciada	Consulte as origens em `/permissions`; deny tem precedência sobre ask e allow
Um hook não é executado	Evento ou matcher não corresponde à ferramenta	Examine `/hooks`; `PreToolUse` executa antes, `PostToolUse` após sucesso e matchers diferenciam maiúsculas de minúsculas
O hook executa, mas o comando falha	Script, diretório de trabalho ou dependência incorreto	Execute primeiro o mesmo comando manualmente no diretório do projeto
Confirmações permanecem após conectar a BetterToken	Provedor de API e permissões locais são separados	Mantenha a Base URL da BetterToken e configure permissões restritas do Claude Code separadamente
É preciso desativar todos os hooks temporariamente	Um hook pode interferir na depuração	Adicione `"disableAllHooks": true` e remova ou defina como `false` depois da depuração

Limites da BetterToken

A BetterToken gerencia acesso à API de modelos do Claude Code, roteamento, saldo e uso. O Claude Code continua controlando:

Acesso de leitura e gravação de arquivos
Comportamento de confirmação do Bash
Quando os hooks são executados e quais scripts executam
Sandbox, MCP e regras de projeto

Para erros 401, de Base URL ou de mapeamento de modelos, consulte o guia de configuração do Claude Code. Para confirmações de comandos e automação, solucione aqui permissões e hooks.

Claude Code

Claude Desktop

Codex

Cursor

Cline

Uso de modelos

Serviço e segurança

Custos e tokens

Conceitos

Como configurar permissões e hooks no Claude Code

Resposta direta

Escolha permissões ou hooks

Escolha o escopo correto

Configure regras mínimas de permissão

Adicione um hook de formatação copiável

Verifique o hook

Erros comuns

Limites da BetterToken

Documentos relacionados

Referências

​Resposta direta

​Escolha permissões ou hooks

​Escolha o escopo correto

​Configure regras mínimas de permissão

​Adicione um hook de formatação copiável

​Verifique o hook

​Erros comuns

​Limites da BetterToken

​Documentos relacionados

​Referências

Resposta direta

Escolha permissões ou hooks

Escolha o escopo correto

Configure regras mínimas de permissão

Adicione um hook de formatação copiável

Verifique o hook

Erros comuns

Limites da BetterToken

Documentos relacionados

Referências