SpyBara
Go Premium

settings.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 83 additions and 83 deletions.

2026
Wed 7 23:59 Fri 9 23:02 Sat 10 23:01 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Tue 27 22:59 Wed 28 23:57

Arquivos de configurações e precedência

Altere as configurações do Claude Code, escolha o escopo ao qual uma chave pertence, verifique a alteração e aprenda qual valor o Claude Code usa quando uma chave é definida em vários locais.

As configurações são as chaves JSON que alteram como o Claude Code se comporta: qual modelo ele inicia, o que pode executar sem perguntar, quais arquivos não pode ler, como aparece no seu terminal e o que sua organização impõe.

[!TIP]

Para procurar uma chave específica, vá para Todas as configurações, que lista cada chave com o arquivo em que você a define, seu padrão e um exemplo.

O Claude Code lê configurações de arquivos de configurações JSON como ~/.claude/settings.json. Ele procura por eles em alguns locais, e o arquivo do qual ele lê uma configuração decide a quem a configuração se aplica. Esta página cobre esses arquivos: em qual colocar uma configuração, como alterar uma configuração e confirmar que foi aplicada, e qual valor o Claude Code usa quando a mesma chave é definida em mais de um arquivo. Configurar permissões cobre o que o Claude Code pode executar sem perguntar e como escrever regras allow, ask e deny.

[!NOTE]

Esta página cobre o Claude Code em execução na sua máquina: o terminal, as extensões VS Code e JetBrains, e o aplicativo desktop, que todos leem os mesmos arquivos de configurações. Uma sessão em nuvem no Claude Code na web é executada em uma máquina diferente e lê apenas alguns deles; veja Configurações em sessões em nuvem.

Arquivos de configurações e quem eles afetam

O Claude Code lê configurações de quatro arquivos, e uma organização também pode entregar configurações gerenciadas do console claude.ai. Cada fonte tem um escopo: o conjunto de pessoas e projetos aos quais uma configuração salva nela se aplica, seja apenas você, todos em um projeto ou todos em sua organização.

Escopo Arquivo Quem afeta Use para
Usuário ~/.claude/settings.json Você, em cada projeto nesta máquina Preferências pessoais: tema, modo de editor, modelo padrão, suas próprias regras de permissão
Projeto compartilhado .claude/settings.json Todos trabalhando na pasta que o contém. Em um repositório git, faça commit dele para que os colegas de equipe o obtenham Permissões de equipe, hooks, plugins e as variáveis de ambiente que o projeto precisa
Projeto local .claude/settings.local.json Você, apenas neste projeto. O Claude Code o mantém fora do git quando cria o arquivo; se você o criar manualmente, adicione-o ao .gitignore você mesmo Substituições pessoais para um projeto e testes antes de compartilhar
Gerenciado managed-settings.json e outras fontes gerenciadas Todos para os quais sua organização o implanta; Precedência de configurações diz o que pode sobrescrevê-lo Política de segurança e requisitos de conformidade

Na coluna Arquivo, ~/.claude é a pasta .claude no seu diretório home, e um .claude simples é a pasta .claude dentro do seu projeto.

Compare o escopo de cada arquivo de configurações

Suponha que você tenha três projetos em sua máquina, website/, api/ e acme-app/, um colega de equipe tenha seu próprio clone de acme-app/ e você inicie uma sessão na nuvem em acme-app/.

O gráfico abaixo mostra em quais dessas pastas uma configuração se aplica quando você inicia o Claude Code a partir delas. Clique em um arquivo de configurações para ver as pastas que ele alcança.

Settings file

Your machine

A teammate’s machine

A cloud session

  • ~/.claude/settings.json: cada projeto em sua máquina, e nada no de seu colega de equipe ou na sessão na nuvem
  • acme-app/.claude/settings.json: seu acme-app/. Alcança o clone do seu colega de equipe e a sessão na nuvem apenas se você fizer commit do arquivo no controle de versão; até então, é um arquivo no seu disco como qualquer outro e ninguém mais o tem
  • acme-app/.claude/settings.local.json: seu acme-app/ apenas. O Claude Code o adiciona às suas exclusões git globais na primeira vez que escreve o arquivo, para que fique fora de seus commits; se você criar o arquivo manualmente, adicione-o ao .gitignore você mesmo
  • Configurações gerenciadas, seja um arquivo managed-settings.json, uma política MDM ou configurações gerenciadas pelo servidor do console claude.ai: cada projeto em cada máquina para a qual sua organização as implanta, ou que você entra com sua conta organizacional. Apenas configurações gerenciadas pelo servidor alcançam a sessão na nuvem

Encontre ou crie seus arquivos de configurações

Instalar o Claude Code não cria nenhum arquivo de configurações. Se sua máquina ou projeto já tiver um, ele veio de uma dessas fontes:

  • Gerenciado: sua organização o implanta. Você não o cria ou edita.
  • Projeto compartilhado: um projeto que já usa Claude Code pode ter um incluído em um commit. Se não, crie-o em .claude/settings.json na pasta do projeto.
  • Usuário e Projeto local: crie-os você mesmo, ou deixe o Claude Code criá-los. Ele escreve ~/.claude/settings.json na primeira vez que você altera uma opção no menu /config que ele armazena em configurações de usuário, como o tema, e .claude/settings.local.json na primeira vez que você dá uma aprovação permanente em um prompt de permissão, como "Sim, e não pergunte novamente" para um comando Bash. Algumas opções /config, incluindo Mostrar dicas, são salvas em .claude/settings.local.json em vez do arquivo de usuário.

[!NOTE]

No Windows, ~/.claude significa %USERPROFILE%\.claude. Para manter os arquivos do diretório home em outro lugar, defina CLAUDE_CONFIG_DIR; o Claude Code então armazena suas configurações, histórico de sessão e plugins lá em vez disso.

O Claude Code também mantém um quinto arquivo, ~/.claude.json, que ele escreve para si mesmo; você não precisa editá-lo. Ele contém os detalhes da sua conta, configurações de servidor MCP, estado por projeto como decisões de confiança, e as chaves de config globais que /config escreve para você.

Compartilhe configurações com sua equipe

Faça commit de .claude/settings.json para que todos que clonem o repositório obtenham as mesmas permissões, hooks e plugins. Cada colega de equipe ainda pode sobrescrevê-lo para si mesmo em seu próprio .claude/settings.local.json, para que exceções pessoais não precisem de um commit. Para um arquivo de equipe completo, veja configurações compartilhadas de uma equipe.

Parte do que você inclui no commit espera até que cada colega de equipe confie na pasta, e algumas chaves nunca entram em vigor de um arquivo de repositório; Solucione problemas de uma configuração que não se aplica cobre ambos.

Mantenha configurações pessoais fora de um repositório

Para alterar uma configuração para você em um projeto sem alterá-la para seus colegas de equipe, salve-a em .claude/settings.local.json dentro do projeto. O Claude Code aplica esse arquivo sobre o .claude/settings.json incluído no commit, então se o arquivo da sua equipe define "model": "claude-sonnet-5" e você quer Opus, coloque "model": "claude-opus-5-5" no seu arquivo local e apenas suas sessões mudam.

O Claude Code também escreve neste arquivo, o mantém fora de seus commits e aplica suas regras allow sem a etapa de confiança:

  • O Claude Code também o escreve. Quando Claude pede permissão para executar um comando Bash e você escolhe "Sim, e não pergunte novamente", o Claude Code salva essa aprovação de permissão aqui como uma regra allow.
  • Você não precisa adicioná-lo ao gitignore você mesmo, a menos que o tenha criado manualmente. Na primeira vez que o Claude Code escreve o arquivo em um repositório git que ainda não o ignora, ele adiciona **/.claude/settings.local.json ao seu arquivo de exclusões git globais, para que o arquivo fique fora de seus commits em cada repositório. Esse arquivo é core.excludesFile quando sua config git global o define para um caminho absoluto ou com prefixo ~; caso contrário é $XDG_CONFIG_HOME/git/ignore, ou ~/.config/git/ignore quando XDG_CONFIG_HOME não está definido. Se você criou o arquivo manualmente e o Claude Code ainda não escreveu nele, adicione-o ao .gitignore você mesmo.
  • Suas regras allow não esperam por confiança enquanto o arquivo permanece não rastreado. Como o arquivo é seu e não do repositório, o Claude Code aplica suas regras allow sem a etapa de confiança do workspace que exige para o arquivo incluído no commit. Se o arquivo for rastreado pelo git, a etapa de confiança também se aplica a ele; veja Quando seu arquivo de configurações local precisa de confiança.

Onde o Claude Code mantém o arquivo local em um repositório git

Quando Claude pede permissão para executar um comando Bash e você escolhe "Sim, e não pergunte novamente", o Claude Code salva essa aprovação como uma regra allow em .claude/settings.local.json. Se você iniciar o Claude Code em um subdiretório de um repositório git, ele lê e escreve esse arquivo na raiz do repositório e aplica a aprovação em todo o repositório. Em um worktree, ele usa o arquivo na raiz do checkout principal.

Duas regras qualificam a localização da raiz:

  • Quando o arquivo fica com .claude/settings.json em vez disso: fora de um repositório git, quando a raiz do repositório é seu diretório home, no Windows ou quando a raiz do repositório ou sua entrada .git ou .claude não é de propriedade do seu usuário.
  • Caminhos no arquivo não ancoram na raiz do repositório: uma regra de permissão que começa com / ou um caminho de sandbox relativo ancora no diretório de trabalho primário da sessão em vez disso.

Antes da v2.1.211, o Claude Code mantinha o arquivo no diretório inicial. Ele ainda lê um arquivo que uma versão anterior deixou lá ao lado do arquivo raiz; onde ambos definem a mesma chave, o valor da raiz se aplica, e regras de permissão de ambos os arquivos se aplicam. O helper resolveSettings() do Agent SDK sempre lê o arquivo do diretório inicial.

O Claude Code lê o .claude/settings.json compartilhado do diretório de trabalho primário da sessão, então para usar um arquivo incluído no commit na raiz do repositório, inicie o Claude Code lá. Depois que você mover a sessão com /cd, o Claude Code lê ambos os arquivos do projeto do novo diretório em vez disso, colocando o arquivo local pelas mesmas regras. Lê-los do diretório para o qual você se moveu requer Claude Code v2.1.246 ou posterior. Para uma sessão de worktree que você inicia a partir do aplicativo desktop, veja O que os worktrees compartilham com o checkout principal.

Verifique o que sua organização impõe

Se sua organização gerencia o Claude Code, algumas configurações são decididas para você e nada que você coloque em seus próprios arquivos as altera. Para ver quais, execute /status: a linha Setting sources nomeia a fonte gerenciada que se aplica a você. As configurações gerenciadas se aplicam onde quer que o Claude Code seja executado nesta máquina; O que um desenvolvedor pode alterar cobre direitos de administrador local e ferramentas diferentes do Claude Code.

As configurações gerenciadas chegam até você através dos mecanismos de entrega na página de configurações gerenciadas, mais comumente:

Em uma sessão Cowork que é executada em sua máquina no aplicativo Claude Desktop, o Claude Code não busca configurações gerenciadas pelo servidor do console de administração claude.ai, e lê a política implantada em seu dispositivo a menos que a configuração Claude Desktop da sua organização defina requireCoworkFullVmSandbox. Onde e quando uma política se aplica cobre Cowork e sessões na nuvem.

Se você é o administrador, Configure o Claude Code para sua organização o guia através da escolha do que impor, e Implante configurações gerenciadas cobre entrega e como confirmar que uma política está em vigor. Para o aviso que o editor de configurações gerenciadas no console de administração claude.ai pode mostrar, veja Configurar configurações gerenciadas pelo servidor.

Altere uma configuração

Você pode alterar uma configuração no menu /config, editando um arquivo de configurações ou para uma sessão a partir da linha de comando.

O prompt do sistema do Claude Code não é publicado. Para dar ao Claude instruções permanentes, use arquivos CLAUDE.md ou a flag --append-system-prompt.

Use o menu /config

Execute /config dentro do Claude Code e abra a aba Config. Ela lista um pequeno conjunto de opções pessoais como tema, modo de editor e saída verbose, não cada chave de configurações. Selecione uma opção para alterá-la; o Claude Code a salva para você:

  • Maioria das opções: ~/.claude/settings.json
  • Algumas opções, como Mostrar dicas: .claude/settings.local.json
  • As opções de config globais: ~/.claude.json

Para definir uma opção sem o menu, passe key=value, como /config verbose=true.

[!NOTE]

/config faz parte da interface do terminal. O painel de chat VS Code e o aplicativo desktop não o abrem; altere as configurações lá editando um arquivo de configurações ou através das configurações desses aplicativos.

Edite um arquivo de configurações

Abra o arquivo de configurações para o escopo que você quer no seu editor e adicione ou altere uma chave. Os arquivos de configurações são JSON rigoroso: um comentário // ou uma vírgula à direita é um erro de sintaxe, e o Claude Code relata o arquivo como um Erro de Configurações na próxima inicialização. Por exemplo, para deixar o Claude Code executar seus comandos lint e test sem perguntar e impedi-lo de ler arquivos .env, adicione isto a ~/.claude/settings.json:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Cada entrada sob permissions é uma regra que nomeia uma ferramenta e o que ela pode fazer; Configurar permissões explica a sintaxe. A linha $schema aponta para o esquema JSON publicado para configurações do Claude Code, que oferece a você preenchimento automático e validação inline no VS Code, Cursor e qualquer outro editor que suporte esquema JSON. O esquema pode ficar atrás dos lançamentos CLI mais recentes, então um aviso de validação em uma chave documentada recentemente não significa que sua configuração é inválida.

