Configurações do Claude Code

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

​

Arquivos de configurações

O 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:
  • .claude/settings.json para configurações que são incluídas no controle de versão e compartilhadas com sua equipe
  • .claude/settings.local.json para configurações que não são incluídas no controle de versão, úteis para preferências pessoais e experimentação. 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ítica gerenciada empresarial. Estas têm precedência sobre as configurações de usuário e projeto. Os administradores de sistema podem implantar políticas em:
  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux e WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\ProgramData\ClaudeCode\managed-settings.json

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

​

Configurações disponíveis

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

​

Configurações de permissão

​

Precedência de configurações

As configurações são aplicadas em ordem de precedência (maior para menor):

1. Políticas gerenciadas empresariais (managed-settings.json)

   • Implantadas por TI/DevOps
   • Não podem ser substituídas

2. Argumentos de linha de comando

   • Substituições temporárias para uma sessão específica

3. Configurações locais do projeto (.claude/settings.local.json)

   • Configurações pessoais específicas do projeto

4. Configurações compartilhadas do projeto (.claude/settings.json)

   • Configurações do projeto compartilhadas pela equipe no controle de versão

5. Configurações do usuário (~/.claude/settings.json)

   • Configurações globais pessoais

Esta hierarquia garante que as políticas de segurança empresariais sejam sempre aplicadas, permitindo ainda que equipes e indivíduos personalizem sua experiência.

​

Pontos-chave sobre o sistema de configuração

• Arquivos de memória (CLAUDE.md): Contêm instruções e contexto que Claude carrega na inicialização
• Arquivos de configurações (JSON): Configuram permissões, variáveis de ambiente e comportamento de ferramentas
• Comandos slash: Comandos personalizados que podem ser invocados durante uma sessão com /nome-do-comando
• Servidores MCP: Estendem o Claude Code com ferramentas e integrações adicionais
• Precedência: Configurações de nível superior (Empresarial) substituem as de nível inferior (Usuário/Projeto)
• Herança: As configurações são mescladas, com configurações mais específicas adicionando ou substituindo as mais amplas

​

Disponibilidade do prompt do sistema

​

Excluindo arquivos sensíveis

Para impedir que o Claude Code acesse arquivos contendo informações sensíveis (por exemplo, chaves de API, segredos, arquivos de ambiente), use a configuração permissions.deny no seu arquivo .claude/settings.json:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

Isso substitui a configuração ignorePatterns descontinuada. Arquivos que correspondem a esses padrões serão completamente invisíveis ao Claude Code, impedindo qualquer exposição acidental de dados sensíveis.

​

Configuração de subagentes

O Claude Code suporta subagentes de IA personalizados que podem ser configurados tanto em níveis de usuário quanto de projeto. Esses subagentes são armazenados como arquivos Markdown com frontmatter YAML:

• Subagentes do usuário: ~/.claude/agents/ - Disponíveis em todos os seus projetos
• Subagentes do projeto: .claude/agents/ - Específicos do seu projeto e podem ser compartilhados com sua equipe

Os arquivos de subagentes definem assistentes de IA especializados com prompts personalizados e permissões de ferramentas. Saiba mais sobre criar e usar subagentes na documentação de subagentes.

​

Variáveis de ambiente

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

​

Opções de configuração

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

​

Ferramentas disponíveis para Claude

O Claude Code tem acesso a um conjunto de ferramentas poderosas que o ajudam a entender e modificar sua base de código:

Regras de permissão podem ser configuradas usando /allowed-tools ou em configurações de permissão.

​

Estendendo ferramentas com hooks

Você pode executar comandos personalizados antes ou depois de qualquer ferramenta executar usando hooks do Claude Code.

Por exemplo, você poderia executar automaticamente um formatador Python depois que Claude modifica arquivos Python, ou impedir modificações em arquivos de configuração de produção bloqueando operações Write para certos caminhos.

​

Veja também

• Gerenciamento de Identidade e Acesso - Aprenda sobre o sistema de permissões do Claude Code
• IAM e controle de acesso - Gerenciamento de políticas empresariais
• Solução de problemas - Soluções para problemas comuns de configuração