Configurações do Claude Code

O Claude Code oferece uma variedade de configurações para ajustar seu comportamento às suas necessidades. Você pode configurar o Claude Code executando claude config no seu terminal, ou o comando /config ao usar o REPL interativo.

​

Hierarquia de configuração

O novo arquivo settings.json é nosso mecanismo oficial para configurar o Claude Code através de configurações hierárquicas.

As configurações do usuário são definidas em ~/.claude/settings.json e se aplicam a todos os projetos.

As configurações do projeto são salvas no diretório do seu projeto em .claude/settings.json para configurações compartilhadas, e .claude/settings.local.json para configurações locais do projeto. O Claude Code irá configurar o git para ignorar .claude/settings.local.json quando ele for criado.

Para implantações empresariais do Claude Code, também suportamos configurações de política gerenciadas pela empresa. Estas têm precedência sobre as configurações do usuário e do projeto. Os administradores do sistema podem implantar políticas em /Library/Application Support/ClaudeCode/policies.json no macOS e /etc/claude-code/policies.json no Linux e Windows via WSL.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

​

Precedência de configurações

As configurações são aplicadas em ordem de precedência, com fontes posteriores sobrescrevendo fontes anteriores:

• Configurações do usuário
• Configurações compartilhadas do projeto
• Configurações locais do projeto
• Argumentos da linha de comando
• Políticas empresariais

​

Opções de configuração

O Claude Code suporta configuração global e em nível de projeto.

Para gerenciar suas configurações, use os seguintes comandos:

• Listar configurações: claude config list
• Ver uma configuração: claude config get <key>
• Alterar uma configuração: claude config set <key> <value>
• Adicionar a uma configuração (para listas): claude config add <key> <value>
• Remover de uma configuração (para listas): claude config remove <key> <value>

Por padrão, config altera sua configuração de projeto. Para gerenciar sua configuração global, use a flag --global (ou -g).

​

Configuração global

Para definir uma configuração global, use claude config set -g <key> <value>:

​

Configuração do projeto

Gerencie a configuração do projeto com claude config set <key> <value> (sem a flag -g):

Por exemplo:

# Permitir que npm test seja executado sem aprovação
claude config add allowedTools "Bash(npm test)"

# Permitir que npm test e qualquer um de seus subcomandos sejam executados sem aprovação
claude config add allowedTools "Bash(npm test:*)"

# Instruir o Claude a ignorar node_modules
claude config add ignorePatterns node_modules
claude config add ignorePatterns "node_modules/**"

​

Permissões

Você pode gerenciar as permissões de ferramentas do Claude Code com /allowed-tools. Esta UI lista todas as regras de permissão e o arquivo settings.json de onde elas são originadas.

• Regras Allow permitirão que o Claude Code use a ferramenta especificada sem aprovação manual adicional.
• Regras Deny impedirão que o Claude Code use a ferramenta especificada. Regras Deny têm precedência sobre regras Allow.

As regras de permissão usam o formato: Tool(optional-specifier).

Por exemplo, adicionar WebFetch à lista de regras allow permitiria qualquer uso da ferramenta de busca web sem exigir aprovação do usuário. Veja a lista de ferramentas disponíveis para o Claude (use o nome entre parênteses quando fornecido.)

Algumas ferramentas usam o especificador opcional para controles de permissão mais refinados. Por exemplo, uma regra allow com WebFetch(domain:example.com) permitiria buscas em example.com mas não em outras URLs.

Regras Bash podem ser correspondências exatas como Bash(npm run build), ou correspondências de prefixo quando terminam com :* como Bash(npm run test:*)

Regras Read() e Edit() seguem a especificação gitignore. Os padrões são resolvidos relativamente ao diretório contendo .claude/settings.json. Para referenciar um caminho absoluto, use //. Para um caminho relativo ao seu diretório home, use ~/. Por exemplo Read(//tmp/build_cache) ou Edit(~/.zshrc). O Claude também fará uma tentativa de aplicar regras Read e Edit a outras ferramentas relacionadas a arquivos como Grep, Glob e LS.

Os nomes das ferramentas MCP seguem o formato: mcp__server_name__tool_name onde:

• server_name é o nome do servidor MCP conforme configurado no Claude Code
• tool_name é a ferramenta específica fornecida por esse servidor

Mais exemplos:

​

Opções de permissão do auto-atualizador

Quando o Claude Code detecta que não tem permissões suficientes para escrever no seu diretório npm prefix global (necessário para atualizações automáticas), você verá um aviso que aponta para esta página de documentação. Para soluções detalhadas para problemas do auto-atualizador, veja o guia de solução de problemas.

