Todas as configurações

Referência completa para cada chave settings.json do Claude Code: onde cada uma vai, seu tipo e padrão, e um exemplo pronto para colar, com um índice de cada chave.

Voltar ao índice

Esta página de referência lista cada chave que Claude Code lê de um arquivo de configurações, além do pequeno grupo de chaves que mantém em ~/.claude.json. Para escolher um arquivo ou verificar a precedência, comece com Arquivos de configurações e precedência.

Índice de configurações

Cada chave abaixo está vinculada à sua entrada. O escopo lista os arquivos em que pode estar: User é ~/.claude/settings.json, Project é .claude/settings.json, Local é .claude/settings.local.json, e Managed é o que sua organização implanta. Any file significa todos os quatro, e Global config significa ~/.claude.json.

Modelo e respostas

Escolha quais modelos o Claude Code usa e como ele responde. Para saber como essas configurações interagem com o comando /model e variáveis de ambiente, consulte Configuração de modelo.

advisorModel

Escolha qual modelo responde quando Claude chama a ferramenta advisor do lado do servidor. Deixe-a sem definir para desativar o advisor. O advisor deve ser pelo menos tão capaz quanto seu modelo principal. Consulte Escolha um modelo advisor para os emparelhamentos aceitos e o que acontece quando você escolhe um que não é aceito.

Você normalmente não edita essa chave manualmente. Execute /advisor para abrir um seletor que mostra a escolha atual, os modelos que podem aconselhar e Sem advisor. Claude Code salva sua escolha nessa chave em ~/.claude/settings.json. Se você escolher em um cliente Remote Control ou em uma sessão anexada a um worker remoto, a escolha se aplica apenas a essa sessão e não altera essa chave.

Se sua conta exigir o consentimento de créditos de uso, aceite-o primeiro executando /model fable. Até fazer isso, escolher Fable em /advisor não salva nada e Claude Code diz para executar /model fable primeiro.

• Escopo: Qualquer arquivo
• Tipo: string, um dos aliases "fable", "opus" ou "sonnet", que resolvem para a versão padrão atual do Claude Code dessa família de modelos, ou um ID de modelo completo como "claude-opus-5-5"
• Padrão: sem definir, então o advisor está desativado
• Substituições por sessão: --advisor tem precedência sobre essa chave para uma sessão. CLAUDE_CODE_DISABLE_ADVISOR_TOOL desativa o advisor, e essa chave não pode ativá-lo novamente

{
  "advisorModel": "opus"
}

A chave não tem efeito em provedores onde o advisor não está disponível, como Amazon Bedrock e Claude Platform na AWS. "fable" requer acesso a Fable.

alwaysThinkingEnabled

Desative o pensamento estendido para cada sessão definindo isso como false. O pensamento está ativado por padrão, então true não muda nada. A maioria das pessoas define isso através de /config em vez de editar o arquivo.

Em modelos que sempre pensam, como Opus 5.5, Sonnet 5.5, Haiku 5.5 e os modelos Fable, false não tem efeito. Em provedores de terceiros, Claude Code omite o parâmetro thinking em vez de desativar o pensamento, então modelos de raciocínio adaptativo podem ainda pensar. Com o pensamento desativado na API Anthropic, Claude Code envia esforço high em vez de um nível superior para modelos que sabe não aceitam essa combinação, como Opus 5.

• Escopo: Qualquer arquivo
• Tipo: Boolean
  • true: sem efeito; o pensamento já está ativado
  • false: Claude Code desativa o pensamento estendido para cada sessão
• Padrão: sem definir, então o pensamento está ativado para modelos que o suportam
• Substituições por sessão: MAX_THINKING_TOKENS tem precedência sobre essa chave para uma sessão: 0 desativa o pensamento, sob os mesmos limites de modelo e provedor que false, e um valor positivo ativa o pensamento mesmo quando essa chave é false. Em modelos de raciocínio adaptativo, o número em si é ignorado

{
  "alwaysThinkingEnabled": false
}

availableModels

Restrinja quais modelos as pessoas podem selecionar para a sessão principal, subagentes, skills e o advisor. Uma lista gerenciada restringe /model, --model e a chave model nos próprios arquivos de um desenvolvedor; um modelo fora dela não pode ser selecionado. Com a correspondência de prefixo padrão, isso não afeta a opção Padrão por si só; combine-o com enforceAvailableModels para isso.

• Escopo: Qualquer arquivo. Implante-o em configurações gerenciadas para aplicá-lo a uma organização.
• Tipo: array de aliases de modelo ou IDs
• Padrão: sem definir, então cada modelo está disponível

Este exemplo permite que as pessoas selecionem apenas modelos Sonnet e Haiku:

{
  "availableModels": ["sonnet", "haiku"]
}

Uma entrada de ID de modelo como "claude-opus-5" também permite versões posteriores que a estendem, como Opus 5.5. Para bloquear uma dessas versões, use deniedModels. Para fazer cada entrada de ID de modelo permitir apenas a versão que ela nomeia, use availableModelsMatch. Consulte Restrinja a seleção de modelo. Para IDs de provedores de terceiros, consulte Fixe modelos para implantações de terceiros.

availableModelsMatch

Escolha como as entradas availableModels correspondem aos IDs de modelo. Por padrão, uma entrada de ID de modelo também permite versões posteriores que a estendem, então "claude-opus-5" permite Opus 5.5. Com "exact", cada entrada de ID de modelo permite apenas a versão que ela nomeia, então uma versão mais nova desse modelo permanece bloqueada até você listá-la. Requer Claude Code v2.1.283 ou posterior.

• Escopo: Gerenciado. Claude Code ignora a chave em configurações de usuário, projeto e local e em --settings, com um aviso
• Tipo: string, um de:
  • "prefix": uma entrada de ID de modelo permite sua versão e qualquer ID de modelo que a estenda com outro segmento
  • "exact": uma entrada de ID de modelo permite apenas a versão que ela nomeia, então "claude-opus-5" permite Opus 5 mas não claude-opus-5-5. Uma entrada como "claude-opus-4-5" também permite seu ID de modelo Anthropic datado claude-opus-4-5-20251101. Um alias de família como "opus" ainda permite toda a família, e entradas best, opusplan e default são ignoradas
• Padrão: "prefix"

Este exemplo permite Opus 5 e Sonnet 5 e nenhuma versão posterior de nenhum deles:

{
  "availableModels": ["claude-opus-5", "claude-sonnet-5"],
  "availableModelsMatch": "exact"
}

Com "exact", a opção Padrão também é limitada aos modelos listados sempre que a lista nomeia pelo menos um modelo ou família. Consulte Bloqueie modelos ou versões específicas.

deniedModels

Bloqueie modelos específicos, com ou sem uma lista de permissões availableModels e mesmo quando essa lista os permite. Claude Code oculta um modelo bloqueado do seletor /model, e o modelo não pode ser selecionado em nenhum lugar onde availableModels é aplicado. Uma sessão na opção Padrão também não executa um modelo bloqueado, como Bloqueie modelos ou versões específicas descreve. Requer Claude Code v2.1.283 ou posterior.

• Escopo: Gerenciado. Claude Code ignora a chave em configurações de usuário, projeto e local e em --settings, com um aviso
• Tipo: array de aliases de modelo ou IDs
  • Um alias de família como "opus" bloqueia cada modelo nessa família
  • Um ID de modelo como "claude-opus-5-5" bloqueia essa versão em cada grafia, incluindo IDs datados e específicos do provedor
  • Um ID de modelo sem versão menor, como "claude-opus-5", também bloqueia versões menores posteriores como Opus 5.5. Escreva "claude-opus-5-0" para bloquear apenas Opus 5
  • Entradas best, opusplan e default são ignoradas
• Padrão: sem definir, então nenhum modelo é bloqueado

Este exemplo permite modelos Opus e Sonnet e bloqueia Opus 5.5:

{
  "availableModels": ["opus", "sonnet"],
  "deniedModels": ["claude-opus-5-5"]
}

Consulte Bloqueie modelos ou versões específicas.

effortLevel

Defina um nível de esforço padrão para modelos para os quais você não salvou um nível. Níveis mais baixos são mais rápidos e mais baratos em tarefas diretas, e níveis mais altos raciocinam mais profundamente em problemas complexos.

Quando você executa /effort low, medium, high ou xhigh em uma sessão interativa em sua máquina, Claude Code salva o nível para o modelo ativo em modelSettings em vez de escrever essa chave. Antes da v2.1.251, /effort escrevia essa chave.

Dentro do mesmo arquivo de configurações, Claude Code usa o nível salvo de um modelo em vez dessa chave. modelSettings indica a precedência entre arquivos.

Em uma sessão anexada a um worker remoto, em uma execução -p e no Agent SDK, /effort se aplica apenas a essa sessão. Ajuste o nível de esforço lista as escolhas interativas que também se aplicam apenas a essa sessão. A mensagem que /effort imprime diz qual aconteceu.

• Escopo: Qualquer arquivo
• Tipo: string, um de:
  • "low": o mínimo de raciocínio, para tarefas curtas, delimitadas, sensíveis à latência que não são sensíveis à inteligência
  • "medium": reduz o uso de tokens para trabalho sensível a custos que pode fazer trade-off de alguma inteligência
  • "high": equilibra o uso de tokens e inteligência
  • "xhigh": raciocínio mais profundo com maior gasto de tokens
• Padrão: sem definir
• Substituições por sessão: --effort tem precedência sobre essa chave para uma sessão, e CLAUDE_CODE_EFFORT_LEVEL tem precedência sobre ambas

{
  "effortLevel": "xhigh"
}

Em suas configurações de usuário, ~/.claude/settings.json, essa chave é a forma mais antiga que /effort escrevia antes de salvar níveis por modelo, e continua se aplicando onde se aplicava antes, em Opus 5, Fable 5.1 e modelos anteriores. Opus 5.5 e modelos lançados após ele a ignoram e começam em seu próprio padrão até você salvar um nível para eles, que /effort escreve em modelSettings. Em configurações de projeto, local e gerenciada, e com --settings, essa chave se aplica a cada modelo.

enforceAvailableModels

O seletor /model tem uma opção Padrão, e default model setting descreve o modelo ao qual ela resolve. Uma lista de permissões availableModels limita os modelos que você pode nomear, mas com a correspondência de prefixo padrão ela não remapeia o padrão do seu tipo de conta, então Padrão ainda pode resolver para um modelo fora da lista. Esta chave fecha essa lacuna. Requer Claude Code v2.1.175 ou posterior.

Quando sua organização implanta qualquer configuração gerenciada, Claude Code lê essa chave apenas da fonte gerenciada e a ignora em seus outros arquivos.

Para saber como essa chave se aplica às verificações de modelo na inicialização, consulte Amazon Bedrock e Agent Platform do Google Cloud.

• Escopo: Qualquer arquivo
• Tipo: Boolean
  • true: quando Padrão resolveria para um modelo fora de availableModels, Claude Code o resolve para o primeiro modelo disponível na lista
  • false: esta chave não muda como Padrão resolve
• Padrão: false

Este exemplo restringe seleções nomeadas a modelos Sonnet e Haiku e faz Padrão resolver para o primeiro deles que está disponível:

{
  "availableModels": ["sonnet", "haiku"],
  "enforceAvailableModels": true
}

Esta chave não tem efeito quando availableModels está sem definir ou vazio. Consulte Aplique a lista de permissões ao modelo Padrão. Requer Claude Code v2.1.175 ou posterior.

fallbackModel

Nomeie modelos de backup para Claude Code tentar, em ordem, quando seu modelo principal está sobrecarregado ou indisponível. Claude Code muda para o próximo modelo disponível na cadeia para o resto da volta e mostra um aviso. Sem uma cadeia, Claude Code tenta novamente o mesmo modelo e depois exibe o erro do servidor, e você tenta novamente ou muda de modelos você mesmo.

Uma mudança significa uma volta com um cache de prompt frio no modelo de fallback; sua próxima mensagem tenta o modelo principal primeiro novamente.

• Escopo: Qualquer arquivo
• Tipo: array de aliases de modelo ou IDs; "default" expande para o modelo padrão
• Padrão: sem definir, então uma solicitação falhada não é tentada novamente em outro modelo
• Substituições por sessão: --fallback-model tem precedência sobre essa chave para uma sessão

Este exemplo tenta Sonnet 5 primeiro, depois Haiku 4.5, quando seu modelo principal falha:

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

Diferentemente da maioria das configurações de array, essa chave não mescla entre arquivos de configurações: o arquivo de maior precedência que a define fornece toda a cadeia. Se seu arquivo de projeto define ["claude-sonnet-5"] e seu arquivo de usuário define ["claude-haiku-4-5"], a cadeia é apenas ["claude-sonnet-5"]. Claude Code mantém no máximo três modelos distintos permitidos da lista e ignora o resto. Consulte Cadeias de modelo de fallback.

fastMode

Ative o modo rápido para sessões onde está disponível, para trabalho interativo como iteração rápida ou depuração ao vivo onde você quer velocidade a um custo mais alto por token. Você normalmente não edita essa chave manualmente: executar /fast escreve fastMode: true em ~/.claude/settings.json, e executá-lo novamente para desativar o modo rápido remove a chave. O modo rápido funciona apenas em Opus 5.5, Opus 5 e Opus 4.8: ativá-lo de outro modelo o muda para Opus, e mudar para um modelo não suportado o desativa. Consulte Mude de modelos enquanto o modo rápido está ativado.

• Escopo: Qualquer arquivo
• Tipo: Boolean
  • true: Claude Code ativa o modo rápido para sessões onde está disponível
  • false: o modo rápido permanece desativado
• Padrão: sem definir, então o modo rápido está desativado
• Substituições por sessão: CLAUDE_CODE_DISABLE_FAST_MODE desativa o modo rápido para uma sessão, e essa chave não pode ativá-lo novamente

{
  "fastMode": true
}

fastModePerSessionOptIn

Normalmente, executar /fast salva fastMode nas configurações de usuário de uma pessoa, então o modo rápido está ativado no início de cada sessão posterior. Defina essa chave como true para parar isso: um fastMode: true salvo não ativa mais o modo rápido no início da sessão, e cada pessoa tem que executar /fast em cada sessão que o quer. Claude Code deixa a chave fastMode em seu arquivo, então desativar essa chave restaura o comportamento antigo.

Proprietários em planos Team ou Enterprise podem implantá-lo em toda a organização através de configurações gerenciadas pelo servidor. Quando as configurações gerenciadas definem a chave, /fast on é recusado fora de sessões de terminal interativas e relata que sua organização desativou o modo rápido. Isso cobre modo não interativo, a extensão VS Code e sessões na nuvem.

• Escopo: Qualquer arquivo
• Tipo: Boolean
  • true: um fastMode: true salvo não ativa mais o modo rápido no início da sessão, então cada pessoa executa /fast em cada sessão que o quer; um fastMode: true passado com --settings ainda conta para essa sessão a menos que as configurações gerenciadas definam essa chave
  • false: um fastMode: true salvo ativa o modo rápido no início de cada sessão posterior
• Padrão: false

{
  "fastModePerSessionOptIn": true
}

Consulte Exija opt-in por sessão.

language

Faça Claude responder em um idioma diferente do inglês por padrão. Não há lista fixa para respostas: Claude Code passa o valor verbatim para Claude como uma instrução para sempre responder nesse idioma, então qualquer nome de idioma que Claude possa ler funciona. Claude Code não verifica o valor, então um nome digitado incorretamente chega a Claude como escrito em vez de produzir um erro. O mesmo valor define o idioma para ditado de voz, que tem uma lista fixa de idiomas de ditado suportados, e para títulos de sessão gerados automaticamente.

• Escopo: Qualquer arquivo
• Tipo: string, qualquer nome de idioma, como "japanese", "spanish" ou "french"; Claude Code não o valida
• Padrão: sem definir; os títulos de sessão então correspondem ao idioma de sua conversa

{
  "language": "japanese"
}

maxEffortLevel

Limite o nível de esforço que uma sessão pode usar, deixando níveis mais baixos disponíveis. Qualquer nível mais alto funciona no limite em vez disso, incluindo um de /effort, o seletor /model, --effort, CLAUDE_CODE_EFFORT_LEVEL, a frontmatter effort de uma skill ou subagente, ou o padrão do próprio modelo. Claude Code aplica o limite em si antes de cada solicitação, então ele se mantém em cada provedor, incluindo Amazon Bedrock, Agent Platform do Google Cloud e Microsoft Foundry. Requer Claude Code v2.1.267 ou posterior.

• Escopo: Qualquer arquivo. Implante-o em configurações gerenciadas para aplicá-lo a uma organização. Quando vários escopos definem um limite, o mais baixo se aplica, então um limite definido em um escopo não pode ser aumentado de outro
• Tipo: string, um de "low", "medium", "high", "xhigh" ou "max". Um valor "max" não define limite
• Padrão: sem definir, então nenhum limite se aplica
• Limites por modelo: adicione maxEffortLevel à entrada modelSettings de um modelo. Essa entrada substitui essa chave apenas para o modelo dentro da fonte de configurações que define ambas, como suas configurações de usuário ou uma fonte gerenciada. Defina "max" lá para isentar o modelo do limite dessa fonte; Claude Code ainda aplica limites de outras fontes

Este exemplo limita cada modelo a medium e isenta Sonnet 4.6:

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

Quando sua organização também define um limite de esforço para um modelo, o menor dos dois limites se aplica.

model

Defina o modelo que cada nova sessão usa, então você não tem que escolher um com /model cada vez. Defini-lo aqui não o impede de mudar no meio da sessão. Se seu admin definiu um modelo padrão da organização para substituir a seleção do usuário, você obtém esse modelo mesmo quando define essa chave em configurações de usuário, projeto ou local.

• Escopo: Qualquer arquivo
• Tipo: string, um alias de modelo ou ID de modelo completo
• Padrão: sem definir, então Claude Code usa o modelo padrão de sua conta
• Substituições por sessão: --model tem precedência sobre ANTHROPIC_MODEL, e ambos têm precedência sobre essa chave para uma sessão, incluindo sobre um model gerenciado; uma lista availableModels ainda se aplica à escolha

{
  "model": "claude-sonnet-5"
}

Um valor aqui supera ANTHROPIC_DEFAULT_MODEL, que Claude Code usa apenas quando nada mais seleciona um modelo.

modelOverrides

Mapeie IDs de modelo Anthropic para IDs de modelo específicos do provedor, como ARNs de perfil de inferência do Amazon Bedrock. Cada entrada do seletor de modelo então usa seu valor mapeado ao chamar a API do provedor. Administradores usam isso em Amazon Bedrock, Agent Platform do Google Cloud e Microsoft Foundry para rotear cada versão de modelo para um perfil de inferência específico, nome de versão ou implantação para governança, alocação de custos ou roteamento regional.

• Escopo: Qualquer arquivo
• Tipo: objeto mapeando ID de modelo para ID de modelo do provedor
• Padrão: sem definir

Este exemplo roteia cada chamada para Opus 4.6 para o perfil de inferência Bedrock nomeado:

{
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456789012:inference-profile/example"
  }
}

Consulte Substitua IDs de modelo por versão.

modelPicker

Liste os modelos que o seletor /model oferece, na ordem que você os escreve e sob rótulos que você escolhe, então o seletor lista os modelos que sua organização executa, após o lineup integrado ou em vez dele. O model de cada linha é tomado verbatim, então aceita qualquer coisa que --model aceita: um alias como opus, um ID de modelo Anthropic ou um ID de formato de provedor para Amazon Bedrock, Agent Platform do Google Cloud, Microsoft Foundry ou um gateway LLM. Requer Claude Code v2.1.242 ou posterior.

• Escopo: Usuário ou gerenciado. Claude Code lê a chave de configurações gerenciadas, --settings e configurações de usuário, e a ignora em configurações de projeto e local para que um repositório que você clone não possa rotular novamente o seletor. O maior dos três que define a chave fornece todo o lineup, e Claude Code nunca combina lineups de duas fontes.
• Tipo: objeto com um array options de linhas e um Boolean replaceBuiltInOptions opcional
• Padrão: sem definir, então o seletor mostra o lineup integrado

Este exemplo adiciona duas implantações Bedrock após o lineup integrado, sob nomes que sua equipe reconhece:

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}

Campos para modelPicker

A chave leva dois campos, um para as linhas em si e outro para se elas substituem o lineup integrado ou o adicionam.