Depois que você salvar, execute /status dentro do Claude Code para confirmar que o arquivo foi carregado; Confirme o que foi carregado diz o que a linha Setting sources mostra e como um arquivo quebrado é relatado.

Para um arquivo pessoal completo, arquivo de equipe e arquivo de organização, cada um mostrado com um comentário em cada chave que define, veja os arquivos de configurações de exemplo.

Altere uma configuração para uma sessão

Para tentar um valor sem salvá-lo, defina-o quando você inicia o Claude Code. O valor se aplica a essa sessão e seus arquivos de configurações permanecem como estavam. Você tem três maneiras de fazer isto:

  • --settings: passe uma chave como JSON, inline ou como um caminho para um arquivo. O Claude Code a aplica acima de seus arquivos de usuário, projeto e local e abaixo de configurações gerenciadas. Pode definir qualquer chave que seu arquivo de configurações de usuário pode definir; não pode definir chaves Managed ou Global config.
  • Uma flag para essa chave: algumas chaves têm sua própria flag, como --model para model e --effort para effortLevel e modelSettings.
  • Uma variável de ambiente: exporte a variável emparelhada da chave antes de executar claude, como ANTHROPIC_MODEL para model.

Cada entrada da chave na referência de configurações lista suas substituições por sessão e qual tem precedência, então verifique a entrada para a chave que você quer alterar.

Os comandos que você executa dentro de uma sessão principalmente salvam sua escolha: quando você altera uma configuração em /config, o Claude Code a escreve em seus arquivos de configurações, e /model salva o valor como seu padrão para novas sessões.

Se você pressionar s no seletor /model, o Claude Code muda o modelo sem salvá-lo como seu padrão de usuário. Ajuste o nível de esforço diz quais picks /effort o Claude Code salva como seu padrão para o modelo que você está usando e quais se aplicam apenas à sessão atual.

Por exemplo, para iniciar uma sessão em Opus sem alterar seu padrão:

claude --settings '{"model": "claude-opus-5-5"}'

Quando as edições entram em vigor

O Claude Code observa seus arquivos de configurações e os recarrega quando mudam, para que aplique a maioria das edições à sessão em execução sem uma reinicialização, incluindo edições em permissions, hooks e auxiliares de credenciais como apiKeyHelper. O Claude Code também carrega um arquivo de configurações que você cria no meio da sessão se sua pasta existia quando a sessão começou. Para a pasta .claude/ do projeto, ele carrega o arquivo mesmo quando você cria a pasta na mesma sessão.

O recarregamento cobre configurações de usuário, projeto, local e gerenciadas, e o Claude Code executa o hook ConfigChange para cada mudança de arquivo de configurações que detecta, não para configurações gerenciadas que chegam de MDM ou do console claude.ai. As configurações gerenciadas que chegam através de MDM ou do console claude.ai alcançam uma sessão em execução em um cronograma em vez de ao salvar; a tabela de entrega fornece por fonte.

O Claude Code lê algumas chaves apenas uma vez, na inicialização da sessão, então uma edição em uma delas não alcança a sessão em execução. As chaves do lado do administrador que também esperam por uma reinicialização, como requiredMinimumVersion, são listadas em onde e quando uma política se aplica. As que você provavelmente editará no meio da sessão:

Confirme o que foi carregado

Execute /status dentro do Claude Code para ver quais fontes de configurações estão ativas. A aba Status inclui uma linha Setting sources que lista cada arquivo de configurações que o Claude Code carregou para a sessão atual, como User settings ou Project local settings. Quando configurações gerenciadas estão em vigor, a entrada de configurações gerenciadas mostra entre parênteses como chegaram à sua máquina.

A linha confirma quais arquivos o Claude Code leu; ela não mostra qual arquivo forneceu cada chave. Para listar entradas que o Claude Code rejeitou, execute claude doctor; para um modelo que configurações de projeto ou gerenciadas definem, o cabeçalho de inicialização nomeia o arquivo que o definiu. /status e /config abrem o mesmo diálogo em abas diferentes, e a aba Config não é uma visualização do conteúdo do seu settings.json.

Corrija um arquivo de configurações quebrado

