Referência de Definições do Claude Code
Cada chave no settings.json, a lista completa de variáveis de ambiente e a cadeia de precedência de cinco âmbitos que decide qual configuração ganha quando as geridas e as do utilizador colidem.
Pare de configurar. Comece a construir.
Templates SaaS com orquestração de IA.
Problema: A maior parte do sofrimento com o Claude Code tem uma causa raiz. A tua configuração não está alinhada com a forma como trabalhas. Passas o dia a aprovar comandos bash, os padrões da equipa nunca carregam, ou uma chave que editaste ontem não faz nada.
A solução é conhecer o sistema de definições. Não só as chaves, mas as regras de precedência que escolhem um vencedor quando dois âmbitos discordam.
Vitória Rápida: Coloca uma linha $schema no settings.json e qualquer editor que entenda JSON schema acende com autocomplete e verificações inline. VS Code, Cursor, e tudo o mais com suporte a schema beneficia disso.
A Cadeia de Precedência de Cinco Âmbitos
As definições seguem uma ordem fixa. Conhecê-la é a diferença entre "porque é que a minha alteração não funcionou" e "ah, ficheiro errado."
Precedência de Âmbitos (do Mais Alto ao Mais Baixo)
| Prioridade | Âmbito | Localização | Quem Afeta | Partilhado? |
|---|---|---|---|---|
| 1 | Gerido | Diretórios do sistema | Todos os utilizadores na máquina | Sim (implementado pelo IT) |
| 2 | Linha de comandos | Flags CLI | Apenas sessão atual | Não |
| 3 | Local | .claude/settings.local.json | Tu, neste projeto | Não (no gitignore) |
| 4 | Projeto | .claude/settings.json | Todos os colaboradores | Sim (no git) |
| 5 | Utilizador | ~/.claude/settings.json | Tu, todos os projetos | Não |
Âmbitos mais altos ganham sempre aos mais baixos. Ponto final. Uma regra gerida do IT que bloqueia Bash(curl *) é inalcançável por qualquer ficheiro pessoal ou de projeto.
Escolher o Âmbito Certo
Gerido serve organizações que precisam de regras sem escapatória:
- Políticas de segurança (bloquear acesso a credenciais, proibir comandos destrutivos)
- Conformidade que tem de se aplicar a todos os engenheiros e todos os repos
- Hooks padrão ou configs MCP implementados pelo IT
Linha de comandos lida com substituições pontuais dentro de uma sessão:
- Experimentar um modelo diferente:
claude --model claude-sonnet-4-5-20250929 - Conceder margem de permissão extra para um trabalho específico
- Correr com o flag
--debug
Local é o teu sandbox privado para um determinado repo:
- Substituir silenciosamente uma regra de projeto que não se adapta à tua máquina
- Experimentar um hook antes de o propor à equipa
- Caminhos únicos desta máquina (onde fica a tua chave SSH, em que porta corre o proxy local)
Projeto é o lugar onde a equipa se alinha:
- Regras de permissão que todos seguem
- Hooks partilhados para formatação automática e lint
- Configs de servidores MCP de que todos os membros precisam
- Instruções CLAUDE.md que descrevem o projeto
Utilizador são os teus próprios padrões:
- Língua, tema e o estilo de saída que preferes
- Plugins que queres em todos os repos
- Regras de permissão globais (como uma negação geral em
~/.ssh)
Caminhos das Definições Geridas por OS
Os ficheiros geridos precisam de direitos de administrador e ficam fora de qualquer diretório home de utilizador:
| Sistema Operativo | Caminho |
|---|---|
| macOS | /Library/Application Support/ClaudeCode/ |
| Linux / WSL | /etc/claude-code/ |
| Windows | C:\Program Files\ClaudeCode\ |
Dois ficheiros ficam nessas pastas. managed-settings.json contém as definições, managed-mcp.json contém os servidores MCP.
Cada configuração no Claude Code vive num caminho de ficheiro conhecido em cada âmbito:
| Funcionalidade | Utilizador | Projeto (partilhado) | Local (pessoal) |
|---|---|---|---|
| Definições | ~/.claude/settings.json | .claude/settings.json | .claude/settings.local.json |
| Subagentes | ~/.claude/agents/ | .claude/agents/ | N/A |
| Servidores MCP | ~/.claude.json | .mcp.json | ~/.claude.json (por projeto) |
| Plugins | ~/.claude/settings.json | .claude/settings.json | .claude/settings.local.json |
| CLAUDE.md | ~/.claude/CLAUDE.md | CLAUDE.md ou .claude/CLAUDE.md | CLAUDE.local.md |
Referência de Definições
Definições Gerais
| Chave | Descrição | Padrão | Exemplo |
|---|---|---|---|
model | Substitui o modelo padrão | (padrão do sistema) | "claude-sonnet-4-5-20250929" |
language | Língua de resposta preferida do Claude | Inglês | "japanese" |
outputStyle | Ajusta o estilo do system prompt | (nenhum) | "Explanatory" |
cleanupPeriodDays | Dias antes de sessões inativas serem eliminadas | 30 | 20 |
autoUpdatesChannel | Canal de lançamento: "stable" ou "latest" | "latest" | "stable" |
showTurnDuration | Mostra o tempo de resposta ("Cooked for 1m 6s") | true | false |
spinnerVerbs | Personaliza o texto do spinner | (padrões) | {"mode": "append", "verbs": ["Pondering"]} |
spinnerTipsEnabled | Mostra dicas enquanto o Claude trabalha | true | false |
terminalProgressBarEnabled | Barra de progresso no terminal (iTerm2, Windows Terminal) | true | false |
alwaysThinkingEnabled | Ativa o pensamento extendido por padrão | false | true |
plansDirectory | Onde os ficheiros de plano são armazenados | ~/.claude/plans | "./plans" |
respectGitignore | O seletor de ficheiros @ respeita .gitignore | true | false |
companyAnnouncements | Mensagens mostradas no arranque (ciclo aleatório) | (nenhum) | ["Review guidelines at docs.acme.com"] |
Definições de Permissões
As chaves abaixo ficam todas dentro do objeto "permissions".
| Chave | Descrição | Exemplo |
|---|---|---|
allow | Regras para permitir automaticamente o uso de ferramentas | ["Bash(npm run lint)", "Read(~/.zshrc)"] |
ask | Regras que requerem confirmação | ["Bash(git push *)"] |
deny | Regras para bloquear completamente o uso de ferramentas | ["WebFetch", "Bash(curl *)", "Read(./.env)"] |
additionalDirectories | Diretórios adicionais a que o Claude pode aceder | ["../docs/", "../shared/"] |
defaultMode | Modo de permissão padrão no arranque | "acceptEdits" |
disableBypassPermissionsMode | Bloqueia --dangerously-skip-permissions | "disable" |
Ordem de avaliação: Deny tem a primeira passagem. Ask é o seguinte. Allow vai por último. A primeira regra que corresponde é a que fica.
Exemplos de sintaxe de regras:
| Regra | O que Corresponde |
|---|---|
Bash | Todos os comandos Bash |
Bash(npm run *) | Comandos que começam com npm run |
Read(./.env) | Leitura do ficheiro .env |
Read(./secrets/**) | Leitura de qualquer coisa em secrets/ |
WebFetch(domain:example.com) | Pedidos fetch para example.com |
Definições de Sandbox
As chaves abaixo ficam dentro do objeto "sandbox" e governam como os comandos bash são isolados.
| Chave | Descrição | Padrão | Exemplo |
|---|---|---|---|
enabled | Ativa o sandboxing de bash | false | true |
autoAllowBashIfSandboxed | Aprovação automática de comandos quando em sandbox | true | true |
excludedCommands | Comandos que correm fora do sandbox | (nenhum) | ["git", "docker"] |
allowUnsandboxedCommands | Permite escape dangerouslyDisableSandbox | true | false |
enableWeakerNestedSandbox | Sandbox mais fraco para Docker (Linux/WSL2) | false | true |
network.allowedDomains | Lista de domínios de saída permitidos | (nenhum) | ["github.com", "*.npmjs.org"] |
network.allowUnixSockets | Caminhos de sockets Unix acessíveis no sandbox | (nenhum) | ["~/.ssh/agent-socket"] |
network.allowAllUnixSockets | Permite todas as ligações de sockets Unix | false | true |
network.allowLocalBinding | Permite ligação ao localhost (só macOS) | false | true |
network.httpProxyPort | Porta proxy HTTP personalizada | (automático) | 8080 |
network.socksProxyPort | Porta proxy SOCKS5 personalizada | (automático) | 8081 |
Definições de Atribuição
As chaves abaixo ficam dentro do objeto "attribution" e decidem como o git atribui o trabalho do Claude.
| Chave | Descrição | Padrão |
|---|---|---|
commit | Texto adicionado às mensagens de commit git | "Generated with Claude Code..." + trailer Co-Authored-By |
pr | Texto adicionado às descrições de pull request | "Generated with Claude Code..." |
Deixa qualquer chave em branco com "" e a linha correspondente desaparece do git. A chave legada includeCoAuthoredBy ainda funciona, embora esteja agora obsoleta.
Definições de Plugins
| Chave | Descrição | Exemplo |
|---|---|---|
enabledPlugins | Ativa/desativa plugins | {"formatter@acme-tools": true} |
extraKnownMarketplaces | Fontes adicionais de plugins | Ver exemplo abaixo |
strictKnownMarketplaces | (Só Gerido) Restringe fontes de marketplace | [{"source": "github", "repo": "acme/plugins"}] |
Existem quatro tipos de fontes. github aponta para um repo. git aceita qualquer URL. directory usa um caminho local enquanto estás a desenvolver. hostPattern faz correspondência regex em hostnames.
Definições de Servidores MCP
| Chave | Descrição | Exemplo |
|---|---|---|
enableAllProjectMcpServers | Aprova automaticamente todos os servidores MCP do projeto | true |
enabledMcpjsonServers | Servidores MCP específicos a aprovar | ["memory", "github"] |
disabledMcpjsonServers | Servidores MCP específicos a rejeitar | ["filesystem"] |
allowedMcpServers | (Só Gerido) Lista de permissão de servidores MCP | [{"serverName": "github"}] |
deniedMcpServers | (Só Gerido) Lista de bloqueio de servidores MCP | [{"serverName": "filesystem"}] |
Definições de Autenticação e Fornecedor
| Chave | Descrição | Exemplo |
|---|---|---|
apiKeyHelper | Script para gerar valor de autenticação | "/bin/generate_temp_api_key.sh" |
forceLoginMethod | Restringe a claudeai ou console | "claudeai" |
forceLoginOrgUUID | Seleciona automaticamente a organização no login | "xxxxxxxx-xxxx-..." |
awsAuthRefresh | Script para atualizar credenciais AWS | "aws sso login --profile myprofile" |
awsCredentialExport | Script que produz JSON de credenciais AWS | "/bin/generate_aws_grant.sh" |
otelHeadersHelper | Script que gera cabeçalhos OpenTelemetry | "/bin/generate_otel_headers.sh" |
Definições de Hooks e Avançadas
| Chave | Descrição | Exemplo |
|---|---|---|
hooks | Configuração de hook para eventos do ciclo de vida | Ver guia de hooks |
disableAllHooks | Desativa todos os hooks | true |
allowManagedHooksOnly | (Só Gerido) Bloqueia hooks de utilizador/projeto | true |
allowManagedPermissionRulesOnly | (Só Gerido) Bloqueia regras de permissão de utilizador/projeto | true |
fileSuggestion | Script de autocomplete de ficheiros @ personalizado | {"type": "command", "command": "~/.claude/file-suggestion.sh"} |
statusLine | Exibição de linha de estado personalizada | {"type": "command", "command": "~/.claude/statusline.sh"} |
env | Variáveis de ambiente para cada sessão | {"FOO": "bar"} |
Variáveis de Ambiente
O Claude Code lê cerca de 70 variáveis de ambiente. A maioria são casos extremos. Um conjunto de trabalho de cerca de 20 é tudo o que vês no uso diário.
Modelo e Fornecedor
| Variável | Propósito |
|---|---|
ANTHROPIC_API_KEY | Chave API para acesso direto à API |
ANTHROPIC_MODEL | Substitui o modelo padrão |
ANTHROPIC_DEFAULT_SONNET_MODEL | Nome do modelo para o alias Sonnet |
CLAUDE_CODE_SUBAGENT_MODEL | Modelo para subagentes (separado do modelo principal) |
CLAUDE_CODE_USE_BEDROCK | Encaminha através do AWS Bedrock |
CLAUDE_CODE_USE_VERTEX | Encaminha através do Google Vertex |
As variáveis de alias (ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL) são úteis quando a tua organização aponta um modelo ajustado para os nomes de alias padrão.
Ajuste de Performance
| Variável | Propósito |
|---|---|
CLAUDE_CODE_MAX_OUTPUT_TOKENS | Máximo de tokens de saída (padrão: 32K, máximo: 64K) |
MAX_THINKING_TOKENS | Orçamento de pensamento extendido (padrão: 31.999, define 0 para desativar) |
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE | % da capacidade de contexto (1-100) que dispara compactação automática |
BASH_DEFAULT_TIMEOUT_MS | Timeout padrão de comandos bash |
BASH_MAX_TIMEOUT_MS | Timeout máximo de bash que o Claude pode definir |
BASH_MAX_OUTPUT_LENGTH | Máximo de caracteres de saída bash antes de truncar |
Privacidade e Telemetria
| Variável | Propósito |
|---|---|
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | Desativa atualizações, telemetria, relatório de erros de uma vez |
DISABLE_TELEMETRY | Opta por sair da telemetria Statsig |
DISABLE_ERROR_REPORTING | Opta por sair do relatório de erros Sentry |
CLAUDE_CODE_HIDE_ACCOUNT_INFO | Esconde email e nome da organização da UI |
DISABLE_AUTOUPDATER | Desativa atualizações automáticas de versão |
Controlo de Sessão
| Variável | Propósito |
|---|---|
CLAUDE_CODE_TASK_LIST_ID | Partilha uma lista de tarefas entre várias sessões |
CLAUDE_CODE_ENABLE_TASKS | Define false para reverter para a lista TODO antiga |
CLAUDE_CODE_SHELL | Substitui a deteção automática de shell |
CLAUDE_CONFIG_DIR | Localização personalizada de diretório de configuração/dados |
MCP_TIMEOUT | Timeout em ms para arranque do servidor MCP |
MCP_TOOL_TIMEOUT | Timeout em ms para execução de ferramentas MCP |
Existem duas formas. Exporta-as do teu perfil de shell, ou coloca-as no objeto "env" do settings.json para que sobrevivam entre sessões sem qualquer edição do shell rc.
Resolver Conflitos de Configuração
A maior parte das dores de cabeça clássicas de configuração desaparecem quando sabes qual âmbito ganha qual.
Caso 1: Uma regra de permissão discorda entre âmbitos
A tua configuração de utilizador permite Bash(curl *). A configuração do projeto bloqueia-o. Quem ganha? Projeto está na prioridade 4 e utilizador está na prioridade 5, por isso o bloqueio mantém-se. Se o curl é genuinamente necessário na tua própria máquina, coloca a regra de permissão em .claude/settings.local.json. Local na prioridade 3 ultrapassa projeto na prioridade 4, e o allow local substitui a regra bloqueada.
Caso 2: Um ficheiro gerido derruba uma regra de projeto
O settings.json da tua equipa no projeto permite Bash(rm -rf *). O IT envia então um ficheiro gerido que bloqueia esse mesmo comando. Gerido é o vencedor. Sempre. Nada num ficheiro de utilizador, local ou projeto consegue superar regras geridas. O design é intencional, e a conformidade é a razão.
Caso 3: Experimentar algo localmente
Queres testar um novo hook antes de o oferecer à equipa. Coloca-o em .claude/settings.local.json. Ultrapassa o .claude/settings.json partilhado e fica apenas na tua máquina.
Caso 4: Dois âmbitos a fundir
Os âmbitos não se apagam mutuamente por completo. Acumulam-se. A configuração de utilizador a permitir Bash(git status) e a configuração de projeto a permitir Bash(npm run lint) dão-te ambas as regras ativas ao mesmo tempo. A fusão une os arrays de permissões. Se a mesma chave tem um valor diferente em dois âmbitos, o âmbito mais alto é o que fica para essa chave única.
Caso 5: Uma variável de ambiente exportada do shell e listada no settings.json
Exporta ANTHROPIC_MODEL do teu shell e também lista-a no objeto env do settings.json, e a exportação do shell é o valor que o Claude Code usa.
Como as Definições se Ligam ao Resto do Sistema
Os ficheiros CLAUDE.md contêm as instruções que o Claude carrega no arranque, mais o contexto de que precisa. Modelo mental limpo: as definições dizem o que o Claude tem permissão para fazer, o CLAUDE.md diz o que o Claude deve saber.
Os servidores MCP ligam novas ferramentas ao Claude. A sua configuração vive nos seus próprios ficheiros (.mcp.json ao nível do projeto, ~/.claude.json ao nível do utilizador). O settings.json é o lugar que decide quais desses servidores estão aprovados e quais estão bloqueados.
Os hooks ficam dentro do settings.json sob a chave hooks. Cada um executa um comando shell, ou envia um prompt LLM, quando um evento do ciclo de vida dispara.
Os plugins também correm através do settings.json, via enabledPlugins e a tua lista de marketplace.
Os subagentes são ficheiros Markdown simples. Os de utilizador ficam em ~/.claude/agents/, os de projeto em .claude/agents/.
Cópias de Segurança e Recuperação
Cada vez que um ficheiro de configuração muda, o Claude Code escreve uma cópia de segurança com timestamp. As últimas cinco cópias por ficheiro ficam guardadas. Uma má atualização já não significa escavar no git reflog. A versão anterior a funcionar fica ao lado da que está com problemas.
Começar
Novo nas definições do Claude Code? Passa por esta lista curta por ordem.
- Regras de permissão ao nível do projeto. Bloqueia qualquer leitura em
.enve outros ficheiros secretos. Permite os comandos de build ou test que usas todos os dias - Um hook PostToolUse que formata automaticamente ao guardar. Esta única entrada destrói a fadiga de aprovação mais rápido do que qualquer outra coisa
- Definições de atribuição se a linha Co-Authored-By precisa de ajuste ou remoção
- Padrões de utilizador para as preferências que queres ativas em todos os repos que tocas
- Um ficheiro CLAUDE.md com contexto do projeto e as tuas convenções de código
Pare de configurar. Comece a construir.
Templates SaaS com orquestração de IA.