Uma entrada em options também pode levar um behavesAs string opcional ao lado de seu model, que requer v2.1.257 ou posterior. Defina-o para o ID de um modelo que sua versão do Claude Code já conhece, como claude-opus-4-8, em uma entrada cujo model é mais novo que sua versão. Claude Code então aplica as capacidades e padrões de esforço desse modelo conhecido à entrada em vez de tratar seu modelo como desconhecido. O rótulo da entrada e o ID do modelo que Claude Code envia em solicitações não mudam.

Com replaceBuiltInOptions ativado, Claude Code oculta todas as outras linhas: o lineup integrado, as linhas que adiciona para entradas availableModels, os modelos que descoberta de gateway encontrou e ANTHROPIC_CUSTOM_MODEL_OPTION. Com ele desativado, Claude Code pula um modelo listado que o lineup integrado já cobre. Um rótulo muda o que o seletor mostra, não qual modelo Claude Code executa.

Uma lista de permissões availableModels ainda se aplica a essas linhas. Antes de adicionar um modelo listado à lista de permissões, leia Comportamento de mesclagem: um ID de modelo específico estreita a entrada curinga de sua família. Claude Code também verifica cada linha contra a sessão antes de mostrar o seletor:

• Descartada: uma linha que Claude Code não pode servir, como um modelo aposentado ou um modelo ao qual sua organização não tem acesso
• Acinzentada: uma linha que você não pode selecionar ainda, mostrada com o motivo
• Nenhuma linha sobrevive: Claude Code mantém o lineup integrado, filtrado pela lista de permissões como usual

Claude Code descarta uma linha que não pode analisar e mantém o resto. Consulte Corrija um arquivo de configurações quebrado.

modelPricing

Relate gastos nas taxas que sua organização paga em vez de preço de lista. Defina-o quando sua organização tem taxas contratadas, então os valores em dólares que os desenvolvedores veem correspondem à sua fatura. Claude Code aplica as taxas em /usage, a linha de status, o total_cost_usd do Agent SDK, o limite --max-budget-usd e a métrica de custo OpenTelemetry e eventos. Você fornece as taxas: Claude Code não as lê de seu contrato ou do Claude Console. Requer Claude Code v2.1.242 ou posterior.

• Escopo: Gerenciado. Implante a chave através de configurações gerenciadas pelo servidor, uma política MDM, um arquivo managed-settings.json ou um auxiliar de política. Claude Code a ignora em configurações de usuário, projeto e local, em --settings e no Windows no registro HKCU gravável pelo usuário. Com configurações gerenciadas pelo servidor, cada sessão relata custos ao preço de lista até que a busca de configurações dessa sessão tenha confirmado a configuração. Um aplicativo host que incorpora Claude Code e define CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST pode fornecer uma tabela própria através da opção SDK managedSettings, que Claude Code usa apenas quando nenhuma fonte gerenciada define a chave e apenas em Claude Code v2.1.246 ou posterior.
• Tipo: objeto com um multiplier opcional e um mapa overrides opcional
• Padrão: sem definir, então Claude Code relata preço de lista a menos que um aplicativo host forneça uma tabela

Defina multiplier sozinho para um desconto fixo, overrides sozinho para taxas por modelo ou ambos.

Este exemplo define taxas contratadas para Sonnet 4.6 e depois reduz cada figura, a linha Sonnet incluída, em 15%:

{
  "modelPricing": {
    "multiplier": 0.85,
    "overrides": {
      "claude-sonnet-4-6": {
        "input": 2.4,
        "output": 12,
        "cacheRead": 0.24,
        "cacheWrite": 3
      }
    }
  }
}

Defina multiplier acima de 1, até 10, para marcar cada figura para cima. Uma marcação requer Claude Code v2.1.271 ou posterior. Versões anteriores ignoram um multiplier acima de 1 com um aviso e mantêm o resto da configuração.

Para as etapas, incluindo como confirmar que as taxas estão em vigor, consulte Relate gastos em suas taxas contratadas.

Campos para modelPricing

Claude Code usa as taxas de uma linha exatamente como você as escreveu, sem adicionar a sobretaxa do modo rápido ou a taxa de inferência apenas para EUA. Se você também definir multiplier, Claude Code a aplica no topo das taxas da linha. Claude Code descarta uma linha com uma taxa que não pode analisar ou um multiplier que não pode analisar e mantém o resto; consulte Corrija um arquivo de configurações quebrado.

Quais modelos uma linha modelPricing se aplica a

Claude Code decide quais modelos uma linha se aplica a partir da chave da linha:

• ID de um modelo integrado: uma chave que Claude Code usa para um modelo integrado, independentemente de essa chave ser o próprio ID do modelo, como claude-sonnet-4-6, ou seu ID Bedrock, Agent Platform ou Foundry. Claude Code aplica a linha a cada ID de snapshot datado e ID específico do provedor desse modelo.
• Qualquer outra chave: uma chave que não é o ID de um modelo integrado, como um alias de modelo de gateway. Claude Code aplica a linha apenas a esse ID. Quando um ID de modelo corresponde exatamente a uma de suas chaves e também se enquadra em uma linha com chave de ID de modelo integrado, Claude Code usa a correspondência exata.
• Um perfil de inferência de aplicação Bedrock: uma vez que Claude Code resolveu o perfil para o modelo ao qual roteia, através de seu mapa modelOverrides ou da busca bedrock:GetInferenceProfile, Claude Code aplica a linha desse modelo ao perfil.

modelSettings

Salve um nível de esforço para cada modelo que você usa. Requer Claude Code v2.1.251 ou posterior.

Em uma sessão interativa em sua máquina, quando você salva low, medium, high ou xhigh como seu padrão com /effort ou o controle deslizante de esforço do seletor /model, Claude Code escreve esse nível aqui sob o modelo que você está usando, então você raramente edita essa chave você mesmo. Quando você escolhe um desses níveis no seletor de modelo da extensão VS Code, Claude Code salva-o aqui da mesma forma. A entrada effortLevel lista as sessões onde /effort se aplica apenas a essa sessão.

Edite a chave manualmente para alterar ou remover um nível que você salvou.

Um effortLevel de um modelo aqui tem precedência sobre o effortLevel de nível superior no mesmo arquivo de configurações. Entre arquivos, Claude Code resolve cada modelo separadamente: o arquivo de configurações de maior precedência settings file que define um effortLevel para esse modelo ou o effortLevel de nível superior que se aplica a esse modelo decide, então um effortLevel em configurações gerenciadas supera um nível que você salvou em configurações de usuário. Ajuste o nível de esforço lista o que mais pode substituir um nível salvo, como --effort no lançamento.

Para limitar o esforço de um modelo em vez de definir seu nível, adicione um campo maxEffortLevel à entrada desse modelo. O campo requer Claude Code v2.1.267 ou posterior.

• Escopo: Qualquer arquivo
• Tipo: objeto mapeando um nome de modelo para um objeto com qualquer um destes campos:
  • effortLevel: um de "low", "medium", "high" ou "xhigh"
  • maxEffortLevel: o nível de esforço mais alto em que o modelo pode ser executado
  • autoCompactWindow: um número de tokens de 100000 a 1000000, ou "auto" para a janela ajustada para o modelo. /autocompact salva aqui. Para esse modelo, o valor tem precedência sobre um autoCompactWindow de nível superior no mesmo arquivo de configurações. Requer Claude Code v2.1.288 ou posterior
• Padrão: sem definir

Claude Code escreve cada entrada sob o nome canônico do modelo, como claude-opus-5-5, e corresponde ao alias desse modelo, com sufixo de data, [1m] e IDs específicos do provedor reconhecidos à mesma entrada.

Este exemplo mantém Opus 5.5 em high enquanto outros modelos usam seus próprios níveis salvos ou padrão:

{
  "modelSettings": {
    "claude-opus-5-5": {
      "effortLevel": "high"
    }
  }
}

Execute /effort auto para limpar seu nível salvo para o modelo que você está usando. Claude Code deixa as outras entradas e qualquer effortLevel de nível superior em vigor.

outputStyle

Selecione um estilo de saída por nome. Um estilo de saída é um conjunto salvo de instruções que muda o papel, tom e formato de saída de Claude, como os estilos Explanatory e Learning integrados ou um que você escreveu você mesmo.

Se você alterar essa chave durante uma sessão, Claude usa o novo estilo começando com sua próxima mensagem. Para o que essa mensagem custa em cache de prompt, consulte Alterando estilo de saída. Antes da v2.1.251, a edição se aplicava apenas depois que você executava /clear ou iniciava uma nova sessão.

• Escopo: Qualquer arquivo
• Tipo: string, o nome de um estilo de saída integrado ou personalizado
• Padrão: sem definir, então Claude Code usa o estilo padrão

Este exemplo seleciona o estilo Explanatory integrado, que adiciona insights educacionais entre tarefas:

{
  "outputStyle": "Explanatory"
}

promptCacheTtl

Escolha quanto tempo o cache de prompt mantém a conversa principal. Esta chave se aplica a suas voltas interativas, -p e Agent SDK, juntamente com os auxiliares que Claude Code executa inline com elas. A vida útil de uma hora mantém o cache aquecido entre pausas mais longas, e a API cobra cada gravação de cache a uma taxa mais alta do que na vida útil de cinco minutos. Requer Claude Code v2.1.242 ou posterior.

• Escopo: Qualquer arquivo
• Tipo: string, um de:
  • "5m": o cache se mantém por cinco minutos
  • "1h": o cache se mantém por uma hora
• Padrão: sem definir, então cada solicitação de conversa principal obtém sua vida útil padrão
• Substituições por sessão: FORCE_PROMPT_CACHING_5M tem precedência sobre tudo mais, depois CLAUDE_CODE_PROMPT_CACHE_TTL, depois essa chave e por último ENABLE_PROMPT_CACHING_1H

Este exemplo mantém a conversa principal na vida útil de uma hora e deixa subagentes em cinco minutos:

{
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "5m"
}

Para o que cada vida útil custa, consulte Vida útil do cache.

showThinkingSummaries

Veja resumos do pensamento estendido de Claude em sessões interativas. Defina-o se você quer os resumos completos quando expande o pensamento com Ctrl+O. Quando sem definir ou false, a API Anthropic redige blocos de pensamento e Claude Code mostra um stub recolhido.

• Escopo: Qualquer arquivo
• Tipo: Boolean
  • true: você vê resumos completos de pensamento quando expande o pensamento com Ctrl+O
  • false: a API Anthropic redige blocos de pensamento e Claude Code mostra um stub recolhido
• Padrão: false

{
  "showThinkingSummaries": true
}

A redação muda apenas o que você vê, não o que o modelo gera. Para reduzir o gasto de pensamento, reduza o orçamento ou desative o pensamento em vez disso.

subagentPromptCacheTtl

Escolha quanto tempo o cache de prompt mantém as solicitações que Claude Code faz fora da conversa principal. Esta chave se aplica a subagentes, workflows e as próprias solicitações de background e auxiliar de Claude Code, como compactação e títulos de sessão. A vida útil de uma hora mantém o cache aquecido entre pausas mais longas, e a API cobra cada gravação de cache a uma taxa mais alta do que na vida útil de cinco minutos. Requer Claude Code v2.1.242 ou posterior.

• Escopo: Qualquer arquivo
• Tipo: string, um de:
  • "5m": o cache se mantém por cinco minutos
  • "1h": o cache se mantém por uma hora
• Padrão: sem definir, então cada uma dessas solicitações obtém sua vida útil padrão
• Substituições por sessão: FORCE_PROMPT_CACHING_5M tem precedência sobre tudo mais, depois CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, depois essa chave, depois ENABLE_PROMPT_CACHING_1H, que pede a vida útil de uma hora em cada solicitação. Para onde o valor de frontmatter próprio de um subagente se classifica, consulte Escolha o TTL você mesmo

Este exemplo dá aos subagentes e às outras solicitações fora da conversa principal a vida útil de uma hora:

{
  "subagentPromptCacheTtl": "1h"
}

Esta chave cobre as solicitações que promptCacheTtl não cobre, então defina ambas para escolher uma vida útil para cada solicitação que Claude Code faz. Para como o cache de um subagente difere do cache da conversa principal, consulte Subagentes e o cache.

switchModelsOnFlag

Escolha o que acontece quando um classificador de segurança sinaliza uma solicitação: mude para o modelo de fallback e continue, ou pause para que você possa escolher entre mudar e editar o prompt.

• Escopo: Qualquer arquivo. Aparece em /config como Switch models when a message is flagged, com as opções Switch automatically e Ask each time.
• Tipo: Boolean
  • true: Claude Code muda para o modelo de fallback e continua
  • false: em uma sessão interativa Claude Code pausa para que você possa escolher entre mudar e editar o prompt; onde nenhum diálogo pode mostrar, como uma execução -p, a solicitação sinalizada termina como um erro
• Padrão: sem definir. Claude Code muda automaticamente, embora possa perguntar primeiro em uma sessão interativa

{
  "switchModelsOnFlag": false
}

Consulte Pergunte antes de mudar.

ultracode

Inicie sessões com ultracode ativado. Com ele ativado, Claude planeja um workflow para cada tarefa substancial em vez de esperar você pedir. Claude planeja workflows apenas quando workflows dinâmicos estão habilitados para você e seu modelo suporta esforço xhigh. A chave não muda o nível de esforço da sessão: ultracode funciona em qualquer nível que a sessão usa. Claude Code lê essa chave mas nunca a escreve: /effort ultracode ativa ultracode apenas para a sessão atual.

• Escopo: Qualquer arquivo
• Tipo: Boolean
  • true: sessões começam com ultracode ativado quando workflows dinâmicos estão habilitados para você e seu modelo suporta xhigh
  • false: sessões começam com ultracode desativado
• Padrão: sem definir, então ultracode está desativado
• Substituições por sessão: /effort ultracode ativa ultracode para uma sessão sem essa chave, e /effort ultracode off o desativa para uma sessão quando essa chave é true. A flag --effort ultracode também o ativa para uma sessão, em esforço xhigh

{
  "ultracode": true
}

O nível de esforço da sessão vem de effortLevel, modelSettings e as outras fontes de esforço, e um limite de esforço como maxEffortLevel reduz esse nível sem desativar ultracode. Isso e a forma /effort ultracode off requerem Claude Code v2.1.284 ou posterior. Antes da v2.1.284, ultracode: true executava a sessão em esforço xhigh, e um limite de esforço abaixo de xhigh mantinha ultracode desativado. Uma solicitação de controle apply_flag_settings do Agent SDK também aceita a chave.

Configurações de permissão

Decida o que Claude pode fazer sem perguntar, em qual modo de permissão uma sessão começa e o que o classificador do modo automático permite. Para a sintaxe de regras e o modelo de permissão, consulte Configurar permissões.

allowManagedPermissionRulesOnly

Torne as configurações gerenciadas a única fonte de regras de permissão. Claude Code então ignora as regras allow, ask e deny em arquivos de usuário, projeto, local e --settings, ignora --allowedTools, oculta as opções de sempre permitir nos prompts de permissão e para de salvar novas regras.

Quando configurações pai de um host de incorporação se aplicam, Claude Code as trata como parte da camada gerenciada. Ele descarta suas regras allow e additionalDirectories, e mantém suas regras deny e ask exceto regras Read e Edit cujo padrão começa com !. Um host não pode esculpir caminhos fora das regras gerenciadas com uma regra !, independentemente de você definir esta chave.

As regras --disallowedTools e as regras deny e ask da sessão atual ainda se aplicam, inclusive após Claude Code recarregar as configurações no meio da sessão. Elas apenas restringem, portanto não podem ampliar o que as regras gerenciadas concedem. Antes da v2.1.257, Claude Code descartava essas regras de linha de comando e de sessão no primeiro recarregamento de configurações.

Para o que um padrão ! em uma regra --disallowedTools ou de sessão pode esculpir, consulte Regras Read e Edit.

Quando você define esta chave, Claude Code v2.1.282 ou posterior também ignora o frontmatter allowed-tools em skills e arquivos .claude/commands/ destas fontes:

• O diretório .claude/ de um repositório
• Seus diretórios ~/.claude/skills/ e ~/.claude/commands/, incluindo skills sincronizadas do claude.ai
• Um diretório --add-dir
• Plugins declarados com um manifesto .claude-plugin dentro de ~/.claude/skills/ ou do .claude/skills/ do projeto
• Plugins carregados para apenas uma sessão, cujos ids terminam em @inline, quando todas estas condições se aplicam:
  • A sessão é uma sessão Code ou sessão Cowork, exceto uma sessão na nuvem, para a qual o próprio aplicativo Claude Desktop inicia Claude Code
  • Suas configurações gerenciadas definem a chave, não apenas as configurações pai de um host de incorporação
  • A sessão executa Claude Code v2.1.305 ou posterior

As skills de configurações gerenciadas e as skills incluídas mantêm seu allowed-tools. Plugins @inline fora dessas sessões do Desktop também mantêm o seu, exceto um chamado anthropic-skills. O disallowed-tools de uma skill ainda se aplica. Para o que um desenvolvedor vê quando Claude Code ignora o campo, consulte Quando apenas regras de permissão gerenciadas se aplicam.

• Escopo: Managed
• Tipo: Booleano
  • true: as configurações gerenciadas se tornam a única fonte de regras de permissão
  • false: Claude Code aplica regras de permissão de arquivos de usuário, projeto, local e --settings além das gerenciadas
• Padrão: não definido, portanto Claude Code aplica regras de permissão de configurações de usuário, projeto e local e de --settings, além das gerenciadas

{
  "allowManagedPermissionRulesOnly": true
}

Esta chave não bloqueia a allowlist de servidores MCP; para isso, defina allowManagedMcpServersOnly. Consulte Configurações apenas gerenciadas.

autoMode

Adicione suas próprias regras ao que o classificador do modo automático bloqueia e permite. Use-o para informar ao classificador quais repositórios, buckets e domínios sua organização confia, para que ele pare de bloquear operações internas rotineiras. O classificador é fornecido com regras de permissão e bloqueio integradas. Inclua a string literal "$defaults" em um array para manter essas regras integradas nessa posição e adicione as suas ao redor; deixe-a de fora para substituí-las pelas suas.

• Escopo: User or managed
• Tipo: objeto com arrays environment, allow, soft_deny e hard_deny de regras em prosa, mais o Booleano classifyAllShell
• Padrão: não definido, portanto o classificador usa apenas suas regras integradas

Este exemplo mantém as regras soft_deny integradas, através de "$defaults", e adiciona uma mais que bloqueia terraform apply:

{
  "autoMode": {
    "soft_deny": ["$defaults", "Never run terraform apply"]
  }
}

Quando mais de um desses arquivos define o mesmo array, Claude Code concatena as entradas. Para o formato de regra e como cada array é aplicado, consulte Configurar modo automático.

autoMode.classifyAllShell

Envie cada comando Bash e PowerShell através do classificador do modo automático enquanto o modo automático está ativo. Por padrão, o modo automático suspende apenas regras de permissão que poderiam executar código arbitrário: regras de ferramenta inteira e curinga como Bash(*), e prefixos de interpretador ou wrapper de shell como Bash(python *). Um comando que qualquer outra regra de permissão corresponde, como Bash(npm test), pula o classificador a menos que ele carregue domínios permitidos por comando. Quando pula, um argumento destrutivo que o prefixo da regra não antecipou pode passar despercebido. Definir esta chave suspende cada regra de shell de permissão para a sessão para que o classificador veja cada comando. Requer Claude Code v2.1.193 ou posterior.

• Escopo: User or managed. Leia onde autoMode é lido.
• Tipo: Booleano
  • true: enquanto o modo automático está ativo, Claude Code envia cada comando Bash e PowerShell através do classificador e suspende suas regras de shell de permissão; fora do modo automático as regras ainda se aplicam
  • false: o modo automático suspende apenas regras de permissão que poderiam executar código arbitrário, como Bash(*) e Bash(python *); um comando que qualquer outra regra de permissão corresponde pula o classificador a menos que ele carregue domínios permitidos por comando, e cada outro comando de shell passa por ele
• Padrão: false

{
  "autoMode": {
    "classifyAllShell": true
  }
}

Consulte Rotear todos os comandos de shell através do classificador.

disableAutoMode

Remova o modo automático do ciclo Shift+Tab. Qualquer sessão que de outra forma começaria em modo automático, seja de --permission-mode auto, um arquivo de configurações ou o padrão integrado, começa em default em vez disso. Administradores o definem em configurações gerenciadas para impedir que desenvolvedores em sua organização usem o modo automático.

• Escopo: Any file. Mais útil em configurações gerenciadas, onde os usuários não podem substituí-lo. Também aceito sob permissions como permissions.disableAutoMode.
• Tipo: a string "disable"
• Padrão: não definido

{
  "disableAutoMode": "disable"
}

permissions

Controle quais ferramentas Claude pode usar sem perguntar, quais sempre solicitam e quais são bloqueadas, e defina o modo de permissão em que uma sessão começa. Cada chave permissions.* abaixo se aninha sob este objeto.

• Escopo: Any file
• Tipo: objeto com allow, ask, deny, additionalDirectories, blockReadsOutsideWorkingDirectories, defaultMode, disableBypassPermissionsMode e disableAutoMode
• Padrão: não definido

Este exemplo aprova comandos npm run sem perguntar, solicita antes de git push, bloqueia leituras de .env e inicia sessões em acceptEdits:

{
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)"],
    "defaultMode": "acceptEdits"
  }
}

Os três arrays de regras compartilham uma sintaxe; consulte Sintaxe de regra de permissão sob permissions.allow. Para como as regras de permissão de diferentes arquivos se combinam, consulte como as regras de permissão se mesclam entre escopos; para como as chaves de configurações em geral se combinam, consulte Precedência de configurações no guia de configurações.

useAutoModeDuringPlan

Escolha se Claude Code usa o classificador do modo automático para revisar comandos de shell no modo de planejamento. Com o padrão true, o classificador revisa cada comando durante o planejamento quando o modo automático está disponível e você não vê nenhum prompt, exceto para remoções de caminho crítico. Defina false para obter um prompt de permissão para cada comando fora do conjunto integrado somente leitura. Aparece em /config como Use auto mode during plan.

• Escopo: User, local, or managed. Um repositório não pode desativá-lo para você.
• Tipo: Booleano
  • true: o mesmo que não definido; quando o modo automático está disponível, o classificador revisa cada comando de shell durante o planejamento em vez de solicitar a você, exceto remoções de caminho crítico. Um false em qualquer um desses arquivos ainda o desativa
  • false: você obtém um prompt de permissão para cada comando fora do conjunto integrado somente leitura
• Padrão: true

{
  "useAutoModeDuringPlan": false
}

permissions.allow

Liste os usos de ferramentas que Claude Code aprova sem perguntar a você. Em uma regra MCP, * pode aparecer apenas no nome da ferramenta após o prefixo mcp__<server>__, como mcp__github__get_*; não pode aparecer no nome do servidor.

• Escopo: Any file
• Tipo: array de strings de regra de permissão
• Padrão: não definido
• Substituições por sessão: --allowedTools adiciona regras de permissão para uma sessão, e uma regra de bloqueio de qualquer arquivo de configurações ainda bloqueia uma ferramenta que ela nomeia

Este exemplo aprova git diff e permite que Claude Code leia seu .zshrc sem perguntar:

{
  "permissions": {
    "allow": ["Bash(git diff *)", "Read(~/.zshrc)"]
  }
}

Claude Code aplica regras allow do .claude/settings.json de um projeto apenas depois que você aceita o diálogo de confiança do workspace para essa pasta.

Sintaxe de regra de permissão

As regras de permissão seguem o formato Tool ou Tool(specifier). Claude Code avalia as regras deny primeiro, depois ask, depois allow, e a primeira correspondência decide independentemente de quão específica cada regra é; consulte a ordem de avaliação de regra de permissão.

Cada linha mostra uma forma de regra e o que ela corresponde.

Para a sintaxe de regra completa, incluindo comportamento de curinga, padrões específicos de ferramenta para Read, Edit, WebFetch, MCP e regras de Agent, e as limitações de segurança de padrões Bash, consulte Sintaxe de regra de permissão.

permissions.ask

Liste os usos de ferramentas que solicitam sua confirmação mesmo em um modo de permissão que de outra forma os aprovaria, como acceptEdits ou bypassPermissions. No modo dontAsk, Claude Code nega um uso de ferramenta correspondente em vez de solicitar.

• Escopo: Any file
• Tipo: array de strings de regra de permissão
• Padrão: não definido

{
  "permissions": {
    "ask": ["Bash(git push *)"]
  }
}

permissions.deny

Liste os usos de ferramentas que Claude Code bloqueia. Use-o para arquivos que contêm chaves de API, segredos ou valores de ambiente: Claude Code exclui arquivos correspondentes da descoberta de arquivos e resultados de pesquisa, nega leituras deles e bloqueia as ferramentas Edit e Write nos caminhos correspondentes.

As regras de bloqueio Read e Edit se aplicam às ferramentas de arquivo integradas de Claude, aos comandos de arquivo que Claude Code reconhece em Bash, como cat, head, tail, sed e tee, e aos destinos de redirecionamentos de Bash como > file e < file; elas não se aplicam a um comando que lê arquivos sem nomeá-los, como grep -r pattern ., ou a subprocessos arbitrários, portanto para aplicação em nível de SO ative o sandbox.

• Escopo: Any file
• Tipo: array de strings de regra de permissão
• Padrão: não definido
• Substituições por sessão: --disallowedTools adiciona regras de bloqueio para uma sessão ao lado desta chave

Este exemplo nega leituras de arquivos .env, o diretório secrets e um arquivo de credenciais, e bloqueia comandos curl:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Bash(curl *)"
    ]
  }
}

Os nomes de ferramentas aceitam padrões glob, portanto "*" nega cada ferramenta e "mcp__*" nega cada ferramenta MCP. Claude Code ignora uma regra de bloqueio para a ferramenta EndConversation enquanto qualquer outra ferramenta ainda estiver disponível para Claude. Uma regra de bloqueio Bash corresponde ao comando como Claude o escreve, portanto Bash(curl *) não para /usr/bin/curl ou sh -c 'curl …'; consulte o que uma regra Bash não corresponde. Esta chave substitui a configuração ignorePatterns descontinuada.

permissions.additionalDirectories

Dê a Claude acesso a arquivos em diretórios fora do que você começou, como diretórios de trabalho adicionais. A maioria da configuração .claude/ não é descoberta desses diretórios.

• Escopo: Any file, com limites no acesso de gravação do sandbox que as entradas de projeto e local concedem
• Tipo: array de caminhos de diretório
• Padrão: não definido
• Substituições por sessão: --add-dir e /add-dir adicionam diretórios para uma sessão ao lado desta chave

{
  "permissions": {
    "additionalDirectories": ["../docs/"]
  }
}

Como as regras allow, as entradas no .claude/settings.json de um projeto entram em vigor apenas depois que você aceita o diálogo de confiança do workspace para essa pasta.

permissions.blockReadsOutsideWorkingDirectories

Faça as ferramentas de arquivo de Claude recusarem leituras fora dos diretórios de trabalho em cada modo de permissão, incluindo bypassPermissions. Claude Code nega chamadas Read, Grep, Glob e LSP nesses caminhos e diz a Claude para pedir que você adicione o diretório com /add-dir. Arquivos que Claude Code em si precisa permanecem legíveis, como suas skills, plugins, regras, agentes, comandos e o arquivo de memória CLAUDE.md sob ~/.claude/. Requer Claude Code v2.1.257 ou posterior.

Claude Code não recusa comandos de shell da mesma forma:

• Ações que nenhum modo aprova automaticamente cobre quando um comando de shell que lê tal caminho solicita a você
• Comandos em sandbox sob o bloqueio cobre o que um comando em sandbox pode ler

Um comando Bash que o analisador de shell não consegue rastrear, como um que muda de diretório mais de uma vez ou executa um subshell, solicita a você mesmo no modo automático e no modo bypassPermissions. O prompt aparece mesmo quando o comando não nomeia nenhum caminho fora dos diretórios de trabalho. Este prompt não se aplica quando o comando é executado no sandbox e o sandbox aplica o bloqueio.

Claude Code também escreve true aqui quando você escolhe bloquear tais leituras no prompt do modo automático antes da primeira leitura fora dos diretórios de trabalho.

• Escopo: Any file. Um true em qualquer arquivo se aplica, portanto um repositório pode ativar o bloqueio para si mesmo, mas não pode levantar o seu.
• Tipo: Booleano
  • true: as ferramentas de arquivo de Claude recusam leituras fora dos diretórios de trabalho
  • false: o mesmo que não definido; o bloqueio ainda se aplica se outro arquivo definir true
• Padrão: não definido, portanto leituras fora dos diretórios de trabalho seguem seu modo de permissão

{
  "permissions": {
    "blockReadsOutsideWorkingDirectories": true
  }
}

Diretórios que você adiciona com --add-dir, /add-dir ou additionalDirectories em suas configurações de usuário ou gerenciadas contam como diretórios de trabalho para o bloqueio. Diretórios adicionados apenas em configurações de repositório não contam: aqueles em .claude/settings.json e aqueles em .claude/settings.local.json a menos que git relate esse arquivo como não rastreado. Em um diretório que não é um repositório git, ou quando git rastreia o arquivo, Claude Code trata .claude/settings.local.json como configurações de repositório, portanto coloque diretórios que você quer manter legíveis em suas configurações de usuário em vez disso.

Quando autoMemoryDirectory vem do .claude/settings.json do projeto, ou de um .claude/settings.local.json tratado como fornecido pelo repositório, Claude Code não carrega nenhuma memória automática desse diretório e não salva nenhuma nele.

Para levantar o bloqueio, remova a chave de cada arquivo de configurações que a define, depois inicie uma nova sessão.

Comandos em sandbox sob o bloqueio

Quando sandboxing está ativado, o bloqueio também cobre comandos em sandbox. Claude Code nega a eles acesso de leitura ao seu diretório pessoal e às outras raízes que contêm arquivos de usuário: /Users, /home, /root, /Volumes, /mnt, /media, /run/media e /srv. Ele então reabre os diretórios de trabalho, worktrees que Claude Code cria na sessão, o diretório temporário da sessão e as partes de ~/.claude que os comandos precisam, como skills e plugins. Enquanto o bloqueio está em vigor, entradas allowRead e allowWrite de configurações de repositório não contam.

Quando o diretório de trabalho da sessão é um git worktree vinculado, incluindo um que Claude Code entrou no meio da sessão, o diretório .git comum do repositório permanece legível e gravável para comandos em sandbox, para que o git continue funcionando lá.

Nestes casos o bloqueio não alcança comandos em sandbox, enquanto as ferramentas de arquivo de Claude continuam aplicando-o:

• O isolamento do sistema de arquivos está desativado através de sandbox.filesystem.disabled
• allowManagedReadPathsOnly está definido
• O caminho do diretório em que você iniciou Claude Code contém um caractere glob como *, ? ou [

Sob o bloqueio, Claude Code reabre seus arquivos de configuração git global para comandos em sandbox para que git mantenha sua identidade e configurações:

• ~/.gitconfig
• Os arquivos config, ignore e attributes sob $XDG_CONFIG_HOME/git, que padrão para ~/.config/git
• Arquivos que sua configuração git global nomeia através de [include], [includeIf], core.excludesFile ou core.attributesFile

Claude Code julga cada arquivo separadamente. Quando um arquivo fica onde um comando em sandbox pode escrever, diretamente ou através de um symlink, Claude Code não reabre os arquivos que ele nomeia.

No Linux e WSL2, um arquivo de configuração que é um symlink pode permanecer ilegível em seu próprio caminho, e git então é executado sem ele. ~/.git-credentials e $XDG_CONFIG_HOME/git/credentials permanecem bloqueados.

Se um arquivo reaberto contém um segredo, como um token http.extraHeader, adicione seu caminho a sandbox.filesystem.denyRead. Uma entrada denyRead que cobre um arquivo sempre tem precedência sobre esta reabertura.

permissions.defaultMode

Defina o modo de permissão em que novas sessões começam. Quando você deixa não definido, as sessões começam no padrão integrado para sua superfície.

• Escopo: Any file. auto e bypassPermissions não entram em vigor a partir de configurações de projeto ou local, portanto defina-os em ~/.claude/settings.json em vez disso. Antes da v2.1.257, bypassPermissions entrava em vigor a partir de qualquer arquivo. Para conversas que a extensão VS Code inicia, Claude Code lê apenas valores de usuário, gerenciados e --settings.
• Tipo: string, uma de:
  • "default": Claude Code executa apenas leituras sem perguntar
  • "acceptEdits": Claude Code também executa edições de arquivo e comandos comuns do sistema de arquivos como mkdir e mv sem perguntar
  • "plan": Claude Code lê e planeja, mas bloqueia edições até que você aprove um plano
  • "auto": Claude Code executa sem prompts rotineiros; antes de ações como comandos de shell e requisições de rede serem executadas, um classificador em segundo plano verifica se elas se alinham com sua solicitação
  • "dontAsk": Claude Code nega automaticamente cada chamada que de outra forma solicitaria, embora um mod que você instalou ainda possa aprovar algumas dessas chamadas. Leituras de arquivos dentro dos seus diretórios de trabalho, outras ações que não precisam de aprovação e ferramentas pré-aprovadas ainda são executadas, exceto leituras de caminhos de rede
  • "bypassPermissions": Claude Code executa tudo sem perguntar
  • "manual": um alias para "default"
• Padrão: não definido
• Substituições por sessão: --permission-mode e seu equivalente --dangerously-skip-permissions para bypassPermissions têm precedência sobre esta chave para uma sessão

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

As regras de permissão se sobrepõem a cada modo: as regras deny bloqueiam em cada modo, incluindo bypassPermissions. Consulte Modos de permissão. Em sessões na nuvem, Claude Code honra apenas acceptEdits, plan, default e auto desta chave. Para conversas que a extensão VS Code inicia, consulte qual configuração a extensão lê para o modo de permissão inicial.

permissions.disableBypassPermissionsMode

Impeça que qualquer pessoa entre no modo bypassPermissions. Claude Code então rejeita a flag --dangerously-skip-permissions e ignora uma definição de agente permissionMode: bypassPermissions, portanto o subagente é executado com o modo de permissão da sessão pai.

• Escopo: Any file. Normalmente definido em configurações gerenciadas para aplicar a política organizacional.
• Tipo: a string "disable"
• Padrão: não definido
• Substituições por sessão: esta chave tem precedência sobre --dangerously-skip-permissions, que Claude Code rejeita enquanto a chave está definida

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

Antes da v2.1.223, Claude Code aplicava o modo de permissão do frontmatter mesmo com bypass desativado.

skipAutoPermissionPrompt

Pule o aviso único descrevendo o modo automático que Claude Code mostra quando você entra no modo automático pela primeira vez, por exemplo através de suas próprias configurações ou do seletor de modo, em vez de quando o padrão integrado inicia uma sessão nele. Claude Code mostra esse aviso uma vez e depois registra que foi mostrado, portanto esta chave só importa onde o aviso ainda não apareceu.

• Escopo: User or managed. Um repositório não pode defini-lo para você.
• Tipo: Booleano
  • true: Claude Code pula o aviso
  • false: o mesmo que não definido; o aviso aparece uma vez a menos que outro desses arquivos defina true
• Padrão: não definido, portanto o aviso aparece uma vez

{
  "skipAutoPermissionPrompt": true
}

skipDangerousModePermissionPrompt

Pule o diálogo de confirmação que Claude Code mostra antes de uma sessão entrar no modo bypassPermissions, seja de --dangerously-skip-permissions ou de defaultMode: "bypassPermissions". Claude Code escreve true aqui em suas configurações de usuário quando você aceita esse diálogo uma vez.

• Escopo: User, local, or managed. Um repositório não confiável não pode pular o diálogo para você.
• Tipo: Booleano
  • true: Claude Code pula o diálogo de confirmação antes de uma sessão entrar no modo bypassPermissions
  • false: o mesmo que não definido; o diálogo aparece a menos que outro desses arquivos defina true
• Padrão: não definido, portanto o diálogo aparece

{
  "skipDangerousModePermissionPrompt": true
}

Configurações de sandbox

Isole os comandos que Claude executa do seu sistema de arquivos, da sua rede e das suas credenciais. Para saber como o sandboxing funciona e os requisitos de plataforma, consulte Sandboxing.

sandbox

Isole os comandos Bash que Claude executa do seu sistema de arquivos e rede com sandboxing. Ative o sandbox com enabled, depois restrinja ou amplie o que os comandos em sandbox podem acessar com os sub-objetos filesystem, network e credentials. O sandbox é executado em macOS, Linux e WSL2.

• Scope: Any file
• Tipo: objeto com enabled, failIfUnavailable, autoAllowBashIfSandboxed, excludedCommands, allowUnsandboxedCommands, enableWeakerNestedSandbox, enableWeakerNetworkIsolation, allowAppleEvents, allowNestedUserNamespaces, bwrapPath, socatPath, ignoreViolations e ripgrep, além dos objetos filesystem, network e credentials
• Default: não definido, então Claude Code executa comandos sem sandbox

Isso ativa o sandbox, ignora prompts de permissão para comandos em sandbox, executa docker fora do sandbox, abre dois caminhos de escrita extras, oculta seu arquivo de credenciais AWS e pré-autoriza GitHub e npm:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

Quando as configurações gerenciadas definem uma chave booleana como enabled ou failIfUnavailable, esse valor sobrescreve qualquer coisa que um desenvolvedor defina. Claude Code mescla chaves de array em todos os escopos de configurações que a sessão carrega, então um desenvolvedor pode anexar entradas; consulte Keep developers from widening the policy para os bloqueios somente gerenciados. Para exigir o sandbox para uma organização, consulte Enforce sandboxing with managed settings.

sandbox.enabled

Ative sandboxing para comandos Bash. Quando você escolhe um modo no painel /sandbox, Claude Code escreve essa chave em .claude/settings.local.json para o projeto atual; defina-a em ~/.claude/settings.json para fazer sandbox em todos os projetos.

• Scope: Any file, com limites em configurações de projeto e locais
• Type: Boolean
  • true: Claude Code faz sandbox dos comandos Bash
  • false: Comandos Bash são executados sem sandbox
• Default: false

{
  "sandbox": {
    "enabled": true
  }
}

No Linux e WSL2, o sandbox precisa de bubblewrap e socat; consulte Set up Linux and WSL2. Quando o sandbox não consegue iniciar, Claude Code executa comandos sem sandbox, a menos que você também defina failIfUnavailable.

sandbox.failIfUnavailable

Faça Claude Code sair com um erro na inicialização quando sandbox.enabled é true mas o sandbox não consegue iniciar, porque uma dependência está faltando ou a plataforma não é suportada. Sem essa chave, Claude Code executa comandos sem sandbox. Implantações gerenciadas que exigem sandboxing como uma barreira de segurança podem usar essa configuração.

Em uma plataforma que o sandbox não suporta, Claude Code não inicia com essa chave ativada. Consulte Enforce sandboxing with managed settings.

• Scope: Any file, com limites em configurações de projeto e locais
• Type: Boolean
  • true: Claude Code sai com um erro na inicialização quando sandbox.enabled é true mas o sandbox não consegue iniciar
  • false: Claude Code executa comandos sem sandbox quando o sandbox não consegue iniciar
• Default: false

Isso faz com que cada máquina gerenciada faça sandbox dos comandos ou recuse iniciar:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true
  }
}

Consulte Enforce sandboxing with managed settings.

sandbox.autoAllowBashIfSandboxed

Permite que o Claude Code execute comandos Bash em sandbox sem um prompt de permissão. Comandos que não podem ser executados no sandbox ainda passam pelo fluxo normal de permissões, e as regras deny e as regras ask com escopo de conteúdo, como Bash(git push *), continuam valendo; uma regra ask Bash simples é ignorada para comandos em sandbox. Defina como false para que os comandos em sandbox também passem pelo fluxo normal de permissões, o que a aba Mode do /sandbox chama de modo de permissões normais.

• Scope: Any file
• Type: Boolean
  • true: Claude Code executa comandos Bash em sandbox sem um prompt de permissão, exceto nos casos que Auto-allow mode descreve; CLAUDE_CODE_SUBPROCESS_ENV_SCRUB desativa a auto-autorização
  • false: comandos em sandbox passam pelo fluxo de permissão regular, então suas regras de autorização e modo de permissão decidem. A aba Mode do /sandbox chama isso modo de permissões regular
• Default: true

Isso mantém o sandbox ativado e envia comandos em sandbox pelo fluxo de permissão regular:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false
  }
}

Consulte Auto-allow mode para saber o que o modo auto-autorização ainda solicita e como se comporta em modo de planejamento.

sandbox.excludedCommands

