Configurações do Claude Code

​

Escopos de configuração

​

Escopos disponíveis

​

Quando usar cada escopo

• 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

• 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)

• Configurações compartilhadas pela equipe (permissões, hooks, servidores MCP)
• Plugins que toda a equipe deve ter
• Padronização de ferramentas entre colaboradores

• 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

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

​

O que usa escopos

​

Arquivos de configuração

• 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. Como este arquivo é seu em vez do repositório, suas regras de permissão allow entram em vigor sem a etapa de confiança do workspace que as regras allow de .claude/settings.json exigem. Se o repositório fornece o arquivo, por exemplo ao confirmá-lo, a confiança do workspace ainda se aplica.
• 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 auto-hospedado. Veja configurações gerenciadas pelo servidor.
  • 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 e Configuração MCP gerenciada para detalhes. Este repositório 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.
• Outra configuração é armazenada em ~/.claude.json. Este arquivo contém sua sessão OAuth, configurações de MCP server 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.

{
  "$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"
  ]
}

​

Quando as edições entram em vigor

• model: use /model para mudar no meio da sessão
• outputStyle: parte do prompt do sistema, que é reconstruído em /clear ou reinicialização

​

Entradas inválidas em configurações gerenciadas

• 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 lista cada entrada inválida com sua fonte e campo.

​

Configurações disponíveis

​

Configurações de config global

​

Configurações de worktrees

​

Configurações de permissão

​

Sintaxe de regra de permissão

​

Configurações de sandbox

​

Prefixos de caminho de sandbox

{
  "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
    }
  }
}

• 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 (uma regra deny Read também bloqueia a ferramenta Edit nos caminhos correspondentes), 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

• Commits usam git trailers (como Co-Authored-By) por padrão, que podem ser personalizados ou desabilitados
• Descrições de pull request são texto simples

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

​

Configurações de sugestão de arquivo

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

{"query": "src/comp"}

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

#!/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

​

Badges de link de rodapé

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

​

Configuração de hooks

• 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

{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}

​

Calcular configurações gerenciadas com um auxiliar de política

{
  "managedSettings": {
    "permissions": { "deny": ["Read(//etc/secrets/**)"] }
  },
  "claudeMd": "# Organization context\n...",
  "appendSystemPrompt": "Always cite the internal style guide."
}

​

Precedência de configurações

1. Configurações gerenciadas (gerenciadas pelo servidor, políticas de nível MDM/SO, ou configurações gerenciadas)
   • 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, apenas uma fonte é usada e as outras são ignoradas em vez de mescladas. Precedência, mais alta primeiro:
     • Saída policyHelper: quando configurada, esta é a única fonte gerenciada usada
     • Remota (configurações gerenciadas pelo servidor do claude.ai ou gateway de aplicativos Claude-entregues)
     • Políticas de nível MDM/SO
     • Baseada em arquivo (managed-settings.d/*.json e managed-settings.json, mescladas juntas)
     • Registro HKCU (apenas Windows)
   • Algumas chaves são exceções, honradas quando qualquer fonte gerenciada controlada por administrador as define em vez de apenas a fonte vencedora. A fonte de registro HKCU gravável pelo usuário é excluída. As chaves de exceção são:
     • as chaves de bloqueio de sandbox sandbox.network.allowManagedDomainsOnly e sandbox.filesystem.allowManagedReadPathsOnly, com suas listas de permissões associadas
     • allowAllClaudeAiMcps
     • os caminhos binários de sandbox sandbox.bwrapPath e sandbox.socatPath
     • forceRemoteSettingsRefresh
   • 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 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 <file-or-json> 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

​

Verificar configurações ativas

​

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

​

Prompt do sistema

​

Excluindo arquivos sensíveis

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

​

Configuração de subagent

• 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

​

Configuração de plugin

​

Configurações de plugin

{
  "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

• 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

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}

​

pluginConfigs

{
  "pluginConfigs": {
    "deployer@acme-tools": {
      "options": {
        "api_endpoint": "https://api.example.com"
      }
    }
  }
}

​

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

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/security/plugins.git"
      }
    }
  }
}

• 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)

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "settings",
        "name": "team-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": {
              "source": "github",
              "repo": "acme-corp/code-formatter"
            }
          }
        ]
      }
    }
  }
}

​

strictKnownMarketplaces

• 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

• 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

• 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

1. Repositórios GitHub:

{ "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" }

2. Repositórios Git:

{ "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" }

3. Marketplaces baseados em URL:

{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }

4. Pacotes NPM:

{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }

5. Caminhos de arquivo:

{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

6. Caminhos de diretório:

{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

7. Correspondência de padrão de host:

{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }

• 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:

{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
{ "source": "pathPattern", "pathPattern": ".*" }

{
  "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"
    }
  ]
}

{
  "strictKnownMarketplaces": []
}

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

• 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)

// 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" }

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ]
}

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ],
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

• 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

​

strictPluginOnlyCustomization

{
  "strictPluginOnlyCustomization": ["skills", "hooks"]
}

​

Gerenciando plugins

• Procurar plugins disponíveis de marketplaces
• Instalar/desinstalar plugins
• Habilitar/desabilitar plugins
• Ver detalhes de plugin (skills, agents, hooks fornecidos)
• Adicionar/remover marketplaces

​

Variáveis de ambiente

​

Ferramentas disponíveis para Claude

​

Veja também

• Permissões: sistema de permissões, sintaxe de regra, padrões específicos de ferramenta, e políticas gerenciadas
• Autenticação: configurar acesso de usuário ao Claude Code
• Depurar sua configuração: diagnosticar por que uma configuração, hook, ou servidor MCP não está tendo efeito
• Solucionar problemas de instalação e login: problemas de instalação, autenticação e plataforma