Configurações do Claude Code

O Claude Code oferece uma variedade de configurações para ajustar seu comportamento de acordo com suas necessidades. Você pode configurar o Claude Code executando o comando /config ao usar o REPL interativo.

​

Arquivos de configurações

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

• Configurações do usuário são definidas em ~/.claude/settings.json e se aplicam a todos os projetos.
• 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 configurará o git para ignorar .claude/settings.local.json quando for criado.
• Para implantações empresariais do Claude Code, também suportamos configurações de políticas gerenciadas pela empresa. Estas têm precedência sobre as configurações de usuário e projeto. Os administradores de 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"
  }
}

​

Configurações disponíveis

O settings.json suporta várias opções:

​

Precedência de configurações

As configurações são aplicadas em ordem de precedência:

1. Políticas empresariais
2. Argumentos de linha de comando
3. Configurações locais do projeto
4. Configurações compartilhadas do projeto
5. Configurações do usuário

​

Permissões

Você pode visualizar e gerenciar as permissões de ferramentas do Claude Code com /permissions. Esta interface lista todas as regras de permissão e o arquivo settings.json de onde são originadas.

• As regras de Permitir permitirão que o Claude Code use a ferramenta especificada sem aprovação manual adicional.
• As regras de Negar impedirão que o Claude Code use a ferramenta especificada. Regras de negação têm precedência sobre regras de permissão.

As regras de permissão usam o formato: Ferramenta(especificador-opcional)

Uma regra que é apenas o nome da ferramenta corresponde a qualquer uso dessa ferramenta. Por exemplo, adicionar Bash à lista de regras de permissão permitiria que o Claude Code usasse a ferramenta Bash sem exigir aprovação do usuário. Veja a lista de ferramentas disponíveis para o Claude.

​

Regras de permissão específicas para ferramentas

Algumas ferramentas usam o especificador opcional para controles de permissão mais granulares. Por exemplo, uma regra de permissão com Bash(git diff:*) permitiria comandos Bash que começam com git diff. As seguintes ferramentas suportam regras de permissão com especificadores:

​

Bash

• Bash(npm run build) Corresponde ao comando Bash exato npm run build
• Bash(npm run test:*) Corresponde a comandos Bash que começam com npm run test.

​

Read & Edit

As regras de Edit se aplicam a todas as ferramentas integradas que editam arquivos. O Claude fará uma tentativa de melhor esforço para aplicar regras de Read a todas as ferramentas integradas que leem arquivos como Grep, Glob e LS.

As regras de Read & Edit seguem a especificação gitignore. Os padrões são resolvidos relativamente ao diretório que contém .claude/settings.json. Para referenciar um caminho absoluto, use //. Para um caminho relativo ao seu diretório pessoal, use ~/.

• Edit(docs/**) Corresponde a edições em arquivos no diretório docs do seu projeto
• Read(~/.zshrc) Corresponde a leituras do seu arquivo ~/.zshrc
• Edit(//tmp/scratch.txt) Corresponde a edições em /tmp/scratch.txt

​

WebFetch

• WebFetch(domain:example.com) Corresponde a solicitações de busca para example.com

​

MCP

• mcp__puppeteer Corresponde a qualquer ferramenta fornecida pelo servidor puppeteer (nome configurado no Claude Code)
• mcp__puppeteer__puppeteer_navigate Corresponde à ferramenta puppeteer_navigate fornecida pelo servidor puppeteer

​

Opções de permissão do atualizador automático

Quando o Claude Code detecta que não tem permissões suficientes para escrever no seu diretório de prefixo npm 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 atualizador automático, consulte o guia de solução de problemas.

​

Recomendado: Criar um novo prefixo npm 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 de 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
# Veja ~/npm-global-packages.txt e instale os pacotes que deseja manter
# npm install -g package1 package2 package3...

Por que recomendamos esta opção:

• Evita modificar as permissões do 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 atualizador automático

Se você preferir desativar o atualizador automático em vez de corrigir as permissões, você pode definir a variável de ambiente DISABLE_AUTOUPDATER como 1

​

Otimize sua configuração de 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 é gerenciado pelo seu aplicativo de terminal. Você pode combinar o tema do Claude Code com seu terminal durante o onboarding ou a qualquer momento através do 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 em 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 de campainha do terminal

Ative alertas sonoros quando as tarefas forem concluídas:

claude config set --global preferredNotifChannel terminal_bell

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

​

Notificações de sistema do iTerm 2

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

1. Abra as Preferências do iTerm 2
2. Navegue até Perfis → Terminal
3. Ative “Silenciar campainha” e Filtrar Alertas → “Enviar alertas gerados por sequência de escape”
4. Defina seu atraso de notificação preferido

Observe que essas notificações são específicas para o 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 arquivos: Escreva o 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 de teclado do Vim que podem ser ativados com /vim ou configurados via /config.

O subconjunto suportado inclui:

• Alternância 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:

​

Opções de configuração

Estamos no processo de migração da configuração global para settings.json.

claude config será descontinuado em favor de settings.json

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

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

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 <chave> <valor>: