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, MCP servers)
• 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. Gerenciado (mais alto) - não pode ser substituído 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. Projeto - substitui configurações de usuário
5. Usuário (mais baixo) - se aplica quando nada mais especifica a configuração

​

O que usa escopos

​

Arquivos de configuração

• Configurações do usuário são definidas em ~/.claude/settings.json e se aplicam a todos os projetos.
• 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. O Claude Code configurará o git para ignorar .claude/settings.local.json quando for criado.
• 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 dos servidores da Anthropic através do console de administração do Claude.ai. Veja configurações gerenciadas pelo servidor.
  • Políticas MDM/nível do SO: entregues através do gerenciamento nativo de dispositivos no macOS e Windows:
    • macOS: domínio de preferências gerenciadas com.anthropic.claudecode (implantado através de perfis de configuração no Jamf, Kandji ou outras ferramentas MDM)
    • Windows: chave de registro HKLM\SOFTWARE\Policies\ClaudeCode com um valor Settings (REG_SZ ou REG_EXPAND_SZ) contendo JSON (implantado através de 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\
  Veja configurações gerenciadas e Configuração MCP gerenciada para detalhes.
  Implantações gerenciadas também podem restringir adições do 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 suas preferências (tema, configurações de notificação, modo de editor), 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. 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"
  ]
}

​

Configurações disponíveis

​

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"],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  }
}

• Configurações sandbox.filesystem (mostradas acima): Controlam caminhos no limite do sandbox em nível do 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

• 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

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

   Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

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

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <[email protected]>",
    "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')
your-repo-file-index --query "$query" | head -20

​

Configuração de hooks

• Hooks gerenciados e hooks SDK são carregados
• Hooks de usuário, hooks de projeto e hooks de plugin são bloqueados

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

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

​

Precedência de configurações

1. Configurações gerenciadas (gerenciadas pelo servidor, políticas MDM/nível do 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ção gerenciados
   • Não podem ser substituídas por configurações de usuário ou projeto
   • Dentro do nível gerenciado, a precedência é: gerenciadas pelo servidor > políticas MDM/nível do SO > managed-settings.json > registro HKCU (apenas Windows). Apenas uma fonte gerenciada é usada; fontes não são mescladas.
2. Argumentos de linha de comando
   • Substituições temporárias para uma sessão específica
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 do 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): Configuram permissões, variáveis de ambiente e comportamento de ferramenta
• Skills: Prompts personalizados que podem ser invocados com /skill-name ou carregados automaticamente pelo Claude
• MCP servers: Estendem Claude Code com ferramentas e integrações adicionais
• Precedência: Configurações de nível superior (Gerenciadas) substituem as de nível inferior (Usuário/Projeto)
• Herança: Configurações são mescladas, com configurações mais específicas adicionando ou substituindo as mais amplas

​

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 do seu projeto e podem ser compartilhados 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": "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 (não confirmadas)

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

​

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. Os usuários podem pular marketplaces ou plugins indesejados (armazenados em configurações de usuário)
4. A 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)

​

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

• Disponível apenas em configurações gerenciadas (managed-settings.json)
• Não pode ser substituído por configurações de usuário ou projeto (precedência mais alta)
• Aplicado ANTES de operações de rede/sistema de arquivos (fontes bloqueadas nunca executam)
• Usa correspondência exata para especificações de fonte (incluindo ref, path para fontes git), exceto hostPattern, que usa correspondência regex

• undefined (padrão): Sem restrições - usuários podem adicionar qualquer marketplace
• Array vazio []: Bloqueio completo - usuários não podem adicionar novos marketplaces
• Lista de fontes: Usuários podem adicionar apenas 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://[email protected]/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

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

• Restrições são verificadas ANTES de qualquer solicitação de rede ou operação de sistema de arquivos
• Quando bloqueado, os usuários veem mensagens de erro claras indicando que a fonte é bloqueada por política gerenciada
• A restrição se aplica apenas à adição de NOVOS marketplaces; marketplaces previamente instalados permanecem acessíveis
• Configurações gerenciadas têm a precedência mais alta e não podem ser substituídas

​

Gerenciando plugins

• Procure plugins disponíveis de marketplaces
• Instale/desinstale plugins
• Habilite/desabilite plugins
• Veja detalhes de plugin (comandos, agents, hooks fornecidos)
• Adicione/remova marketplaces

​

Variáveis de ambiente

​

Ferramentas disponíveis para Claude

​

Comportamento da ferramenta Bash

• Diretório de trabalho persiste: Quando Claude muda o diretório de trabalho (por exemplo, cd /path/to/dir), comandos Bash subsequentes serão executados naquele diretório. Você pode usar CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 para resetar ao diretório do projeto após cada comando.
• Variáveis de ambiente NÃO persistem: Variáveis de ambiente definidas em um comando Bash (por exemplo, export MY_VAR=value) não estão disponíveis em comandos Bash subsequentes. Cada comando Bash é executado em um ambiente shell fresco.

conda activate myenv
# ou: source /path/to/venv/bin/activate
claude

export CLAUDE_ENV_FILE=/path/to/env-setup.sh
claude

conda activate myenv
# ou: source /path/to/venv/bin/activate
# ou: export MY_VAR=value

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""
      }]
    }]
  }
}

​

Estendendo ferramentas com hooks

​

Veja também

• Permissões: sistema de permissões, sintaxe de regra, padrões específicos de ferramenta e políticas gerenciadas
• Autenticação: configure acesso de usuário ao Claude Code
• Troubleshooting: soluções para problemas de configuração comuns