​

Recomendado: Criar um novo npm prefix gravável pelo usuário

# Primeiro, salve uma lista dos seus pacotes globais existentes para migração posterior
npm list -g --depth=0 > ~/npm-global-packages.txt

# Crie um diretório para seus pacotes globais
mkdir -p ~/.npm-global

# Configure o npm para usar o novo caminho do diretório
npm config set prefix ~/.npm-global

# Nota: Substitua ~/.bashrc por ~/.zshrc, ~/.profile, ou outro arquivo apropriado para seu shell
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# Aplique a nova configuração PATH
source ~/.bashrc

# Agora reinstale o Claude Code no novo local
npm install -g @anthropic-ai/claude-code

# Opcional: Reinstale seus pacotes globais anteriores no novo local
# Olhe em ~/npm-global-packages.txt e instale os pacotes que você quer manter
# npm install -g package1 package2 package3...

Por que recomendamos esta opção:

• Evita modificar permissões de diretório do sistema
• Cria um local limpo e dedicado para seus pacotes npm globais
• Segue as melhores práticas de segurança

Como o Claude Code está em desenvolvimento ativo, recomendamos configurar atualizações automáticas usando a opção recomendada acima.

​

Desativando o auto-atualizador

Se você preferir desativar o auto-atualizador em vez de corrigir permissões, você pode usar:

claude config set -g autoUpdaterStatus disabled

​

Otimize sua configuração do terminal

O Claude Code funciona melhor quando seu terminal está configurado adequadamente. Siga estas diretrizes para otimizar sua experiência.

Shells suportados:

• Bash
• Zsh
• Fish

​

Temas e aparência

O Claude não pode controlar o tema do seu terminal. Isso é controlado pelo seu aplicativo de terminal. Você pode combinar o tema do Claude Code com seu terminal durante a integração ou a qualquer momento via comando /config

​

Quebras de linha

Você tem várias opções para inserir quebras de linha no Claude Code:

• Escape rápido: Digite \ seguido de Enter para criar uma nova linha
• Atalho de teclado: Pressione Option+Enter (Meta+Enter) com a configuração adequada

Para configurar Option+Enter no seu terminal:

Para Mac Terminal.app:

1. Abra Configurações → Perfis → Teclado
2. Marque “Usar Option como tecla Meta”

Para iTerm2 e terminal VSCode:

1. Abra Configurações → Perfis → Teclas
2. Em Geral, defina a tecla Option esquerda/direita para “Esc+”

Dica para usuários de iTerm2 e VSCode: Execute /terminal-setup dentro do Claude Code para configurar automaticamente Shift+Enter como uma alternativa mais intuitiva.

​

Configuração de notificações

Nunca perca quando o Claude completa uma tarefa com a configuração adequada de notificações:

​

Notificações do sino do terminal

Ative alertas sonoros quando as tarefas forem concluídas:

claude config set --global preferredNotifChannel terminal_bell

Para usuários macOS: Não se esqueça de ativar as permissões de notificação em Configurações do Sistema → Notificações → [Seu App de Terminal].

​

Notificações do sistema iTerm 2

Para alertas do iTerm 2 quando as tarefas forem concluídas:

1. Abra Preferências do iTerm 2
2. Navegue até Perfis → Terminal
3. Ative “Silenciar sino” e “Enviar notificação quando ocioso”
4. Defina seu atraso de notificação preferido

Observe que essas notificações são específicas do iTerm 2 e não estão disponíveis no Terminal padrão do macOS.

​

Lidando com entradas grandes

Ao trabalhar com código extenso ou instruções longas:

• Evite colar diretamente: O Claude Code pode ter dificuldades com conteúdo colado muito longo
• Use fluxos de trabalho baseados em arquivo: Escreva conteúdo em um arquivo e peça ao Claude para lê-lo
• Esteja ciente das limitações do VS Code: O terminal do VS Code é particularmente propenso a truncar colagens longas

​

Modo Vim

O Claude Code suporta um subconjunto de atalhos do Vim que podem ser ativados com /vim ou configurados via /config.

O subconjunto suportado inclui:

• Mudança de modo: Esc (para NORMAL), i/I, a/A, o/O (para INSERT)
• Navegação: h/j/k/l, w/e/b, 0/$/^, gg/G
• Edição: x, dw/de/db/dd/D, cw/ce/cb/cc/C, . (repetir)

​

Variáveis de ambiente

O Claude Code suporta as seguintes variáveis de ambiente para controlar seu comportamento: