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 com a 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. 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 arquivos managed-settings.json e managed-mcp.json que podem ser implantados em diretórios do sistema:
  • macOS: /Library/Application Support/ClaudeCode/
  • Linux e WSL: /etc/claude-code/
  • Windows: C:\Program Files\ClaudeCode\
  Estes são caminhos em nível de sistema (não diretórios home do usuário como ~/Library/...) que requerem privilégios de administrador. Eles são projetados para serem implantados por administradores de TI.
  Veja Configurações gerenciadas e Configuração MCP gerenciada para detalhes.
  As 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 do editor), sessão OAuth, configurações de servidor MCP para escopos de usuário e local, estado por projeto (ferramentas permitidas, configurações de confiança) e vários caches. Servidores MCP com escopo de projeto são armazenados separadamente em .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"
  },
  "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

​

Ordem de avaliação de regra

1. Regras de negação são verificadas primeiro
2. Regras de pergunta são verificadas segundo
3. Regras de permissão são verificadas por último

​

Correspondência de todos os usos de uma ferramenta

​

Usando especificadores para controle refinado

​

Padrões de wildcard

{
  "permissions": {
    "allow": [
      "Bash(npm run:*)",
      "Bash(git commit:*)",
      "Bash(docker compose:*)"
    ],
    "deny": [
      "Bash(git push:*)",
      "Bash(rm -rf:*)"
    ]
  }
}

{
  "permissions": {
    "allow": [
      "Bash(git * main)",
      "Bash(* --version)"
    ]
  }
}

​

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/**)"
    ]
  }
}

• Use regras de negação Read para bloquear Claude de ler arquivos ou diretórios específicos
• Use regras de permissão Edit para permitir que Claude escreva em diretórios além do diretório de trabalho atual
• Use regras de negação Edit para bloquear escritas em caminhos específicos
• Use regras de permissão/negação WebFetch para controlar quais domínios de rede Claude pode acessar

​

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.5 <[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, projeto e plugin são bloqueados

{
  "allowManagedHooksOnly": true
}

​

Precedência de configurações

1. Configurações gerenciadas (managed-settings.json)
   • Políticas implantadas por TI/DevOps em diretórios do sistema
   • Não podem ser substituídas por configurações de usuário ou projeto
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 com a equipe no controle de origem
5. Configurações do 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): Configuram permissões, variáveis de ambiente e comportamento de ferramentas
• Skills: Prompts personalizados que podem ser invocados com /skill-name ou carregados por Claude automaticamente
• Servidores MCP: Estendem Claude Code com ferramentas e integrações adicionais
• Precedência: Configurações de nível superior (Gerenciado) 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

​

Prompt do sistema

​

Excluindo arquivos sensíveis

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

​

Configuração de subagentos

• Subagentos de usuário: ~/.claude/agents/ - Disponíveis em todos os seus projetos
• Subagentos de projeto: .claude/agents/ - Específicos do seu projeto e podem ser compartilhados com sua equipe

​

Configuração de plugins

​

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

​

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)

• 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 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://[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" }

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

• 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, usuários veem mensagens de erro claras indicando que a fonte é bloqueada por política gerenciada
• A restrição se aplica apenas a adicionar 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
• Visualize detalhes de plugin (comandos, agentes, 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 executarão 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 executa em um ambiente de 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

• Gerenciamento de Identidade e Acesso - Visão geral do sistema de permissão e como regras allow/ask/deny interagem
• Regras de permissão específicas de ferramentas - Padrões detalhados para ferramentas Bash, Read, Edit, WebFetch, MCP e Task, incluindo limitações de segurança
• Configurações gerenciadas - Configuração de política gerenciada para organizações
• Solução de problemas - Soluções para problemas de configuração comuns