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.
export const SettingsPrecedence = () => {
const LEVELS = [{
n: 1,
name: 'Managed settings',
file: 'managed-settings.json, MDM, or the claude.ai console',
who: 'Your organization',
w: 390
}, {
n: 2,
name: 'Command line',
file: 'claude --settings',
who: 'You, this session',
w: 420
}, {
n: 3,
name: 'Project local',
file: '.claude/settings.local.json',
who: 'You, this project',
w: 480
}, {
n: 4,
name: 'Shared project',
file: '.claude/settings.json',
who: 'Everyone in the project',
w: 540
}, {
n: 5,
name: 'User',
file: '~/.claude/settings.json',
who: 'You, every project',
w: 600
}];
const W = 760;
const ROW = 58;
const GAP = 8;
const TOP = 34;
const H = TOP + LEVELS.length * (ROW + GAP) + 30;
const cx = W / 2;
const mono = 'var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace)';
const sans = 'var(--font-sans, system-ui, -apple-system, sans-serif)';
return
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.
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.
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, confirme-o 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
Todos em sua organização para os quais é implantado; nada que você defina o substitui, exceto algumas exceções sensíveis à segurança
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 em 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.
~/.claude/settings.json: cada projeto em sua máquina, e nada no de seu colega de equipe ou na sessão em nuvem
acme-app/.claude/settings.json: seu acme-app/. Alcança o clone do seu colega de equipe e a sessão em nuvem apenas se você confirmar o 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 em 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 confirmado. 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.
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 sua sessão de entrada, 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
Confirme .claude/settings.json para que todos que clonem o repositório obtenham as mesmas permissões, hooks, telemetria e plugins. Cada colega de equipe ainda pode substituí-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.
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 confirmado, 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 de permissão 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 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 confirmado. 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 uma 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.
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 confirmado 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.
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 em nuvem.
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
Para definir uma opção sem o menu, passe key=value, como /config verbose=true.
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:
model: use /model para mudar no meio da sessão. Cada modelo tem seu próprio cache de prompt, então a primeira solicitação após uma mudança relê toda a conversa sem cache; veja Mudando modelos
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.
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.
Em ordem, precedência mais alta primeiro:
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 que você defina as substitui: uma chave que você passa com --settings não substitui a mesma chave gerenciada, e uma flag como --model escolhe apenas entre os modelos que sua organização permite. Uma model gerenciada define o modelo com o qual cada sessão inicia, e você ainda pode mudar com /model; o bloqueio é availableModels, que restringe /model, --model e a chave model em seus próprios arquivos. 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.
Argumentos de linha de comando: flags que você passa quando inicia claude de um terminal, para uma sessão; veja Altere uma configuração para uma sessão. O Claude Code mescla JSON que você passa com --settings <file-or-json> com seus arquivos de configurações pelas mesmas regras que os outros níveis: ele toma uma chave que você define aqui sobre a mesma chave em configurações local, projeto ou usuário, e mantém o valor de nível inferior para uma chave que você omite.
Configurações locais de projeto (.claude/settings.local.json): suas configurações pessoais para este projeto.
Configurações compartilhadas de projeto (.claude/settings.json): configurações que sua equipe verifica no controle de origem.
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.
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.
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.
O arquivo não pode definir esse valor. Os valores permissions.defaultModeauto 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 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.
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, 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.
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.
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 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:
Configurações compartilhadas de projeto (.claude/settings.json): lidas em uma sessão com um repositório, porque o arquivo faz parte do clone e a sessão começa dentro dele. Confirme uma configuração lá para aplicá-la nessas sessões. 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 em nuvem.
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.
/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 em nuvem, defina uma variável de ambiente no ambiente, ou em uma sessão com um repositório, confirme a chave no .claude/settings.json desse repositório.
Referência do diretório Claude: cada arquivo que o Claude Code lê, incluindo subagents, servidores MCP, plugins e CLAUDE.md
settings.md+3−3
468 Mantenha configurações pessoais fora de um repositório468 Mantenha configurações pessoais fora de um repositório
469</h3>469</h3>
470470
471Para 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` confirmado, então se o arquivo da sua equipe define `"model": "claude-sonnet-5"` e você quer Opus, coloque `"model": "claude-opus-4-8"` no seu arquivo local e apenas suas sessões mudam.471Para 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` confirmado, 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.
472472
473O Claude Code também escreve neste arquivo, o mantém fora de seus commits e aplica suas regras de permissão sem a etapa de confiança:473O Claude Code também escreve neste arquivo, o mantém fora de seus commits e aplica suas regras de permissão sem a etapa de confiança:
474474
598Por exemplo, para iniciar uma sessão em Opus sem alterar seu padrão:598Por exemplo, para iniciar uma sessão em Opus sem alterar seu padrão:
804Uma [sessão em nuvem](/docs/pt/claude-code-on-the-web) é executada em um [ambiente em nuvem](/docs/pt/cloud-environments) em um clone fresco do seu repositório, não em sua máquina. Isso muda quais configurações a alcançam:804Uma [sessão em nuvem](/docs/pt/claude-code-on-the-web) é executada em um [ambiente em nuvem](/docs/pt/cloud-environments) em um clone fresco do seu repositório, não em sua máquina. Isso muda quais configurações a alcançam:
805805
806* **Configurações compartilhadas de projeto** (`.claude/settings.json`): lidas em uma sessão com um repositório, porque o arquivo faz parte do clone e a sessão começa dentro dele. Confirme uma configuração lá para aplicá-la nessas sessões. Uma sessão com vários repositórios começa acima dos clones,entãodecada `.claude/settings.json` do repositório ela carrega apenas os plugins e marketplaces que oarquivodeclara, não regras de permissão, hooks, `env` ou outras chaves;veja[O que étransferidodesuaconfiguração](/docs/pt/cloud-environments#what-carries-over-from-your-setup).806* **Configurações compartilhadas de projeto** (`.claude/settings.json`): lidas em uma sessão com um repositório, porque o arquivo faz parte do clone e a sessão começa dentro dele. Confirme uma configuração lá para aplicá-la nessas sessões. Uma sessão com vários repositórios começa acima dos clones elêapenasas chaves `enabledPlugins` e `extraKnownMarketplaces` do `.claude/settings.json` decadarepositório, não regras de permissão, hooks, `env` ou outras chaves.Osmarketplacese plugins que essasduaschavesdeclaramainda [não carregam em uma sessão em nuvem](/docs/pt/cloud-environments#what-carries-over-from-your-setup).
807* **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.807* **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.
808* **Configurações gerenciadas**: apenas [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) alcançam uma sessão em nuvem; um arquivo `managed-settings.json` ou perfil MDM em seu dispositivo não. Um [ambiente auto-hospedado](/docs/pt/self-hosted-environments) também lê o arquivo de configurações gerenciadas em sua imagem de runner. [Como o Claude Code combina fontes gerenciadas](/docs/pt/managed-settings#how-claude-code-combines-managed-sources) diz quando esse arquivo se aplica.808* **Configurações gerenciadas**: apenas [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) alcançam uma sessão em nuvem; um arquivo `managed-settings.json` ou perfil MDM em seu dispositivo não. Um [ambiente auto-hospedado](/docs/pt/self-hosted-environments) também lê o arquivo de configurações gerenciadas em sua imagem de runner. [Como o Claude Code combina fontes gerenciadas](/docs/pt/managed-settings#how-claude-code-combines-managed-sources) diz quando esse arquivo se aplica.
809* **`/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 em nuvem, defina uma [variável de ambiente](/docs/pt/cloud-environments#set-environment-variables) no ambiente, ou em uma sessão com um repositório, confirme a chave no `.claude/settings.json` desse repositório.809* **`/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 em nuvem, defina uma [variável de ambiente](/docs/pt/cloud-environments#set-environment-variables) no ambiente, ou em uma sessão com um repositório, confirme a chave no `.claude/settings.json` desse repositório.