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

1. Execute /hooks no Claude Code.
2. Abra PostToolUse e confirme que aparecem Edit|Write e npm run format.
3. Peça ao Claude que altere um arquivo de teste.
4. 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.

Documentos relacionados

• Configuração do Claude Code com a BetterToken
• O que é CLAUDE.md no Claude Code?
• Por que o Claude Code usa muitos tokens
• MCP do Claude Code versus API Key e Base URL

Referências

• Permissões do Claude Code
• Guia de hooks do Claude Code
• Referência de hooks do Claude Code
• Depurar a configuração do Claude Code