Configurações do Claude Code: o guia de campos do settings.json
Todas as chaves do settings.json que importam: os quatro arquivos de configuração e sua precedência, modelo e effort, regras allow/deny de permissões, o bloco env e um fluxo real de limpeza do settings.local.json — verificado contra a documentação oficial.
A versão curta
- Quatro arquivos, uma hierarquia: managed-settings.json vence a linha de comando, que vence o .claude/settings.local.json, que vence o .claude/settings.json, que vence o ~/.claude/settings.json. Listas allow se somam entre arquivos em vez de se sobreporem.
- O settings.json é JSON estrito: sem comentários, sem vírgula final. Adicione a linha "$schema": "https://json.schemastore.org/claude-code-settings.json" e seu editor vai autocompletar todas as chaves.
- Regras deny sempre vencem. Um deny em qualquer nível sobrepuja todos os allows — comece com Read(./.env) e Bash(git push:*) e, em duas linhas, você protegeu seus segredos e seu remoto.
- O settings.local.json é seu sandbox só da máquina: vence os settings compartilhados do projeto e entra no gitignore automaticamente, então caminhos pessoais e experimentos nunca vazam para o repositório.
Claude Code Configuration EP1: The Global Files Decoded (settings.json, CLAUDE.md, skills)
Canal: Terminode AI2:31
Learning In Public: Cleaning Up Claude Code Settings
Canal: Ben Nadel5:26
Settings — official documentation
Documentação oficial: code.claude.com/docs
Settings reference — the full key table
Documentação oficial: code.claude.com/docs
Environment variables — official reference
Documentação oficial: code.claude.com/docs
Os fatos desta página foram verificados contra a documentação oficial de configurações; os dois vídeos acima são as fontes visuais e a inspiração do fluxo de auditoria.
As capturas de tela pertencem aos seus criadores, com links diretos para os timestamps exatos. Nenhum quadro com rosto é usado.
Configurar o settings.json do Claude Code, passo a passo
Parte 1 — Mapear o cenário de configuração
- 1
Conheça os quatro arquivos de configuração
O Claude Code lê configurações de quatro escopos: ~/.claude/settings.json (você, todos os projetos), .claude/settings.json (compartilhado com o time, comitado), .claude/settings.local.json (você, só este projeto) e managed-settings.json (sua organização). Tudo dentro de ~/.claude — CLAUDE.md, projects, skills, agents, plugins — faz parte do mesmo cenário.
A camada global num relance: cada arquivo que o Claude Code lê de ~/.claude quando uma sessão começa.Ver em 2:28 - 2
Abra ou crie o ~/.claude/settings.json
No Mac e no Linux o arquivo vive em ~/.claude/settings.json; no Windows, em %USERPROFILE%\.claude\settings.json. Crie-o se não existir — o Claude Code o assume na próxima sessão. Defina CLAUDE_CONFIG_DIR se quiser a pasta de configuração inteira em outro lugar.
O settings.json controla temas, escolha de modelo, plugins, variáveis de ambiente e permissões em todos os projetos da sua máquina.Ver em 0:20 - 3
Fixe seu modelo e nível de effort
Defina "model" com um modelo específico ou "opusplan" (Opus planeja, Sonnet executa) e ele vira o padrão de toda nova sessão — a mesma escolha que o /model faz interativamente. Combine com "effortLevel" para limitar o quanto o Claude pensa por padrão, e com modelSettings para sobreposições por modelo.
- 4
Permita os comandos em que confia
Dentro do bloco permissions, "allow" lista regras de ferramenta que dispensam o prompt de aprovação: "Bash(npm run lint)", "Bash(npm run test *)", "Read(~/.zshrc)". Regras são padrões com escopo por ferramenta — o curinga * precisa de um espaço antes ("Bash(git push:*)") para não engolir nomes de comando mais longos.
Um allow list real do settings.local.json: cada entrada aqui foi um prompt de aprovação que nunca mais vai aparecer.Ver em 0:50
Parte 2 — Permissões, env e sobreposições
- 5
Proteja segredos com regras deny
Regras deny são avaliadas primeiro e nada, em nenhum nível, pode sobrepô-las. Comece com "Read(./.env)" e "Read(./.env.*)" para que chaves de API nunca entrem no contexto, além de "Bash(git push:*)" para que publicar no remoto siga sendo decisão humana. Deixe as regras ask cuidarem da zona cinzenta.
- 6
Ajustes locais da máquina ficam no settings.local.json
Quando o Claude Code grava uma permissão para você, ela cai no .claude/settings.local.json — que ele também coloca no gitignore automaticamente. Use esse arquivo para caminhos pessoais, flags de experimento e tudo que você não quer impor aos colegas. Regras deliberadas e compartilhadas pertencem ao .claude/settings.json.
- 7
Segredos e toggles vão no bloco env
O objeto "env" aplica variáveis de ambiente a todas as sessões: "ANTHROPIC_API_KEY", "DISABLE_TELEMETRY": "1", "DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1" ou CLAUDE_CODE_MAX_OUTPUT_TOKENS. Uma heurística útil da documentação: chaves em ALL_CAPS dentro do settings.json quase sempre pertencem ao env.
- 8
Não confunda ~/.claude.json com configuração
~/.claude.json é estado, não configuração: tokens OAuth, registros de servidores MCP, decisões de confiança por projeto e toggles globais moram ali. Edite o settings.json para expressar intenção; deixe o Claude Code gerenciar o .claude.json sozinho — e faça backup dos dois, porque o cleanupPeriodDays também governa quanto tempo o histórico de transcrições sobrevive.
Dentro de ~/.claude: feature flags, plugins, snapshots de shell e o arquivo de estado .claude.json que é fácil de confundir com um arquivo de configuração.Ver em 2:00
Parte 3 — Manter tudo limpo com o tempo
- 9
Saiba o que mais mora em ~/.claude
CLAUDE.md é seu arquivo global de instruções, lido no início de cada sessão. projects/ guarda o histórico de conversas e a memória automática por repositório, skills/ contém fluxos SKILL.md sob demanda, agents/ define subagentes, plugins/ rastreia plugins instalados e statsig/ faz cache de feature flags. O settings.json orquestra tudo isso.
CLAUDE.md é o arquivo irmão que as pessoas confundem com configuração: ele carrega preferências e convenções, não chaves de configuração.Ver em 0:45 - 10
Peça ao Claude para auditar seu allow list
Allow lists crescem um prompt por vez até que ninguém mais lembre o que há nelas. Abra o Claude Code e peça para revisar o .claude/settings.local.json em busca de entradas redundantes, desnecessárias e arriscadas — o Claude sabe quais ferramentas ele mesmo tem embutidas e quais regras se sobrepõem.
O prompt de auditoria: revisar o allow list, sinalizar o que é redundante, o que duplica ferramentas embutidas e o que é francamente arriscado.Ver em 1:40 - 11
Leia o veredito como um revisor
Na auditoria real que esta página capturou em screenshots, o Claude classificou 41 entradas: ls, grep, find, echo e cd duplicam ferramentas embutidas; entradas com curinga já cobriam comandos explícitos; caminhos absolutos locais eram desnecessários porque o Claude conhece o próprio diretório de trabalho; e só o curl foi sinalizado como francamente permissivo demais.
O veredito: 41 entradas classificadas em desnecessárias, redundantes e arriscadas — com a substituição de cada linha.Ver em 3:05 - 12
Aplique a limpeza e revise todo mês
Aprove as edições propostas e o arquivo encolhe de 41 para 15 entradas. Transforme em hábito: um allow list que você não consegue ler é uma superfície de ataque que você não consegue ver. Rode a auditoria de novo após projetos grandes e prefira regras com escopo, como Bash(git diff:*), a aprovações genéricas.
A limpeza aplicada: curl, caminhos explícitos da home e scripts de shell de uso único removidos do allow list.Ver em 4:50
settings.json vs CLAUDE.md vs ~/.claude.json vs /config
Quatro superfícies parecem todas "configurações do Claude Code" — mas não são intercambiáveis. Qual arquivo é dono do quê:
- 1settings.json (todos os escopos) — configuração declarativa: model, effort, permissions, env, hooks, statusLine, plugins. JSON estrito, validado por schema, seguro para commit (exceto o .local).
- 2CLAUDE.md — instruções e convenções em linguagem natural. Ele molda comportamento, não configuração; não há contrato chave-valor e é lido a cada sessão.
- 3~/.claude.json — estado da máquina: dados de OAuth/sessão, registros MCP, confiança por projeto, flags de onboarding. O Claude Code escreve nele; você não deveria editá-lo à mão.
- 4/config — o painel interativo. É uma UI sobre as mesmas chaves: a maioria dos toggles grava no ~/.claude/settings.json, alguns (como Show tips) vão para o settings.local.json, e opções globais caem no ~/.claude.json.
- 5managed-settings.json — a camada da organização. Ela sobrepõe tudo (com poucas exceções de segurança em que o valor mais rígido vence), e é por isso que sua escolha local de modelo pode perder silenciosamente numa máquina do trabalho.
Regra de bolso: comportamento vai no CLAUDE.md, configuração no settings.json — e se um valor parece te ignorar, verifique se ~/.claude.json ou um arquivo gerenciado já decidiu por você.
As configurações não estão valendo? Primeiros socorros
A maioria dos problemas de settings.json se reduz a cinco causas. Siga na ordem:
- 1Erros de sintaxe JSON. O settings.json é JSON estrito — uma vírgula final ou um comentário // e o arquivo inteiro é rejeitado. Cole num validador, ou adicione a linha $schema para o editor apontar erros enquanto você digita.
- 2Uma regra mais rígida acima de você. Configurações gerenciadas e chaves sensíveis à segurança (como disableClaudeAiConnectors ou useAutoModeDuringPlan) vencem seu arquivo, não importa o quê. Veja se uma máquina corporativa está sobrepondo você.
- 3Arquivo errado, escopo errado. Regras no .claude/settings.json só valem dentro daquele projeto; os valores auto e bypassPermissions de defaultMode são ignorados em arquivos de nível de projeto por design.
- 4Valores de env no lugar errado. Chaves em ALL_CAPS pertencem ao bloco env, não ao nível de topo. Se ANTHROPIC_API_KEY ou DISABLE_TELEMETRY parecem ignorados, provavelmente estão um nível acima do devido.
- 5Entradas silenciosamente rejeitadas. Rode claude doctor para listar entradas que falharam na validação, e /status numa sessão para ver quais arquivos realmente carregaram.
Ainda travado? Desfaça sua última edição, confirme com /status que o arquivo carrega, e reaplique as mudanças uma chave por vez — bissecar o arquivo rende mais que encará-lo.