> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Configurações do Claude Code
> Configure o Claude Code com configurações globais e em nível de projeto, e variáveis de ambiente.
O Claude Code oferece uma variedade de configurações para personalizar seu comportamento de acordo com suas necessidades. Você pode configurar o Claude Code executando o comando `/config`, que abre uma interface de Configurações com abas onde você pode visualizar informações de status e modificar opções de configuração. {/* min-version: 2.1.181 */}A partir da v2.1.181, você pode alterar uma única opção sem abrir a interface passando `key=value` para `/config`, por exemplo `/config verbose=true`.
Escopos de configuração
O Claude Code usa um sistema de escopo para determinar onde as configurações se aplicam e com quem são compartilhadas. Compreender os escopos ajuda você a decidir como configurar o Claude Code para uso pessoal, colaboração em equipe ou implantação empresarial.
Escopos disponíveis
| Escopo | Localização | Quem afeta | Compartilhado com a equipe? |
| :---------- | :-------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------ |
| **Managed** | Configurações gerenciadas pelo servidor, plist / registro, ou `managed-settings.json` em nível de sistema | Todos os membros da organização para entrega gerenciada pelo servidor; todos os usuários na máquina para plist, registro HKLM e entrega de arquivo; o usuário atual para entrega de registro HKCU | Sim (implantado por TI) |
| **User** | Diretório `~/.claude/` | Você, em todos os projetos | Não |
| **Project** | `.claude/` no repositório | Todos os colaboradores neste repositório | Sim (confirmado no git) |
| **Local** | `.claude/settings.local.json` | Você, apenas neste repositório | Não (ignorado pelo git quando Claude Code o cria) |
Quando usar cada escopo
O escopo **Managed** é para:
* Políticas de segurança que devem ser aplicadas em toda a organização
* Requisitos de conformidade que não podem ser substituídos
* Configurações padronizadas implantadas por TI/DevOps
O escopo **User** é melhor para:
* Preferências pessoais que você deseja em todos os lugares (temas, configurações do editor)
* Ferramentas e plugins que você usa em todos os projetos
* Chaves de API e autenticação (armazenadas com segurança)
O escopo **Project** é melhor para:
* Configurações compartilhadas pela equipe (permissões, hooks, servidores MCP)
* Plugins que toda a equipe deve ter
* Padronização de ferramentas entre colaboradores
O escopo **Local** é melhor para:
* Substituições pessoais para um projeto específico
* Testar configurações antes de compartilhar com a equipe
* Configurações específicas da máquina que não funcionarão para outros
Como os escopos interagem
Quando a mesma configuração aparece em vários escopos, o Claude Code as aplica em ordem de prioridade:
1. **Managed** (mais alta): não pode ser substituída por nada
2. **Argumentos de linha de comando**: substituições de sessão temporárias
3. **Local**: substitui configurações de projeto e usuário
4. **Project**: substitui configurações de usuário
5. **User** (mais baixa): se aplica quando nada mais especifica a configuração
Por exemplo, se suas configurações de usuário definem `spinnerTipsEnabled` como `true` e as configurações de projeto a definem como `false`, o valor do projeto se aplica. As regras de permissão se comportam de forma diferente porque se mesclam entre escopos em vez de substituir. Veja [Precedência de configurações](#settings-precedence).
O que usa escopos
Os escopos se aplicam a muitos recursos do Claude Code:
| Recurso | Localização do usuário | Localização do projeto | Localização local |
| :-------------- | :------------------------ | :--------------------------------- | :----------------------------- |
| **Settings** | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |
| **Subagents** | `~/.claude/agents/` | `.claude/agents/` | Nenhum |
| **MCP servers** | `~/.claude.json` | `.mcp.json` | `~/.claude.json` (por projeto) |
| **Plugins** | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |
| **CLAUDE.md** | `~/.claude/CLAUDE.md` | `CLAUDE.md` ou `.claude/CLAUDE.md` | `CLAUDE.local.md` |
No Windows, os caminhos mostrados como `~/.claude` são resolvidos para `%USERPROFILE%\.claude`.
***
Arquivos de configuração
O arquivo `settings.json` é o mecanismo oficial para configurar o Claude Code através de configurações hierárquicas:
* As **configurações do usuário** são definidas em `~/.claude/settings.json` e se aplicam a todos os projetos.
* As **configurações do projeto** são salvas no diretório do seu projeto:
* `.claude/settings.json` para configurações que são verificadas no controle de origem e compartilhadas com sua equipe
* `.claude/settings.local.json` para configurações que não são verificadas, úteis para preferências pessoais e experimentação. Quando o Claude Code cria `.claude/settings.local.json`, ele configura o git para ignorar o arquivo. Se você criar o arquivo você mesmo, adicione-o ao seu gitignore manualmente.
* **Configurações gerenciadas**: Para organizações que precisam de controle centralizado, o Claude Code suporta múltiplos mecanismos de entrega para configurações gerenciadas. Todos usam o mesmo formato JSON e não podem ser substituídos por configurações de usuário ou projeto:
* **Configurações gerenciadas pelo servidor**: entregues remotamente na entrada, seja dos servidores da Anthropic através do console de administração do claude.ai ou de um [gateway de aplicativos Claude](/pt/claude-apps-gateway) auto-hospedado. Veja [configurações gerenciadas pelo servidor](/pt/server-managed-settings).
* **Políticas de nível MDM/SO**: entregues através do gerenciamento nativo de dispositivos no macOS e Windows:
* macOS: domínio de preferências gerenciadas `com.anthropic.claudecode`. As chaves de nível superior do plist espelham `managed-settings.json`, com configurações aninhadas como dicionários e arrays como arrays de plist. Implante via perfis de configuração em Jamf, Iru (Kandji), ou ferramentas MDM similares.
* Windows: chave de registro `HKLM\SOFTWARE\Policies\ClaudeCode` com um valor `Settings` (REG\_SZ ou REG\_EXPAND\_SZ) contendo JSON (implantado via Política de Grupo ou Intune)
* Windows (nível de usuário): `HKCU\SOFTWARE\Policies\ClaudeCode` (prioridade de política mais baixa, usada apenas quando nenhuma fonte de nível de administrador existe)
* **Baseado em arquivo**: `managed-settings.json` e `managed-mcp.json` implantados em diretórios do sistema:
* macOS: `/Library/Application Support/ClaudeCode/`
* Linux e WSL: `/etc/claude-code/`
* Windows: `C:\Program Files\ClaudeCode\`
O caminho legado do Windows `C:\ProgramData\ClaudeCode\managed-settings.json` não é mais suportado a partir da v2.1.75. Administradores que implantaram configurações nesse local devem migrar arquivos para `C:\Program Files\ClaudeCode\managed-settings.json`.
Configurações gerenciadas baseadas em arquivo também suportam um diretório drop-in em `managed-settings.d/` no mesmo diretório do sistema ao lado de `managed-settings.json`. Isto permite que equipes separadas implantem fragmentos de política independentes sem coordenar edições em um único arquivo.
Seguindo a convenção systemd, `managed-settings.json` é mesclado primeiro como base, então todos os arquivos `*.json` no diretório drop-in são classificados alfabeticamente e mesclados por cima. Arquivos posteriores substituem anteriores para valores escalares, arrays são concatenados e desduplicados, e objetos são mesclados profundamente. Arquivos ocultos começando com `.` são ignorados.
Use prefixos numéricos para controlar a ordem de mesclagem, por exemplo `10-telemetry.json` e `20-security.json`.
Veja [configurações gerenciadas](/pt/permissions#managed-only-settings) e [Configuração MCP gerenciada](/pt/managed-mcp) para detalhes.
Este [repositório](https://github.com/anthropics/claude-code/tree/main/examples/mdm) inclui modelos de implantação iniciais para Jamf, Iru (Kandji), Intune, e Política de Grupo. Use estes como pontos de partida e ajuste-os para suas necessidades.
Implantações gerenciadas também podem restringir **adições ao marketplace de plugins** usando `strictKnownMarketplaces`. Para mais informações, veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions).
* **Outra configuração** é armazenada em `~/.claude.json`. Este arquivo contém sua sessão OAuth, configurações de [MCP server](/pt/mcp) para escopos de usuário e local, estado por projeto (ferramentas permitidas, configurações de confiança), e vários caches. Os MCP servers com escopo de projeto são armazenados separadamente em `.mcp.json`.
O Claude Code cria automaticamente backups com timestamp dos arquivos de configuração e retém os cinco backups mais recentes para evitar perda de dados.
```JSON Exemplo settings.json theme={null}
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)",
"Read(~/.zshrc)"
],
"deny": [
"Bash(curl *)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
]
},
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_METRICS_EXPORTER": "otlp"
},
"companyAnnouncements": [
"Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
"Reminder: Code reviews required for all PRs",
"New security policy in effect"
]
}
```
A linha `$schema` no exemplo acima aponta para o [esquema JSON oficial](https://json.schemastore.org/claude-code-settings.json) para configurações do Claude Code. Adicioná-la ao seu `settings.json` ativa o preenchimento automático e validação inline no VS Code, Cursor e qualquer outro editor que suporte validação de esquema JSON.
O esquema publicado é atualizado periodicamente e pode não incluir configurações adicionadas nos lançamentos CLI mais recentes, então um aviso de validação em um campo documentado recentemente não significa necessariamente que sua configuração é inválida.
Quando as edições entram em vigor
O Claude Code observa seus arquivos de configuração e os recarrega quando mudam, então edições na maioria das chaves se aplicam à sessão em execução sem uma reinicialização. Isto inclui `permissions`, `hooks`, e auxiliares de credenciais como `apiKeyHelper`. O recarregamento cobre configurações de usuário, projeto, local e gerenciadas, e o [hook `ConfigChange`](/pt/hooks#configchange) dispara para cada mudança detectada.
Algumas poucas chaves são lidas uma vez na inicialização da sessão e se aplicam na próxima reinicialização em vez disso:
* `model`: use [`/model`](/pt/model-config#setting-your-model) para mudar no meio da sessão
* [`outputStyle`](/pt/output-styles): parte do prompt do sistema, que é reconstruído em `/clear` ou reinicialização
Entradas inválidas em configurações gerenciadas
Configurações gerenciadas analisam com tolerância. Quando uma configuração gerenciada contém uma entrada que falha na validação de esquema, o Claude Code remove essa entrada, registra um aviso, e aplica todas as políticas válidas restantes. Um único erro de digitação não pode desabilitar o resto da política da sua organização. Este comportamento é consistente em todos os três mecanismos de entrega: [configurações gerenciadas pelo servidor](/pt/server-managed-settings), políticas de plist e registro implantadas através de MDM, e arquivos `managed-settings.json`. Requer Claude Code v2.1.169 ou posterior.
Campos de aplicação de segurança são tratados por campo em vez de serem removidos no atacado quando estão presentes mas inválidos:
| Campo | Comportamento quando presente mas inválido |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowedMcpServers` | Aplicado como uma lista de permissões vazia, então nenhum MCP server é admitido até que o valor seja corrigido. Uma entrada individual inválida é removida e o subconjunto válido é aplicado. |
| `allowManagedMcpServersOnly` | Tratado como `true`. |
| `availableModels` | {/* min-version: 2.1.175 */}Aplicado como uma lista de permissões vazia, então apenas o modelo Padrão está disponível até que o valor seja corrigido. Uma entrada individual não-string é removida e o subconjunto válido é aplicado. Se aplica em v2.1.175 e posterior. |
| `enforceAvailableModels` | {/* min-version: 2.1.175 */}Tratado como `true`. Se aplica em v2.1.175 e posterior. |
| `forceLoginOrgUUID` | Nenhuma organização é permitida fazer login até que o valor seja corrigido. |
| `deniedMcpServers` | Uma entrada individual inválida é removida e o subconjunto válido é aplicado. Um valor totalmente inválido é descartado com um aviso, já que negar cada servidor bloquearia servidores que a política nunca nomeou. |
| `sandbox.credentials` | {/* min-version: 2.1.191 */}Uma entrada individual inválida em `files` ou `envVars` é removida com um aviso e o subconjunto válido é aplicado. Um valor totalmente inválido de `credentials` é descartado com um aviso enquanto o resto de `sandbox` ainda se aplica. Se aplica em v2.1.191 e posterior. |
`requiredMinimumVersion` e `requiredMaximumVersion` falham abertos por design: um valor inválido é removido em vez de ser aplicado, então um push de política ruim não pode impedir que o Claude Code inicie.
Erros de validação aparecem em três lugares:
* Sessões interativas mostram um diálogo na inicialização listando as entradas inválidas.
* Execuções headless com `-p` imprimem um resumo para stderr.
* [`claude doctor`](/pt/debug-your-config) lista cada entrada inválida com sua fonte e campo.
Valide mudanças de política executando `claude doctor` em uma máquina de teste antes de implantá-las em toda a frota.
Esta tolerância se aplica apenas a configurações gerenciadas. Arquivos de configuração de usuário, projeto e local permanecem rigorosos: um arquivo que falha na validação é rejeitado como um todo e relatado.
Configurações disponíveis
`settings.json` suporta várias opções:
| Chave | Descrição | Exemplo |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| `advisorModel` | {/* min-version: 2.1.98 */}Modelo para a [ferramenta advisor](/pt/advisor) do lado do servidor. Aceita um alias de modelo como `"opus"`, `"sonnet"`, ou `"fable"` ({/* min-version: 2.1.170 */}v2.1.170+), ou um ID de modelo completo. Escrito automaticamente quando você executa `/advisor`. Desdefina para desabilitar o advisor. Requer Claude Code v2.1.98 ou posterior | `"opus"` |
| `agent` | Executar a thread principal como um subagent nomeado, e definir o agente padrão para sessões despachadas de `claude agents`. Aplica o prompt do sistema, restrições de ferramenta e modelo do subagent. Veja [Invocar subagents explicitamente](/pt/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |
| `agentPushNotifEnabled` | {/* min-version: 2.1.119 */}**Padrão**: `false`. Quando [Controle Remoto](/pt/remote-control) está conectado, permitir que Claude envie notificações push proativas para seu telefone, por exemplo quando uma tarefa longa termina. Aparece em `/config` como **Push when Claude decides**. Veja [Notificações push móveis](/pt/remote-control#mobile-push-notifications). Requer Claude Code v2.1.119 ou posterior | `true` |
| `allowAllClaudeAiMcps` | (Apenas configurações gerenciadas) Carregar conectores claude.ai ao lado de um `managed-mcp.json` implantado, que de outra forma assume controle exclusivo e os suprime. Veja [Configuração MCP gerenciada](/pt/managed-mcp) | `true` |
| `allowedChannelPlugins` | (Apenas configurações gerenciadas) Lista de permissões de plugins de canal que podem enviar mensagens. Substitui a lista de permissões padrão da Anthropic quando definido. Indefinido = voltar para o padrão, array vazio = bloquear todos os plugins de canal. Requer `channelsEnabled: true`. Veja [Restringir quais plugins de canal podem executar](/pt/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |
| `allowedHttpHookUrls` | Lista de permissões de padrões de URL que hooks HTTP podem almejar. Suporta `*` como curinga. Quando definido, hooks com URLs não correspondentes são bloqueados. Indefinido = sem restrição, array vazio = bloquear todos os hooks HTTP. Arrays se mesclam entre fontes de configuração. Veja [Configuração de hooks](#hook-configuration) | `["https://hooks.example.com/*"]` |
| `allowedMcpServers` | Quando definido em managed-settings.json, lista de permissões de MCP servers que os usuários podem configurar. Indefinido = sem restrições, array vazio = bloqueio. Se aplica a todos os escopos. A lista de negação tem precedência. Veja [Configuração MCP gerenciada](/pt/managed-mcp) | `[{ "serverName": "github" }]` |
| `allowManagedHooksOnly` | (Apenas configurações gerenciadas) Apenas hooks gerenciados, hooks SDK, e hooks de plugins força-habilitados em configurações gerenciadas `enabledPlugins` são carregados. Hooks de usuário, projeto e todos os outros plugins são bloqueados. Veja [Configuração de hooks](#hook-configuration) | `true` |
| `allowManagedMcpServersOnly` | (Apenas configurações gerenciadas) Apenas `allowedMcpServers` de configurações gerenciadas são respeitados. `deniedMcpServers` ainda se mescla de todas as fontes. Usuários ainda podem adicionar MCP servers, mas apenas a lista de permissões definida pelo administrador se aplica. Veja [Configuração MCP gerenciada](/pt/managed-mcp) | `true` |
| `allowManagedPermissionRulesOnly` | (Apenas configurações gerenciadas) Impedir que configurações de usuário e projeto definam regras de permissão `allow`, `ask` ou `deny`. Apenas regras em configurações gerenciadas se aplicam. Veja [Configurações apenas gerenciadas](/pt/permissions#managed-only-settings) | `true` |
| `alwaysThinkingEnabled` | Ativar [pensamento estendido](/pt/model-config#extended-thinking) por padrão para todas as sessões. Tipicamente configurado via comando `/config` em vez de editar diretamente. Para forçar o pensamento desligado independentemente desta configuração, defina [`MAX_THINKING_TOKENS=0`](/pt/env-vars) em `env`, que desabilita o pensamento na API Anthropic exceto em Fable 5, que não pode ter o pensamento desligado. Em [provedores de terceiros](/pt/third-party-integrations) isto omite o parâmetro `thinking` em vez disso, e modelos de raciocínio adaptativo ainda podem pensar | `true` |
| `apiKeyHelper` | Comando personalizado, executado através do shell do sistema (`/bin/sh` no macOS e Linux, `cmd` no Windows), para gerar um valor de autenticação. Este valor será enviado como cabeçalhos `X-Api-Key` e `Authorization: Bearer` para solicitações de modelo. Defina o intervalo de atualização com [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/pt/env-vars) | `/bin/generate_temp_api_key.sh` |
| `attribution` | Personalizar atribuição para commits git e pull requests. Veja [Configurações de atribuição](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |
| `autoCompactEnabled` | {/* min-version: 2.1.119 */}**Padrão**: `true`. Compactar automaticamente a conversa quando o contexto se aproxima do limite. Aparece em `/config` como **Auto-compact**. Para desabilitar via variável de ambiente, defina [`DISABLE_AUTO_COMPACT`](/pt/env-vars) em `env` | `false` |
| `autoMemoryDirectory` | Diretório personalizado para armazenamento de [memória automática](/pt/memory#storage-location). Aceita um caminho absoluto ou um caminho com prefixo `~/`. A partir de configurações de projeto ou local, isto é honrado apenas após você aceitar o diálogo de confiança do workspace, já que um repositório clonado pode fornecer este arquivo | `"~/my-memory-dir"` |
| `autoMemoryEnabled` | **Padrão**: `true`. Ativar [memória automática](/pt/memory#enable-or-disable-auto-memory). Quando `false`, Claude não lê ou escreve no diretório de memória automática. Você também pode alternar isto com `/memory` durante uma sessão. Para desabilitar via variável de ambiente, defina [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/pt/env-vars) em `env` | `false` |
| `autoMode` | Personalizar o que o classificador de [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) bloqueia e permite. Contém arrays `environment`, `allow`, `soft_deny`, e `hard_deny` de regras em prosa. Inclua a string literal `"$defaults"` em um array para herdar as regras integradas nessa posição. Veja [Configurar modo automático](/pt/auto-mode-config). Não lido de configurações de projeto compartilhadas | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |
| `autoMode.classifyAllShell` | {/* min-version: 2.1.193 */}**Padrão**: `false`. Quando `true`, suspende cada regra allow de Bash e PowerShell enquanto o modo automático está ativo para que todos os comandos shell sejam roteados através do classificador, não apenas regras que correspondem a padrões de execução de código arbitrário. Veja [Rotear todos os comandos shell através do classificador](/pt/auto-mode-config#route-all-shell-commands-through-the-classifier). Requer Claude Code v2.1.193 ou posterior | `true` |
| `autoScrollEnabled` | **Padrão**: `true`. Em [renderização fullscreen](/pt/fullscreen), seguir nova saída até o fundo da conversa. Aparece em `/config` como **Auto-scroll**. Prompts de permissão ainda rolam para a vista quando isto está desligado | `false` |
| `autoUpdatesChannel` | **Padrão**: `"latest"`. Canal de lançamento a seguir para atualizações. Use `"stable"` para uma versão que é tipicamente cerca de uma semana antiga e pula versões com regressões maiores, ou `"latest"` para o lançamento mais recente. Para desabilitar auto-atualizações completamente, defina [`DISABLE_AUTOUPDATER`](/pt/setup#disable-auto-updates) em `env` | `"stable"` |
| `availableModels` | Restringir quais modelos os usuários podem selecionar para a sessão principal, [subagents](/pt/sub-agents), [skills](/pt/skills), e o [advisor](/pt/advisor). Não afeta a opção Padrão a menos que `enforceAvailableModels` também esteja definido. Veja [Restringir seleção de modelo](/pt/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |
| `awaySummaryEnabled` | Mostrar um resumo de sessão de uma linha quando você retorna ao terminal após alguns minutos ausente. Defina como `false` ou desative Resumo de sessão em `/config` para desabilitar. Mesmo que [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/pt/env-vars) | `true` |
| `awsAuthRefresh` | Script personalizado que modifica o diretório `.aws` (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |
| `awsCredentialExport` | Script personalizado que produz JSON com credenciais AWS (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |
| `axScreenReader` | {/* min-version: 2.1.181 */}Renderizar saída amigável ao leitor de tela: texto simples sem bordas decorativas ou animações. O modo leitor de tela sempre usa o renderizador clássico, então a configuração `tui` não tem efeito enquanto está ativo. A variável de ambiente [`CLAUDE_AX_SCREEN_READER`](/pt/env-vars) e a flag [`--ax-screen-reader`](/pt/cli-reference#cli-flags) têm precedência. Requer Claude Code v2.1.181 ou posterior | `true` |
| `blockedMarketplaces` | (Apenas configurações gerenciadas) Lista de negação de fontes de marketplace. Aplicado em adição de marketplace e em instalação, atualização, atualização e auto-atualização de plugin, então um marketplace adicionado antes da política ser definida não pode ser usado para buscar plugins. Fontes bloqueadas são verificadas antes do download, então nunca tocam o sistema de arquivos. Veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |
| `channelsEnabled` | (Apenas configurações gerenciadas) Permitir [channels](/pt/channels) para a organização. Em planos Claude.ai Team e Enterprise, channels são bloqueados quando isto está indefinido ou `false`. Para contas [Anthropic Console](/pt/authentication#claude-console-authentication) usando autenticação de chave de API, channels são permitidos por padrão a menos que sua organização implante configurações gerenciadas, nesse caso esta chave deve ser definida como `true` | `true` |
| `claudeMd` | (Apenas configurações gerenciadas) Instruções no estilo CLAUDE.md injetadas como memória gerenciada pela organização. Apenas honrado quando definido em configurações gerenciadas ou de política e ignorado em configurações de usuário, projeto e local. Veja [CLAUDE.md em toda a organização](/pt/memory#deploy-organization-wide-claude-md) | `"Always run make lint before committing."` |
| `claudeMdExcludes` | Padrões Glob ou caminhos absolutos de arquivos `CLAUDE.md` para pular ao carregar [memória](/pt/memory). Padrões correspondem contra caminhos de arquivo absolutos. Aplica-se apenas a memória de usuário, projeto e local; arquivos de política gerenciada não podem ser excluídos | `["**/vendor/**/CLAUDE.md"]` |
| `cleanupPeriodDays` | **Padrão**: `30` dias, mínimo `1`. Arquivos de sessão mais antigos que este período são deletados na inicialização. Definir como `0` é rejeitado com um erro de validação. Também controla o corte de idade para remoção automática de [worktrees de subagent órfãos](/pt/worktrees#clean-up-worktrees) na inicialização. Para desabilitar escritas de transcrição completamente, defina a variável de ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars), ou em modo não interativo (`-p`) use a flag `--no-session-persistence` ou a opção SDK `persistSession: false`. | `20` |
| `companyAnnouncements` | Anúncio a ser exibido aos usuários na inicialização. Se múltiplos anúncios forem fornecidos, eles serão alternados aleatoriamente. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |
| `defaultShell` | **Padrão**: `"bash"`, ou `"powershell"` no Windows quando Bash não está disponível. Shell padrão para comandos `!` da caixa de entrada. Aceita `"bash"` ou `"powershell"`. Definir `"powershell"` roteia comandos `!` interativos através do PowerShell no Windows. Requer `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. Veja [Ferramenta PowerShell](/pt/tools-reference#powershell-tool) | `"powershell"` |
| `deniedMcpServers` | Quando definido em managed-settings.json, lista de negação de MCP servers que são explicitamente bloqueados. Se aplica a todos os escopos incluindo servers gerenciados. A lista de negação tem precedência sobre a lista de permissões. Veja [Configuração MCP gerenciada](/pt/managed-mcp) | `[{ "serverName": "filesystem" }]` |
| `disableAgentView` | Defina como `true` para desligar [agentes em background e visualização de agente](/pt/agent-view): `claude agents`, `--bg`, `/background`, e o supervisor sob demanda. Tipicamente definido em [configurações gerenciadas](/pt/permissions#managed-settings). Equivalente a definir `CLAUDE_CODE_DISABLE_AGENT_VIEW` como `1` | `true` |
| `disableAllHooks` | Desabilitar todos os [hooks](/pt/hooks) e qualquer [linha de status](/pt/statusline) personalizada | `true` |
| `disableArtifact` | Defina como `true` para desabilitar a ferramenta [Artifact](/pt/artifacts), que publica saída de sessão como uma página web privada no claude.ai. Equivalente a definir `CLAUDE_CODE_DISABLE_ARTIFACT` como `1` | `true` |
| `disableAutoMode` | Defina como `"disable"` para impedir que o [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) seja ativado. Remove `auto` do ciclo `Shift+Tab` e rejeita `--permission-mode auto` na inicialização. Mais útil em [configurações gerenciadas](/pt/permissions#managed-settings) onde os usuários não podem substituir | `"disable"` |
| `disableBundledSkills` | Defina como `true` para desabilitar as [skills](/pt/skills) e workflows que vêm com o Claude Code: skills agrupadas e workflows são removidos completamente, enquanto comandos slash integrados como `/init` permanecem digitáveis mas são ocultados do modelo. Skills de plugins, `.claude/skills/`, e `.claude/commands/` não são afetadas. Equivalente a definir `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` como `1` | `true` |
| `disableClaudeAiConnectors` | {/* min-version: 2.1.182 */}Desabilitar [conectores MCP claude.ai](/pt/mcp#use-mcp-servers-from-claude-ai) para que não sejam auto-buscados ou conectados. Defina em qualquer escopo de configuração. `true` em qualquer fonte tem precedência, então um `.claude/settings.json` de projeto verificado pode optar um repositório por conectores de nuvem, mas um `false` de nível de projeto não pode substituir um `true` de nível de usuário ou política. Servers passados explicitamente via `--mcp-config` não são afetados. Para negar conectores individuais em vez de todos eles, use [`deniedMcpServers`](/pt/managed-mcp). Requer Claude Code v2.1.182 ou posterior | `true` |
| `disableDeepLinkRegistration` | Defina como `"disable"` para impedir que o Claude Code registre o manipulador de protocolo `claude-cli://` com o sistema operacional na inicialização. [Deep links](/pt/deep-links) permitem que ferramentas externas abram uma sessão do Claude Code com um prompt pré-preenchido. Útil em ambientes onde o registro de manipulador de protocolo é restrito ou gerenciado separadamente | `"disable"` |
| `disabledMcpjsonServers` | Lista de MCP servers específicos de arquivos `.mcp.json` para rejeitar | `["filesystem"]` |
| `disableRemoteControl` | {/* min-version: 2.1.128 */}Desabilitar [Controle Remoto](/pt/remote-control): bloqueia `claude remote-control`, a flag `--remote-control`, auto-start, e o toggle em sessão. Tipicamente colocado em [configurações gerenciadas](/pt/permissions#managed-settings) para aplicação de MDM por dispositivo, mas funciona de qualquer escopo. Requer Claude Code v2.1.128 ou posterior | `true` |
| `disableSideloadFlags` | {/* min-version: 2.1.193 */}(Apenas configurações gerenciadas) Rejeitar as flags CLI `--plugin-dir`, `--plugin-url`, `--agents`, e `--mcp-config` na inicialização, que os usuários poderiam passar para contornar [`strictKnownMarketplaces`](#strictknownmarketplaces) para uma única execução. Também rejeita estas flags de qualquer superfície que gera a CLI com elas internamente, atualmente [Cowork](/pt/desktop) sessões locais no aplicativo desktop. Um `--mcp-config` cujos servers são todas entradas `type: "sdk"` em processo ainda é aceito, então o Agent SDK e a extensão VS Code continuam funcionando. Não bloqueia `claude mcp add`, `.mcp.json`, ou SDK `setMcpServers()`; emparelhe com [`allowedMcpServers`](/pt/managed-mcp) para controle de MCP por servidor. Requer Claude Code v2.1.193 ou posterior | `true` |
| `disableSkillShellExecution` | Desabilitar execução de shell inline para blocos `` !`...` `` e ` ```! ` em [skills](/pt/skills) e comandos personalizados de fontes de usuário, projeto, plugin ou diretório adicional. Comandos são substituídos por `[shell command execution disabled by policy]` em vez de serem executados. Skills agrupadas e gerenciadas não são afetadas. Mais útil em [configurações gerenciadas](/pt/permissions#managed-settings) onde os usuários não podem substituir | `true` |
| `disableWorkflows` | **Padrão**: `false`. Desabilitar [workflows dinâmicos](/pt/workflows#turn-workflows-off) e os comandos de workflow agrupados. Equivalente a definir `CLAUDE_CODE_DISABLE_WORKFLOWS` como `1` | `true` |
| `editorMode` | **Padrão**: `"normal"`. Modo de atalho de teclado para o prompt de entrada: `"normal"` ou `"vim"`. Aparece em `/config` como **Editor mode** | `"vim"` |
| `effortLevel` | Persistir o [nível de esforço](/pt/model-config#adjust-effort-level) entre sessões. Aceita `"low"`, `"medium"`, `"high"`, ou `"xhigh"`. Escrito automaticamente quando você executa `/effort` com um desses valores. `--effort` e [`CLAUDE_CODE_EFFORT_LEVEL`](/pt/env-vars) substituem isto para uma sessão. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) para modelos suportados | `"xhigh"` |
| `enableAllProjectMcpServers` | Aprovar automaticamente todos os MCP servers definidos em arquivos `.mcp.json` do projeto. {/* min-version: 2.1.196 */}A partir de v2.1.196, `claude mcp list` e `claude mcp get` honram esta chave em uma pasta não confiável apenas de [arquivos de configuração que não são verificados no repositório](/pt/mcp#managing-your-servers) | `true` |
| `enableArtifact` | {/* min-version: 2.1.196 */}Ativar ou desabilitar a ferramenta [Artifact](/pt/artifacts) para este usuário. Quando indefinido, o padrão segue a [disponibilidade](/pt/artifacts#availability) do recurso para sua conta. A linha **Artifacts** em `/config` escreve esta chave. Um `disableArtifact` gerenciado e sua [configuração de administrador](/pt/artifacts#manage-artifacts-for-your-organization) da organização têm precedência, e a chave é ignorada em configurações de projeto e local (`.claude/settings.json`, `.claude/settings.local.json`), que um repositório poderia de outra forma confirmar. Requer Claude Code v2.1.196 ou posterior | `true` |
| `enabledMcpjsonServers` | Lista de MCP servers específicos de arquivos `.mcp.json` para aprovar. {/* min-version: 2.1.196 */}A partir de v2.1.196, `claude mcp list` e `claude mcp get` honram esta chave em uma pasta não confiável apenas de [arquivos de configuração que não são verificados no repositório](/pt/mcp#managing-your-servers) | `["memory", "github"]` |
| `enforceAvailableModels` | {/* min-version: 2.1.175 */}Estender a lista de permissões `availableModels` para o modelo Padrão. Quando `true` em configurações gerenciadas e `availableModels` é uma lista não-vazia, a opção Padrão volta para a primeira entrada na lista de permissões que está disponível, mas apenas quando o modelo padrão para o tipo de conta do usuário não está na lista de permissões; um padrão na lista de permissões é mantido como está. Não tem efeito quando `availableModels` está indefinido ou vazio. Veja [Aplicar a lista de permissões para o modelo Padrão](/pt/model-config#enforce-the-allowlist-for-the-default-model). Requer Claude Code v2.1.175 ou posterior | `true` |
| `env` | Variáveis de ambiente aplicadas a cada sessão e a subprocessos que Claude Code gera a partir dela. {/* min-version: 2.1.143 */}A partir da v2.1.143, `NO_COLOR` e `FORCE_COLOR` definidos aqui são passados para subprocessos mas não mudam as cores da interface do Claude Code. Defina estes em seu shell antes de lançar `claude` para mudar as cores da interface. {/* min-version: 2.1.195 */}A partir de v2.1.195, variáveis de identidade que ambientes de hospedagem do Claude Code definem, por exemplo `CLAUDE_CODE_REMOTE` e `CLAUDE_CODE_ACCOUNT_UUID`, são ignoradas quando definidas aqui | `{"FOO": "bar"}` |
| `fallbackModel` | Modelo(s) de fallback para tentar em ordem quando o modelo primário está sobrecarregado ou indisponível. O Claude Code muda para o próximo modelo disponível na cadeia para o resto do turno e mostra um aviso. `"default"` expande para o modelo padrão. Cadeias são limitadas a três modelos; entradas extras são ignoradas. Ao contrário da maioria das configurações de array, esta chave não se mescla entre arquivos de configuração: o arquivo de precedência mais alta que a define fornece a cadeia inteira. A flag [`--fallback-model`](/pt/cli-reference#cli-flags) substitui isto para uma sessão. Veja [Cadeias de modelo de fallback](/pt/model-config#fallback-model-chains) | `["claude-sonnet-5", "claude-haiku-4-5"]` |
| `fastModePerSessionOptIn` | Quando `true`, o modo rápido não persiste entre sessões. Cada sessão começa com modo rápido desligado, exigindo que os usuários o habilitem com `/fast`. A preferência de modo rápido do usuário ainda é salva. Veja [Exigir opt-in por sessão](/pt/fast-mode#require-per-session-opt-in) | `true` |
| `feedbackSurveyRate` | Probabilidade (0–1) que a [pesquisa de qualidade de sessão](/pt/data-usage#session-quality-surveys) aparece quando elegível. Defina como `0` para suprimir completamente, ou defina [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/pt/env-vars) em `env`. Útil ao usar Bedrock, Vertex, ou Foundry onde a taxa de amostra padrão não se aplica | `0.05` |
| `fileCheckpointingEnabled` | {/* min-version: 2.1.119 */}**Padrão**: `true`. Fazer snapshot de arquivos antes de cada edição para que [`/rewind`](/pt/checkpointing) possa restaurá-los. Aparece em `/config` como **Rewind code (checkpoints)**. Para desabilitar via variável de ambiente, defina [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/pt/env-vars) em `env` | `false` |
| `fileSuggestion` | Configure um script personalizado para preenchimento automático de arquivo `@`. Veja [Configurações de sugestão de arquivo](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |
| `footerLinksRegexes` | {/* min-version: 2.1.176 */}Renderizar badges clicáveis extras no rodapé quando uma regex corresponde à saída de turno. Cada entrada tem um `pattern`, um modelo de URL `url` com placeholders `{name}` preenchidos de grupos de captura nomeados, e um `label` opcional. Lido apenas de configurações de usuário, flag `--settings`, e configurações gerenciadas. Veja [Badges de link de rodapé](#footer-link-badges) para restrições de URL, lista de permissões de esquema, e limites. Requer Claude Code v2.1.176 ou posterior | `[{"type": "regex", "pattern": "\\b(?PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |
| `forceLoginMethod` | Use `claudeai` para restringir login a contas Claude.ai, `console` para restringir login a contas Claude Console, ou `gateway` para restringir login a um gateway de nuvem; veja [gateway de aplicativos Claude](/pt/claude-apps-gateway). Quando definido em qualquer valor em configurações gerenciadas, sessões autenticadas por `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, ou `apiKeyHelper` são bloqueadas na inicialização, já que uma credencial de ambiente não pode satisfazer o método de login necessário. Sessões de provedor de terceiros como Bedrock, Vertex, e Foundry não são bloqueadas: elas autenticam contra seu provedor de nuvem em vez de Anthropic | `claudeai` |
| `forceLoginGatewayUrl` | Pré-preenche e bloqueia a URL do gateway na tela `/login` Cloud gateway. Ou esta chave ou `forceLoginMethod: "gateway"` superficializa essa tela; defina ambas para que a URL seja preenchida. Honrado apenas no nível de política gerenciada; ignorado em configurações de usuário e projeto. Veja [gateway de aplicativos Claude](/pt/claude-apps-gateway#set-the-gateway-url) | `"https://claude-gateway.example.com"` |
| `forceLoginOrgUUID` | Exigir que o login pertença a uma organização Anthropic específica. Aceita uma string UUID única, que também pré-seleciona essa organização durante o login, ou um array de UUIDs onde qualquer organização listada é aceita sem pré-seleção. Quando definido em configurações gerenciadas, o login falha se a conta autenticada não pertencer a uma organização listada, e sessões autenticadas por `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, ou `apiKeyHelper` são bloqueadas na inicialização já que a associação à organização não pode ser verificada para elas. Sessões de provedor de terceiros como Bedrock, Vertex, e Foundry não são bloqueadas: use seu IAM de nuvem para restringir quais contas de nuvem podem ser usadas. Um array vazio falha fechado e bloqueia o login com uma mensagem de configuração incorreta | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` ou `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |
| `forceRemoteSettingsRefresh` | (Apenas configurações gerenciadas) Bloquear inicialização da CLI até que configurações gerenciadas remotas sejam buscadas recentemente do servidor. Se a busca falhar, a CLI sai em vez de continuar com configurações em cache ou sem configurações. Quando não definido, a inicialização continua sem esperar por configurações remotas. Veja [aplicação fail-closed](/pt/server-managed-settings#enforce-fail-closed-startup) | `true` |
| `gcpAuthRefresh` | Script personalizado que atualiza as Credenciais Padrão de Aplicação GCP quando expiram ou não podem ser carregadas. Veja [configuração avançada de credenciais](/pt/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |
| `hooks` | Configure comandos personalizados para executar em eventos do ciclo de vida. Veja [documentação de hooks](/pt/hooks) para formato | Veja [hooks](/pt/hooks) |
| `httpHookAllowedEnvVars` | Lista de permissões de nomes de variáveis de ambiente que hooks HTTP podem interpolar em cabeçalhos. Quando definido, o `allowedEnvVars` efetivo de cada hook é a interseção com esta lista. Indefinido = sem restrição. Arrays se mesclam entre fontes de configuração. Veja [Configuração de hooks](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |
| `includeGitInstructions` | **Padrão**: `true`. Incluir instruções de workflow de commit e PR integradas e o snapshot de status git no prompt do sistema do Claude. Defina como `false` para remover ambos, por exemplo ao usar suas próprias skills de workflow git. A variável de ambiente `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` tem precedência sobre esta configuração quando definida | `false` |
| `inputNeededNotifEnabled` | {/* min-version: 2.1.119 */}**Padrão**: `false`. Quando [Controle Remoto](/pt/remote-control) está conectado, enviar uma notificação push para seu telefone quando um prompt de permissão ou pergunta está aguardando sua entrada. Aparece em `/config` como **Push when actions required**. Veja [Notificações push móveis](/pt/remote-control#mobile-push-notifications). Requer Claude Code v2.1.119 ou posterior | `true` |
| `language` | Configure o idioma de resposta preferido do Claude (por exemplo, `"japanese"`, `"spanish"`, `"french"`). Claude responderá neste idioma por padrão. Também define o idioma de [ditado por voz](/pt/voice-dictation#change-the-dictation-language) e títulos de sessão gerados automaticamente. {/* min-version: 2.1.176 */}A partir de v2.1.176, quando não definido, títulos de sessão correspondem ao idioma de sua conversa | `"japanese"` |
| `minimumVersion` | Piso que impede auto-atualizações em background e `claude update` de instalar uma versão abaixo desta. Mudar do canal `"latest"` para `"stable"` via `/config` solicita que você fique na versão atual ou permita o downgrade. Escolher ficar define este valor. Também útil em [configurações gerenciadas](/pt/permissions#managed-settings) para fixar um mínimo em toda a organização. Para um piso duro que bloqueia a inicialização completamente, veja `requiredMinimumVersion` | `"2.1.100"` |
| `model` | Substituir o modelo padrão a usar para Claude Code. `--model` e [`ANTHROPIC_MODEL`](/pt/model-config#environment-variables) substituem isto para uma sessão | `"claude-sonnet-5"` |
| `modelOverrides` | Mapear IDs de modelo Anthropic para IDs de modelo específicos do provedor, como ARNs de perfil de inferência Bedrock. Cada entrada do seletor de modelo usa seu valor mapeado ao chamar a API do provedor. Veja [Substituir IDs de modelo por versão](/pt/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |
| `otelHeadersHelper` | Script para gerar cabeçalhos OpenTelemetry dinâmicos. Executa na inicialização e periodicamente. Defina o intervalo de atualização com [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/pt/env-vars). Veja [Cabeçalhos dinâmicos](/pt/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |
| `outputStyle` | Configure um estilo de saída para ajustar o prompt do sistema. Veja [documentação de estilos de saída](/pt/output-styles) | `"Explanatory"` |
| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}(Apenas configurações gerenciadas) **Padrão**: `"first-wins"`. Controla se configurações gerenciadas fornecidas programaticamente por um processo host de incorporação, como o Agent SDK ou uma extensão IDE, se aplicam quando um nível gerenciado implantado por administrador também está presente. `"first-wins"`: as configurações fornecidas pelo pai são descartadas e apenas o nível de administrador se aplica. `"merge"`: as configurações fornecidas pelo pai se aplicam sob o nível de administrador, filtradas para que possam apertar a política mas não afrouxá-la. Não tem efeito quando nenhum nível de administrador é implantado. Requer Claude Code v2.1.133 ou posterior | `"merge"` |
| `permissions` | Veja a tabela abaixo para a estrutura de permissões. | |
| `plansDirectory` | **Padrão**: `~/.claude/plans`. Personalizar onde os arquivos de plano são armazenados. O caminho é relativo à raiz do projeto. | `"./plans"` |
| `pluginSuggestionMarketplaces` | (Apenas configurações gerenciadas) Nomes de marketplace cujos plugins podem aparecer como sugestões de instalação contextual. Nenhuma sugestão declarada por marketplace aparece sem esta lista de permissões; a dica integrada de design de frontend de primeira parte não é afetada. Sugestões vêm da declaração `relevance` de cada plugin em sua entrada de marketplace. Um nome só tem efeito quando o marketplace está registrado na máquina e sua fonte registrada também é declarada em configurações gerenciadas, seja como a entrada `extraKnownMarketplaces` para esse nome ou como uma entrada de `strictKnownMarketplaces`. Um marketplace registrado de uma fonte diferente sob um nome na lista de permissões é ignorado. O marketplace oficial é isento do requisito de fonte: permitir seu nome sozinho é suficiente, já que esse nome só pode se registrar da fonte Anthropic oficial. | `["acme-corp-plugins"]` |
| `pluginTrustMessage` | (Apenas configurações gerenciadas) Mensagem personalizada anexada ao aviso de confiança de plugin mostrado antes da instalação. Use isto para adicionar contexto específico da organização, por exemplo para confirmar que plugins do seu marketplace interno são verificados. | `"All plugins from our marketplace are approved by IT"` |
| `policyHelper` | {/* min-version: 2.1.136 */}Executável implantado por administrador que calcula configurações gerenciadas dinamicamente na inicialização. Apenas honrado de MDM ou um arquivo `managed-settings.json` do sistema. Veja [Calcular configurações gerenciadas com um auxiliar de política](#compute-managed-settings-with-a-policy-helper). Requer Claude Code v2.1.136 ou posterior | `{"path": "/usr/local/bin/claude-policy"}` |
| `preferredNotifChannel` | **Padrão**: `"auto"`. Método para notificações de conclusão de tarefa e prompt de permissão: `"auto"`, `"terminal_bell"`, `"iterm2"`, `"iterm2_with_bell"`, `"kitty"`, `"ghostty"`, ou `"notifications_disabled"`. `"auto"` envia uma notificação de desktop em iTerm2, Ghostty, e Kitty e não faz nada em outros terminais. Defina `"terminal_bell"` para tocar o caractere de sino em qualquer terminal. Aparece em `/config` como **Notifications**. Veja [Obter um sino de terminal ou notificação](/pt/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |
| `prefersReducedMotion` | Reduzir ou desabilitar animações de UI (spinners, shimmer, efeitos de flash) para acessibilidade | `true` |
| `prUrlTemplate` | Modelo de URL para o badge de PR mostrado no rodapé e em resumos de resultado de ferramenta. Substitui `{host}`, `{owner}`, `{repo}`, `{number}`, e `{url}` da URL de PR relatada por `gh`. Use para apontar links de PR para uma ferramenta de revisão de código interna em vez de `github.com`. Não afeta autolinks `#123` na prosa do Claude | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |
| `remoteControlAtStartup` | {/* min-version: 2.1.119 */}Conectar [Controle Remoto](/pt/remote-control) automaticamente quando cada sessão interativa inicia, em vez de esperar por `/remote-control`. Defina como `true` para sempre auto-conectar, `false` para nunca auto-conectar, ou deixe indefinido para seguir o padrão da sua organização. Aparece em `/config` como **Enable Remote Control for all sessions**. Veja [Ativar Controle Remoto para todas as sessões](/pt/remote-control#enable-remote-control-for-all-sessions) | `false` |
| `requiredMaximumVersion` | Apenas configurações gerenciadas. Versão máxima do Claude Code permitida para iniciar. Se a versão em execução for mais nova, o Claude Code sai na inicialização e instrui o usuário a instalar uma versão aprovada através do método aprovado da organização; `claude install ` também pode funcionar. Auto-atualizações em background e `claude update` pulam versões acima do teto, então uma instalação dentro do intervalo permanece dentro do intervalo. `claude update`, `claude install`, e `claude doctor` continuam funcionando acima do teto para que os usuários possam se recuperar. Versões que antecedem esta configuração a ignoram | `"2.1.150"` |
| `requiredMinimumVersion` | Apenas configurações gerenciadas. Versão mínima do Claude Code necessária para iniciar. Se a versão em execução for mais antiga, o Claude Code sai na inicialização e instrui o usuário a atualizar através do método aprovado da organização. `claude update`, `claude install`, e `claude doctor` continuam funcionando abaixo do piso para que os usuários possam se recuperar. Difere de `minimumVersion`, que impede downgrades mas nunca bloqueia a inicialização. Versões que antecedem esta configuração a ignoram | `"2.1.150"` |
| `respectGitignore` | **Padrão**: `true`. Controlar se o seletor de arquivo `@` respeita padrões `.gitignore`. Quando `true`, arquivos correspondentes a padrões `.gitignore` são excluídos das sugestões | `false` |
| `respondToBashCommands` | {/* min-version: 2.1.186 */}**Padrão**: `true`. Se Claude responde após um comando shell `!` da caixa de entrada ser executado. Defina como `false` para adicionar a saída do comando ao contexto sem uma resposta. Veja [Modo Shell com prefixo `!`](/pt/interactive-mode#shell-mode-with-prefix). Requer Claude Code v2.1.186 ou posterior | `false` |
| `showClearContextOnPlanAccept` | **Padrão**: `false`. Mostrar a opção "limpar contexto" na tela de aceitação do plano. Defina como `true` para restaurar a opção | `true` |
| `showThinkingSummaries` | **Padrão**: `false`. Mostrar resumos de [pensamento estendido](/pt/model-config#extended-thinking) em sessões interativas. Quando indefinido ou `false`, blocos de pensamento são redatados pela API e mostrados como um stub recolhido. A redação apenas muda o que você vê, não o que o modelo gera: para reduzir gastos de pensamento, [reduza o orçamento ou desabilite o pensamento](/pt/model-config#extended-thinking) em vez disso. Esta configuração não tem efeito em modo não interativo (`-p`), no Agent SDK, ou em extensões IDE como VS Code | `true` |
| `showTurnDuration` | **Padrão**: `true`. Mostrar mensagens de duração de turno após respostas, por exemplo "Cooked for 1m 6s". Aparece em `/config` como **Show turn duration** | `false` |
| `skillListingBudgetFraction` | {/* min-version: 2.1.105 */}**Padrão**: `0.01` (1%). Fração da janela de contexto do modelo reservada para a [listagem de skills](/pt/skills#skill-descriptions-are-cut-short) que Claude vê a cada turno. Quando a listagem excede o orçamento, descrições para as skills menos usadas são recolhidas para nomes simples para que Claude ainda possa invocá-las mas não verá por quê. Aumente para manter mais descrições visíveis ao custo de mais contexto por turno. `/doctor` mostra a contagem de truncamento atual e quais skills são afetadas. Requer Claude Code v2.1.105 ou posterior | `0.02` |
| `skillListingMaxDescChars` | {/* min-version: 2.1.105 */}**Padrão**: `1536`. Limite de caracteres por skill no texto combinado `description` e `when_to_use` na [listagem de skills](/pt/skills#skill-descriptions-are-cut-short) que Claude vê a cada turno. Texto mais longo que isto é truncado. Aumente para manter descrições longas intactas ao custo de mais contexto por turno; diminua para caber mais skills sob [`skillListingBudgetFraction`](#available-settings). Requer Claude Code v2.1.105 ou posterior | `2048` |
| `skillOverrides` | {/* min-version: 2.1.129 */}Substituições de visibilidade por skill com chave de nome de skill. O valor é `"on"`, `"name-only"`, `"user-invocable-only"`, ou `"off"`. Permite ocultar ou recolher uma skill sem editar seu SKILL.md. Não se aplica a skills de plugin, que são gerenciadas através de `/plugin`. O menu `/skills` escreve estes em `.claude/settings.local.json`. Veja [Substituir visibilidade de skill a partir de configurações](/pt/skills#override-skill-visibility-from-settings). Requer Claude Code v2.1.129 ou posterior | `{"legacy-context": "name-only", "deploy": "off"}` |
| `skipWebFetchPreflight` | Pular a [verificação de segurança de domínio WebFetch](/pt/data-usage#webfetch-domain-safety-check) que envia cada nome de host solicitado para `api.anthropic.com` antes de buscar. Defina como `true` em ambientes que bloqueiam tráfego para Anthropic, como implantações Bedrock, Vertex AI, ou Foundry com egresso restritivo. Quando pulado, WebFetch tenta qualquer URL sem consultar a lista de bloqueio | `true` |
| `spinnerTipsEnabled` | **Padrão**: `true`. Mostrar dicas no spinner enquanto Claude está trabalhando. Defina como `false` para desabilitar dicas | `false` |
| `spinnerTipsOverride` | Substituir dicas do spinner com strings personalizadas. `tips`: array de strings de dica. `excludeDefault`: se `true`, mostrar apenas dicas personalizadas; se `false` ou ausente, dicas personalizadas são mescladas com dicas integradas | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |
| `spinnerVerbs` | Personalizar os verbos de ação mostrados enquanto um turno está em progresso. Defina `mode` como `"replace"` para usar apenas seus verbos, ou `"append"` para adicioná-los aos padrões | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |
| `sshConfigs` | Conexões SSH para mostrar no dropdown de ambiente [Desktop](/pt/desktop#pre-configure-ssh-connections-for-your-team). Cada entrada requer `id`, `name`, e `sshHost`; `sshPort`, `sshIdentityFile`, e `startDirectory` são opcionais. Quando definido em configurações gerenciadas, conexões são somente leitura para usuários. Lido apenas de configurações gerenciadas e de usuário | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |
| `statusLine` | Configure uma linha de status personalizada para exibir contexto. O objeto opcional tem campos `padding`, `refreshInterval`, e `hideVimModeIndicator` que controlam espaçamento, re-execuções periódicas, e se o indicador de modo vim integrado abaixo do prompt está oculto. Veja [documentação de `statusLine`](/pt/statusline#manually-configure-a-status-line) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |
| `strictKnownMarketplaces` | (Apenas configurações gerenciadas) Lista de permissões de marketplaces de plugin. Indefinido = sem restrições, array vazio = bloqueio. Aplicado em adição de marketplace e em instalação, atualização, atualização e auto-atualização de plugin, então um marketplace adicionado antes da política ser definida não pode ser usado para buscar plugins. Veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |
| `strictPluginOnlyCustomization` | (Apenas configurações gerenciadas) Bloquear skills, agents, hooks, e MCP servers de fontes de usuário e projeto, para que possam vir apenas de plugins ou configurações gerenciadas. `true` bloqueia todas as quatro superfícies; um array bloqueia apenas as nomeadas. Veja [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | `["skills", "hooks"]` |
| `syntaxHighlightingDisabled` | Desabilitar destaque de sintaxe em diffs, blocos de código e visualizações de arquivo | `true` |
| `teammateMode` | **Padrão**: `in-process`. Como [colegas de equipe de agente](/pt/agent-teams) são exibidos: `in-process`, `auto` (painéis divididos ao executar dentro de tmux ou iTerm2, em processo caso contrário), `tmux` (painéis divididos usando tmux ou iTerm2, detectado do seu terminal), ou {/* min-version: 2.1.186 */}`iterm2` (painéis divididos nativos do iTerm2 via CLI `it2`, adicionado em v2.1.186). O padrão mudou de `auto` em v2.1.179. `--teammate-mode` substitui isto para uma sessão. Veja [escolher um modo de exibição](/pt/agent-teams#choose-a-display-mode) | `"auto"` |
| `terminalProgressBarEnabled` | **Padrão**: `true`. Mostrar a barra de progresso do terminal em terminais suportados: ConEmu, Ghostty 1.2.0+, e iTerm2 3.6.6+. Aparece em `/config` como **Terminal progress bar** | `false` |
| `theme` | {/* min-version: 2.1.119 */}**Padrão**: `"dark"`. Tema de cor para a interface: `"auto"`, `"dark"`, `"light"`, `"dark-daltonized"`, `"light-daltonized"`, `"dark-ansi"`, `"light-ansi"`, ou uma referência de tema personalizado como `"custom:"` ou `"custom::"`. Veja [Criar um tema personalizado](/pt/terminal-config#create-a-custom-theme). Aparece em `/config` como **Theme** | `"dark"` |
| `tui` | Renderizador de UI de terminal. Use `"fullscreen"` para o renderizador [alt-screen](/pt/fullscreen) sem cintilação com scrollback virtualizado. Use `"default"` para o renderizador clássico de tela principal. Defina via `/tui`. Você também pode definir a variável de ambiente [`CLAUDE_CODE_NO_FLICKER`](/pt/env-vars) | `"fullscreen"` |
| `ultracode` | Ativar [ultracode](/pt/workflows#let-claude-decide-with-ultracode) para a sessão. Apenas sessão e não lido de `settings.json`. Defina através de `/effort ultracode`, `--settings`, ou uma solicitação de controle do Agent SDK | `true` |
| `useAutoModeDuringPlan` | **Padrão**: `true`. Se Plan Mode usa semântica de modo automático quando o modo automático está disponível. Não lido de configurações de projeto compartilhadas. Aparece em `/config` como "Use auto mode during plan" | `false` |
| `verbose` | {/* min-version: 2.1.119 */}**Padrão**: `false`. Mostrar saída completa de ferramenta em vez de resumos truncados. Aparece em `/config` como **Verbose output**. A flag `--verbose` substitui isto para uma sessão | `true` |
| `viewMode` | Modo de visualização de transcrição padrão na inicialização: `"default"`, `"verbose"`, ou `"focus"`. Substitui a seleção pegajosa `/focus` quando definido. A flag `--verbose` substitui isto para uma sessão | `"verbose"` |
| `voice` | Configurações de [ditado por voz](/pt/voice-dictation): `enabled` ativa ditado, `mode` seleciona `"hold"` ou `"tap"`, e `autoSubmit` envia o prompt ao soltar a tecla em modo hold. Escrito automaticamente quando você executa `/voice`. Requer uma conta Claude.ai | `{ "enabled": true, "mode": "tap" }` |
| `voiceEnabled` | Alias legado para `voice.enabled`. Prefira o objeto `voice` | `true` |
| `wheelScrollAccelerationEnabled` | {/* min-version: 2.1.174 */}**Padrão**: `true`. Em [renderização fullscreen](/pt/fullscreen#mouse-wheel-scrolling), acelerar velocidade de scroll de roda do mouse durante scrolls rápidos. Defina como `false` para uma taxa de scroll constante por entalhe de roda. Requer Claude Code v2.1.174 ou posterior | `false` |
| `workflowKeywordTriggerEnabled` | {/* min-version: 2.1.157 */}**Padrão**: `true`. Se a palavra-chave `ultracode` em um prompt dispara um [workflow dinâmico](/pt/workflows#ask-for-a-workflow-in-your-prompt). Defina como `false` para digitar a palavra sem disparar um. A configuração de esforço ultracode, `/workflows`, e comandos de workflow salvos não são afetados. Aparece em `/config` como **Ultracode keyword trigger**. Adicionado em v2.1.157; antes de v2.1.160 a palavra-chave de disparo era `workflow` | `false` |
| `wslInheritsWindowsSettings` | (Apenas configurações gerenciadas do Windows) Quando `true`, Claude Code no WSL lê configurações gerenciadas da cadeia de política do Windows além de `/etc/claude-code`, com fontes do Windows tendo prioridade. Apenas honrado quando definido na chave de registro HKLM ou `C:\Program Files\ClaudeCode\managed-settings.json`, ambos exigindo admin do Windows para escrever. Para que a política HKCU também se aplique no WSL, a flag deve ser adicionalmente definida no HKCU em si. Não tem efeito no Windows nativo | `true` |
Configurações de config global
Estas configurações são armazenadas em `~/.claude.json` em vez de `settings.json`. Adicioná-las a `settings.json` acionará um erro de validação de esquema.
Versões antes da v2.1.119 também armazenam um número de chaves de preferência `/config` aqui em vez de em `settings.json`, incluindo `theme`, `verbose`, `editorMode`, `autoCompactEnabled`, e `preferredNotifChannel`.
| Chave | Descrição | Exemplo |
| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- |
| `autoConnectIde` | **Padrão**: `false`. Conectar automaticamente a um IDE em execução quando Claude Code inicia de um terminal externo. Aparece em `/config` como **Auto-connect to IDE (external terminal)** ao executar fora de um terminal VS Code ou JetBrains. A variável de ambiente [`CLAUDE_CODE_AUTO_CONNECT_IDE`](/pt/env-vars) substitui isto quando definida | `true` |
| `autoInstallIdeExtension` | **Padrão**: `true`. Instalar automaticamente a extensão IDE do Claude Code ao executar de um terminal VS Code. Aparece em `/config` como **Auto-install IDE extension** ao executar dentro de um terminal VS Code ou JetBrains. Você também pode definir a variável de ambiente [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/pt/env-vars) | `false` |
| `externalEditorContext` | **Padrão**: `false`. Prepend a resposta anterior do Claude como contexto comentado com `#` quando você abre o editor externo com `Ctrl+G`. Aparece em `/config` como **Show last response in external editor** | `true` |
| `teammateDefaultModel` | Modelo padrão para [colegas de equipe de agente](/pt/agent-teams) quando o prompt de spawn não especifica um. Defina como um alias de modelo como `"sonnet"`, ou `null` para herdar a seleção `/model` atual do líder. Aparece em `/config` como **Default teammate model** | `"sonnet"` |
Configurações de worktrees
Configure como `--worktree` cria e gerencia git worktrees.
| Chave | Descrição | Exemplo |
| :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |
| `worktree.baseRef` | Qual ref novos worktrees ramificam. `"fresh"` (padrão) ramifica de `origin/` para uma árvore limpa correspondendo ao remoto. `"head"` ramifica de seu `HEAD` local atual, então commits não enviados e estado de branch de feature estão presentes no worktree. Se aplica a `--worktree`, a ferramenta `EnterWorktree`, e isolamento de subagent | `"head"` |
| `worktree.symlinkDirectories` | Diretórios para criar symlink do repositório principal em cada worktree para evitar duplicar grandes diretórios no disco. Nenhum diretório é criado symlink por padrão | `["node_modules", ".cache"]` |
| `worktree.sparsePaths` | Diretórios para fazer checkout em cada worktree via git sparse-checkout. Apenas os caminhos listados mais arquivos de nível raiz são escritos no disco, o que é mais rápido em grandes monorepos | `["packages/my-app", "shared/utils"]` |
| `worktree.bgIsolation` | {/* min-version: 2.1.143 */}Modo de isolamento para [sessões em background](/pt/agent-view#how-file-edits-are-isolated). `"worktree"` (padrão) bloqueia `Edit`/`Write` no checkout principal até que `EnterWorktree` seja chamado. `"none"` permite que trabalhos em background editem a cópia de trabalho diretamente. Requer Claude Code v2.1.143 ou posterior | `"none"` |
Para copiar arquivos ignorados pelo git como `.env` em novos worktrees, use um arquivo [`.worktreeinclude`](/pt/worktrees#copy-gitignored-files-into-worktrees) na raiz do seu projeto em vez de uma configuração.
Configurações de permissão
| Chaves | Descrição | Exemplo |
| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |
| `allow` | Array de regras de permissão para permitir uso de ferramenta. Nomes de ferramenta globs são suportados apenas na posição de ferramenta após um prefixo literal `mcp____`, como `mcp__github__get_*`; o segmento de servidor deve estar livre de glob. Veja [Sintaxe de regra de permissão](#permission-rule-syntax) abaixo para detalhes de correspondência de padrão | `[ "Bash(git diff *)" ]` |
| `ask` | Array de regras de permissão para pedir confirmação ao usar ferramenta. Veja [Sintaxe de regra de permissão](#permission-rule-syntax) abaixo | `[ "Bash(git push *)" ]` |
| `deny` | Array de regras de permissão para negar uso de ferramenta. Use isto para excluir arquivos sensíveis do acesso do Claude Code. Nomes de ferramenta aceitam padrões glob: `"*"` nega cada ferramenta e `"mcp__*"` nega todas as ferramentas MCP. Veja [Sintaxe de regra de permissão](#permission-rule-syntax) e [Limitações de permissão Bash](/pt/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |
| `additionalDirectories` | [Diretórios de trabalho](/pt/permissions#working-directories) adicionais para acesso a arquivos. A maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) destes diretórios | `[ "../docs/" ]` |
| `defaultMode` | [Modo de permissão](/pt/permission-modes) padrão ao abrir Claude Code. Valores válidos: `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`. {/* min-version: 2.1.142 */}A partir do Claude Code v2.1.142, `auto` é ignorado quando definido em configurações de projeto ou local (`.claude/settings.json`, `.claude/settings.local.json`) para que um repositório não possa se conceder modo automático. Defina-o em `~/.claude/settings.json` em vez disso. A flag CLI `--permission-mode` substitui esta configuração para uma única sessão | `"acceptEdits"` |
| `disableBypassPermissionsMode` | Defina como `"disable"` para impedir que o modo `bypassPermissions` seja ativado. Isto desabilita a flag de linha de comando `--dangerously-skip-permissions`. Tipicamente colocado em [configurações gerenciadas](/pt/permissions#managed-settings) para aplicar política organizacional, mas funciona de qualquer escopo | `"disable"` |
| `skipDangerousModePermissionPrompt` | Pular o prompt de confirmação mostrado antes de entrar no modo de permissões de bypass via `--dangerously-skip-permissions` ou `defaultMode: "bypassPermissions"`. Ignorado quando definido em configurações de projeto (`.claude/settings.json`) para evitar que repositórios não confiáveis contornem automaticamente o prompt | `true` |
Sintaxe de regra de permissão
Regras de permissão seguem o formato `Tool` ou `Tool(specifier)`. Regras são avaliadas em ordem: regras de negação primeiro, depois ask, depois allow. A primeira regra correspondente determina o resultado independentemente da especificidade da regra. Veja a [ordem de avaliação de regra de permissão](/pt/permissions#manage-permissions) para detalhes.
Exemplos rápidos:
| Regra | Efeito |
| :----------------------------- | :--------------------------------------------------- |
| `Bash` | Corresponde a todos os comandos Bash |
| `Bash(npm run *)` | Corresponde a comandos começando com `npm run` |
| `Read(./.env)` | Corresponde a leitura do arquivo `.env` |
| `WebFetch(domain:example.com)` | Corresponde a solicitações de fetch para example.com |
Para a referência completa de sintaxe de regra, incluindo comportamento de curinga, padrões específicos de ferramenta para Read, Edit, WebFetch, MCP, e regras de Agent, e limitações de segurança de padrões Bash, veja [Sintaxe de regra de permissão](/pt/permissions#permission-rule-syntax).
Configurações de sandbox
Configure comportamento avançado de sandboxing. Sandboxing isola comandos bash do seu sistema de arquivos e rede. Veja [Sandboxing](/pt/sandboxing) para detalhes.
| Chaves | Descrição | Exemplo |
| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
| `enabled` | Ativar sandboxing bash (macOS, Linux, e WSL2). Padrão: false | `true` |
| `failIfUnavailable` | Sair com um erro na inicialização se `sandbox.enabled` é true mas o sandbox não pode iniciar (dependências faltantes ou plataforma não suportada). Quando false (padrão), um aviso é mostrado e comandos executam sem sandbox. Destinado para implantações de configurações gerenciadas que exigem sandboxing como um portão duro | `true` |
| `autoAllowBashIfSandboxed` | Aprovar automaticamente comandos bash quando sandboxed. Padrão: true | `true` |
| `excludedCommands` | Comandos que devem executar fora do sandbox | `["docker *"]` |
| `allowUnsandboxedCommands` | Permitir que comandos executem fora do sandbox via parâmetro `dangerouslyDisableSandbox`. Quando definido como `false`, a saída de escape `dangerouslyDisableSandbox` é completamente desabilitada e todos os comandos devem executar sandboxed (ou estar em `excludedCommands`). Útil para políticas empresariais que exigem sandboxing rigoroso. Padrão: true | `false` |
| `filesystem.allowWrite` | Caminhos adicionais onde comandos sandboxed podem escrever. Arrays são mesclados em todos os escopos de configuração: caminhos de usuário, projeto e gerenciados são combinados, não substituídos. Também mesclado com caminhos de regras de permissão `Edit(...)` allow. Veja [prefixos de caminho de sandbox](#sandbox-path-prefixes) abaixo. | `["/tmp/build", "~/.kube"]` |
| `filesystem.denyWrite` | Caminhos onde comandos sandboxed não podem escrever. Arrays são mesclados em todos os escopos de configuração. Também mesclado com caminhos de regras de permissão `Edit(...)` deny. | `["/etc", "/usr/local/bin"]` |
| `filesystem.denyRead` | Caminhos onde comandos sandboxed não podem ler. Arrays são mesclados em todos os escopos de configuração. Também mesclado com caminhos de regras de permissão `Read(...)` deny. | `["~/.aws/credentials"]` |
| `filesystem.allowRead` | Caminhos para re-permitir leitura dentro de regiões `denyRead`. Tem precedência sobre `denyRead`. Arrays são mesclados em todos os escopos de configuração. Use isto para criar padrões de acesso de leitura apenas para workspace. | `["."]` |
| `filesystem.allowManagedReadPathsOnly` | (Apenas configurações gerenciadas) Apenas caminhos `allowRead` de configurações gerenciadas são respeitados. `denyRead` ainda se mescla de todas as fontes. Padrão: false | `true` |
| `credentials.files` | Arquivos ou diretórios de credenciais que comandos sandboxed não podem ler. Aplica o mesmo bloqueio de leitura que `filesystem.denyRead`; a chave separada mantém caminhos de credenciais agrupados com `credentials.envVars` e separados de regras gerais de sistema de arquivos. Cada entrada é `{ "path": "...", "mode": "deny" }`. Caminhos usam os mesmos [prefixos](#sandbox-path-prefixes) que configurações `filesystem.*`. Arrays são mesclados em todos os escopos de configuração. Apenas `deny` é suportado. Requer Claude Code v2.1.187 ou posterior. | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |
| `credentials.envVars` | Variáveis de ambiente para desconfigurar antes de executar comandos sandboxed. Cada entrada é `{ "name": "...", "mode": "deny" }`. Arrays são mesclados em todos os escopos de configuração. Apenas `deny` é suportado. Requer Claude Code v2.1.187 ou posterior. | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |
| `network.allowUnixSockets` | (Apenas macOS) Caminhos de socket Unix acessíveis no sandbox. Ignorado no Linux e WSL2, onde o filtro seccomp não pode inspecionar caminhos de socket; use `allowAllUnixSockets` em vez disso. | `["~/.ssh/agent-socket"]` |
| `network.allowAllUnixSockets` | Permitir todas as conexões de socket Unix no sandbox. No Linux e WSL2 esta é a única maneira de permitir sockets Unix, já que pula o filtro seccomp que de outra forma bloqueia chamadas `socket(AF_UNIX, ...)`. Padrão: false | `true` |
| `network.allowLocalBinding` | Permitir vinculação a portas localhost (apenas macOS). Padrão: false | `true` |
| `network.allowMachLookup` | Nomes de serviço XPC/Mach adicionais que o sandbox pode procurar (apenas macOS). Suporta um único `*` à direita para correspondência de prefixo. Necessário para ferramentas que se comunicam via XPC, como o iOS Simulator ou Playwright. | `["com.apple.coresimulator.*"]` |
| `network.allowedDomains` | Array de domínios para permitir para tráfego de rede de saída. Suporta curingas (por exemplo, `*.example.com`). | `["github.com", "*.npmjs.org"]` |
| `network.deniedDomains` | Array de domínios para bloquear para tráfego de rede de saída. Suporta a mesma sintaxe de curinga que `allowedDomains`. Tem precedência sobre `allowedDomains` quando ambos correspondem. Mesclado de todas as fontes de configuração independentemente de `allowManagedDomainsOnly`. | `["sensitive.cloud.example.com"]` |
| `network.allowManagedDomainsOnly` | (Apenas configurações gerenciadas) Apenas `allowedDomains` e regras allow `WebFetch(domain:...)` de configurações gerenciadas são respeitadas. Domínios de configurações de usuário, projeto e local são ignorados. Domínios não permitidos são bloqueados automaticamente sem solicitar o usuário. Domínios negados ainda são respeitados de todas as fontes. Padrão: false | `true` |
| `network.httpProxyPort` | Porta de proxy HTTP usada se você deseja trazer seu próprio proxy. Se não especificado, Claude executará seu próprio proxy. | `8080` |
| `network.socksProxyPort` | Porta de proxy SOCKS5 usada se você deseja trazer seu próprio proxy. Se não especificado, Claude executará seu próprio proxy. | `8081` |
| `enableWeakerNestedSandbox` | Ativar sandbox mais fraco para ambientes Docker sem privilégios (apenas Linux e WSL2). **Reduz segurança.** Padrão: false | `true` |
| `enableWeakerNetworkIsolation` | (Apenas macOS) Permitir acesso ao serviço de confiança TLS do sistema (`com.apple.trustd.agent`) no sandbox. Necessário para ferramentas baseadas em Go como `gh`, `gcloud`, e `terraform` verificarem certificados TLS ao usar `httpProxyPort` com um proxy MITM e CA personalizada. **Reduz segurança** abrindo um possível caminho de exfiltração de dados. Padrão: false | `true` |
| `allowAppleEvents` | (Apenas macOS) Permitir que comandos sandboxed enviem Apple Events. Necessário para `open`, `osascript`, e ferramentas que abrem URLs em um navegador, que de outra forma falham com erro `-600`. **Remove isolamento de execução de código.** Comandos sandboxed podem lançar outras aplicações sem sandbox sem prompt do usuário; eles também podem enviar comandos AppleScript para aplicações em execução como Terminal, sujeito ao prompt de consentimento de automação por aplicativo do macOS (TCC). Apenas honrado de configurações de usuário, gerenciadas, ou CLI, não de configurações de projeto. Padrão: false | `true` |
| `bwrapPath` | (Apenas configurações gerenciadas, Linux/WSL2) Caminho absoluto para o binário bubblewrap (`bwrap`). Substitui detecção automática via `PATH`. Apenas honrado de [configurações gerenciadas](/pt/settings#settings-files), não de configurações de usuário ou projeto. Útil quando `bwrap` é instalado em um local não padrão em ambientes gerenciados. | `/opt/admin/bwrap` |
| `socatPath` | (Apenas configurações gerenciadas, Linux/WSL2) Caminho absoluto para o binário `socat` usado para o proxy de rede do sandbox. Substitui detecção automática via `PATH`. Apenas honrado de configurações gerenciadas. | `/opt/admin/socat` |
Prefixos de caminho de sandbox
Caminhos em `filesystem.allowWrite`, `filesystem.denyWrite`, `filesystem.denyRead`, `filesystem.allowRead`, e `credentials.files` suportam estes prefixos:
| Prefixo | Significado | Exemplo |
| :------------------ | :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- |
| `/` | Caminho absoluto da raiz do sistema de arquivos | `/tmp/build` permanece `/tmp/build` |
| `~/` | Relativo ao diretório home | `~/.kube` se torna `$HOME/.kube` |
| `./` ou sem prefixo | Relativo à raiz do projeto para configurações de projeto, ou a `~/.claude` para configurações de usuário | `./output` em `.claude/settings.json` resolve para `/output` |
O prefixo mais antigo `//path` para caminhos absolutos ainda funciona. Se você usou anteriormente `/path` esperando resolução relativa ao projeto, mude para `./path`. Esta sintaxe difere de [regras de permissão Read e Edit](/pt/permissions#read-and-edit), que usam `//path` para absoluto e `/path` para relativo ao projeto. Caminhos de sistema de arquivos de sandbox usam convenções padrão: `/tmp/build` é um caminho absoluto.
**Exemplo de configuração:**
```json theme={null}
{
"sandbox": {
"enabled": true,
"autoAllowBashIfSandboxed": true,
"excludedCommands": ["docker *"],
"filesystem": {
"allowWrite": ["/tmp/build", "~/.kube"],
"denyRead": ["~/.aws/credentials"]
},
"network": {
"allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
"deniedDomains": ["uploads.github.com"],
"allowUnixSockets": [
"/var/run/docker.sock"
],
"allowLocalBinding": true
}
}
}
```
**Restrições de sistema de arquivos e rede** podem ser configuradas de duas formas que são mescladas juntas:
* **Configurações `sandbox.filesystem`** (mostradas acima): Controlam caminhos no limite do sandbox de nível de SO. Estas restrições se aplicam a todos os comandos de subprocesso (por exemplo, `kubectl`, `terraform`, `npm`), não apenas às ferramentas de arquivo do Claude.
* **Regras de permissão**: Use regras allow/deny `Edit` para controlar acesso à ferramenta de arquivo do Claude, regras deny `Read` para bloquear leituras, e regras allow/deny `WebFetch` para controlar domínios de rede. Caminhos destas regras também são mesclados na configuração do sandbox.
Configurações de atribuição
O Claude Code adiciona atribuição a commits git e pull requests. Estes são configurados separadamente:
* Commits usam [git trailers](https://git-scm.com/docs/git-interpret-trailers) (como `Co-Authored-By`) por padrão, que podem ser personalizados ou desabilitados
* Descrições de pull request são texto simples
| Chaves | Descrição |
| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `commit` | Atribuição para commits git, incluindo qualquer trailer. String vazia oculta atribuição de commit |
| `pr` | Atribuição para descrições de pull request. String vazia oculta atribuição de pull request |
| `sessionUrl` | Se deve anexar o link de sessão claude.ai como um trailer `Claude-Session` em commits e um link em descrições de pull request ao executar de uma sessão web ou Controle Remoto. Padrão: `true`. Defina como `false` para omitir o link |
**Atribuição de commit padrão:**
```text theme={null}
Co-Authored-By: Claude Sonnet 5
```
O nome do modelo no trailer reflete o modelo ativo para a sessão.
**Atribuição de pull request padrão:**
```text theme={null}
🤖 Generated with [Claude Code](https://claude.com/claude-code)
```
**Exemplo:**
```json theme={null}
{
"attribution": {
"commit": "Generated with AI\n\nCo-Authored-By: AI ",
"pr": ""
}
}
```
A configuração `attribution` tem precedência sobre a configuração descontinuada `includeCoAuthoredBy`. Para ocultar toda atribuição, defina `commit` e `pr` como strings vazias e `sessionUrl` como `false`.
Configurações de sugestão de arquivo
Configure um comando personalizado para preenchimento automático de caminho de arquivo `@`. A sugestão de arquivo integrada usa travessia rápida do sistema de arquivos, mas grandes monorepos podem se beneficiar de indexação específica do projeto, como um índice de arquivo pré-construído ou ferramentas personalizadas.
```json theme={null}
{
"fileSuggestion": {
"type": "command",
"command": "~/.claude/file-suggestion.sh"
}
}
```
O comando executa com as mesmas variáveis de ambiente que [hooks](/pt/hooks), incluindo `CLAUDE_PROJECT_DIR`. Recebe JSON via stdin com um campo `query`:
```json theme={null}
{"query": "src/comp"}
```
Produz caminhos de arquivo separados por nova linha para stdout (atualmente limitado a 15):
```text theme={null}
src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx
```
**Exemplo:**
```bash theme={null}
#!/bin/bash
query=$(cat | jq -r '.query')
# Substitua your-repo-file-index pelo seu próprio comando de busca de arquivo
your-repo-file-index --query "$query" | head -20
```
A configuração `footerLinksRegexes` renderiza badges clicáveis extras no rodapé abaixo da caixa de entrada. Use-a para transformar IDs impressos por CLIs de projeto, como ferramentas de revisão e rastreadores de problemas, em links de sessão.
Cada regex `pattern` de entrada é correspondida contra a saída de turno: resultados de ferramenta, incluindo conteúdo de arquivo e páginas buscadas, e respostas do próprio Claude. Placeholders `{name}` em `url` e `label` são preenchidos de grupos de captura nomeados no padrão.
O exemplo a seguir renderiza um badge sempre que uma chave de problema como `PROJ-1234` aparece na saída de turno. O grupo nomeado `(?...)` captura a chave, e `{key}` a substitui na URL e label:
```json ~/.claude/settings.json theme={null}
{
"footerLinksRegexes": [
{
"type": "regex",
"pattern": "\\b(?PROJ-\\d+)\\b",
"url": "https://issues.example.com/browse/{key}",
"label": "{key}"
}
]
}
```
Com isto configurado, quando `PROJ-1234` aparece em um resultado de ferramenta ou na resposta do Claude, um chip `PROJ-1234` aparece no rodapé ligando para `https://issues.example.com/browse/PROJ-1234`.
As seguintes restrições se aplicam a cada entrada:
| Restrição | Comportamento |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Origem de URL | Valores capturados são codificados em URL e a URL construída deve compartilhar a origem literal do modelo. Uma captura pode preencher um segmento de caminho ou valor de query mas não pode mudar para onde o link aponta |
| Comprimento de URL | URLs construídas mais longas que 2048 caracteres são descartadas |
| Esquema de URL | Deve ser `https`, `http`, ou um esquema de deep-link reconhecido de editor ou workspace: `vscode`, `vscode-insiders`, `cursor`, `windsurf`, `zed`, `jetbrains`, `idea`, `slack`, `linear`, `notion`, `figma` |
| Label | Padrão para o texto correspondido e é truncado para 28 colunas de exibição |
| Contagem de badge | No máximo 5 badges renderizam. O mais antigo é deslocado por correspondências mais novas e `/clear` os remove |
| Escopo de configuração | Lido apenas de configurações de usuário, flag `--settings`, e configurações gerenciadas. Ignorado em `.claude/settings.json` de projeto e `.claude/settings.local.json` local |
Quando um turno é concluído, Claude Code corresponde cada regex `pattern` de entrada contra a saída de turno na thread principal, então uma regex lenta bloqueia a UI até terminar. Quantificadores aninhados como `(a+)+$` podem levar exponencialmente tempo contra certas entradas e congelar a sessão, então mantenha cada `pattern` linear e evite aninhar `+` ou `*`.
Badges de rodapé renderizam ao lado de uma [linha de status personalizada](/pt/statusline) quando uma está configurada; nenhuma substitui a outra. Use uma linha de status para uma linha acionada 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.
Configuração de hooks
Estas configurações controlam quais hooks são permitidos executar e o que hooks HTTP podem acessar. A configuração `allowManagedHooksOnly` pode ser configurada apenas em [configurações gerenciadas](#settings-files). As listas de permissões de URL e variável de ambiente podem ser definidas em qualquer nível de configuração e se mesclam entre fontes.
**Comportamento quando `allowManagedHooksOnly` é `true`:**
* Hooks gerenciados e hooks SDK são carregados
* Hooks de plugins força-habilitados em configurações gerenciadas `enabledPlugins` são carregados. Isto permite que administradores distribuam hooks verificados através de um marketplace de organização enquanto bloqueiam tudo mais. A confiança é concedida pelo ID completo `plugin@marketplace`, então um plugin com o mesmo nome de um marketplace diferente permanece bloqueado
* Hooks de usuário, hooks de projeto e todos os outros hooks de plugin são bloqueados
**Restringir URLs de hook HTTP:**
Limitar quais URLs hooks HTTP podem almejar. Suporta `*` como curinga para correspondência. Quando o array é definido, hooks HTTP almejando URLs não correspondentes são silenciosamente bloqueados. A correspondência de nome de host é insensível a maiúsculas e minúsculas e ignora um ponto FQDN à direita, correspondendo à semântica de DNS.
```json theme={null}
{
"allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}
```
**Restringir variáveis de ambiente de hook HTTP:**
Limitar quais nomes de variáveis de ambiente hooks HTTP podem interpolar em valores de cabeçalho. O `allowedEnvVars` efetivo de cada hook é a interseção de sua própria lista e esta configuração.
```json theme={null}
{
"httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}
```
Calcular configurações gerenciadas com um auxiliar de política
A configuração `policyHelper` aponta para um executável que calcula configurações gerenciadas na inicialização, para que administradores possam derivar política da postura do dispositivo, identidade, ou um serviço remoto em vez de um arquivo estático. Configure-o a partir de MDM ou um arquivo `managed-settings.json` do sistema. O Claude Code ignora `policyHelper` quando aparece em qualquer outro escopo, incluindo configurações de usuário, configurações de projeto, a hive de registro HKCU, e [configurações gerenciadas pelo servidor](/pt/server-managed-settings).
A configuração aceita estas chaves:
| Chave | Tipo | Descrição |
| ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `path` | string | Caminho absoluto para o executável auxiliar |
| `timeoutMs` | number | Quanto tempo esperar pelo auxiliar antes de tratar a execução como falha |
| `refreshIntervalMs` | number | Com que frequência re-executar o auxiliar em background. Defina como `0` para desabilitar atualização, ou para pelo menos `60000` |
O auxiliar escreve um envelope JSON para stdout. Coloque as configurações sob uma chave `managedSettings` em vez de no nível superior, já que um objeto de configurações simples analisa com `managedSettings` indefinido e não aplica nada:
```json theme={null}
{
"managedSettings": {
"permissions": { "deny": ["Read(//etc/secrets/**)"] }
},
"claudeMd": "# Organization context\n...",
"appendSystemPrompt": "Always cite the internal style guide."
}
```
Quando o auxiliar emite `managedSettings`, esse objeto substitui as configurações gerenciadas baseadas em arquivo para a execução. Quando o auxiliar sai com código não-zero na inicialização, Claude Code imprime o erro e recusa iniciar, então um auxiliar que precisa de resiliência de interrupção deve servir a partir de seu próprio cache e sair com `0`.
Precedência de configurações
Configurações se aplicam em ordem de precedência. De mais alta para mais baixa:
1. **Configurações gerenciadas** ([gerenciadas pelo servidor](/pt/server-managed-settings), [políticas de nível MDM/SO](#configuration-scopes), ou [configurações gerenciadas](/pt/settings#settings-files))
* Políticas implantadas por TI através de entrega de servidor, perfis de configuração MDM, políticas de registro, ou arquivos de configurações gerenciadas
* Não podem ser substituídas por qualquer outro nível, incluindo argumentos de linha de comando
* Dentro do nível gerenciado, a precedência é: saída [`policyHelper`](#compute-managed-settings-with-a-policy-helper), que quando configurada é a única fonte gerenciada usada > remota (configurações gerenciadas pelo servidor do [claude.ai](/pt/server-managed-settings) ou [gateway de aplicativos Claude](/pt/claude-apps-gateway)-entregues) > políticas de nível MDM/SO > baseadas em arquivo (`managed-settings.d/*.json` + `managed-settings.json`) > registro HKCU (apenas Windows). Apenas uma fonte gerenciada é usada; fontes não se mesclam entre camadas, com uma exceção: as chaves de bloqueio de sandbox `sandbox.network.allowManagedDomainsOnly` e `sandbox.filesystem.allowManagedReadPathsOnly`, com suas listas de permissões associadas, `allowAllClaudeAiMcps`, e os caminhos binários de sandbox `sandbox.bwrapPath` e `sandbox.socatPath` são honrados quando qualquer fonte gerenciada controlada por administrador os define; a camada HKCU gravável pelo usuário é excluída. Dentro da camada baseada em arquivo, arquivos drop-in e o arquivo base são mesclados juntos.
* Hosts de incorporação como Claude Desktop podem fornecer política via opção SDK `managedSettings`. Por padrão isto é ignorado quando qualquer fonte gerenciada controlada por administrador está presente: configurações gerenciadas pelo servidor, uma política MDM ou SO, ou um arquivo de configurações gerenciadas. O fallback de registro HKCU gravável pelo usuário não conta como uma fonte gerenciada controlada por administrador. Administradores podem optar por definir [`parentSettingsBehavior`](#available-settings) como `"merge"`. Os valores do incorporador são filtrados para que possam apertar a política gerenciada mas não afrouxá-la.
2. **Argumentos de linha de comando**
* Substituições temporárias para uma sessão específica. JSON passado via `--settings ` se mescla com configurações baseadas em arquivo usando as mesmas regras que as outras camadas: uma chave definida aqui substitui a mesma chave em configurações local, projeto, ou usuário, e omitir uma chave deixa o valor da camada inferior no lugar
3. **Configurações de projeto local** (`.claude/settings.local.json`)
* Configurações pessoais específicas do projeto
4. **Configurações de projeto compartilhadas** (`.claude/settings.json`)
* Configurações de projeto compartilhadas pela equipe no controle de origem
5. **Configurações de usuário** (`~/.claude/settings.json`)
* Configurações globais pessoais
Esta hierarquia garante que políticas organizacionais sejam sempre aplicadas enquanto ainda permite que equipes e indivíduos personalizem sua experiência. A mesma precedência se aplica se você executar Claude Code a partir da CLI, da [extensão VS Code](/pt/vs-code), ou de um [IDE JetBrains](/pt/jetbrains).
Por exemplo, se suas configurações de usuário definem `permissions.defaultMode` como `acceptEdits` e as configurações compartilhadas de um projeto definem como `default`, o valor do projeto se aplica. O exemplo abaixo cobre como configurações com valor de array como regras de permissão se combinam em vez disso.
**Configurações de array se mesclam entre escopos.** Quando a mesma configuração com valor de array (como `sandbox.filesystem.allowWrite` ou `permissions.allow`) aparece em múltiplos escopos, os arrays são **concatenados e desduplicados**, não substituídos. Isto significa que escopos de prioridade mais baixa podem adicionar entradas sem substituir aquelas definidas por escopos de prioridade mais alta, e vice-versa. Por exemplo, se configurações gerenciadas definem `allowWrite` como `["/opt/company-tools"]` e um usuário adiciona `["~/.kube"]`, ambos os caminhos são incluídos na configuração final.
Duas configurações de array não se mesclam desta forma:
* [`fallbackModel`](#available-settings) é uma cadeia ordenada onde a posição carrega significado: o arquivo de precedência mais alta que a define fornece o valor inteiro.
* [`availableModels`](#available-settings): {/* min-version: 2.1.175 */}quando a [fonte gerenciada de precedência mais alta](/pt/server-managed-settings#settings-precedence) a define, essa lista se aplica como está e entradas de usuário, projeto e local não podem estendê-la. Entre escopos não gerenciados os arrays se mesclam como usual. Veja [Comportamento de mesclagem](/pt/model-config#merge-behavior).
Verificar configurações ativas
Execute `/status` dentro do Claude Code para ver quais fontes de configuração estão ativas. Dentro do menu, a aba **Status** inclui uma linha `Setting sources` que lista cada camada que Claude Code carregou para a sessão atual, como `User settings` ou `Project local settings`. Quando [configurações gerenciadas](/pt/admin-setup#decide-how-settings-reach-devices) estão em efeito, a entrada mostra o canal de entrega entre parênteses, por exemplo `Enterprise managed settings (remote)`, `(plist)`, `(HKLM)`, `(HKCU)`, ou `(file)`. O canal `remote` cobre configurações gerenciadas pelo servidor do claude.ai e políticas [gateway de aplicativos Claude](/pt/claude-apps-gateway)-entregues. Uma camada aparece na lista apenas quando essa fonte é carregada com pelo menos uma chave, então uma lista vazia significa que nenhuma fonte de configuração foi encontrada.
A linha `Setting sources` confirma quais fontes estão sendo lidas. Ela não mostra qual camada forneceu cada chave individual. A aba **Config** no mesmo diálogo é um editor para um conjunto fixo de toggles como tema e saída verbose, não uma visualização do conteúdo do seu `settings.json`.
Se um arquivo de configuração contém erros, como JSON inválido ou um valor que falha na validação, `/status` lista os arquivos afetados. Execute `/doctor` para ver os detalhes de cada erro.
Pontos-chave sobre o sistema de configuração
* **Arquivos de memória (`CLAUDE.md`)**: Contêm instruções e contexto que Claude carrega na inicialização
* **Arquivos de configuração (JSON)**: Configurar permissões, variáveis de ambiente, e comportamento de ferramenta
* **Skills**: Prompts personalizados que podem ser invocados com `/skill-name` ou carregados pelo Claude automaticamente
* **MCP servers**: Estender Claude Code com ferramentas e integrações adicionais
* **Precedência**: Configurações de nível mais alto (Managed) substituem as de nível mais baixo (User/Project)
* **Herança**: Configurações são mescladas entre escopos; valores escalares de escopos de prioridade mais alta substituem, e arrays se concatenam, com duas exceções descritas na [Nota de mesclagem de array](#settings-precedence)
Prompt do sistema
O prompt do sistema interno do Claude Code não é publicado. Para adicionar instruções personalizadas, use arquivos `CLAUDE.md` ou a flag `--append-system-prompt`.
Excluindo arquivos sensíveis
Para impedir que Claude Code acesse arquivos contendo informações sensíveis como chaves de API, segredos, e arquivos de ambiente, use a configuração `permissions.deny` no seu arquivo `.claude/settings.json`:
```json theme={null}
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Read(./config/credentials.json)",
"Read(./build)"
]
}
}
```
Isto substitui a configuração descontinuada `ignorePatterns`. Arquivos correspondentes a estes padrões são excluídos da descoberta de arquivo e resultados de busca, e operações de leitura nestes arquivos são negadas.
Configuração de subagent
O Claude Code suporta subagents de IA personalizados que podem ser configurados em níveis de usuário e projeto. Estes subagents são armazenados como arquivos Markdown com frontmatter YAML:
* **Subagents de usuário**: `~/.claude/agents/`, disponíveis em todos os seus projetos
* **Subagents de projeto**: `.claude/agents/`, específicos ao seu projeto e compartilháveis com sua equipe
Arquivos de subagent definem assistentes de IA especializados com prompts personalizados e permissões de ferramenta. Saiba mais sobre criação e uso de subagents na [documentação de subagents](/pt/sub-agents).
Configuração de plugin
Claude Code suporta um sistema de plugin que permite estender funcionalidade com skills, agents, hooks, e MCP servers. Plugins são distribuídos através de marketplaces e podem ser configurados em níveis de usuário e repositório.
Configurações de plugin
Configurações relacionadas a plugin em `settings.json`:
```json theme={null}
{
"enabledPlugins": {
"formatter@acme-tools": true,
"deployer@acme-tools": true,
"analyzer@security-plugins": false
},
"extraKnownMarketplaces": {
"acme-tools": {
"source": {
"source": "github",
"repo": "acme-corp/claude-plugins"
}
}
}
}
```
`enabledPlugins`
Controla quais plugins estão habilitados. Formato: `"plugin-name@marketplace-name": true/false`. Um plugin sem entrada em nenhum escopo volta ao seu valor [`defaultEnabled`](/pt/plugins-reference#default-enablement).
**Escopos**:
* **Configurações de usuário** (`~/.claude/settings.json`): Preferências pessoais de plugin
* **Configurações de projeto** (`.claude/settings.json`): Plugins específicos do projeto compartilhados com equipe
* **Configurações locais** (`.claude/settings.local.json`): Substituições por máquina, gitignored quando Claude Code as cria
* **Configurações gerenciadas** (`managed-settings.json`): Substituições de política em toda a organização que bloqueiam instalação em todos os escopos e ocultam o plugin do marketplace
As configurações de projeto têm precedência sobre as configurações de usuário, portanto, definir um plugin como `false` em `~/.claude/settings.json` não desabilita um plugin que o `.claude/settings.json` do projeto habilita. Para optar por não usar um plugin habilitado pelo projeto em sua máquina, defina-o como `false` em `.claude/settings.local.json` em vez disso.
Plugins forçadamente habilitados por configurações gerenciadas não podem ser desabilitados desta forma, pois as configurações gerenciadas substituem as configurações locais.
Habilitar um plugin de uma fonte externa como um repositório GitHub ou pacote npm em um `.claude/settings.json` de projeto não o instala para outras pessoas. A partir de Claude Code v2.1.195, cada caminho que carrega plugins pede a cada usuário para [instalar e confiar no plugin](/pt/discover-plugins#configure-team-marketplaces) antes de executá-lo.
**Exemplo**:
```json theme={null}
{
"enabledPlugins": {
"code-formatter@team-tools": true,
"deployment-tools@team-tools": true,
"experimental-features@personal": false
}
}
```
Define marketplaces adicionais que devem ser disponibilizados para o repositório. Tipicamente usado em configurações em nível de repositório para garantir que membros da equipe tenham acesso a fontes de plugin necessárias.
**Quando um repositório inclui `extraKnownMarketplaces`**:
1. Membros da equipe são solicitados a instalar o marketplace quando confiam na pasta
2. Membros da equipe são então solicitados a instalar plugins daquele marketplace
3. Usuários podem pular marketplaces ou plugins indesejados (armazenados em configurações de usuário)
4. Instalação respeita limites de confiança e requer consentimento explícito
**Exemplo**:
```json theme={null}
{
"extraKnownMarketplaces": {
"acme-tools": {
"source": {
"source": "github",
"repo": "acme-corp/claude-plugins"
}
},
"security-plugins": {
"source": {
"source": "git",
"url": "https://git.example.com/security/plugins.git"
}
}
}
}
```
**Tipos de fonte de marketplace**:
* `github`: Repositório GitHub (usa `repo`)
* `git`: Qualquer URL git (usa `url`)
* `directory`: Caminho do sistema de arquivos local (usa `path`, apenas para desenvolvimento)
* `hostPattern`: Padrão regex para corresponder hosts de marketplace (usa `hostPattern`)
* `settings`: marketplace inline declarado diretamente em settings.json sem um repositório hospedado separado (usa `name` e `plugins`)
O tipo de fonte `git` funciona com qualquer serviço de hospedagem git, incluindo GitLab auto-hospedado e Bitbucket. Claude Code clona o repositório com a mesma autenticação que `git clone` usaria naquela máquina: assistentes de credencial configurados, chaves SSH, ou uma variável de ambiente de token específica do host. Veja [Repositórios privados](/pt/plugin-marketplaces#private-repositories) para detalhes de configuração.
Para fontes `github` e `git`, defina `"skipLfs": true` dentro do objeto `source` (junto com `repo` ou `url`) para pular downloads de Git LFS quando Claude Code clona ou atualiza o repositório de marketplace. Arquivos de ponteiro LFS permanecem como ponteiros em vez de baixar seu conteúdo. Use isto quando o repositório contém objetos LFS grandes não relacionados ao conteúdo de plugin. {/* min-version: 2.1.153 */}Requer Claude Code v2.1.153 ou posterior.
Cada entrada de marketplace também aceita um Boolean `autoUpdate` opcional. Defina `"autoUpdate": true` junto com `source` para fazer Claude Code atualizar aquele marketplace e atualizar seus plugins instalados na inicialização. Quando omitido, marketplaces oficiais da Anthropic padrão para `true` e todos os outros marketplaces padrão para `false`. Veja [Configurar auto-atualizações](/pt/discover-plugins#configure-auto-updates).
Use `source: 'settings'` para declarar um pequeno conjunto de plugins inline sem configurar um repositório de marketplace hospedado. Plugins listados aqui devem referenciar fontes externas como GitHub ou npm. Você ainda precisa habilitar cada plugin separadamente em `enabledPlugins`.
```json theme={null}
{
"extraKnownMarketplaces": {
"team-tools": {
"source": {
"source": "settings",
"name": "team-tools",
"plugins": [
{
"name": "code-formatter",
"source": {
"source": "github",
"repo": "acme-corp/code-formatter"
}
}
]
}
}
}
}
```
`strictKnownMarketplaces`
**Apenas configurações gerenciadas**: Controla quais marketplaces de plugin os usuários podem adicionar e instalar plugins. Esta configuração pode ser configurada apenas em [configurações gerenciadas](/pt/settings#settings-files) e fornece aos administradores controle rigoroso sobre fontes de marketplace.
**Localizações de arquivo de configurações gerenciadas**:
* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`
* **Linux e WSL**: `/etc/claude-code/managed-settings.json`
* **Windows**: `C:\Program Files\ClaudeCode\managed-settings.json`
**Características principais**:
* Apenas disponível em configurações gerenciadas (`managed-settings.json`)
* Não pode ser substituída por configurações de usuário ou projeto (precedência mais alta)
* Aplicada antes de operações de rede e sistema de arquivos, portanto fontes bloqueadas nunca executam
* Usa correspondência exata para especificações de fonte (incluindo `ref`, `path` para fontes git), exceto `hostPattern` e `pathPattern`, que usam correspondência regex
**Comportamento de lista de permissões**:
* `undefined` (padrão): sem restrições, portanto usuários podem adicionar qualquer marketplace
* Array vazio `[]`: bloqueio completo, portanto usuários não podem adicionar novos marketplaces
* Lista de fontes: usuários podem apenas adicionar marketplaces que correspondem exatamente
**Todos os tipos de fonte suportados**:
A lista de permissões suporta múltiplos tipos de fonte de marketplace. A maioria das fontes usa correspondência exata, enquanto `hostPattern` e `pathPattern` usam correspondência regex contra o host do marketplace e caminho do sistema de arquivos respectivamente.
1. **Repositórios GitHub**:
```json theme={null}
{ "source": "github", "repo": "acme-corp/approved-plugins" }
{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }
```
Campos: `repo` (obrigatório), `ref` (opcional: branch ou tag), `path` (opcional: subdiretório)
2. **Repositórios Git**:
```json theme={null}
{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }
```
Campos: `url` (obrigatório), `ref` (opcional: branch ou tag), `path` (opcional: subdiretório)
3. **Marketplaces baseados em URL**:
```json theme={null}
{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }
```
Campos: `url` (obrigatório), `headers` (opcional: cabeçalhos HTTP para acesso autenticado)
Marketplaces baseados em URL apenas baixam o arquivo `marketplace.json`. Eles não baixam arquivos de plugin do servidor. Plugins em marketplaces baseados em URL devem usar fontes externas (URLs GitHub, npm, ou git) em vez de caminhos relativos. Para plugins com caminhos relativos, use um marketplace baseado em Git em vez disso. Veja [Troubleshooting](/pt/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces) para detalhes.
4. **Pacotes NPM**:
```json theme={null}
{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }
```
Campos: `package` (obrigatório, suporta pacotes com escopo)
5. **Caminhos de arquivo**:
```json theme={null}
{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }
```
Campos: `path` (obrigatório: caminho absoluto para arquivo marketplace.json)
6. **Caminhos de diretório**:
```json theme={null}
{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }
```
Campos: `path` (obrigatório: caminho absoluto para diretório contendo `.claude-plugin/marketplace.json`)
7. **Correspondência de padrão de host**:
```json theme={null}
{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }
```
Campos: `hostPattern` (obrigatório: padrão regex para corresponder contra o host do marketplace)
Use correspondência de padrão de host quando você deseja permitir todos os marketplaces de um host específico sem enumerar cada repositório individualmente. Isto é útil para organizações com GitHub Enterprise interno ou servidores GitLab onde desenvolvedores criam seus próprios marketplaces.
Extração de host por tipo de fonte:
* `github`: sempre corresponde contra `github.com`
* `git`: extrai nome de host da URL (suporta formatos HTTPS e SSH)
* `url`: extrai nome de host da URL
* `npm`, `file`, `directory`: não suportado para correspondência de padrão de host
8. **Correspondência de padrão de caminho**:
```json theme={null}
{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
{ "source": "pathPattern", "pathPattern": ".*" }
```
Campos: `pathPattern` (obrigatório: padrão regex correspondido contra o campo `path` de fontes `file` e `directory`)
Use correspondência de padrão de caminho para permitir marketplaces baseados em sistema de arquivos junto com restrições `hostPattern` para fontes de rede. Defina `".*"` para permitir todos os caminhos locais, ou um padrão mais estreito para restringir a diretórios específicos.
**Exemplos de configuração**:
Exemplo: permitir apenas marketplaces específicos:
```json theme={null}
{
"strictKnownMarketplaces": [
{
"source": "github",
"repo": "acme-corp/approved-plugins"
},
{
"source": "github",
"repo": "acme-corp/security-tools",
"ref": "v2.0"
},
{
"source": "url",
"url": "https://plugins.example.com/marketplace.json"
},
{
"source": "npm",
"package": "@acme-corp/compliance-plugins"
}
]
}
```
Exemplo: desabilitar todas as adições de marketplace:
```json theme={null}
{
"strictKnownMarketplaces": []
}
```
Exemplo: permitir todos os marketplaces de um servidor git interno:
```json theme={null}
{
"strictKnownMarketplaces": [
{
"source": "hostPattern",
"hostPattern": "^github\\.example\\.com$"
}
]
}
```
**Requisitos de correspondência exata**:
Fontes de marketplace devem corresponder exatamente para que a adição de um usuário seja permitida. Para fontes baseadas em git (`github` e `git`), isto inclui todos os campos opcionais:
* O `repo` ou `url` deve corresponder exatamente
* O campo `ref` deve corresponder exatamente (ou ambos serem indefinidos)
* O campo `path` deve corresponder exatamente (ou ambos serem indefinidos)
Exemplos de fontes que não correspondem:
```json theme={null}
// Estas são DIFERENTES fontes:
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }
// Estas também são DIFERENTES:
{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
{ "source": "github", "repo": "acme-corp/plugins" }
```
**Comparação com `extraKnownMarketplaces`**:
| Aspecto | `strictKnownMarketplaces` | `extraKnownMarketplaces` |
| --------------------------- | ---------------------------------------------- | ------------------------------------------------ |
| **Propósito** | Aplicação de política organizacional | Conveniência da equipe |
| **Arquivo de configuração** | Apenas `managed-settings.json` | Qualquer arquivo de configuração |
| **Comportamento** | Bloqueia adições não permitidas | Auto-instala marketplaces faltantes |
| **Quando aplicado** | Antes de operações de rede/sistema de arquivos | Após prompt de confiança do usuário |
| **Pode ser substituído** | Não (precedência mais alta) | Sim (por configurações de precedência mais alta) |
| **Formato de fonte** | Objeto de fonte direto | Marketplace nomeado com fonte aninhada |
| **Caso de uso** | Conformidade, restrições de segurança | Onboarding, padronização |
**Diferença de formato**:
`strictKnownMarketplaces` usa objetos de fonte diretos:
```json theme={null}
{
"strictKnownMarketplaces": [
{ "source": "github", "repo": "acme-corp/plugins" }
]
}
```
`extraKnownMarketplaces` requer marketplaces nomeados:
```json theme={null}
{
"extraKnownMarketplaces": {
"acme-tools": {
"source": { "source": "github", "repo": "acme-corp/plugins" }
}
}
}
```
**Usando ambos juntos**:
`strictKnownMarketplaces` é um portão de política: controla o que os usuários podem adicionar mas não registra nenhum marketplace. Para restringir e pré-registrar um marketplace para todos os usuários, defina ambos em `managed-settings.json`:
```json theme={null}
{
"strictKnownMarketplaces": [
{ "source": "github", "repo": "acme-corp/plugins" }
],
"extraKnownMarketplaces": {
"acme-tools": {
"source": { "source": "github", "repo": "acme-corp/plugins" }
}
}
}
```
Com apenas `strictKnownMarketplaces` definido, usuários ainda podem adicionar o marketplace permitido manualmente via `/plugin marketplace add`, mas não está disponível automaticamente.
**Notas importantes**:
* Restrições são verificadas antes de qualquer solicitação de rede ou operação de sistema de arquivos
* Quando bloqueado, usuários veem mensagens de erro claras indicando que a fonte é bloqueada por política gerenciada
* A restrição é aplicada em adição de marketplace e em instalação, atualização, atualização e auto-atualização de plugin. Um marketplace adicionado antes da política ser definida não pode ser usado para instalar ou atualizar plugins uma vez que sua fonte não corresponde mais à lista de permissões
* Configurações gerenciadas têm a precedência mais alta e não podem ser substituídas
Veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions) para documentação voltada para o usuário.
`strictPluginOnlyCustomization`
**Apenas configurações gerenciadas**: bloqueia skills, agents, hooks, e MCP servers de fontes de usuário e projeto, para que possam vir apenas de plugins ou configurações gerenciadas. Combine com `strictKnownMarketplaces` para controlar a cadeia de suprimento de personalização completa: a lista de permissões de marketplace controla quais plugins os usuários podem instalar, e esta configuração bloqueia tudo que não vem de um plugin ou de configurações gerenciadas.
`strictPluginOnlyCustomization` requer Claude Code v2.1.82 ou posterior. Versões anteriores ignoram a chave e continuam carregando personalizações de usuário e projeto, portanto o bloqueio não é aplicado até que os clientes atualizem.
O valor é `true` para bloquear todas as quatro superfícies, ou um array nomeando as superfícies a bloquear:
```json theme={null}
{
"strictPluginOnlyCustomization": ["skills", "hooks"]
}
```
Para cada superfície bloqueada, Claude Code pula fontes de nível de usuário e projeto e carrega apenas fontes fornecidas por plugin e gerenciadas:
| Superfície | Bloqueado quando bloqueado | Ainda carrega |
| :--------- | :--------------------------------------------------- | :------------------------------------------------------------------------------ |
| `skills` | `~/.claude/skills/`, `.claude/skills/` | Skills de plugin, skills agrupadas, skills no diretório de política gerenciada |
| `agents` | `~/.claude/agents/`, `.claude/agents/` | Agents de plugin, agents integrados, agents no diretório de política gerenciada |
| `hooks` | Hooks em `settings.json` de usuário, projeto e local | Hooks de plugin, hooks em configurações gerenciadas |
| `mcp` | Servidores em `~/.claude.json` e `.mcp.json` | MCP servers de plugin, servidores [`managed-mcp.json`](/pt/managed-mcp) |
Nomes de superfície que uma versão de Claude Code não reconhece são ignorados em vez de falhar no arquivo de configurações, portanto você pode adicionar novos nomes de superfície antes que todos os clientes tenham atualizado.
Gerenciando plugins
Use o comando `/plugin` para gerenciar plugins interativamente:
* Procurar plugins disponíveis de marketplaces
* Instalar/desinstalar plugins
* Habilitar/desabilitar plugins
* Ver detalhes de plugin (skills, agents, hooks fornecidos)
* Adicionar/remover marketplaces
Saiba mais sobre o sistema de plugin na [documentação de plugins](/pt/plugins).
Variáveis de ambiente
Variáveis de ambiente permitem controlar o comportamento do Claude Code sem editar arquivos de configuração. Qualquer variável também pode ser configurada em [`settings.json`](#available-settings) sob a chave `env` para aplicá-la a cada sessão ou implantá-la para sua equipe.
Veja a [referência de variáveis de ambiente](/pt/env-vars) para a lista completa.
O Claude Code tem acesso a um conjunto de ferramentas para leitura, edição, busca, execução de comandos, e orquestração de subagents. Nomes de ferramenta são as strings exatas que você usa em regras de permissão e correspondedores de hook.
Veja a [referência de ferramentas](/pt/tools-reference) para a lista completa e detalhes de comportamento da ferramenta Bash.
Veja também
* [Permissões](/pt/permissions): sistema de permissões, sintaxe de regra, padrões específicos de ferramenta, e políticas gerenciadas
* [Autenticação](/pt/authentication): configurar acesso de usuário ao Claude Code
* [Depurar sua configuração](/pt/debug-your-config): diagnosticar por que uma configuração, hook, ou servidor MCP não está tendo efeito
* [Solucionar problemas de instalação e login](/pt/troubleshoot-install): problemas de instalação, autenticação e plataforma