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, ú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 do usuário e do projeto. Os administradores do sistema podem implantar políticas para:
- macOS: /Library/Application Support/ClaudeCode/managed-settings.json
- Linux e WSL: /etc/claude-code/managed-settings.json
- Windows: C:\ProgramData\ClaudeCode\managed-settings.json

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

Chave	Descrição	Exemplo
`apiKeyHelper`	Script personalizado, a ser executado em `/bin/sh`, para gerar um valor de autenticação. Este valor será enviado como cabeçalhos `X-Api-Key` e `Authorization: Bearer` para solicitações de modelo	`/bin/generate_temp_api_key.sh`
`cleanupPeriodDays`	Por quanto tempo manter localmente as transcrições de chat com base na data da última atividade (padrão: 30 dias)	`20`
`env`	Variáveis de ambiente que serão aplicadas a cada sessão	`{"FOO": "bar"}`
`includeCoAuthoredBy`	Se deve incluir a linha `co-authored-by Claude` em commits git e pull requests (padrão: `true`)	`false`
`permissions`	Veja a tabela abaixo para a estrutura das permissões.
`hooks`	Configure comandos personalizados para executar antes ou depois das execuções de ferramentas. Veja documentação de hooks	`{"PreToolUse": {"Bash": "echo 'Running command...'"}}`
`disableAllHooks`	Desabilitar todos os hooks	`true`
`model`	Substituir o modelo padrão a ser usado para o Claude Code	`"claude-3-5-sonnet-20241022"`
`statusLine`	Configure uma linha de status personalizada para exibir contexto. Veja documentação statusLine	`{"type": "command", "command": "~/.claude/statusline.sh"}`
`outputStyle`	Configure um estilo de saída para ajustar o prompt do sistema. Veja documentação de estilos de saída	`"Explanatory"`
`forceLoginMethod`	Use `claudeai` para restringir login a contas Claude.ai, `console` para restringir login a contas do Console Anthropic (cobrança de uso da API)	`claudeai`
`forceLoginOrgUUID`	Especifique o UUID de uma organização para selecioná-la automaticamente durante o login, ignorando a etapa de seleção da organização. Requer que `forceLoginMethod` seja definido	`"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`
`enableAllProjectMcpServers`	Aprovar automaticamente todos os servidores MCP definidos nos arquivos `.mcp.json` do projeto	`true`
`enabledMcpjsonServers`	Lista de servidores MCP específicos dos arquivos `.mcp.json` para aprovar	`["memory", "github"]`
`disabledMcpjsonServers`	Lista de servidores MCP específicos dos arquivos `.mcp.json` para rejeitar	`["filesystem"]`
`awsAuthRefresh`	Script personalizado que modifica o diretório `.aws` (veja configuração avançada de credenciais)	`aws sso login --profile myprofile`
`awsCredentialExport`	Script personalizado que produz JSON com credenciais AWS (veja configuração avançada de credenciais)	`/bin/generate_aws_grant.sh`

Configurações de permissão

Chaves	Descrição	Exemplo
`allow`	Array de regras de permissão para permitir o uso de ferramentas. Nota: Regras Bash usam correspondência de prefixo, não regex	`[ "Bash(git diff:*)" ]`
`ask`	Array de regras de permissão para pedir confirmação no uso de ferramentas.	`[ "Bash(git push:*)" ]`
`deny`	Array de regras de permissão para negar o uso de ferramentas. Use isso para também excluir arquivos sensíveis do acesso do Claude Code. Nota: Padrões Bash são correspondências de prefixo e podem ser contornados (veja limitações de permissão Bash)	`[ "WebFetch", "Bash(curl:)", "Read(./.env)", "Read(./secrets/*)" ]`
`additionalDirectories`	Diretórios de trabalho adicionais aos quais Claude tem acesso	`[ "../docs/" ]`
`defaultMode`	Modo de permissão padrão ao abrir o Claude Code	`"acceptEdits"`
`disableBypassPermissionsMode`	Defina como `"disable"` para impedir que o modo `bypassPermissions` seja ativado. Veja configurações de política gerenciada	`"disable"`

Precedência das configurações

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

Políticas gerenciadas empresariais (managed-settings.json)
- Implantadas por TI/DevOps
- Não podem ser substituídas
Argumentos da linha de comando
- Substituições temporárias para uma sessão específica
Configurações locais do projeto (.claude/settings.local.json)
- Configurações pessoais específicas do projeto
Configurações compartilhadas do projeto (.claude/settings.json)
- Configurações do projeto compartilhadas pela equipe no controle de versão
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 /command-name
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

Diferentemente do claude.ai, não publicamos o prompt interno do sistema do Claude Code neste site. Use arquivos CLAUDE.md ou --append-system-prompt para adicionar instruções personalizadas ao comportamento do Claude Code.

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:

