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.
Quer o framework por trás destes projetos?
Obtenha o sistema Claude Code que usamos para planejar, construir, testar e lançar software em produção.
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
Quer o framework por trás destes projetos?
Obtenha o sistema Claude Code que usamos para planejar, construir, testar e lançar software em produção.
Sandbox do Claude Code
O sandbox do Claude Code aplica limites de sistema de ficheiros e rede ao nível do kernel. Configuração para macOS Seatbelt, Linux e WSL2 com bubblewrap, e listas de domínios permitidos.
AI Research (July 2026)
The latest AI research, explained: OpenAI shipped GPT-5.6, Anthropic shipped Claude Opus 5, Moonshot open-weighted Kimi K3, and three separate results showed an agent benchmark score measures your whole evaluation setup, not just your model. What each finding means if you build with AI, with every vendor self-report flagged.