Se você digitar JSON incorretamente ou definir uma chave para um valor que o Claude Code não aceita, o Claude Code o informa no início de uma sessão interativa. O que ele mostra depende de quanto do arquivo é afetado:

  • Erro de Configurações: um arquivo de usuário, projeto ou local tem JSON inválido ou um valor que o esquema rejeita. No início de uma sessão interativa, o Claude Code mostra um diálogo que permite você corrigir o arquivo com a ajuda do Claude, sair ou continuar sem as configurações quebradas.
  • Aviso de Configurações: apenas entradas individuais falham, como uma regra de permissão malformada ou um nome de evento de hook desconhecido. O Claude Code pula esses valores e mantém o resto do arquivo em vigor.
  • Configurações gerenciadas: o Claude Code continua impondo o resto do arquivo. Entradas inválidas em configurações gerenciadas diz o que ele descarta e quais chaves voltam para um valor mais rigoroso até você corrigi-las. Para um documento de configurações gerenciadas que não é JSON válido, veja Documento de configurações gerenciadas não pôde ser analisado.
  • Erro de configuração: ~/.claude.json não pode ser analisado. O Claude Code copia o arquivo quebrado para ~/.claude/backups/.claude.json.corrupted.<timestamp> e pergunta se você quer sair e corrigi-lo manualmente ou redefinir para a configuração padrão; uma execução -p imprime o erro e sai. Para recuperar seu estado anterior, copie de volta um dos cinco arquivos .claude.json.backup.<timestamp> mais recentes em ~/.claude/backups/, que o Claude Code salva antes de escrever o arquivo.

Depois que você continuar, execute /status para ver os arquivos afetados e claude doctor para os detalhes de cada erro.

Uma execução -p não mostra diálogo. A menos que um documento de configurações gerenciadas não possa ser analisado, o Claude Code pula o arquivo ou valores quebrados e continua com o resto, então após uma execução -p que ignora uma configuração, execute claude doctor para ver o que ele descartou.

Precedência de configurações

Quando a mesma chave aparece em mais de um lugar, o Claude Code usa o valor do nível mais alto que a define. A pilha abaixo mostra os níveis, mais alto no topo; uma chave em um nível mais alto substitui a mesma chave em qualquer lugar abaixo.

Settings precedence, highest first: managed settings, command line, project local, shared project, user. A key set at a higher level overrides the same key set lower down.

Em ordem, precedência mais alta primeiro:

  1. Configurações gerenciadas: configurações que sua organização implanta, por um arquivo managed-settings.json, uma política MDM ou configurações gerenciadas pelo servidor do console claude.ai. Nada em seus próprios arquivos de configurações ou em --settings sobrescreve uma chave gerenciada, e uma flag como --model escolhe apenas entre os modelos que sua organização permite. Um model gerenciado é um padrão inicial, não um bloqueio; os bloqueios são availableModels e deniedModels. Quando sua organização entrega mais de uma fonte gerenciada, as regras para precedência dentro do nível gerenciado dizem o que o Claude Code lê de cada uma.
  2. Linha de comando: JSON que você passa com --settings <file-or-json> ao iniciar claude, apenas para essa sessão; veja Altere uma configuração para uma sessão. Uma chave que você define ali sobrescreve a mesma chave em seus arquivos de configurações de projeto e de usuário, e uma chave que você omite mantém seu valor desses arquivos. Outras flags, como --model, definem uma coisa para a sessão e não fazem parte desta pilha; a entrada de uma chave na referência de configurações diz quais flags a sobrescrevem.
  3. Configurações locais de projeto (.claude/settings.local.json): suas configurações pessoais para este projeto.
  4. Configurações compartilhadas de projeto (.claude/settings.json): configurações que sua equipe verifica no controle de origem.
  5. Configurações de usuário (~/.claude/settings.json): suas configurações pessoais para cada projeto.

As variáveis de ambiente não são um nível nesta pilha. Quando um comportamento tem tanto uma variável de shell quanto uma chave de configurações, qual se aplica é decidido por par, não por nível: ANTHROPIC_MODEL exportada em seu shell se aplica sobre a chave model de qualquer arquivo, enquanto ANTHROPIC_DEFAULT_MODEL se aplica apenas quando nenhum arquivo define model. A referência de variáveis de ambiente diz quais chaves têm um par e qual o Claude Code lê primeiro. Um bloco env dentro de um arquivo de configurações é uma chave ordinária e segue os níveis acima.

Para algumas chaves sensíveis à segurança, o Claude Code honra um valor mais rigoroso de um nível inferior sobre um valor gerenciado; Exceções à precedência de configurações gerenciadas as lista.

As listas se mesclam em vez de substituir