Todas as variáveis de ambiente também podem ser configuradas em settings.json. Isso é útil como uma forma de definir automaticamente variáveis de ambiente para cada sessão, ou para implementar um conjunto de variáveis de ambiente para toda a sua equipe ou organização.

Variável	Propósito
`ANTHROPIC_API_KEY`	Chave de API enviada como cabeçalho `X-Api-Key`, tipicamente para o SDK Claude (para uso interativo, execute `/login`)
`ANTHROPIC_AUTH_TOKEN`	Valor personalizado para o cabeçalho `Authorization` (o valor que você definir aqui será prefixado com `Bearer` )
`ANTHROPIC_CUSTOM_HEADERS`	Cabeçalhos personalizados que você deseja adicionar à solicitação (no formato `Name: Value`)
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	Veja Configuração de modelo
`ANTHROPIC_DEFAULT_OPUS_MODEL`	Veja Configuração de modelo
`ANTHROPIC_DEFAULT_SONNET_MODEL`	Veja Configuração de modelo
`ANTHROPIC_MODEL`	Nome da configuração do modelo a ser usado (veja Configuração de Modelo)
`ANTHROPIC_SMALL_FAST_MODEL`	[DESCONTINUADO] Nome do modelo classe Haiku para tarefas em segundo plano
`ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION`	Substituir região AWS para o modelo classe Haiku ao usar Bedrock
`AWS_BEARER_TOKEN_BEDROCK`	Chave de API Bedrock para autenticação (veja chaves de API Bedrock)
`BASH_DEFAULT_TIMEOUT_MS`	Timeout padrão para comandos bash de longa duração
`BASH_MAX_OUTPUT_LENGTH`	Número máximo de caracteres nas saídas bash antes de serem truncadas no meio
`BASH_MAX_TIMEOUT_MS`	Timeout máximo que o modelo pode definir para comandos bash de longa duração
`CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR`	Retornar ao diretório de trabalho original após cada comando Bash
`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`	Intervalo em milissegundos no qual as credenciais devem ser atualizadas (ao usar `apiKeyHelper`)
`CLAUDE_CODE_CLIENT_CERT`	Caminho para o arquivo de certificado do cliente para autenticação mTLS
`CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`	Frase-senha para CLAUDE_CODE_CLIENT_KEY criptografado (opcional)
`CLAUDE_CODE_CLIENT_KEY`	Caminho para o arquivo de chave privada do cliente para autenticação mTLS
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	Equivalente a definir `DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, e `DISABLE_TELEMETRY`
`CLAUDE_CODE_DISABLE_TERMINAL_TITLE`	Defina como `1` para desabilitar atualizações automáticas do título do terminal baseadas no contexto da conversa
`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`	Pular auto-instalação de extensões IDE
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Definir o número máximo de tokens de saída para a maioria das solicitações
`CLAUDE_CODE_SKIP_BEDROCK_AUTH`	Pular autenticação AWS para Bedrock (por exemplo, ao usar um gateway LLM)
`CLAUDE_CODE_SKIP_VERTEX_AUTH`	Pular autenticação Google para Vertex (por exemplo, ao usar um gateway LLM)
`CLAUDE_CODE_SUBAGENT_MODEL`	Veja Configuração de modelo
`CLAUDE_CODE_USE_BEDROCK`	Usar Bedrock
`CLAUDE_CODE_USE_VERTEX`	Usar Vertex
`DISABLE_AUTOUPDATER`	Defina como `1` para desabilitar atualizações automáticas. Isso tem precedência sobre a configuração `autoUpdates`.
`DISABLE_BUG_COMMAND`	Defina como `1` para desabilitar o comando `/bug`
`DISABLE_COST_WARNINGS`	Defina como `1` para desabilitar mensagens de aviso de custo
`DISABLE_ERROR_REPORTING`	Defina como `1` para optar por não participar do relatório de erros Sentry
`DISABLE_NON_ESSENTIAL_MODEL_CALLS`	Defina como `1` para desabilitar chamadas de modelo para caminhos não críticos como texto de sabor
`DISABLE_TELEMETRY`	Defina como `1` para optar por não participar da telemetria Statsig (note que eventos Statsig não incluem dados do usuário como código, caminhos de arquivo ou comandos bash)
`HTTP_PROXY`	Especificar servidor proxy HTTP para conexões de rede
`HTTPS_PROXY`	Especificar servidor proxy HTTPS para conexões de rede
`MAX_MCP_OUTPUT_TOKENS`	Número máximo de tokens permitidos em respostas de ferramentas MCP. Claude Code exibe um aviso quando a saída excede 10.000 tokens (padrão: 25000)
`MAX_THINKING_TOKENS`	Forçar um orçamento de pensamento para o modelo
`MCP_TIMEOUT`	Timeout em milissegundos para inicialização do servidor MCP
`MCP_TOOL_TIMEOUT`	Timeout em milissegundos para execução de ferramentas MCP
`NO_PROXY`	Lista de domínios e IPs para os quais as solicitações serão emitidas diretamente, ignorando o proxy
`USE_BUILTIN_RIPGREP`	Defina como `0` para usar `rg` instalado no sistema em vez do `rg` incluído com Claude Code
`VERTEX_REGION_CLAUDE_3_5_HAIKU`	Substituir região para Claude 3.5 Haiku ao usar Vertex AI
`VERTEX_REGION_CLAUDE_3_5_SONNET`	Substituir região para Claude Sonnet 3.5 ao usar Vertex AI
`VERTEX_REGION_CLAUDE_3_7_SONNET`	Substituir região para Claude 3.7 Sonnet ao usar Vertex AI
`VERTEX_REGION_CLAUDE_4_0_OPUS`	Substituir região para Claude 4.0 Opus ao usar Vertex AI
`VERTEX_REGION_CLAUDE_4_0_SONNET`	Substituir região para Claude 4.0 Sonnet ao usar Vertex AI
`VERTEX_REGION_CLAUDE_4_1_OPUS`	Substituir região para Claude 4.1 Opus ao usar Vertex AI

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

Chave	Descrição	Exemplo
`autoUpdates`	DESCONTINUADO. Use a variável de ambiente `DISABLE_AUTOUPDATER` em vez disso.	`false`
`preferredNotifChannel`	Onde você deseja receber notificações (padrão: `iterm2`)	`iterm2`, `iterm2_with_bell`, `terminal_bell`, ou `notifications_disabled`
`theme`	Tema de cores	`dark`, `light`, `light-daltonized`, ou `dark-daltonized`
`verbose`	Se deve mostrar saídas completas de bash e comandos (padrão: `false`)	`true`

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:

Ferramenta	Descrição	Permissão Necessária
Bash	Executa comandos shell no seu ambiente	Sim
Edit	Faz edições direcionadas a arquivos específicos	Sim
Glob	Encontra arquivos baseado em correspondência de padrões	Não
Grep	Busca por padrões no conteúdo dos arquivos	Não
MultiEdit	Executa múltiplas edições em um único arquivo atomicamente	Sim
NotebookEdit	Modifica células de notebook Jupyter	Sim
NotebookRead	Lê e exibe conteúdos de notebook Jupyter	Não
Read	Lê o conteúdo dos arquivos	Não
Task	Executa um subagente para lidar com tarefas complexas e de múltiplas etapas	Não
TodoWrite	Cria e gerencia listas de tarefas estruturadas	Não
WebFetch	Busca conteúdo de uma URL especificada	Sim
WebSearch	Executa buscas na web com filtragem de domínio	Sim
Write	Cria ou sobrescreve arquivos	Sim

Regras de permissão podem ser configuradas usando /allowed-tools ou em configurações de permissão. Veja também Regras de permissão específicas de ferramentas.

Estendendo ferramentas com hooks

Você pode executar comandos personalizados antes ou depois que qualquer ferramenta execute 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

Primeiros passos

Construir com Claude Code

Claude Code SDK

Implantação

Administração

Configuração

Referência

Recursos

Configurações do Claude Code

Arquivos de configurações

Configurações disponíveis

Configurações de permissão

Precedência das configurações

Pontos-chave sobre o sistema de configuração

Disponibilidade do prompt do sistema

Excluindo arquivos sensíveis

Configuração de subagentes

Variáveis de ambiente

Opções de configuração

Configuração global

Ferramentas disponíveis para Claude

Estendendo ferramentas com hooks

Veja também

Primeiros passos

Construir com Claude Code

Claude Code SDK

Implantação

Administração

Configuração

Referência

Recursos

​Arquivos de configurações

​Configurações disponíveis

​Configurações de permissão

​Precedência das configurações

​Pontos-chave sobre o sistema de configuração

​Disponibilidade do prompt do sistema

​Excluindo arquivos sensíveis

​Configuração de subagentes

​Variáveis de ambiente

​Opções de configuração

​Configuração global

​Ferramentas disponíveis para Claude

​Estendendo ferramentas com hooks

​Veja também

Arquivos de configurações

Configurações disponíveis

Configurações de permissão

Precedência das configurações

Pontos-chave sobre o sistema de configuração

Disponibilidade do prompt do sistema

Excluindo arquivos sensíveis

Configuração de subagentes

Variáveis de ambiente

Opções de configuração

Configuração global

Ferramentas disponíveis para Claude

Estendendo ferramentas com hooks

Veja também