Nomeie comandos que Claude Code executa fora do sandbox, como ferramentas que não funcionam sob ele. Cada entrada usa a mesma sintaxe do conteúdo de uma regra de permissão Bash(...): um comando exato, um prefixo como docker * ou um padrão curinga. Um padrão sem curinga é uma correspondência exata, então docker corresponde apenas a docker sem argumentos.

Suas entradas tiram uma chamada Bash do sandbox apenas quando cobrem cada comando nela, e algumas formas de chamada permanecem em sandbox mesmo assim. Uma entrada docker * sozinha não tira npm ci && docker build . do sandbox.

• Scope: Any file, com limites em configurações de projeto e locais
• Type: array de padrões de comando
• Default: não definido, então nenhum comando é excluído

{
  "sandbox": {
    "excludedCommands": ["docker *"]
  }
}

Claude Code mantém uma chamada Bash em sandbox quando ela tem uma destas formas, entre outras:

• Um comando começando com sudo, eval ou xargs
• Um cd, pushd ou popd, onde quer que apareça na chamada
• Uma substituição de comando, um subshell ou um bloco de fluxo de controle como if ou for
• Um redirecionamento, como docker build . > build.log, outro que não apenas duplica um descritor de arquivo, como 2>&1 faz
• Um nome de comando que vem de uma variável
• Um git clone, git init, git worktree add, git worktree move ou git bundle create com um argumento de caminho que é absoluto, começa com ~ ou contém um segmento ..

Por exemplo, cd build && docker compose up permanece em sandbox sob uma entrada docker *, e adicionar uma entrada cd não muda isso. Sob uma entrada git *, git clone <url> vendor/lib é executado fora do sandbox, mas git clone <url> ~/tools permanece em sandbox. Um clone escreve uma árvore inteira de arquivos, possivelmente executáveis, onde quer que seu caminho de destino aponte.

Comandos excluídos ainda passam pelo fluxo de permissão regular. Exclusão é uma conveniência, não uma barreira de segurança: quando uma ferramenta só precisa escrever em algum lugar específico, filesystem.allowWrite a mantém em sandbox.

Entradas dos escopos de configurações que a sessão carrega se combinam em uma única lista, a menos que o sandbox seja exigido pelo administrador. Enquanto for, Claude Code ignora entradas em .claude/settings.json e .claude/settings.local.json, para que um repositório clonado não possa tirar comandos do sandbox. Entradas em configurações gerenciadas, --settings e seu ~/.claude/settings.json ainda se aplicam, e nenhum bloqueio somente gerenciado cobre essa lista.

sandbox.allowUnsandboxedCommands

Deixe Claude tentar novamente um comando fora do sandbox com o parâmetro dangerouslyDisableSandbox depois que o sandbox o bloqueia. Quando é false, Claude Code ignora esse parâmetro. Enquanto o sandbox está em execução, os comandos que Claude executa ficam então em sandbox, a menos que correspondam a uma entrada de excludedCommands. A aba Overrides do /sandbox mostra esse estado como Strict sandbox mode. Um false em configurações gerenciadas ativa o modo de sandbox rigoroso para os desenvolvedores que elas cobrem.

• Scope: Any file, com um limite em configurações de projeto e locais
• Type: Boolean
  • true: Claude pode tentar novamente um comando fora do sandbox com o parâmetro dangerouslyDisableSandbox depois que o sandbox o bloqueia
  • false: Claude Code ignora esse parâmetro, então, enquanto o sandbox está em execução, os comandos que Claude executa ficam em sandbox, a menos que correspondam a uma entrada de excludedCommands
• Default: true

Isso impõe modo de sandbox rigoroso para todos que as configurações gerenciadas cobrem:

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false
  }
}

Um false vindo de configurações gerenciadas ou de --settings também torna o sandbox exigido pelo administrador. Um false em suas configurações de usuário prevalece sobre um true de um projeto, mas não torna o sandbox exigido pelo administrador. Prevalecer sobre o valor de um projeto requer Claude Code v2.1.285 ou posterior.

Quem aprova uma nova tentativa sem sandbox depende do seu modo de permissão e das suas regras de autorização. Consulte The unsandboxed retry escape hatch.

Para ver quando comandos que você digita você mesmo no prompt de modo shell ! são executados em sandbox, consulte strict sandbox mode.

sandbox.filesystem

Controle quais caminhos os comandos em sandbox podem ler e escrever. Por padrão, eles podem escrever no diretório de trabalho, no diretório temporário por usuário e em diretórios que você adiciona com --add-dir, /add-dir ou permissions.additionalDirectories, e podem ler o resto do sistema de arquivos, incluindo arquivos de credenciais. Amplie ou restrinja isso com as quatro listas de caminhos, ou desative a camada do sistema de arquivos com disabled. Consulte Filesystem isolation para os limites padrão.

• Scope: Any file
• Type: object com arrays allowWrite, denyWrite, denyRead e allowRead, além dos booleanos allowManagedReadPathsOnly e disabled
• Default: não definido, então os limites padrão de leitura e escrita se aplicam

Isso permite que comandos em sandbox escrevam em um diretório de build e seu kubeconfig, e oculta seu arquivo de credenciais AWS:

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    }
  }
}

Claude Code impõe essas listas no limite do sandbox do SO, então elas se aplicam a cada subprocesso que um comando em sandbox inicia, como kubectl, terraform ou npm. Claude Code adiciona suas regras de permissão às mesmas listas: regras Edit allow e deny para allowWrite e denyWrite, regras Read deny para denyRead e regras WebFetch(domain:...) allow e deny para as listas de domínio network.

A menos que um bloqueio se aplique, Claude Code mescla essas listas nos arquivos de configurações que a sessão carrega. allowManagedReadPathsOnly limita allowRead a entradas de configurações gerenciadas, e allowManagedDomainsOnly faz o mesmo para domínios permitidos. Bloqueios de repositório deixam de fora entradas dos arquivos de configurações de um repositório.

Configure sandboxing cobre fontes que você exclui com --setting-sources. Quando você edita uma lista durante uma sessão, Claude Code aplica a mudança à sessão em execução.

Prefixos de caminho do sandbox

Caminhos em allowWrite, denyWrite, denyRead, allowRead e credentials.files são resolvidos por seu prefixo:

O prefixo //path para caminhos absolutos também funciona. Se você usar /path com barra única esperando resolução relativa ao projeto, mude para ./path. Essa sintaxe difere das regras de permissão Read e Edit, que usam //path para absoluto e /path para relativo ao projeto: caminhos do sistema de arquivos do sandbox usam convenções padrão, então /tmp/build é um caminho absoluto.

Claude Code remove uma barra final de um caminho de diretório, então ~/.aws e ~/.aws/ correspondem ao mesmo diretório. Antes da v2.1.224, Claude Code passava a barra final para o sandbox, e Claude ainda podia ler ou escrever caminhos sob uma entrada denyRead ou denyWrite escrita com uma.

Onde os curingas funcionam nos caminhos do sandbox

Os curingas *, ? e ** funcionam nas quatro listas de caminhos de sandbox.filesystem no macOS e em menos lugares no Linux e no WSL2:

Em ~/keys/*.pem, o curinga vem depois do primeiro nome de diretório, que é home para um diretório pessoal /home/alice:

~/keys/*.pem              the entry
/home/alice/keys/*.pem    its full path
 ^^^^                     the first directory name, home

No Linux e no WSL2, a aba Config do /sandbox em uma sessão avisa sobre regras de permissão Edit que contêm um curinga diferente de um /** final. Esses curingas não funcionam para comandos em sandbox. Adicione cada caminho que a regra deveria cobrir, ou o diretório que os contém, a allowWrite no caso de uma regra allow ou a denyWrite no caso de uma regra deny.

Nomes de diretório com colchetes, chaves ou parênteses

Para permitir ou bloquear um diretório cujo nome contém colchetes, escreva o nome como ele é, por exemplo ./app/[slug]. Nessa entrada, [slug] é o nome real do diretório, com os colchetes:

app/
└── [slug]/
    └── page.tsx

Essa entrada cobre tudo sob o diretório, então omita um /** final. No macOS e no Linux e WSL2, o diretório app/[slug] precisa existir quando o comando em sandbox é iniciado.

• Colchetes como [slug]: em todas as listas no macOS, e em denyRead e allowRead no Linux e WSL2, os colchetes em ./app/[slug] também são um padrão. A entrada então também corresponde a qualquer caminho sob app nomeado com um caractere de slug, como app/s ou app/g. Com essa entrada em allowRead, ou em allowWrite no macOS, os comandos em sandbox também podem acessar esses caminhos. Renomeie os que eles não devem acessar.
• Colchetes como [user-id] ou [post-id], em que o caractere à esquerda do hífen é ordenado depois do caractere à direita: ./app/[user-id] cobre apenas o diretório com exatamente esse nome, em todas as listas e em todas as plataformas. Antes da v2.1.304, os comandos em sandbox no Linux e WSL2 não conseguiam iniciar enquanto denyRead ou allowRead contivesse uma entrada desse tipo.
• Chaves e parênteses: esses são caracteres comuns, então ~/data/{keys,tokens} cobre um diretório chamado {keys,tokens}, não duas alternativas. Para cobrir ~/data/keys e ~/data/tokens, adicione cada um como uma entrada separada.

sandbox.filesystem.allowWrite

Adicione caminhos onde comandos em sandbox podem escrever, além do diretório de trabalho, do diretório temporário por usuário e dos diretórios que você adicionou com --add-dir, /add-dir ou permissions.additionalDirectories. Use-o quando um subprocesso como kubectl ou uma ferramenta de build precisa escrever fora do projeto.

• Scope: Any file, com limites em configurações de projeto e locais
• Type: array de strings de caminho, usando os prefixos de caminho do sandbox
• Default: não definido, então comandos em sandbox podem escrever no diretório de trabalho, no diretório temporário por usuário, em diretórios que você adicionou com --add-dir ou /add-dir e em diretórios em permissions.additionalDirectories

Isso permite que um build escreva sob /tmp/build e deixa kubectl atualizar seu kubeconfig:

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"]
    }
  }
}

Claude Code mescla entradas allowWrite e os caminhos de suas regras de permissão Edit(...) allow em todos os escopos de configurações que a sessão carrega, deixando de fora os de configurações de repositório enquanto permissions.blockReadsOutsideWorkingDirectories está ativado. Bloqueios de repositório também podem deixar de fora as entradas de um repositório. Uma entrada allowWrite não pode levantar um caminho protegido.

sandbox.filesystem.denyWrite

Bloqueie comandos em sandbox de escrever em caminhos específicos, incluindo caminhos dentro de um diretório que é de outra forma gravável.

• Scope: Any file
• Type: array de strings de caminho, usando os prefixos de caminho do sandbox
• Default: não definido

Isso impede que comandos em sandbox alterem a configuração do sistema ou instalem binários:

{
  "sandbox": {
    "filesystem": {
      "denyWrite": ["/etc", "/usr/local/bin"]
    }
  }
}

Claude Code mescla entradas em todos os escopos de configurações que a sessão carrega e adiciona os caminhos de suas regras de permissão Edit(...) deny.

sandbox.filesystem.denyRead

Bloqueie comandos em sandbox de ler caminhos específicos, como arquivos de credenciais que a política de leitura padrão exporia de outra forma. Para proteger um arquivo de credenciais e mantê-lo utilizável através do proxy do sandbox, consulte sandbox.credentials em vez disso.

• Scope: Any file
• Type: array de strings de caminho, usando os prefixos de caminho do sandbox
• Default: não definido, então comandos em sandbox mantêm o acesso de leitura padrão, que inclui arquivos de credenciais como ~/.aws/credentials

{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/.aws/credentials"]
    }
  }
}

Claude Code mescla entradas em todos os escopos de configurações que a sessão carrega e adiciona os caminhos de suas regras de permissão Read(...) deny. Quando filesystem.disabled é true, Claude Code não impõe essas entradas.

sandbox.filesystem.allowRead

Reabra a leitura para caminhos específicos dentro de uma região que denyRead bloqueia, para construir acesso de leitura somente do espaço de trabalho. Uma entrada denyRead exata ou curinga permanece bloqueada dentro de um allowRead mais amplo, como a tabela de sobreposição mostra. Quando uma entrada denyRead curinga como ~/**/.env corresponde a um diretório, Claude Code bloqueia leituras de seu conteúdo também. Antes da v2.1.236 em macOS, Claude Code reabria os caminhos que uma entrada denyRead curinga correspondia onde uma entrada allowRead mais ampla as cobria, e deixava o conteúdo de um diretório correspondido legível.

• Scope: Any file, com limites em configurações de projeto e locais
• Type: array de strings de caminho, usando os prefixos de caminho do sandbox
• Default: não definido

Isso bloqueia leituras de seu diretório pessoal exceto o projeto em si:

{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

Claude Code resolve uma entrada . para a raiz do projeto em configurações de projeto e para ~/.claude em configurações de usuário. Claude Code mescla entradas em todos os arquivos de configurações que a sessão carrega, a menos que allowManagedReadPathsOnly seja definido, e deixa de fora entradas de configurações de repositório enquanto permissions.blockReadsOutsideWorkingDirectories está ativado. Bloqueios de repositório também podem deixar de fora as entradas de um repositório.

sandbox.filesystem.allowManagedReadPathsOnly

Honre apenas as entradas allowRead que vêm de configurações gerenciadas, para que desenvolvedores não possam reabrir acesso de leitura a caminhos que sua organização bloqueou. Claude Code ainda mescla entradas denyRead de todos os escopos de configurações que a sessão carrega.

• Scope: Managed
• Type: Boolean
  • true: Claude Code honra apenas as entradas allowRead de configurações gerenciadas
  • false: entradas allowRead de outros arquivos de configurações podem ser mescladas
• Default: false

Isso bloqueia leituras do diretório pessoal, reabre ~/work e impede que desenvolvedores reabram qualquer outra coisa:

{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["~/work"],
      "allowManagedReadPathsOnly": true
    }
  }
}

Consulte Keep developers from widening the policy.

sandbox.filesystem.disabled

Ignore isolamento do sistema de arquivos mantendo isolamento de rede. Comandos em sandbox obtêm acesso irrestrito de leitura e escrita ao sistema de arquivos do host, e sua saída de rede permanece confinada a network.allowedDomains. Use-o quando você faz sandbox para controlar onde os comandos se conectam em vez do que eles escrevem. Requer Claude Code v2.1.216 ou posterior.

• Scope: User or managed. Quando configurações gerenciadas configuram sandbox.filesystem de qualquer forma, ou listam uma entrada sandbox.credentials.files com "mode": "deny", apenas configurações gerenciadas podem defini-lo.
• Type: Boolean
  • true: Claude Code ignora isolamento do sistema de arquivos e mantém isolamento de rede
  • false: isolamento do sistema de arquivos permanece ativado
• Default: false, então isolamento do sistema de arquivos permanece ativado

Isso deixa o sistema de arquivos aberto e confina a saída de rede para GitHub e npm:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

Com a camada desativada, Claude Code não impõe entradas denyRead ou credentials.files deny, enquanto entradas credentials.envVars e entradas mask aplicadas continuam funcionando. autoAllowBashIfSandboxed ainda tem true como padrão, então defina-o como false para continuar solicitando. Consulte Disable filesystem isolation para a lista completa de fontes que podem defini-lo e o que muda quando o isolamento está desativado. Requer Claude Code v2.1.216 ou posterior.

sandbox.ignoreViolations

Silencie relatórios de violação de sandbox para caminhos que você espera que um comando sonde e seja recusado, como uma ferramenta que verifica /etc/hosts na inicialização, para que essas negações não apareçam como violações ou no que Claude vê. O sandbox ainda bloqueia o acesso; apenas o relatório é suprimido. As chaves são substrings para corresponder contra o comando, com * correspondendo a cada comando, e os valores são substrings da violação a ignorar para esse comando, como um caminho do sistema de arquivos.

• Scope: Any file, com limites em configurações de projeto e locais
• Type: object mapeando uma substring de comando para um array de substrings de violação, geralmente caminhos
• Default: não definido, então cada violação é relatada

{
  "sandbox": {
    "ignoreViolations": {
      "*": ["/etc/hosts"]
    }
  }
}

sandbox.enableWeakerNestedSandbox

Execute o sandbox do Linux dentro de um contêiner Docker sem privilégios, onde bubblewrap não consegue montar um /proc fresco. Em vez disso, o sandbox interno faz bind-mount do /proc existente do contêiner, o que expõe informações de processo que uma montagem fresca ocultaria. Isso reduz a segurança; use-o apenas quando o contêiner externo já fornece o isolamento que você precisa.

• Scope: Any file, com limites em configurações de projeto e locais
• Type: Boolean
  • true: o sandbox interno faz bind-mount do /proc existente do contêiner em vez de montar um fresco
  • false: o sandbox monta um /proc fresco, o que não funciona em um contêiner Docker sem privilégios
• Default: false

{
  "sandbox": {
    "enabled": true,
    "enableWeakerNestedSandbox": true
  }
}

Apenas Linux e WSL2. Consulte Bubblewrap fails to start inside a container.

sandbox.enableWeakerNetworkIsolation

Deixe comandos em sandbox em macOS alcançar o serviço de confiança TLS do sistema, com.apple.trustd.agent. Ferramentas baseadas em Go como gh, gcloud e terraform precisam disso para verificar certificados TLS quando você usa network.httpProxyPort com um proxy MITM e uma CA personalizada. Isso reduz a segurança abrindo um possível caminho de exfiltração de dados através do serviço de confiança.

• Scope: Any file, com limites em configurações de projeto e locais
• Type: Boolean
  • true: comandos em sandbox em macOS podem alcançar com.apple.trustd.agent
  • false: comandos em sandbox em macOS não podem alcançar o serviço de confiança TLS do sistema
• Default: false

{
  "sandbox": {
    "enabled": true,
    "enableWeakerNetworkIsolation": true
  }
}

Se você não usar um proxy MITM, liste as ferramentas que falham em excludedCommands em vez disso; consulte Go-based CLIs fail TLS verification on macOS.

sandbox.allowAppleEvents

Deixe comandos em sandbox em macOS enviar Apple Events, que open, osascript e ferramentas que abrem URLs em um navegador precisam; sem isso, eles falham com erro -600. Isso remove isolamento de execução de código: comandos em sandbox podem iniciar outros aplicativos sem sandbox sem prompt do usuário e podem enviar comandos AppleScript para aplicativos em execução como Terminal, sujeito ao prompt de consentimento de automação por aplicativo do macOS (TCC).

• Scope: User or managed
• Type: Boolean
  • true: comandos em sandbox em macOS podem enviar Apple Events
  • false: comandos em sandbox em macOS não podem enviar Apple Events, então open e osascript falham com erro -600
• Default: false

{
  "sandbox": {
    "enabled": true,
    "allowAppleEvents": true
  }
}

Para manter isolamento e ainda executar uma ferramenta assim, adicione-a a excludedCommands em vez disso. Consulte Apple Events on macOS.

sandbox.allowNestedUserNamespaces

Permite que os comandos em sandbox no Linux e no WSL2 criem namespaces de usuário, dos quais o próprio sandbox do Chromium e do Electron, um bubblewrap aninhado e o unshare precisam. Se você definir esta chave como true, desativará uma barreira de segurança: o código de um comando em sandbox pode acabar sendo executado fora do sandbox. Para Podman ou Buildah rootless, use excludedCommands, porque o sandbox também os impede de outras formas. Requer o Claude Code v2.1.305 ou posterior.

• Escopo: User or managed. Um true vale quando vem de ~/.claude/settings.json, de JSON passado com --settings ou das configurações gerenciadas. O Claude Code ignora um true no .claude/settings.json ou no .claude/settings.local.json de um projeto. Em uma sessão com CLAUDE_CODE_SUBPROCESS_ENV_SCRUB definida como 1, o Claude Code ignora um true de qualquer fonte. Um false vale vindo de qualquer arquivo, de acordo com a precedência das configurações.
• Tipo: Booleano
  • true: os comandos em sandbox podem criar namespaces de usuário
  • false: esta chave não permite nada extra, e o padrão do sandbox se aplica
• Padrão: false

{
  "sandbox": {
    "enabled": true,
    "allowNestedUserNamespaces": true
  }
}

Com esta chave ativada, não confie em nenhuma das restrições do sandbox, incluindo caminhos protegidos e entradas de credentials.files, para impedir um comando malicioso. No modo de permissão automática, esse comando pode ser executado sem um prompt de permissão. Se sua organização tem uma equipe de segurança, consulte-a antes de ativar a chave.

Para encontrar a correção para sua ferramenta, consulte O Chromium ou o Podman rootless falha dentro do sandbox no Linux.

sandbox.ripgrep

Aponte o sandbox para um binário ripgrep seu em vez do que Claude Code usa, por exemplo, quando sua plataforma precisa de um rg compilado de forma diferente.

• Scope: User or managed
• Type: object com command, o caminho para o binário ripgrep, e args opcional, um array de argumentos para prepender
• Default: não definido, então o sandbox usa o mesmo binário ripgrep que Claude Code. Esse é o binário agrupado, a menos que você defina USE_BUILTIN_RIPGREP para 0

{
  "sandbox": {
    "ripgrep": {
      "command": "/usr/local/bin/rg"
    }
  }
}

sandbox.bwrapPath

Aponte o sandbox para um binário bubblewrap instalado fora de PATH, como uma cópia fornecida em um host isolado. Claude Code usa o caminho tanto para a verificação de dependência de inicialização quanto quando envolve cada comando em sandbox.

• Scope: Managed. Claude Code o lê apenas de configurações gerenciadas para que um arquivo de usuário, projeto ou local não possa apontar o sandbox para um binário diferente.
• Type: string, um caminho absoluto; Claude Code descarta um caminho relativo e volta para busca em PATH
• Default: não definido, então Claude Code encontra bwrap em PATH

{
  "sandbox": {
    "enabled": true,
    "bwrapPath": "/opt/admin/bwrap"
  }
}

Apenas Linux e WSL2.

sandbox.socatPath

Aponte o proxy de rede do sandbox para um binário socat instalado fora de PATH.

• Scope: Managed
• Type: string, um caminho absoluto; Claude Code descarta um caminho relativo e volta para busca em PATH
• Default: não definido, então Claude Code encontra socat em PATH

{
  "sandbox": {
    "enabled": true,
    "socatPath": "/opt/admin/socat"
  }
}

Apenas Linux e WSL2.

sandbox.credentials

Declare os arquivos de credenciais e variáveis de ambiente para proteger de comandos em sandbox. Cada entrada nomeia um arquivo path ou uma variável name e um mode: deny oculta a credencial dentro do sandbox, e mask mostra aos comandos em sandbox um espaço reservado enquanto o proxy do sandbox substitui o valor real em requisições de saída. Claude Code protege apenas as entradas que você lista; não há lista de negação de credenciais integrada.

• Scope: Any file. Claude Code honra entradas mask, allowPlaintextInject, awsPairs e sigv4 apenas de configurações de usuário, configurações gerenciadas e a flag --settings.
• Type: object com files, envVars, allowPlaintextInject, awsPairs e sigv4
• Default: não definido, então nenhuma credencial é protegida

Isso oculta seu arquivo de credenciais AWS e remove GITHUB_TOKEN de comandos em sandbox:

{
  "sandbox": {
    "credentials": {
      "files": [{ "path": "~/.aws/credentials", "mode": "deny" }],
      "envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }]
    }
  }
}

A proteção de arquivo deny faz parte da camada do sistema de arquivos, então não se aplica quando você desativa isolamento do sistema de arquivos; a proteção de variável de ambiente ainda se aplica.

Entradas de credenciais inválidas em configurações gerenciadas

Quando uma entrada sandbox.credentials gerenciada falha na validação, Claude Code continua protegendo a credencial onde pode:

• Uma entrada em files ou envVars que ainda tem um path ou name válido e um mode de mask ou deny, como uma cujo padrão extract não tem grupo de captura, é degradada para mode: "deny" com um aviso, então a credencial permanece bloqueada, não mascarada, até você corrigir a entrada. Uma entrada files degradada fixa filesystem.disabled como uma entrada deny explícita, e o aviso observa que seu bloqueio de leitura não é imposto se configurações gerenciadas desativarem isolamento do sistema de arquivos.
• Uma entrada com um mode desconhecido ou um path ou name inválido é removida.
• Cada caso avisa; se uma entrada é degradada ou removida, as entradas válidas restantes ainda são impostas.

Aplica-se em v2.1.191 e posterior; antes da v2.1.221, cada entrada inválida era removida. Para as outras chaves gerenciadas com manipulação por campo, consulte Invalid entries in managed settings.

sandbox.credentials.files

Proteja arquivos ou diretórios de credenciais de comandos em sandbox. Com "mode": "deny", Claude Code bloqueia leituras do caminho dentro do sandbox, o mesmo bloqueio de leitura que sandbox.filesystem.denyRead. Com "mode": "mask", comandos em sandbox em Linux e WSL2 leem uma cópia sentinela do arquivo, e o proxy do sandbox substitui o valor real em requisições de saída para injectHosts dessa entrada; em macOS o arquivo é ilegível dentro do sandbox em vez disso. "mode": "mask" requer Claude Code v2.1.221 ou posterior.

• Scope: Any file. Claude Code descarta entradas mask de .claude/settings.json de projeto e .claude/settings.local.json local.
• Type: array de objetos, cada um com path e um mode de "deny" ou "mask", mais os campos mask opcionais para arquivos
• Default: não definido, então nenhum arquivo de credenciais é protegido

Isso oculta seu arquivo de credenciais AWS e mascara o arquivo de hosts gh, substituindo o valor real apenas em requisições para api.github.com:

{
  "sandbox": {
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.config/gh/hosts.yml", "mode": "mask", "injectHosts": ["api.github.com"] }
      ]
    }
  }
}

Caminhos usam os mesmos prefixos que as configurações sandbox.filesystem.*, e Claude Code mescla os arrays de todos os escopos de configurações que a sessão carrega. Protect credentials cobre o que ainda se aplica de fontes que você exclui com --setting-sources. Entradas mask requerem Claude Code v2.1.221 ou posterior.

A substituição mask é executada apenas através do proxy do sandbox, então defina sandbox.network.tlsTerminate ou allowPlaintextInject para redes de teste HTTP simples. mask se aplica a um único arquivo, então liste cada arquivo de credenciais individualmente. Claude Code aceita mas ignora os campos mask em uma entrada deny. Mask credentials cobre quais fontes de configurações são honradas, e Mask credential files cobre quando uma entrada volta para deny.

Campos mask para arquivos

Uma entrada mask aceita esses campos opcionais. Sem extract ou decode, Claude Code substitui todo o conteúdo do arquivo por um sentinela. Em macOS com isolamento do sistema de arquivos ativado, Claude Code aplica uma entrada mask como deny antes de extract ou decode ser executado; consulte Mask credential files.

Isso mascara apenas o valor oauth_token no arquivo de hosts gh, substitui cada outra cópia dele no arquivo, torna o arquivo ilegível se o padrão não corresponder a nada e substitui o token real apenas em requisições para api.github.com:

{
  "sandbox": {
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "maskDuplicates": true,
          "onExtractNoMatch": "deny",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

sandbox.credentials.envVars

Proteja variáveis de ambiente de comandos em sandbox. Com "mode": "deny", Claude Code remove a variável do ambiente de comandos em sandbox. Com "mode": "mask", comandos em sandbox veem um valor sentinela por sessão, e o proxy do sandbox substitui o valor real em requisições de saída para injectHosts dessa entrada, então ferramentas como gh e npm continuam autenticando sem nunca manter a credencial real.

• Scope: Any file. Claude Code descarta entradas mask de .claude/settings.json de projeto e .claude/settings.local.json local.
• Type: array de objetos, cada um com name e um mode de "deny" ou "mask", mais os campos mask opcionais para variáveis de ambiente
• Default: não definido, então nenhuma variável de ambiente é protegida

Isso remove NPM_TOKEN de comandos em sandbox e mascara GITHUB_TOKEN, substituindo o valor real apenas em requisições para api.github.com:

{
  "sandbox": {
    "credentials": {
      "envVars": [
        { "name": "NPM_TOKEN", "mode": "deny" },
        { "name": "GITHUB_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] }
      ]
    }
  }
}

O name deve começar com uma letra ou sublinhado e conter apenas letras, dígitos e sublinhados. Claude Code mescla os arrays de todos os escopos de configurações que a sessão carrega e aplica deny quando a mesma variável aparece com ambos os modos. Protect credentials cobre o que ainda se aplica de fontes que você exclui com --setting-sources.

A substituição mask é executada apenas através do proxy do sandbox, então defina sandbox.network.tlsTerminate ou allowPlaintextInject para redes de teste HTTP simples; consulte Mask credentials. Claude Code aceita mas ignora os campos mask em uma entrada deny.

Campos mask para variáveis de ambiente

Uma entrada mask aceita esses campos opcionais. Sem extract ou decode, Claude Code substitui todo o valor por um sentinela. extract e decode não podem ser combinados na mesma entrada.

Isso mascara apenas a senha dentro de DATABASE_URL, desdefine a variável se o padrão não corresponder a nada e mascara um JWT em SERVICE_JWT enquanto deixa cada claim exceto api_key legível:

{
  "sandbox": {
    "credentials": {
      "envVars": [
        {
          "name": "DATABASE_URL",
          "mode": "mask",
          "extract": "://[^:]+:([^@]+)@",
          "onExtractNoMatch": "deny"
        },
        {
          "name": "SERVICE_JWT",
          "mode": "mask",
          "decode": "jwt",
          "maskClaims": ["api_key"]
        }
      ]
    }
  }
}

sandbox.credentials.allowPlaintextInject

Permita substituição mask em requisições HTTP simples bem como HTTPS terminado em TLS. Em HTTP simples a identidade upstream não é verificada e a credencial viaja em texto claro, então deixe isso desativado fora de redes de teste confiáveis.

• Scope: User or managed
• Type: Boolean
  • true: Claude Code permite substituição mask em requisições HTTP simples bem como HTTPS terminado em TLS
  • false: Claude Code permite substituição mask apenas em HTTPS terminado em TLS
• Default: false

{
  "sandbox": {
    "credentials": {
      "allowPlaintextInject": true
    }
  }
}

sandbox.credentials.awsPairs

Agrupe variáveis de ambiente mascaradas que formam uma credencial AWS para re-assinatura SigV4 quando sua credencial vive em variáveis com nomes não padrão. Claude Code vincula o trio convencional AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_SESSION_TOKEN automaticamente quando você mascara seus valores inteiros, então você precisa dessa chave apenas para outros nomes. Requer Claude Code v2.1.224 ou posterior.

• Scope: User or managed
• Type: array de objetos, cada um com accessKeyIdVar, secretAccessKeyVar e opcionalmente sessionTokenVar, nomeando entradas sandbox.credentials.envVars
• Default: não definido, então apenas o trio convencional é emparelhado

Isso vincula três variáveis com nomes personalizados em uma credencial AWS para re-assinatura:

{
  "sandbox": {
    "credentials": {
      "awsPairs": [
        {
          "accessKeyIdVar": "MY_KEY_ID",
          "secretAccessKeyVar": "MY_SECRET_KEY",
          "sessionTokenVar": "MY_SESSION_TOKEN"
        }
      ]
    }
  }
}

Cada variável nomeada deve ser uma entrada mask de valor inteiro em sandbox.credentials.envVars, sem extract ou decode, e pode preencher apenas um slot em todos os pares. Estas regras também se aplicam:

• O proxy re-assina requisições nos hosts listados em injectHosts da entrada do ID de chave de acesso
• Quando sessionTokenVar está definido, o proxy envia o token real como x-amz-security-token em requisições re-assinadas
• Nomear qualquer uma das variáveis convencionais em um par substitui o emparelhamento automático

sandbox.credentials.sigv4

Escolha o que o proxy do sandbox faz com formas de requisição AWS que não consegue re-assinar: streaming para uploads de streaming aws-chunked, presigned para URLs pré-assinadas e sigv4a para assinaturas assimétricas SigV4A. Isso se aplica apenas a requisições assinadas com a ID de chave de acesso de espaço reservado de um par mascarado. Requer Claude Code v2.1.224 ou posterior.

• Scope: User or managed
• Type: object com streaming, presigned e sigv4a, cada um de:
  • "deny": o proxy falha a requisição
  • "passthrough": o proxy encaminha a requisição assinada com o espaço reservado mascarado, então a ferramenta recebe a própria rejeição da AWS
• Default: não definido, então cada forma é "deny"

Isso encaminha uploads de streaming em vez de falhá-los no proxy:

{
  "sandbox": {
    "credentials": {
      "sigv4": {
        "streaming": "passthrough"
      }
    }
  }
}

Com deny, o proxy falha a requisição. Com passthrough, o proxy encaminha a requisição com sua assinatura computada a partir do espaço reservado mascarado, então AWS a rejeita e a ferramenta chamadora recebe a própria resposta da AWS em vez de um erro de proxy.

sandbox.network

Controle quais hosts, portas e sockets os comandos em sandbox podem alcançar. O sandbox roteia o tráfego de saída através de um proxy que impõe essas listas; consulte Network isolation para saber como o proxy decide e quando solicita.

• Scope: Any file. strictAllowlist, allowManagedDomainsOnly e tlsTerminate são lidos de menos fontes, como suas entradas dizem.
• Type: object com as sub-chaves abaixo
• Default: não definido, então nenhum domínio é pré-autorizado e seu modo de permissão decide o que acontece com cada novo host

Isso pré-autoriza GitHub e npm, bloqueia uploads.github.com e deixa comandos se vincularem a localhost:

{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "deniedDomains": ["uploads.github.com"],
      "allowLocalBinding": true
    }
  }
}

Claude Code mescla as sub-chaves de array em escopos de configurações, então um projeto pode adicionar domínios à sua lista de usuário, a menos que um bloqueio de repositório se aplique. As regras de permissão WebFetch(domain:...) allow e deny alimentam as mesmas listas de allow e deny.

sandbox.network.allowUnixSockets

Liste os caminhos de socket Unix aos quais comandos em sandbox podem se conectar em macOS. Claude Code ignora essa lista no Linux e WSL2, onde o filtro seccomp não consegue inspecionar caminhos de socket; use allowAllUnixSockets em vez disso.

• Scope: Any file, com limites em configurações de projeto e locais
• Type: array de strings, cada um um caminho de socket
• Default: não definido, então o sandbox macOS bloqueia cada socket Unix

{
  "sandbox": {
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"]
    }
  }
}

Um caminho de socket pode conceder acesso amplo: permitir /var/run/docker.sock, por exemplo, deixa um comando em sandbox controlar o daemon Docker. Consulte Security limitations.

sandbox.network.allowAllUnixSockets

Deixe comandos em sandbox se conectarem a cada socket Unix. No Linux e WSL2, o filtro seccomp do sandbox bloqueia chamadas socket(AF_UNIX, ...), então essa é a única maneira de permitir sockets Unix lá. Quando o filtro está faltando, o que /sandbox relata em sua aba Dependencies, o sandbox não bloqueia chamadas de socket Unix. Consulte Set up Linux and WSL2 para saber de onde o filtro vem.

• Scope: Any file, com limites em configurações de projeto e locais
• Tipo: booleano
  • true: os comandos no sandbox podem se conectar a todos os sockets Unix. No Linux e no WSL2, eles também podem se conectar a sockets de VM, a família de endereços AF_VSOCK
  • false: o sandbox bloqueia conexões de socket Unix: no macOS, exceto os caminhos em allowUnixSockets, e no Linux e no WSL2, por meio do filtro seccomp quando ele está presente
• Default: false

{
  "sandbox": {
    "network": {
      "allowAllUnixSockets": true
    }
  }
}

No WSL2, true também reabre o socket interop que inicia binários Windows como cmd.exe e powershell.exe.

sandbox.network.allowLocalBinding

Deixe comandos em sandbox em macOS escutarem em portas de rede, por exemplo, para iniciar um servidor de desenvolvimento, e se conectarem a qualquer porta em localhost. Um comando que escuta em um endereço que não é de loopback aceita conexões de outras máquinas. A chave não tem efeito no Linux e WSL2, onde cada comando em sandbox tem sua própria interface de loopback. Para alcançar um servidor no host a partir do Linux ou WSL2, consulte A command fails to reach a server on localhost.

• Scope: Any file, com limites em configurações de projeto e locais
• Type: Boolean
  • true: comandos em sandbox em macOS podem escutar em qualquer endereço local e se conectar a qualquer porta em localhost
  • false: comandos em sandbox em macOS não podem escutar em uma porta nem se conectar diretamente a servidores em localhost
• Default: false

{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

sandbox.network.allowMachLookup

Liste nomes de serviço XPC e Mach adicionais que o sandbox macOS pode procurar. Ferramentas que se comunicam sobre XPC, como o iOS Simulator ou Playwright, precisam de seus serviços listados aqui.

• Scope: Any file, com limites em configurações de projeto e locais
• Type: array de strings, cada um um nome de serviço; um único * final corresponde a um prefixo e "*" sozinho corresponde a cada serviço
• Default: não definido

Isso permite cada serviço sob o prefixo com.apple.coresimulator.:

{
  "sandbox": {
    "network": {
      "allowMachLookup": ["com.apple.coresimulator.*"]
    }
  }
}

sandbox.network.allowedDomains

Pré-autorize domínios para tráfego de saída de comandos em sandbox, então o sandbox não solicita por eles. Curingas como *.example.com correspondem a subdomínios, e um sufixo :port opcional limita uma entrada a uma porta; uma entrada sem porta corresponde a cada porta.

• Scope: Any file, com limites em configurações de projeto e locais. Apenas configurações gerenciadas quando allowManagedDomainsOnly está definido.
• Type: array de strings, cada um um domínio, padrão curinga ou literal IP, com um sufixo :port opcional
• Default: não definido, então seu modo de permissão decide o que acontece com cada novo host

Isso pré-autoriza GitHub em cada porta, cada subdomínio npm e um host API em porta 443 apenas:

{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "api.example.com:443"]
    }
  }
}

Escreva literais IPv6 entre colchetes, com uma porta opcional: "[::1]" permite cada porta e "[::1]:443" uma porta. A forma entre colchetes requer Claude Code v2.1.229 ou posterior. Consulte IPv6 addresses in domain lists.

sandbox.network.deniedDomains

Bloqueie domínios para tráfego de saída de comandos em sandbox, usando a mesma sintaxe de curinga, porta e IPv6 que allowedDomains. Um domínio negado permanece bloqueado mesmo quando uma entrada allowedDomains também o corresponde.

• Scope: Any file
• Type: array de strings, cada um um domínio, padrão curinga ou literal IP, com um sufixo :port opcional
• Default: não definido

{
  "sandbox": {
    "network": {
      "deniedDomains": ["sensitive.cloud.example.com"]
    }
  }
}

Claude Code mescla essa lista de cada fonte de configurações que a sessão carrega mesmo quando allowManagedDomainsOnly está definido, então um desenvolvedor pode sempre apertar a lista de negação. Para literais IPv6, consulte IPv6 addresses in domain lists.

Uma entrada escrita com o ponto final que marca um nome de domínio totalmente qualificado, como example.com., bloqueia as mesmas conexões que example.com.

sandbox.network.strictAllowlist

Negue acesso de comandos em sandbox a hosts fora da allowlist em vez de solicitar aprovação. A allowlist é allowedDomains mais domínios de regras WebFetch(domain:...) allow, ou apenas as entradas de configurações gerenciadas quando allowManagedDomainsOnly está definido. Locks that apply without an admin-required sandbox cobre as entradas de um repositório. Requer Claude Code v2.1.219 ou posterior.

• Scope: User or managed. Um repositório não pode ativá-lo ou desativá-lo.
• Type: Boolean
  • true: Claude Code nega acesso de comandos em sandbox a hosts fora da allowlist
  • false: a menos que outro arquivo de configurações confiável defina true, Claude Code decide um host fora da allowlist por modo de permissão em vez de negá-lo imediatamente: em modo auto ele verifica o host contra os domínios permitidos por comando do comando, em modo dontAsk nega, em modo bypassPermissions e em sessões de modo de planejamento de terminal interativo onde bypass está disponível permite, e caso contrário pergunta a você
• Default: false

{
  "sandbox": {
    "network": {
      "strictAllowlist": true
    }
  }
}

Claude Code impõe isso apenas para comandos em sandbox; ferramentas em processo como WebFetch ainda seguem suas regras de permissão. Quando qualquer uma das fontes honradas a define como true, ela permanece ativada. Consulte Network isolation. Requer Claude Code v2.1.219 ou posterior.

sandbox.network.allowManagedDomainsOnly

Bloqueie a allowlist de rede para o que as configurações gerenciadas definem. Claude Code então honra apenas allowedDomains e regras WebFetch(domain:...) allow de configurações gerenciadas, ignora domínios de configurações de usuário, projeto, local e --settings, e bloqueia um domínio não permitido automaticamente em vez de solicitar.