Quando você define a mesma chave de lista, como permissions.allow, em mais de um arquivo, o Claude Code combina as listas em vez de escolher uma, para que cada arquivo possa adicionar entradas sem remover as de outro arquivo. Quatro chaves que contêm listas de modelos ou entradas por modelo seguem suas próprias regras:

  • fallbackModel é uma cadeia ordenada onde a posição carrega significado, então o Claude Code toma o valor inteiro do arquivo de precedência mais alta que o define.
  • modelPicker contém uma lista ordenada de linhas mais uma flag de substituição, então o Claude Code nunca mescla linhas de duas fontes. Ele toma o valor inteiro do mais alto de configurações gerenciadas, --settings e configurações de usuário que o define, e ignora a chave em configurações de projeto e local. Requer Claude Code v2.1.242 ou posterior.
  • availableModels: quando as configurações gerenciadas que o Claude Code aplica a definem, o Claude Code aplica essa lista como está e ignora entradas que você adiciona em configurações de usuário, projeto ou local, a menos que um aplicativo que incorpora o Claude Code forneça sua própria lista de modelos; veja Exceções à precedência de configurações gerenciadas. Entre fontes gerenciadas a lista nunca se mescla também; como o Claude Code combina fontes gerenciadas diz qual lista de fonte se aplica. Entre escopos não gerenciados o Claude Code mescla os arrays como usual.
  • modelSettings: o Claude Code o resolve um modelo por vez, junto com effortLevel. A entrada modelSettings afirma qual arquivo de valor se aplica a um modelo.

Exemplos de precedência

Enquanto Claude trabalha, o Claude Code mostra uma dica de uma linha sob o spinner, como "Use /config para alterar seu modo de permissão padrão (incluindo Plan Mode)". Suponha que você queira essas dicas desligadas, então você define spinnerTipsEnabled como false em ~/.claude/settings.json. Cada cenário abaixo é algo que pode ligá-las novamente, e o que você pode fazer sobre isso.

Configurações de equipe substituem configurações pessoais

O .claude/settings.json da sua equipe o define como true. O Claude Code usa o valor do projeto porque o projeto compartilhado fica acima do usuário, então você vê dicas naquele projeto e em nenhum outro lugar.

Você pode recuperar seu valor: adicione "spinnerTipsEnabled": false a .claude/settings.local.json naquele projeto. O projeto local fica acima do projeto compartilhado, então suas sessões lá param de mostrar dicas e as sessões de seus colegas de equipe não mudam.

Configurações da organização substituem tudo

As configurações gerenciadas da sua organização o definem como true. Nada que você coloque em configurações de usuário, projeto ou local desliga as dicas, e nem --settings. Gerenciado é o nível superior.

Você não pode recuperar seu valor. Execute /status para ver qual fonte gerenciada se aplica e pergunte ao seu administrador se a política deve mudar.

A linha de comando substitui seus arquivos para uma sessão

Você iniciou a sessão com claude --settings '{"spinnerTipsEnabled": true}'. A linha de comando fica acima de cada arquivo exceto gerenciado, então essa sessão mostra dicas mesmo que seus arquivos digam false.

Você recupera seu valor na próxima sessão; --settings dura uma sessão e não escreve em nenhum arquivo.

Uma flag ou variável de ambiente define a mesma coisa

Algumas chaves têm uma flag de linha de comando ou uma variável de ambiente que substitui o valor de configurações independentemente de qual arquivo o definiu: ANTHROPIC_MODEL substitui a configuração model, e --model substitui ambas para uma sessão.

Se você pode recuperar seu valor depende da chave: desdefina a variável ou solte a flag, e verifique a entrada da chave na referência de configurações e a linha da variável na referência de variáveis de ambiente para qual o Claude Code usa.

Solucione problemas de uma configuração que não se aplica

Quando você define uma chave e o Claude Code não se comporta como se você tivesse, comece com /status para ver quais arquivos ele carregou, então encontre seu sintoma abaixo. Depure sua configuração cobre as verificações mais amplas, incluindo um teste de configuração limpa.

Um valor que você define é ignorado

Algo mais está definindo a mesma chave, o arquivo não pode definir esse valor ou o arquivo não foi carregado:

  • Um nível mais alto o define. Outro arquivo de configurações, uma flag --settings ou uma fonte gerenciada define a chave acima da sua; a pilha diz qual. Uma flag ou variável de ambiente também pode substituir a chave por conta própria, decidido chave por chave; a entrada da chave na referência de configurações diz qual o Claude Code usa, e a entrada env cobre um valor env gerenciado versus uma exportação de shell.

  • Uma chave de segurança mantém seu valor rigoroso. Para algumas chaves o Claude Code honra o valor restritivo de qualquer arquivo, então um projeto true para disableClaudeAiConnectors permanece ligado; veja Exceções à precedência de configurações gerenciadas.

  • O arquivo não pode definir esse valor. Os valores permissions.defaultMode auto e bypassPermissions não entram em vigor de configurações de projeto ou local; defina-os em configurações de usuário ou gerenciadas em vez disso, ou passe --permission-mode para uma sessão. Antes da v2.1.257, bypassPermissions entrava em vigor de qualquer arquivo.

    Uma variável de exportação de telemetria em um bloco env também não entra em vigor de configurações de projeto ou local, exceto por alguns valores desligados. Variáveis que o Claude Code ignora em env lista as variáveis e esses valores.

  • O arquivo está quebrado. JSON inválido ou um valor rejeitado faz o Claude Code pular o arquivo ou a entrada; veja Corrija um arquivo de configurações quebrado.

