Configurações do Claude Code

​

Arquivos de configuração

• Configurações de usuário são definidas em ~/.claude/settings.json e se aplicam a todos os projetos.
• Configurações de projeto são salvas no diretório do seu projeto:
  • .claude/settings.json para configurações que são verificadas no controle de versão 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. Claude Code configurará o git para ignorar .claude/settings.local.json quando for criado.
• Para implantações empresariais do Claude Code, também oferecemos suporte a configurações de política gerenciada pela empresa. Estas têm precedência sobre as configurações de usuário e projeto. Administradores de sistema podem implantar políticas em:
  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux e WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\ProgramData\ClaudeCode\managed-settings.json
• Implantações empresariais também podem configurar servidores MCP gerenciados que substituem servidores configurados pelo usuário. Veja Configuração MCP empresarial:
  • macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
  • Linux e WSL: /etc/claude-code/managed-mcp.json
  • Windows: C:\ProgramData\ClaudeCode\managed-mcp.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"
  }
}

​

Configurações disponíveis

​

Configurações de permissão

​

Configurações de sandbox

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)"
    ]
  }
}

• Regras de negação Read bloqueiam leituras de arquivo no sandbox
• Regras de permissão Edit permitem escritas de arquivo (além dos padrões, por exemplo, o diretório de trabalho atual)
• Regras de negação Edit bloqueiam escritas dentro de caminhos permitidos

• Regras de permissão WebFetch permitem domínios de rede
• Regras de negação WebFetch bloqueiam domínios de rede

​

Precedência de configurações

1. Políticas gerenciadas pela empresa (managed-settings.json)
   • Implantadas por TI/DevOps
   • Não podem ser substituídas
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 compartilhado (.claude/settings.json)
   • Configurações de projeto compartilhadas com a equipe no controle de versão
5. Configurações de usuário (~/.claude/settings.json)
   • Configurações globais pessoais

​

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): Configure permissões, variáveis de ambiente e comportamento de ferramentas
• Comandos de barra: Comandos personalizados que podem ser invocados durante uma sessão com /command-name
• Servidores MCP: Estenda Claude Code com ferramentas e integrações adicionais
• Precedência: Configurações de nível superior (Empresa) substituem as de nível inferior (Usuário/Projeto)
• Herança: As configurações são mescladas, com configurações mais específicas adicionando ou substituindo as mais amplas

​

Disponibilidade de prompt do sistema

​

Excluindo arquivos sensíveis

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

​

Configuração de subagente

• Subagentes de usuário: ~/.claude/agents/ - Disponíveis em todos os seus projetos
• Subagentes 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@company-tools": true,
    "deployer@company-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": "github",
      "repo": "company/claude-plugins"
    }
  }
}

​

enabledPlugins

• Configurações de usuário (~/.claude/settings.json): Preferências de plugin pessoais
• Configurações de projeto (.claude/settings.json): Plugins específicos do projeto compartilhados com a 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. Os membros da equipe são solicitados a instalar o marketplace quando confiam na pasta
2. Os membros da equipe são então solicitados a instalar plugins desse 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": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "company-org/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.company.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)

​

Gerenciando plugins

• Procurar plugins disponíveis de marketplaces
• Instalar/desinstalar plugins
• Habilitar/desabilitar plugins
• Visualizar detalhes do plugin (comandos, agentes, hooks fornecidos)
• Adicionar/remover marketplaces

​

Variáveis de ambiente

​

Ferramentas disponíveis para Claude

​

Estendendo ferramentas com hooks

​

Veja também

• Identidade e Gerenciamento de Acesso - Saiba mais sobre o sistema de permissões do Claude Code
• IAM e controle de acesso - Gerenciamento de políticas empresariais
• Solução de problemas - Soluções para problemas comuns de configuração