• Scope: Managed
• Type: Boolean
  • true: Claude Code honra apenas allowedDomains e regras WebFetch(domain:...) allow de configurações gerenciadas e bloqueia um domínio não permitido em vez de solicitar
  • false: domínios de outros arquivos de configurações podem ser mesclados na allowlist
• Default: false

Isso bloqueia a allowlist para GitHub e npm e ignora qualquer domínio que desenvolvedores adicionem:

{
  "sandbox": {
    "network": {
      "allowManagedDomainsOnly": true,
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

Enquanto a chave é true, o sandbox é exigido pelo administrador, e apenas configurações gerenciadas podem definir uma porta de proxy.

Domínios negados ainda são mesclados de cada fonte que a sessão carrega. Consulte Keep developers from widening the policy.

sandbox.network.httpProxyPort

Aponte o sandbox para seu próprio proxy HTTP em vez do que Claude Code executa. Organizações fazem isso para inspecionar tráfego HTTPS, aplicar suas próprias regras de filtragem ou registrar requisições em log. Seu proxy assume a filtragem, e Claude Code deixa de aplicar suas listas de domínios e prompts de rede ao tráfego enviado para lá. Quando não definido, Claude Code inicia seu próprio proxy para tráfego HTTP.

• Scope: Any file, a menos que outras configurações de sandbox limitem quais arquivos podem definir uma porta
• Type: number, uma porta TCP local
• Default: não definido, então Claude Code executa seu próprio proxy

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080
    }
  }
}

Defina socksProxyPort também se seu proxy deve carregar tráfego SOCKS também; com apenas um dos dois definido, Claude Code ainda executa seu próprio proxy para o outro protocolo. Consulte Custom proxy configuration.

sandbox.network.socksProxyPort

Aponte o sandbox para seu próprio proxy SOCKS5 em vez do que Claude Code executa. Seu proxy assume a filtragem, e Claude Code deixa de aplicar suas listas de domínios e prompts de rede ao tráfego enviado para lá. Quando não definido, Claude Code inicia seu próprio proxy para tráfego SOCKS.

• Scope: Any file, a menos que outras configurações de sandbox limitem quais arquivos podem definir uma porta
• Type: number, uma porta TCP local
• Default: não definido, então Claude Code executa seu próprio proxy

{
  "sandbox": {
    "network": {
      "socksProxyPort": 8081
    }
  }
}

Consulte Custom proxy configuration.

sandbox.network.tlsTerminate

Faça o proxy do sandbox terminar TLS para que ele possa ler o conteúdo de requisições HTTPS. Isso é experimental, e a substituição de credenciais mask requer isso. Defina {} para gerar uma autoridade de certificado efêmera para a sessão, ou defina caCertPath e caKeyPath para usar a sua própria.

• Scope: User or managed. Um repositório não pode ativá-lo ou fornecer uma autoridade de certificado.
• Type: object com caCertPath e caKeyPath strings opcionais, cada um um caminho de arquivo
• Default: não definido, então o proxy não termina ou inspeciona TLS

{
  "sandbox": {
    "network": {
      "tlsTerminate": {}
    }
  }
}

Quando mais de uma fonte honrada a define, Claude Code usa o valor da fonte com maior precedência: configurações gerenciadas, depois a flag --settings, depois configurações de usuário.

Memória e contexto

Controle o que o Claude Code carrega no contexto, como ele compacta e onde mantém a memória e os planos. Consulte Gerenciar o contexto e Memória.

autoCompactEnabled

Faz o Claude Code compactar a conversa automaticamente quando o contexto se aproxima do limite. Aparece em /config como Auto-compact, e alterná-la ali grava esta chave nas suas configurações de usuário.

• Escopo: Any file
• Tipo: Boolean
  • true: o Claude Code compacta a conversa automaticamente quando o contexto se aproxima do limite
  • false: o Claude Code não compacta automaticamente
• Padrão: true
• Substituições por sessão: DISABLE_AUTO_COMPACT desativa a compactação automática para uma sessão; qualquer uma das duas que a desative, a outra não consegue reativá-la

{
  "autoCompactEnabled": false
}

O comando manual /compact continua funcionando enquanto a compactação automática está desativada. Se você desativar a compactação automática, a compactação em ociosidade também é desativada.

autoCompactWindow

Define o quanto a janela de contexto fica cheia antes de o Claude Code compactar automaticamente.

• Escopo: Any file
• Tipo: número de tokens, de 100000 a 1000000. O Claude Code limita o valor à janela de contexto do seu modelo; a visão geral dos modelos lista a janela de cada modelo
• Padrão: não definido, então o Claude Code escolhe uma janela ajustada ao seu modelo
• Substituições por sessão: --autocompact tem precedência sobre esta chave para uma sessão, e CLAUDE_CODE_AUTO_COMPACT_WINDOW tem precedência sobre ambas, a menos que o Claude Code ignore o valor da variável

{
  "autoCompactWindow": 500000
}

O comando /autocompact salva uma janela para o modelo atual em modelSettings, que tem precedência sobre esta chave no mesmo arquivo para esse modelo. Definir a janela de compactação automática explica como o comando, a flag, a variável e a configuração interagem.

autoMemoryDirectory

Armazena a memória automática em um diretório de sua escolha em vez do padrão por projeto.

• Escopo: Any file
• Tipo: string, um caminho de diretório absoluto ou com prefixo ~/
• Padrão: não definido, então o Claude Code usa ~/.claude/projects/<project>/memory/

{
  "autoMemoryDirectory": "~/my-memory-dir"
}

Em configurações de projeto ou locais, o Claude Code respeita esta chave sob a mesma regra de confiança do workspace que os hooks, já que um repositório clonado pode fornecer esses arquivos.

autoMemoryEnabled

Ativa ou desativa a memória automática. Quando false, o Claude não lê nem grava no diretório de memória automática. Você também pode alterná-la com /memory durante uma sessão, o que grava esta chave nas suas configurações de usuário.

• Escopo: Any file
• Tipo: Boolean
  • true: o mesmo que não definido; a memória automática permanece ativada, a menos que algo com prioridade sobre esta chave a desative para a sessão, como --bare, o modo seguro ou CLAUDE_CODE_DISABLE_AUTO_MEMORY
  • false: o Claude não lê nem grava no diretório de memória automática
• Padrão: true
• Substituições por sessão: CLAUDE_CODE_DISABLE_AUTO_MEMORY tem precedência sobre esta chave para uma sessão, em qualquer direção

{
  "autoMemoryEnabled": false
}

bashOutputMaxChars

Define quantos caracteres da saída de um comando Bash ou PowerShell bem-sucedido o Claude recebe inline. Quando a saída ultrapassa o limite, o Claude Code a salva em um arquivo e o Claude recebe uma prévia curta mais o caminho do arquivo. Aumente o limite quando a saída de comandos, como um build detalhado ou o log completo de uma suíte de testes, ultrapassar rotineiramente o padrão e você quiser que o Claude a leia sem abrir o arquivo. Requer o Claude Code v2.1.261 ou posterior.

• Escopo: Any file
• Tipo: número de caracteres, um inteiro positivo. O Claude Code restringe o valor ao intervalo de 4000 a 128000
• Padrão: não definido, então o Claude recebe até 30.000 caracteres inline

{
  "bashOutputMaxChars": 100000
}

Quando você define esta chave, o Claude Code ignora a variável de ambiente BASH_MAX_OUTPUT_LENGTH.

claudeMd

Injeta instruções no estilo CLAUDE.md como memória gerenciada pela organização sem implantar um arquivo separado. O Claude Code carrega o texto como uma entrada de memória gerenciada antes dos arquivos CLAUDE.md de usuário e de projeto.

• Escopo: Managed
• Tipo: string, o texto de um arquivo CLAUDE.md; escreva-o como escreveria o arquivo, incluindo markdown, com quebras de linha como \n
• Padrão: não definido

Este exemplo implanta duas regras como uma lista markdown curta:

{
  "claudeMd": "# Engineering rules\n\n- Always run make lint before committing.\n- Never push directly to main."
}

Consulte Implantar CLAUDE.md para toda a organização.

claudeMdExcludes

Ignora arquivos CLAUDE.md específicos quando o Claude Code carrega a memória. Em um monorepo grande, use-a para ignorar arquivos CLAUDE.md de outras equipes que não são relevantes para o seu trabalho; Excluir arquivos CLAUDE.md irrelevantes, no guia de bases de código grandes, detalha esse caso. Os padrões são comparados com caminhos absolutos de arquivos.

• Escopo: Any file
• Tipo: array de strings, cada uma um padrão glob ou caminho absoluto
• Padrão: não definido, então o Claude Code carrega todos os CLAUDE.md que encontrar

{
  "claudeMdExcludes": ["**/vendor/**/CLAUDE.md"]
}

As exclusões se aplicam apenas a arquivos de memória de usuário, de projeto e locais; arquivos CLAUDE.md de política gerenciada não podem ser excluídos.

env

Define variáveis de ambiente para cada sessão e para os subprocessos que o Claude Code inicia a partir dela. A maioria das variáveis na referência de variáveis de ambiente pode ir aqui, e é assim que você aplica uma delas a todas as sessões ou a distribui para a sua equipe. Configurações de projeto e locais não podem definir algumas delas.

• Escopo: Any file
• Tipo: objeto que mapeia nomes de variáveis para valores string
• Padrão: não definido

Este exemplo desativa a compactação automática e encaminha as requisições de API por um proxy:

{
  "env": {
    "DISABLE_AUTO_COMPACT": "1",
    "ANTHROPIC_BASE_URL": "https://proxy.example.com"
  }
}

Como os valores de env interagem com o seu shell

• Um valor aqui sobrescreve a mesma variável exportada no seu shell e, quando mais de um arquivo de configurações define uma variável, aplica-se o de maior precedência. Variáveis que o Claude Code ignora em env lista as exceções para configurações de projeto e locais.
• Quando o aplicativo Claude Desktop ou um executor de ambiente auto-hospedado inicia a sessão, o ambiente de inicialização que ele constrói tem precedência: o Claude Code ignora um valor de env de qualquer arquivo de configurações para uma variável que o ambiente de inicialização já define. O log de depuração nomeia cada variável ignorada.
• Para cancelar uma exportação do shell, defina a variável como "". O Claude Code trata um valor vazio como não definido para a seleção de provedor, e os subprocessos herdam o valor vazio.
• NO_COLOR e FORCE_COLOR definidas aqui alcançam apenas subprocessos. Para alterar as cores da própria interface do Claude Code, defina-as no seu shell antes de iniciar o claude.
• Os valores aqui ficam em texto simples no arquivo de configurações e alcançam todos os subprocessos que o Claude Code inicia. Para um token bearer OTLP que é rotacionado, use otelHeadersHelper; para credenciais de API, use apiKeyHelper.

Quando o Claude Code aplica os valores de env

• De configurações de usuário, --settings e configurações gerenciadas: na inicialização e, novamente, na sessão em execução quando uma alteração salva modifica o env mesclado.
• De configurações de projeto e locais: depois que você confia no workspace, ou na inicialização no modo -p, que nunca mostra o diálogo de confiança, e novamente quando uma alteração salva modifica o env mesclado.
• Variáveis que o Claude Code classifica como seguras, como seleção de modelo, timeouts e limites, e alternâncias de recursos: na inicialização, a partir de todos os arquivos de configurações, exceto as variáveis que configurações de projeto e locais não podem definir.
• Depois que você move a sessão com /cd na v2.1.246 ou posterior: os valores de env de projeto e locais do novo diretório, somados aos do diretório anterior.

Variáveis que o Claude Code ignora em env

• Configurações de projeto e locais não podem definir variáveis que um repositório clonado não deveria controlar; defina-as no seu shell, nas configurações de usuário ou nas configurações gerenciadas. O Claude Code descarta cada uma delas, exceto alguns valores que desativam a telemetria, e registra um aviso que você pode ver com claude --debug. Elas incluem:

  • Variáveis que escolhem onde o Claude Code armazena ou grava seus próprios arquivos: CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR e as variáveis de diretório do sistema operacional, como HOME, TMPDIR, TMP, TEMP e a família XDG_*.

  • Variáveis do Windows que escolhem os programas e a configuração de toda a máquina para os processos que o Claude Code inicia, como SystemRoot, ComSpec, ProgramData, LOCALAPPDATA, PATHEXT, PSModulePath e a família ProgramFiles.

  • Variáveis que exportam o conteúdo da sessão: OTEL_LOG_RAW_API_BODIES e o par de rastreamento beta detalhado ENABLE_BETA_TRACING_DETAILED e BETA_TRACING_ENDPOINT.

  • As variáveis do exportador OpenTelemetry que ativam a telemetria, escolhem para onde ela vai ou escolhem qual conteúdo ela captura:

    • CLAUDE_CODE_ENABLE_TELEMETRY, mais o par beta de telemetria aprimorada CLAUDE_CODE_ENHANCED_TELEMETRY_BETA e ENABLE_ENHANCED_TELEMETRY_BETA
    • Os seletores de exportador OTEL_LOGS_EXPORTER, OTEL_METRICS_EXPORTER e OTEL_TRACES_EXPORTER
    • As variáveis de conteúdo OTEL_LOG_USER_PROMPTS, OTEL_LOG_ASSISTANT_RESPONSES, OTEL_LOG_TOOL_CONTENT e OTEL_LOG_TOOL_DETAILS
    • Variáveis OTEL_EXPORTER_OTLP_* cujos nomes terminam em _ENDPOINT, _HEADERS, _PROTOCOL, _CERTIFICATE, _CLIENT_KEY ou _INSECURE, nas formas genérica e por sinal, como OTEL_EXPORTER_OTLP_ENDPOINT e OTEL_EXPORTER_OTLP_METRICS_HEADERS
    • OTEL_EXPORTER_PROMETHEUS_HOST e OTEL_EXPORTER_PROMETHEUS_PORT

    Apenas estes valores ainda se aplicam a partir de configurações de projeto e locais, porque desativam algo: none para os três seletores de exportador, e um valor de desativação como 0 para OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_CONTENT e OTEL_LOG_TOOL_DETAILS. Esse valor sobrescreve a mesma variável nas suas configurações de usuário, mas não uma que seja definida pelo ambiente a partir do qual você inicia o Claude Code, por um arquivo --settings ou pelas configurações gerenciadas.

    Quando um arquivo de configurações de projeto ou local define uma variável deste grupo, uma sessão interativa local mostra um aviso na inicialização. Execute /status ou claude doctor para ver quais o Claude Code ignorou e quais desativaram a telemetria; ambos listam nomes, nunca valores. Uma execução não interativa com -p ou uma sessão do Agent SDK não mostra aviso, então verifique se o seu coletor ainda recebe dados depois de atualizar. Se não receber, defina as variáveis nas suas configurações de usuário, nas configurações gerenciadas, no ambiente do job ou em um arquivo que você passe com --settings.

    Ignorar este grupo em configurações de projeto e locais requer o Claude Code v2.1.282 ou posterior.

  • Variáveis que alteram como o Claude Code inicia ou sincroniza, como CLAUDE_CODE_PROCESS_WRAPPER, CLAUDE_CODE_SYNC_SKILLS, CLAUDE_CODE_SYNC_PLUGINS, CLAUDE_CODE_PLUGIN_CACHE_DIR e CLAUDE_CODE_PLUGIN_SEED_DIR.

  • A variável do modo de leitor de tela CLAUDE_AX_SCREEN_READER e as outras variáveis cujos nomes começam com CLAUDE_AX_, como CLAUDE_AX_STARTUP_QUIET_MS.

  • CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS, que define o temporizador de um diálogo não respondido.

  • CLAUDE_CODE_DISABLE_ATTACHMENTS, que desativa o processamento de anexos.

  • CLAUDE_CODE_DISABLE_FILE_MENTIONS, que impede o Claude Code de expandir menções @ de arquivos e diretórios.

  Antes da v2.1.251, configurações de projeto e locais também podiam definir as variáveis desta lista que escolhem onde o Claude Code grava seus arquivos ou que exportam o conteúdo da sessão, exceto HOME e XDG_CONFIG_HOME. Antes da v2.1.290, também podiam definir as variáveis de temporizador de diálogo e CLAUDE_CODE_DISABLE_ATTACHMENTS.

• Variáveis de identidade pertencentes aos ambientes de hospedagem do Claude Code, como CLAUDE_CODE_REMOTE e CLAUDE_CODE_ACCOUNT_UUID, são ignoradas em todos os arquivos.

• CLAUDE_CODE_MESSAGING_SOCKET e CLAUDE_CODE_MESSAGING_TOKEN, que o próprio Claude Code exporta, são ignoradas em todos os arquivos. Ignorar a variável de socket requer o Claude Code v2.1.224 ou posterior, e ignorar o token requer a v2.1.228 ou posterior.

• CLAUDE_CODE_PROJECT_DIR_NAME, que o Claude Code lê apenas do ambiente de inicialização, é ignorada em todos os arquivos; requer a v2.1.234 ou posterior.

• CLAUDE_CODE_RESTRICTED, que o Claude Code lê apenas do ambiente de inicialização, é ignorada em todos os arquivos.

• CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY, que o Claude Code lê apenas do ambiente de inicialização, é ignorada em todos os arquivos. A variável requer o Claude Code v2.1.283 ou posterior.

• CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT, CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT, CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT e CLAUDE_CODE_DISABLE_MOUNTED_DRIVE_RM_PROMPT, que o Claude Code lê apenas do ambiente de inicialização, são ignoradas em todos os arquivos.

• CLAUDE_CODE_WARN_DISK_FREE_GIB e CLAUDE_CODE_WARN_MEMORY_FREE_GIB, que o Claude Code lê apenas do ambiente de inicialização, são ignoradas em todos os arquivos. As variáveis requerem o Claude Code v2.1.304 ou posterior.

fileCheckpointingEnabled

Faz o Claude Code criar snapshots dos arquivos antes de cada edição para que o /rewind possa restaurá-los. Aparece em /config como Rewind code (checkpoints), e alterná-la ali grava esta chave nas suas configurações de usuário.

• Escopo: Any file
• Tipo: Boolean
  • true: o Claude Code cria snapshots dos arquivos antes de cada edição para que o /rewind possa restaurá-los
  • false: o Claude Code não cria snapshots dos arquivos, então o /rewind não consegue restaurá-los
• Padrão: true
• Substituições por sessão: CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING desativa o checkpointing para uma sessão; qualquer uma das duas que o desative, a outra não consegue reativá-lo

{
  "fileCheckpointingEnabled": false
}

Em uma execução -p ou em uma sessão do Agent SDK, o Claude Code ignora esta chave. O SDK ativa o checkpointing com sua opção enableFileCheckpointing, e uma execução -p simples precisa de CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true. Consulte Checkpointing de arquivos no Agent SDK.

idleCompaction

A compactação em ociosidade compacta uma conversa longa da qual você se afastou, pouco antes de o cache de prompt dela expirar. Sua próxima mensagem então envia um resumo em vez da conversa inteira. Quando você volta, a conversa mostra uma linha que começa com Compacted while idle, before the prompt cache expired.

A compactação em ociosidade fica ativada por padrão para conversas que atendem a todas estas condições:

• Sessão: você está em uma sessão interativa no terminal
• Compactação automática: autoCompactEnabled está ativada
• Cache de prompt: a conversa está no TTL de cache de prompt de uma hora
• Feature flags: o Claude Code consegue buscar feature flags da Anthropic
• Tamanho: o contexto da conversa atingiu o limite de tokens, que você pode alterar a partir do padrão de 200.000
• Tempo ocioso: passaram-se cerca de 54 minutos desde a última requisição, e seu computador está ativo nesse momento

Para desativar a compactação em ociosidade, defina esta chave como false.

• Escopo: Any file
• Tipo: Boolean
  • true: o Claude Code compacta conversas ociosas que atendem às condições
  • false: o Claude Code não compacta enquanto sua sessão está ociosa
• Padrão: true
• Substituições por sessão: DISABLE_AUTO_COMPACT desativa a compactação em ociosidade junto com a compactação automática

{
  "idleCompaction": false
}

Para desativar ou ativar a compactação em ociosidade de dentro de uma sessão, execute /config e altere a linha Idle compaction. Sua escolha é salva nas suas configurações de usuário e se aplica imediatamente. A linha requer o Claude Code v2.1.302 ou posterior. Se você executa uma dessas versões e o /config não mostra a linha, verifique estas causas:

• Outra fonte de configurações define a chave: um valor nas configurações gerenciadas, na flag --settings ou em um arquivo de configurações de projeto ou local sobrescreve suas configurações de usuário. Altere a chave nessa fonte
• Feature flags indisponíveis: onde o Claude Code não consegue buscar feature flags da Anthropic, a compactação em ociosidade não é executada, então não há nada para desativar

A chave requer o Claude Code v2.1.290 ou posterior. Em uma versão anterior, que ignora esta chave, desative autoCompactEnabled para interromper a compactação em ociosidade.

Alterar o limite da compactação em ociosidade

Defina CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS como o número de tokens que o contexto de uma conversa precisa atingir antes que a compactação em ociosidade se aplique a ela. Use um número inteiro positivo. Valores abaixo de 100000 são elevados para 100000, o limite mais baixo.

No padrão, uma conversa em uma janela de contexto de 200K compacta automaticamente antes de atingir 200.000 tokens. Este exemplo reduz o limite para 150.000 para que essas conversas se qualifiquem:

{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
  }
}

plansDirectory

Escolhe onde o Claude Code armazena os arquivos de plano que ele grava no modo de planejamento. O Claude Code resolve o caminho em relação à raiz do projeto.

• Escopo: Any file
• Tipo: string, um caminho relativo à raiz do projeto
• Padrão: não definido, então o Claude Code usa ~/.claude/plans

{
  "plansDirectory": "./plans"
}

O Claude Code armazena os planos em ~/.claude/plans em vez do diretório que você definiu em casos como estes:

• Fora da raiz do projeto: o caminho é resolvido fora da raiz do projeto, como acontece com "../plans".
• Barra invertida no macOS, Linux e WSL: o caminho resolvido contém uma barra invertida, como o "docs\\plans" no estilo Windows. Escreva "docs/plans", que também funciona no Windows.

skillListingBudgetFraction

A cada turno, o Claude vê uma listagem das suas skills com suas descrições, e o Claude Code limita essa listagem a uma fração da janela de contexto. Quando a listagem ultrapassa o limite, o Claude Code mantém o nome de todas as skills, mas descarta as descrições das skills menos usadas, de modo que o Claude ainda pode invocar essas skills, mas tem menos probabilidade de escolher uma delas por conta própria. Aumente esta chave para manter mais descrições visíveis ao custo de mais contexto por turno.

• Escopo: Any file
• Tipo: número, uma fração maior que 0 e no máximo 1
• Padrão: 0.01, que reserva 1% da janela de contexto

{
  "skillListingBudgetFraction": 0.02
}

Para ver quanto contexto a listagem usa e quais skills contribuem mais, execute /doctor.

skillListingMaxDescChars

A cada turno, o Claude vê uma listagem das suas skills que mostra o texto de description e when_to_use de cada skill. Esta chave limita quantos caracteres desse texto o Claude Code mostra por skill; textos mais longos são cortados no limite.

• Escopo: Any file
• Tipo: número de caracteres, um inteiro positivo
• Padrão: 1536

{
  "skillListingMaxDescChars": 2048
}

Aumente-a para manter descrições longas intactas ao custo de mais contexto por turno; reduza-a para caber mais skills dentro de skillListingBudgetFraction.

taskOutputMaxChars

[!WARNING]

Removida na v2.1.277, junto com a ferramenta TaskOutput cujo tamanho ela definia. Defini-la não tem efeito nas versões atuais. O Claude lê o arquivo de saída de uma tarefa em segundo plano com Read.

Até a v2.1.276, você definia esta chave como o número de caracteres da saída de uma tarefa em segundo plano que o Claude recebia inline quando lia a tarefa com a ferramenta TaskOutput.

Interface e terminal

Altere como Claude Code aparece e se comporta no seu terminal: tema, modo de editor, linha de status, spinner, notificações dentro da sessão e acessibilidade. Veja Configuração de terminal.

askUserQuestionTimeout

Deixe um diálogo AskUserQuestion sem resposta continuar automaticamente após um período de tempo ocioso, enviando quaisquer opções que você já tivesse selecionado. Defina isso quando você se afastar e quiser que Claude continue sem você. Com o padrão, as perguntas aguardam até que você as responda. Para saber quando o temporizador pausa ou nunca inicia, veja Timeout de continuação automática de perguntas.

• Scope: User or managed
• Type: string, um de "60s", "5m", "10m", ou "never"
• Default: "never"

{
  "askUserQuestionTimeout": "5m"
}

Aparece em /config como Question auto-continue timeout, que escreve esta chave nas configurações do usuário; Claude Code oculta a linha enquanto configurações gerenciadas ou a flag --settings definem a chave.

autoContinueAtUsageLimit

Depois que um limite de uso do claude.ai interrompe sua sessão, aguarde na sessão aberta e continue a tarefa automaticamente após a redefinição. Veja Desativar continuação automática. Requer Claude Code v2.1.234 ou posterior.

• Scope: User or managed. Leia a partir das configurações do usuário, --settings e configurações gerenciadas apenas. Quando nenhum desses define a chave, um arquivo de configurações de projeto ou local que a define desativa o recurso em vez de ser ignorado.
• Type: Boolean
  • true: depois que um limite de uso do claude.ai interrompe sua sessão, Claude Code aguarda na sessão aberta e continua a tarefa automaticamente após a redefinição
  • false: Claude Code não inicia a espera por conta própria. Você ainda pode iniciar uma espera você mesmo no menu de opções de limite de uso
• Default: true

{
  "autoContinueAtUsageLimit": false
}

Aparece em /config como Continue automatically at usage limit, que escreve esta chave nas configurações do usuário; Claude Code oculta a linha enquanto configurações gerenciadas ou a flag --settings definem a chave.

autoScrollEnabled

Siga a nova saída até o final da conversa em renderização em tela cheia. Desative-a para permanecer onde você rolou enquanto Claude continua trabalhando; prompts de permissão ainda rolam para a visualização.

• Scope: Any file
• Type: Boolean
  • true: a conversa segue a nova saída até o final
  • false: você permanece onde rolou enquanto Claude continua trabalhando; prompts de permissão ainda aparecem abaixo da transcrição
• Default: true

{
  "autoScrollEnabled": false
}

Aparece em /config como Auto-scroll quando a renderização em tela cheia está ativada, que escreve esta chave nas configurações do usuário.

axScreenReader

Renderize saída amigável ao leitor de tela: texto simples sem bordas decorativas ou animações. O modo leitor de tela usa o renderizador clássico, portanto a configuração tui não tem efeito enquanto está ativo; sessões em segundo plano anexadas ainda renderizam em tela cheia.

• Scope: User or managed. Você também pode definir a chave em um arquivo que passa com --settings. Claude Code ignora a chave nas configurações de projeto e locais, portanto nem um repositório nem seu próprio .claude/settings.local.json podem ativar ou desativar o modo leitor de tela.
• Type: Boolean
  • true: Claude Code renderiza texto simples sem bordas decorativas ou animações, usando o renderizador clássico
  • false: Claude Code renderiza normalmente
• Default: unset, portanto o modo leitor de tela está desativado
• Per-session overrides: --ax-screen-reader tem precedência sobre CLAUDE_AX_SCREEN_READER, e ambos têm precedência sobre esta chave para uma sessão

{
  "axScreenReader": true
}

bashEditDiffEnabled

Escolha se Claude Code registra quais arquivos foram alterados em um repositório Git enquanto um comando Bash é executado. Quando registra, você vê seu diff no terminal após o comando, e seus hooks PostToolUse Bash recebem a lista de arquivos alterados.

Um arquivo listado nem sempre é um que o comando alterou. Uma alteração que outro programa ou outra chamada Bash fez enquanto o comando era executado também pode aparecer lá.

Defina a chave como true para registrá-los em todos os modos de permissão. Requer Claude Code v2.1.269 ou posterior.

• Scope: User or managed. Um true conta apenas a partir de suas configurações de usuário, JSON passado com --settings, ou configurações gerenciadas, portanto um true em um arquivo .claude/settings.json ou .claude/settings.local.json de um repositório não pode ativar o registro. Um false em qualquer arquivo de repositório ainda o desativa a menos que um arquivo de precedência mais alta defina true.
• Type: Boolean
• Default: unset, portanto Claude Code registra alterações no modo auto e modo bypassPermissions quando direciona Claude a editar arquivos através de Bash
• Per-session overrides: CLAUDE_CODE_BASH_EDIT_DIFF tem precedência sobre esta chave para uma sessão

{
  "bashEditDiffEnabled": true
}

companyAnnouncements

Mostre os anúncios da sua organização aos usuários na inicialização. Quando você lista mais de um, Claude Code escolhe um aleatoriamente para cada sessão; no primeiro lançamento de uma pessoa, ele mostra a primeira entrada.

• Scope: Any file
• Type: array de strings
• Default: unset, portanto nenhum anúncio é exibido

{
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.example.com"
  ]
}

defaultShell

Escolha se Bash ou PowerShell executa os comandos shell que você digita com o prefixo ! na caixa de entrada, aqueles que Claude Code executa diretamente e adiciona à sessão.

"powershell" funciona apenas enquanto a ferramenta PowerShell está ativada. A ferramenta está ativada por padrão no Windows sem Git Bash, e no Windows com Git Bash para contas claude.ai e Console. Em sessões do Amazon Bedrock, da Plataforma de Agentes do Google Cloud e do Microsoft Foundry, e no macOS, Linux e WSL, defina CLAUDE_CODE_USE_POWERSHELL_TOOL=1 para ativar a ferramenta. Defina essa variável como 0 para desativar a ferramenta.

• Scope: Any file
• Type: string, um de:
  • "bash": Claude Code executa seus comandos ! em Bash
  • "powershell": Claude Code executa seus comandos ! em PowerShell
• Default: "bash", ou "powershell" no Windows quando Bash não está disponível

{
  "defaultShell": "powershell"
}

Se o shell que você nomeou não estiver disponível, Claude Code usa o outro: "powershell" volta para Bash quando a ferramenta PowerShell está desativada, e "bash" volta para PowerShell quando Bash não está instalado.

dialogExpiry

Defina o prazo para diálogos que Claude Code encaminha para um cliente remoto, como um host Remote Control ou SDK, e para o diálogo de aprovação de uma mensagem entre sessões retida. No Claude Code v2.1.236 ou posterior, o mesmo prazo limita o prompt de consentimento de créditos de uso Fable no meio da sessão em uma sessão que pode não ter ninguém no terminal. Quando nenhuma resposta chega antes do prazo, Claude Code cancela o diálogo e continua com seu padrão sem ação. Requer Claude Code v2.1.224 ou posterior.

• Scope: User or managed
• Type: string, um de "60s", "5m", "10m", ou "never", que desativa o prazo
• Default: "5m"
• Per-session overrides: CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS tem precedência sobre esta chave para uma sessão

{
  "dialogExpiry": "10m"
}

Prompts de permissão e perguntas AskUserQuestion usam seus próprios fluxos e não são regidos por este prazo. Aparece em /config como Dialog expiry, que escreve esta chave nas configurações do usuário; a linha requer Claude Code v2.1.232 ou posterior, e Claude Code a oculta enquanto configurações gerenciadas ou a flag --settings definem a chave.

editorMode

Escolha o modo de vinculação de teclas para o prompt de entrada.

• Scope: Any file
• Type: string, um de:
  • "normal": atalhos de teclado padrão na entrada do prompt
  • "vim": edição no estilo vim com modos NORMAL, INSERT e VISUAL
• Default: "normal"

{
  "editorMode": "vim"
}

Aparece em /config como Editor mode, que escreve esta chave nas configurações do usuário.

emojiCompletionEnabled

Mostre sugestões de emoji quando você digita : mais um código abreviado na entrada do prompt, e substitua um código abreviado concluído como :heart: por seu emoji. Defina como false para desativar ambos.

• Scope: Any file
• Type: Boolean
  • true: Claude Code mostra sugestões de emoji após : e substitui um código abreviado concluído por seu emoji
  • false: Claude Code não sugere emoji nem substitui códigos abreviados
• Default: true

{
  "emojiCompletionEnabled": false
}

Veja Códigos abreviados de emoji. Requer Claude Code v2.1.217 ou posterior.

fileSuggestion

Execute seu próprio comando para fornecer preenchimento automático de caminho de arquivo @ em vez da sugestão de arquivo integrada. A sugestão integrada usa travessia rápida do sistema de arquivos; um grande monorepo pode se sair melhor com indexação específica do projeto, como um índice de arquivo pré-construído.

• Scope: Any file. Sob os portões de linha de status e sugestão de arquivo, Claude Code desativa o comando ou executa apenas um valor gerenciado, e ignora o seu sem aviso.
• Type: objeto com type, sempre "command", e command, o comando shell a executar
• Default: unset, portanto Claude Code usa a sugestão de arquivo integrada

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

Depois de salvar isso, digite @ seguido por parte de um caminho no prompt: as sugestões vêm da saída do seu comando.

Entrada e saída do comando

Claude Code executa o comando com as mesmas variáveis de ambiente que hooks, incluindo CLAUDE_PROJECT_DIR, e para de aguardar após cinco segundos. O comando recebe JSON em stdin com um campo query contendo o que você digitou até agora:

{"query": "src/comp"}

Imprima caminhos de arquivo separados por nova linha em stdout. Claude Code mostra no máximo 15:

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

O script a seguir lê a consulta e a passa para um índice de arquivo de repositório:

#!/bin/bash
query=$(cat | jq -r '.query')
# Replace your-repo-file-index with your own file search command
your-repo-file-index --query "$query" | head -20

footerLinksRegexes

Renderize badges clicáveis extras no rodapé abaixo da caixa de entrada quando um regex corresponde à saída de turno: resultados de ferramentas, incluindo conteúdo de arquivo e páginas buscadas, e respostas do próprio Claude. Use-o para transformar IDs impressos por CLIs de projeto, como ferramentas de revisão e rastreadores de problemas, em links de sessão.

• Scope: User or managed
• Type: array de objetos, cada um com type definido como "regex", um regex pattern, um template url, e um label opcional; placeholders {name} em url e label são preenchidos a partir de grupos de captura nomeados em pattern
• Default: unset, portanto nenhum badge é renderizado

Este exemplo corresponde a chaves de problema como PROJ-1234 e constrói cada link a partir da chave capturada:

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

Com isso configurado, quando PROJ-1234 aparece em um resultado de ferramenta ou na resposta de Claude, um badge PROJ-1234 aparece no rodapé vinculando a https://issues.example.com/browse/PROJ-1234.

Restrições de badge

A URL, rótulo e contagem de badges de cada entrada são limitados da seguinte forma:

Quando um turno é concluído, Claude Code corresponde cada regex pattern da entrada contra a saída do turno no thread principal, portanto um regex lento bloqueia a UI até que termine. Quantificadores aninhados como (a+)+$ podem levar exponencialmente tempo contra certas entradas e congelar a sessão, portanto mantenha cada pattern linear e evite aninhar + ou *.

Badges de rodapé são renderizados junto com uma linha de status personalizada quando uma está configurada; nenhum substitui o outro. Use uma linha de status para uma linha orientada por script que calcula seu próprio conteúdo a partir de dados de sessão, e badges de rodapé para transformar IDs da conversa em links sem um script.

keybindingFlavor

[!WARNING]

Descontinuado desde v2.1.261 e não tem efeito. As teclas de edição de palavras do prompt sempre seguem convenções readline, como em Bash. Claude Code ainda aceita keybindingFlavor, portanto um arquivo de configurações que a define permanece válido.

Na v2.1.238 até v2.1.260, defini-la como "readline" fez Ctrl+W deletar de volta ao espaço em branco anterior em vez de apenas a palavra anterior.

• Scope: Any file
• Type: string, "classic" ou "readline"
• Default: unset

maxProseWidth

Limite a largura da prosa nas respostas de Claude para que as linhas permaneçam legíveis em um terminal amplo. Parágrafos, títulos, listas e citações em bloco se envolvem dentro deste número de colunas, enquanto tabelas e blocos de código mantêm a largura total do terminal. Requer Claude Code v2.1.282 ou posterior.

• Scope: Any file
• Type: número de colunas do terminal, um número inteiro, mínimo 40. Claude Code ignora qualquer outro valor
• Default: unset, portanto a prosa se envolve na borda do terminal

{
  "maxProseWidth": 80
}

prefersReducedMotion

Reduza ou desative animações de interface, como o spinner, shimmer e efeitos de flash. Aparece em /config como Reduce motion.

• Scope: Any file
• Type: Boolean
  • true: Claude Code reduz ou desativa animações de interface, como o spinner, shimmer e efeitos de flash
  • false: o mesmo que unset; Claude Code mostra suas animações
• Default: false

{
  "prefersReducedMotion": true
}

promptSuggestionEnabled

Mostre ou oculte sugestões de prompt, as previsões acinzentadas que aparecem na sua entrada de prompt. Defina como false, ou desative Prompt suggestions em /config, para ocultá-las.

• Scope: Any file
• Type: Boolean
  • true: você vê sugestões de prompt na sua entrada de prompt
  • false: Claude Code oculta sugestões de prompt
• Default: true
• Per-session overrides: CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION tem precedência sobre esta chave para uma sessão

{
  "promptSuggestionEnabled": false
}

Sugestões de prompt precisam de uma conta claude.ai ou Console com telemetria ativada. No Amazon Bedrock, na Plataforma de Agentes do Google Cloud e no Microsoft Foundry, ou com telemetria desativada, como por DISABLE_TELEMETRY, esta chave não tem efeito e apenas CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=1 as ativa.

respectGitignore

Controle se o seletor de arquivo @ deixa de fora arquivos que correspondem aos padrões .gitignore. Aparece em /config como Respect .gitignore in file picker.

• Scope: Any file. Quando nenhum arquivo de configurações a define, Claude Code volta para respectGitignore em ~/.claude.json, que o toggle /config escreve.
• Type: Boolean
  • true: o seletor de arquivo @ deixa de fora arquivos que correspondem aos padrões .gitignore
  • false: o seletor de arquivo @ inclui arquivos que correspondem aos padrões .gitignore
• Default: true

{
  "respectGitignore": false
}

respondToBashCommands

Escolha se Claude responde depois que você executa um comando shell com o prefixo ! na caixa de entrada. Por padrão, Claude Code adiciona a saída do comando à conversa e Claude responde a ela. Defina esta chave como false para adicionar a saída ao contexto sem uma resposta, para que você possa executar vários comandos e perguntar sobre eles juntos.

• Scope: Any file
• Type: Boolean
  • true: Claude Code adiciona a saída do comando à conversa e Claude responde a ela
  • false: Claude Code adiciona a saída ao contexto sem uma resposta
• Default: true

{
  "respondToBashCommands": false
}

Veja Shell mode com prefixo !.

showClearContextOnPlanAccept

Quando Claude termina um plano em modo de plano, ele mostra um menu de aprovação. O planejamento pode usar muito contexto, portanto esta chave adiciona uma primeira opção a esse menu, Yes, clear context and …, que aprova o plano, limpa o contexto da conversa e começa a implementar apenas a partir do plano. O resto do rótulo nomeia o modo de permissão em que a sessão continua, e mostra quanto do seu contexto o planejamento usou.

• Scope: Any file
• Type: Boolean
  • true: o menu de aprovação do plano obtém uma primeira opção, Yes, clear context and …, que aprova o plano e limpa o contexto da conversa
  • false: o menu de aprovação do plano não mostra nenhuma opção de limpar contexto
• Default: false

{
  "showClearContextOnPlanAccept": true
}

showTurnDuration

Mostre ou oculte a mensagem de duração do turno após cada resposta, como "Cooked for 1m 6s · done 6:05 PM". O relógio após "done" mostra quando o turno terminou; timeFormat e timeZone controlam seu formato e zona. Aparece em /config como Show turn duration.

• Scope: Any file. Um valor em ~/.claude.json de uma versão anterior se aplica quando nenhum arquivo de configurações a define.
• Type: Boolean
  • true: você vê a mensagem de duração do turno após cada resposta
  • false: Claude Code oculta a mensagem de duração do turno
• Default: true

{
  "showTurnDuration": false
}

spellcheck

Sublinhe palavras com erros de ortografia na entrada do prompt conforme você digita, usando um verificador de ortografia que você instala. Claude Code verifica apenas o texto na caixa de entrada. Verificar ortografia conforme você digita cobre a instalação de aspell, hunspell ou ispell e o que o verificador cobre. Requer Claude Code v2.1.235 ou posterior.