Uma mudança que você fez no Claude Code é perdida em novas sessões

Quando você salva uma escolha para novas sessões dentro do Claude Code, como um modelo padrão com /model, o Claude Code a escreve em seu arquivo de configurações de usuário, ~/.claude/settings.json. Se você não pode escrever naquele arquivo, por exemplo porque outra ferramenta o gera ou o vincula a uma cópia somente leitura, a mudança se aplica à sessão atual e é perdida na próxima. Defina a chave na ferramenta que gera o arquivo, ou substitua o arquivo por um que você possa escrever.

Se você pode escrever no arquivo e a mudança ainda não dura, verifique se a mudança foi apenas para uma sessão ou um nível mais alto define a mesma chave. Para a chave model, Uma nova sessão inicia em um modelo diferente do que você escolheu lista mais causas.

Uma mudança gerenciada não chegou até você

As fontes gerenciadas alcançam uma sessão em execução no cronograma na tabela de entrega, então reinicie a sessão primeiro. Se /status então nomeia uma fonte diferente da que seu administrador alterou, uma fonte de prioridade mais alta se aplica; Como o Claude Code combina fontes gerenciadas fornece a ordem.

Uma chave confirmada não alcança colegas de equipe

Duas coisas mantêm uma chave em .claude/settings.json de se aplicar para todos que a clonam:

  • O Claude Code ignora a chave em um arquivo de repositório. Procure por User, local, or managed, User or managed, User, Managed ou Global config na coluna Scope do índice de configurações. Essas chaves nunca se aplicam do arquivo compartilhado, exceto por algumas que um arquivo de repositório ainda pode desligar. Cada uma dessas entradas diz assim em sua linha de Scope. As chaves Global config se aplicam apenas de ~/.claude.json.

    Dentro da chave env, as variáveis de exportação de telemetria nunca se aplicam do arquivo compartilhado também, exceto por alguns valores desligados; veja Variáveis que o Claude Code ignora em env.

  • A chave espera por confiança. As regras permissions.allow, permissions.additionalDirectories, extraKnownMarketplaces e a maioria dos valores env se aplicam apenas depois que cada colega de equipe confia na pasta. Até então eles ainda veem prompts e não obtêm plugins de um marketplace que o arquivo declara. As regras deny e ask se aplicam imediatamente.

As regras de permissão se combinam diferentemente do que você esperava

  • Você escolheu "Sim, e não pergunte novamente" em um prompt de permissão mas ainda recebe prompts para a mesma ferramenta. Essa escolha salvou uma regra allow em seu arquivo local, e uma regra allow lá não supera uma regra ask de um arquivo de projeto ou gerenciado; como as regras de permissão se combinam explica a ordem. Na extensão VS Code o cartão de aprovação permite você escolher o arquivo de destino, incluindo o arquivo compartilhado do projeto, que muda a regra para todos; no CLI, o Claude Code escreve apenas em seu arquivo local.
  • As regras allow da sua organização ainda se aplicam ao lado das suas. Isso é esperado: o Claude Code mescla permissions.allow entre escopos, a menos que sua organização defina allowManagedPermissionRulesOnly.

Exceções à precedência de configurações gerenciadas

Para algumas chaves cujos valores restringem uma sessão, o Claude Code honra um valor restritivo de um escopo que de outra forma não poderia substituir configurações gerenciadas. Encontre a chave nesta tabela para ver qual valor ele honra e de onde.

Chave Valor que o Claude Code honra Notas
disableClaudeAiConnectors true de qualquer escopo Honrado mesmo quando uma fonte gerenciada define false
enableArtifact false de qualquer escopo, e disableArtifact: true de qualquer escopo Honrado mesmo quando uma fonte gerenciada define true; nada liga a ferramenta Artifact de volta. Requer Claude Code v2.1.242 ou posterior
isolatePeerMachines true de qualquer escopo Honrado mesmo quando uma fonte gerenciada define false
permissions.blockReadsOutsideWorkingDirectories true de qualquer escopo Honrado mesmo quando uma fonte gerenciada define false. Requer Claude Code v2.1.257 ou posterior
autoMode.classifyAllShell true de ~/.claude/settings.json ou --settings Honrado mesmo quando uma fonte gerenciada define false
remoteControlAtStartup false de .claude/settings.json ou .claude/settings.local.json Honrado mesmo quando uma fonte gerenciada define true; um true de projeto ou local é ignorado
crossSessionInbound Um valor mais rigoroso de .claude/settings.json ou .claude/settings.local.json, na escada accept < hold < refuse Honrado sobre valores gerenciados, --settings e de usuário; um valor de projeto ou local que não é mais rigoroso é ignorado
useAutoModeDuringPlan false de qualquer fonte gerenciada, --settings, ~/.claude/settings.json ou .claude/settings.local.json Honrado mesmo quando a fonte gerenciada vencedora define true; um false em .claude/settings.json é ignorado
syncClaudeAiSkills false de qualquer fonte gerenciada, --settings, ~/.claude/settings.json ou .claude/settings.local.json Honrado mesmo quando a fonte gerenciada vencedora define true; um false em .claude/settings.json é ignorado
syncClaudeAiPlugins false de qualquer fonte gerenciada, --settings, ~/.claude/settings.json ou .claude/settings.local.json Honrado mesmo quando a fonte gerenciada vencedora define true; um false em .claude/settings.json é ignorado
maxEffortLevel Um limite inferior de qualquer escopo, incluindo --settings Honrado mesmo quando as configurações gerenciadas que o Claude Code aplica definem um limite superior; o limite inferior se aplica. Requer Claude Code v2.1.267 ou posterior

Um aplicativo que executa o Claude Code dentro de si e define CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST também é uma exceção. O Claude Code toma a configuração de modelo daquele aplicativo sobre as chaves model, fallbackModel, modelPicker e modelOverrides de cada fonte gerenciada, e sobre as variáveis de seleção de modelo em um bloco env gerenciado, como ANTHROPIC_MODEL e a família ANTHROPIC_DEFAULT_*_MODEL. O Claude Code mantém uma allowlist availableModels gerenciada em vigor a menos que o aplicativo forneça a sua própria.

Configurações em sessões em nuvem

Uma sessão em nuvem é executada em um ambiente em nuvem em um clone fresco do seu repositório, não em sua máquina. Isso muda quais configurações a alcançam:

  • Threads na nuvem em um projeto: em uma thread na nuvem em um projeto, nenhuma das regras de permissão, hooks ou env do .claude/settings.json de um repositório se aplica, independentemente de quantos repositórios o projeto tenha. O que as threads obtêm dos seus repositórios lista o que usar em vez disso.
  • Configurações compartilhadas de projeto (.claude/settings.json): lidas em uma sessão com um repositório fora das threads de um projeto, porque o arquivo faz parte do clone e a sessão começa dentro dele. Faça commit de uma configuração lá para aplicá-la nessas sessões.
  • Configurações compartilhadas de projeto com vários repositórios: em um ambiente hospedado pela Anthropic, uma sessão com vários repositórios começa acima dos clones e lê apenas as chaves enabledPlugins e extraKnownMarketplaces do .claude/settings.json de cada repositório, não regras de permissão, hooks, env ou outras chaves. Os marketplaces e plugins que essas duas chaves declaram ainda não carregam em uma sessão na nuvem. Para um ambiente auto-hospedado, consulte quais configurações de repositório se aplicam.
  • Configurações de usuário e projeto local (~/.claude/settings.json e .claude/settings.local.json): não lidas. Ambas permanecem em sua máquina, e o arquivo local não está no clone.
  • Configurações gerenciadas: um arquivo managed-settings.json ou perfil MDM em seu dispositivo não alcança uma sessão em nuvem. As configurações gerenciadas pelo servidor da sua organização alcançam; cobertura de superfície lista quais sessões em nuvem as recebem. Um ambiente auto-hospedado também lê o arquivo de configurações gerenciadas em sua imagem de runner. Como o Claude Code combina fontes gerenciadas diz quando esse arquivo se aplica.
  • /config: no seu navegador em claude.ai/code, abre a seção Claude Code de suas configurações claude.ai em vez de alterar um valor. Para alterar uma configuração para uma sessão na nuvem, defina uma variável de ambiente no ambiente. Em uma sessão com um repositório fora das threads de um projeto, você pode, em vez disso, fazer commit da chave no .claude/settings.json desse repositório.

O que é transferido de sua configuração lista o resto: CLAUDE.md, skills, servidores MCP, plugins e credenciais.

Próximos passos