• Scope: User or managed. O bloco do nível mais alto que a define se aplica como um todo.
• Type: objeto com enabled (Boolean), checker ("aspell", "hunspell", "ispell", ou "auto"), language (string, passada para o verificador como seu nome de dicionário), e color (string, um nome de cor de terminal, #rrggbb, rgb(r,g,b), ansi256(n), ou ansi:<name>)
• Default: unset, portanto a verificação de ortografia está desativada; checker padrão para "auto", o primeiro dos três encontrado em PATH; language padrão para o próprio dicionário do verificador; color padrão para a cor de erro do tema

{
  "spellcheck": { "enabled": true, "language": "en_GB" }
}

spinnerTipsEnabled

Enquanto Claude trabalha, a linha do spinner gira através de dicas curtas sobre recursos do Claude Code, como "Use Plan Mode para se preparar para uma solicitação complexa antes de fazer alterações. Pressione Shift+Tab duas vezes para ativar." Defina esta chave como false para ocultá-las. Aparece em /config como Show tips.

• Scope: Any file
• Type: Boolean
  • true: você vê dicas no spinner enquanto Claude está trabalhando
  • false: Claude Code oculta dicas do spinner
• Default: true

{
  "spinnerTipsEnabled": false
}

spinnerTipsOverride

Adicione suas próprias dicas às dicas do spinner que Claude Code mostra enquanto Claude trabalha, ou substitua as dicas integradas pelas suas. Claude Code coloca suas dicas na mesma rotação que as integradas.

Se você definir spinnerTipsEnabled como false, Claude Code oculta todas as dicas, incluindo as suas.

• Scope: Any file. Claude Code honra objetos de dica, tipsFile, label e excludeDefault das configurações do usuário, a flag --settings e configurações gerenciadas; a partir de configurações de projeto e local, ele lê apenas dicas de string simples.
• Type: objeto com campos tips, tipsFile, label e excludeDefault, cada um opcional
• Default: unset, portanto Claude Code mostra apenas as dicas integradas

Objetos de dica, tipsFile, label e a regra da linha Scope que configurações de projeto e local contribuem apenas com strings simples requerem Claude Code v2.1.247 ou posterior.

Cada entrada tips é uma string simples ou um objeto com estes campos:

Claude Code lê uma string simples como uma dica com esses padrões e um id baseado em posição, portanto seu histórico de exibição é redefinido quando você reordena a lista. Dê a uma dica um id para manter seu histórico entre edições.

Claude Code lê no máximo 200 dicas entre tips e tipsFile, e descarta uma entrada inválida com um aviso de debug em vez de rejeitar o arquivo de configurações.

Use os campos restantes para nomear um arquivo de dicas, definir o prefixo e ocultar as dicas integradas:

• tipsFile: um caminho absoluto ou ~/ para um arquivo JSON local contendo um array das mesmas entradas, ou um objeto com um array tips, até 256 KB. Claude Code lê o arquivo uma vez por processo, portanto carrega suas edições na próxima inicialização. Você não pode defini-lo através de configurações gerenciadas por servidor; implante tips inline lá, ou implante o caminho em um managed-settings.json em disco.
• label: o prefixo que Claude Code mostra antes de dicas das configurações do usuário, --settings e configurações gerenciadas, até 40 caracteres. O padrão é Tip, o mesmo prefixo que as dicas integradas, e dicas de configurações de projeto e local sempre o usam.
• excludeDefault: defina como true para ocultar as dicas integradas e mostrar apenas as suas. Quando Claude Code não consegue carregar nenhuma de suas dicas, por exemplo porque tipsFile não existe ou cada entrada é inválida, ele mantém a rotação integrada em vez de um spinner vazio.

Quando mais de um arquivo de configurações define a chave, Claude Code mostra dicas de todos eles e pega tipsFile, label e excludeDefault de qualquer um das configurações gerenciadas, a flag --settings e configurações do usuário que seja o de precedência mais alta que define cada um.

Este exemplo, em suas configurações do usuário, adiciona uma dica de string simples e uma dica de objeto à rotação sob o prefixo Acme tip:

{
  "spinnerTipsOverride": {
    "label": "Acme tip",
    "tips": [
      "Run /review before opening a PR",
      {
        "id": "gateway-errors",
        "text": "Seeing 5xx errors? Check the gateway status page first",
        "cooldownSessions": 5,
        "priority": 2
      }
    ]
  }
}

Cada campo no exemplo muda uma coisa sobre como Claude Code mostra as dicas:

• label: Claude Code mostra ambas as dicas como Acme tip: ... em vez de Tip: ....
• A string simples: Claude Code lhe dá os padrões, portanto pode aparecer novamente na próxima sessão.
• id: Claude Code baseia o histórico de exibição da segunda dica em gateway-errors, portanto seu cooldown ainda se aplica depois que você adiciona ou reordena dicas.
• cooldownSessions: depois que Claude Code mostra a dica gateway-errors, ele não mostra essa dica novamente até cinco sessões depois.
• priority: quando a dica gateway-errors e outra dica não foram mostradas pelo mesmo número de sessões, por exemplo quando nenhuma foi mostrada ainda, Claude Code mostra gateway-errors primeiro. A string simples tem a prioridade padrão, 0.

Enquanto Claude trabalha, Claude Code mostra suas dicas no spinner com seu prefixo, como Acme tip: Run /review before opening a PR.

spinnerVerbs

Enquanto um turno está em progresso, o spinner mostra um verbo rotativo como "Accomplishing", "Architecting", ou "Baking". Use esta chave para adicionar seus próprios verbos a essa rotação ou substituir a lista integrada pela sua.

• Scope: Any file
• Type: objeto com um array verbs de strings e mode, um de:
  • "append": Claude Code adiciona seus verbos ao conjunto integrado
  • "replace": Claude Code mostra apenas seus verbos
• Default: unset, portanto Claude Code usa os verbos integrados

Este exemplo adiciona dois verbos ao conjunto integrado:

{
  "spinnerVerbs": {
    "mode": "append",
    "verbs": ["Pondering", "Crafting"]
  }
}

No modo "replace" com um array verbs vazio, Claude Code mantém os verbos integrados.

statusLine

Execute seu próprio comando para renderizar uma linha de status abaixo do prompt com contexto como o modelo, custo ou branch git. Campos opcionais ajustam espaçamento, adicionam re-execuções periódicas e ocultam o indicador de modo vim integrado quando seu script renderiza vim.mode em si.

• Scope: Any file. Quando allowManagedHooksOnly está ativado, ou disableAllHooks está definido fora das configurações gerenciadas, apenas o valor das configurações gerenciadas é executado.
• Type: objeto com type definido como "command" e uma string command, mais padding opcional como um número de caracteres, refreshInterval como um número de segundos, mínimo 1, e hideVimModeIndicator como um Boolean
• Default: unset, portanto nenhuma linha de status

Este exemplo imprime o nome do modelo e o uso de contexto, e adiciona dois caracteres de espaçamento horizontal:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",
    "padding": 2
  }
}

O exemplo precisa de jq instalado e é executado em um shell. Para equivalentes PowerShell e Git Bash, veja Configuração do Windows; para a configuração completa, veja Configurar manualmente uma linha de status.

subagentStatusLine

Quando Claude executa subagentes, Claude Code os lista em uma exibição de tarefa abaixo do prompt, uma linha por subagente mostrando name · description · token count. Esta chave permite que você execute seu próprio comando para reescrever essas linhas, por exemplo para mostrar o uso de contexto de cada subagente como uma porcentagem. Em cada atualização, Claude Code envia as linhas visíveis como um objeto JSON em stdin, com um array tasks carregando id, name, status, model, tokenCount de cada subagente e mais, e substitui a linha para cada id que você escreve de volta como uma linha {"id", "content"}. Linhas que você não escreve de volta mantêm a renderização padrão.

• Scope: Any file. Quando allowManagedHooksOnly está ativado, ou disableAllHooks está definido fora das configurações gerenciadas, apenas o valor das configurações gerenciadas é executado.
• Type: objeto com type definido como "command" e uma string command
• Default: unset, portanto Claude Code renderiza as linhas padrão

{
  "subagentStatusLine": {
    "type": "command",
    "command": "jq -c '.tasks[] | {id, content: \"\\(.name): \\(.tokenCount) tokens\"}'"
  }
}

Veja Linhas de status de subagente.

syntaxHighlightingDisabled

Claude Code colore código por linguagem nos diffs, blocos de código e visualizações de arquivo que mostra no terminal, com seu highlighter integrado; nenhum plugin ou servidor de linguagem está envolvido. Defina esta chave como true para mostrá-los como texto simples em vez disso, por exemplo se as cores entrarem em conflito com seu tema de terminal ou desacelerem um leitor de tela.

• Scope: Any file
• Type: Boolean
  • true: Claude Code desativa o destaque de sintaxe em diffs, blocos de código e visualizações de arquivo
  • false: Claude Code destaca a sintaxe
• Default: false

{
  "syntaxHighlightingDisabled": true
}

terminalProgressBarEnabled

Alguns terminais podem mostrar um indicador de progresso na aba ou na barra de tarefas para o programa em execução neles. Enquanto Claude está trabalhando, Claude Code relata um estado em progresso ao terminal, para que você possa ver de outra aba ou janela se a sessão ainda está ocupada. O indicador permanece visível após o turno terminar enquanto subagentes em segundo plano ou fluxos de trabalho dinâmicos ainda estão em execução, e é limpo assim que a sessão fica ociosa.

Claude Code o relata apenas em terminais que suportam o indicador: ConEmu, Ghostty 1.2.0 ou posterior, e iTerm2 3.6.6 ou posterior. Defina esta chave como false para impedir que Claude Code o relate. Aparece em /config como Terminal progress bar.

• Scope: Any file. Um valor em ~/.claude.json de uma versão anterior se aplica quando nenhum arquivo de configurações a define.
• Type: Boolean
  • true: você vê a barra de progresso do terminal em terminais que a suportam
  • false: Claude Code oculta a barra de progresso do terminal
• Default: true

{
  "terminalProgressBarEnabled": false
}

terminalTitleFromRename

Claude Code define o título da aba do seu terminal. Por padrão, ele usa um título que gera a partir da conversa, e uma vez que você dá à sessão um nome com /rename ou --name, a aba mostra esse nome em vez disso. Defina esta chave como false para manter o título gerado na aba mesmo depois de nomear a sessão. O nome em si ainda se aplica, portanto /resume <name> e o seletor de sessão o encontram.

• Scope: Any file
• Type: Boolean
  • true: o título da aba do terminal mostra o nome da sessão que você definiu
  • false: a aba mantém o título que Claude Code gera a partir de sua conversa
• Default: true

{
  "terminalTitleFromRename": false
}

Para impedir que Claude Code atualize o título do terminal completamente, defina CLAUDE_CODE_DISABLE_TERMINAL_TITLE como 1 em vez disso.

theme

Escolha o tema de cor para a interface. Aparece em /config como Theme.

• Scope: Any file. Um valor em ~/.claude.json de uma versão anterior se aplica quando nenhum arquivo de configurações a define.
• Type: string, um de:
  • "auto": corresponde ao fundo claro ou escuro do seu terminal
  • "dark": o tema escuro
  • "light": o tema claro
  • "dark-daltonized": o tema escuro com cores amigáveis ao daltônico
  • "light-daltonized": o tema claro com cores amigáveis ao daltônico
  • "dark-ansi": o tema escuro usando apenas a paleta de cores ANSI do seu terminal
  • "light-ansi": o tema claro usando apenas a paleta de cores ANSI do seu terminal
  • "custom:<slug>" ou "custom:<plugin-name>:<slug>": um tema personalizado de ~/.claude/themes/ ou um plugin
• Default: "dark"

{
  "theme": "light-daltonized"
}

Veja Criar um tema personalizado.

timeFormat

Escolha como Claude Code escreve os horários que mostra na interface, como o done 6:05 PM no final de cada mensagem de duração de turno e os timestamps no visualizador de transcrição. Para escolher uma predefinição, execute /config e defina Time format. Requer Claude Code v2.1.257 ou posterior.

• Scope: Any file
• Type: string, um de:
  • "auto": o mesmo que unset; cada hora mantém seu formato integrado, que segue sua localidade na mensagem de duração de turno
  • "12-hour": um relógio de 12 horas
  • "24-hour": um relógio de 24 horas
  • "24-hour-utc": um relógio de 24 horas em UTC com Z após os minutos, como 18:05Z; Claude Code ignora timeZone para esta predefinição
  • Um padrão strftime como "%H:%M": Claude Code escreve cada hora com o padrão. Qualquer valor que contenha um % é um padrão, e qualquer outro valor fora das predefinições conta como "auto"
• Default: "auto"

{
  "timeFormat": "24-hour"
}

/config oferece apenas as predefinições, portanto para usar um padrão strftime, adicione a chave a um arquivo de configurações. Este exemplo mostra cada hora como um relógio de 24 horas de dois dígitos:

{
  "timeFormat": "%H:%M"
}

A mensagem de duração de turno e o visualizador de transcrição então mostram horários como 18:05. No visualizador de transcrição, o padrão é o timestamp inteiro, portanto adicione diretivas de data quando quiser a data lá. Este exemplo coloca a data na frente do relógio:

{
  "timeFormat": "%Y-%m-%d %H:%M"
}

As mesmas superfícies então mostram horários como 2026-09-01 18:05.

timeZone

Mostre os horários na interface em um fuso horário diferente do seu sistema. Defina como um nome de fuso horário IANA, como "UTC" ou "Europe/Dublin". Os horários que timeFormat controla então mostram nesta zona. Se timeFormat for "24-hour-utc", os horários permanecem em UTC e Claude Code ignora esta chave. /config não tem linha para esta chave, portanto defina em um arquivo de configurações. Requer Claude Code v2.1.257 ou posterior.

• Scope: Any file
• Type: string, um nome de fuso horário IANA. Quando Claude Code não reconhece o nome, usa seu fuso horário do sistema
• Default: unset, portanto os horários mostram em seu fuso horário do sistema

{
  "timeZone": "Europe/Dublin"
}

tui

Escolha o renderizador de UI do terminal. Use "fullscreen" para o renderizador alt-screen sem cintilação com scrollback virtualizado, ou "default" para o renderizador clássico de tela principal. Executar /tui fullscreen ou /tui default escreve esta chave para você.

• Scope: Any file
• Type: string, um de:
  • "default": o renderizador clássico de tela principal
  • "fullscreen": o renderizador alt-screen sem cintilação com scrollback virtualizado
• Default: unset, portanto Claude Code escolhe o renderizador para você
• Per-session overrides: CLAUDE_CODE_NO_FLICKER e CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN têm precedência sobre esta chave para uma sessão: CLAUDE_CODE_NO_FLICKER=1 ativa tela cheia, e CLAUDE_CODE_NO_FLICKER=0 ou CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 a desativa; quando ambos estão definidos, Claude Code a desativa

{
  "tui": "fullscreen"
}

Sob tmux -CC ou sobre SSH para Windows, Claude Code mantém o renderizador clássico a menos que você defina CLAUDE_CODE_NO_FLICKER=1. Sessões em segundo plano abertas de agent view sempre usam o renderizador em tela cheia independentemente desta configuração.

verbose

Por padrão, a transcrição colapsa cada chamada de ferramenta para um resumo curto, como o comando que Claude executou e uma contagem de linhas de sua saída, e você pressiona Ctrl+O para alternar a transcrição inteira para a visualização expandida quando quiser os detalhes. Defina esta chave como true para mostrar a entrada e saída completas de cada chamada de ferramenta inline conforme acontece, o que é útil quando você está depurando um hook, um servidor MCP ou um comando shell longo. Aparece em /config como Verbose output.

• Scope: Any file. Um valor em ~/.claude.json de uma versão anterior se aplica quando nenhum arquivo de configurações a define.
• Type: Boolean
  • true: você vê saída completa de ferramenta
  • false: você vê resumos truncados de saída de ferramenta
• Default: false
• Per-session overrides: --verbose tem precedência sobre esta chave para uma sessão

{
  "verbose": true
}

Um valor viewMode ou uma seleção sticky /focus substitui esta chave a cada sessão.

viewMode

Defina a visualização de transcrição em que Claude Code começa: "default", "verbose", ou "focus". Quando definido, substitui tanto a seleção sticky /focus quanto a configuração verbose.

• Scope: Any file
• Type: string, um de:
  • "default": a transcrição normal com saída de ferramenta truncada
  • "verbose": a transcrição com saída de ferramenta completa
  • "focus": apenas seu último prompt, um resumo de uma linha de chamadas de ferramenta com diffstats de edição, e a resposta final. A visualização de foco precisa do renderizador em tela cheia
• Default: unset, portanto a configuração verbose e sua última escolha /focus se aplicam
• Per-session overrides: --verbose tem precedência sobre esta chave para uma sessão

{
  "viewMode": "focus"
}

vimInsertModeRemaps

Mapeie sequências de INSERT-mode de duas teclas para Escape no modo de editor vim. Cada chave é exatamente dois caracteres imprimíveis digitados em sequência, e "<Esc>" é o único alvo suportado; Claude Code ignora outras entradas.

• Scope: User or managed. Um repositório não pode remapear seus pressionamentos de tecla.
• Type: objeto mapeando uma sequência de dois caracteres para "<Esc>"
• Default: unset

{
  "vimInsertModeRemaps": {
    "jj": "<Esc>"
  }
}

Não tem efeito a menos que editorMode seja "vim". Veja Remapear sequências de tecla de INSERT-mode.

voice

Ative ditado por voz e escolha como a tecla de ditado se comporta. Claude Code escreve este objeto para você quando você executa /voice.

• Scope: Any file
• Type: objeto com enabled como um Boolean, autoSubmit como um Boolean que se aplica apenas no modo hold, e mode, um de:
  • "hold": você segura a tecla de ditado enquanto fala e a solta para parar
  • "tap": você toca a tecla uma vez para começar a gravar e novamente para enviar
• Default: unset, portanto o ditado está desativado; quando enabled é true e mode é unset, Claude Code usa "hold"

Este exemplo ativa o ditado e faz a tecla tocar uma vez para começar a gravar e novamente para enviar:

{
  "voice": {
    "enabled": true,
    "mode": "tap"
  }
}

autoSubmit envia o prompt quando você solta a tecla no modo hold. O ditado por voz requer uma conta claude.ai.

voiceEnabled

[!WARNING]

Descontinuado desde v2.1.92, quando o objeto voice o substituiu. Claude Code ainda o lê para que arquivos de configurações mais antigos continuem funcionando, mas novas configurações devem definir voice.enabled.

Ative o ditado por voz com o formulário Boolean único que precede o objeto voice. Quando ambos estão definidos, voice.enabled se aplica.

• Scope: Any file
• Type: Boolean
  • true: o ditado por voz está ativado quando você está conectado com uma conta claude.ai e a política da sua organização permite voz, a menos que voice.enabled esteja definido
  • false: o ditado por voz está desativado, a menos que voice.enabled esteja definido
• Default: unset

{
  "voiceEnabled": true
}

wheelScrollAccelerationEnabled

Acelere a velocidade de rolagem da roda do mouse durante rolagens rápidas em renderização em tela cheia. Defina como false para uma taxa de rolagem constante por entalhe de roda.

• Scope: Any file
• Type: Boolean
  • true: Claude Code acelera a velocidade de rolagem da roda do mouse durante rolagens rápidas
  • false: Claude Code rola a uma taxa constante por entalhe de roda
• Default: true

{
  "wheelScrollAccelerationEnabled": false
}

Git e atribuição

Controle a atribuição que Claude Code adiciona aos commits e pull requests e como funciona com git.

attribution

Personalize a atribuição que Claude Code adiciona aos commits git e pull requests. Os commits recebem um git trailer como Co-Authored-By por padrão; as descrições de pull request recebem texto simples. Defina cada parte separadamente com as sub-chaves abaixo.

• Escopo: Qualquer arquivo
• Tipo: objeto com strings commit e pr e um Boolean sessionUrl, ou false para ocultar toda a atribuição. O valor false requer Claude Code v2.1.281 ou posterior; versões anteriores o rejeitam e pulam todo o arquivo de configurações do usuário, projeto ou local que o contém
• Padrão: não definido, então Claude Code usa a atribuição padrão mostrada em cada sub-chave

Para ocultar toda a atribuição, defina attribution como false. Em um arquivo de configurações que versões anteriores também leem, defina commit e pr como strings vazias e sessionUrl como false em vez disso.

Este exemplo substitui a atribuição de commit, remove a atribuição de pull request e descarta o link da sessão:

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": "",
    "sessionUrl": false
  }
}