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 ao usar o REPL interativo, que abre uma interface de Configurações com abas onde você pode visualizar informações de status e modificar opções de configuração.

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

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 é definida em vários escopos, escopos mais específicos têm precedência:

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 uma permissão é permitida nas configurações do usuário, mas negada nas configurações do projeto, a configuração do projeto tem precedência e a permissão é bloqueada.

O que usa escopos

Os escopos se aplicam a muitos recursos do Claude Code:

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

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

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

A linha $schema no exemplo acima aponta para o esquema JSON oficial 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.

Configurações disponíveis

settings.json suporta várias opções:

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.

Configurações de worktrees

Configure como --worktree cria e gerencia git worktrees.

Para copiar arquivos ignorados pelo git como .env em novos worktrees, use um arquivo .worktreeinclude na raiz do seu projeto em vez de uma configuração.

Configurações de permissão

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

Exemplos rápidos:

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.

Configurações de sandbox

Configure comportamento avançado de sandboxing. Sandboxing isola comandos bash do seu sistema de arquivos e rede. Veja Sandboxing para detalhes.

Prefixos de caminho de sandbox

Caminhos em filesystem.allowWrite, filesystem.denyWrite, filesystem.denyRead, e filesystem.allowRead suportam estes prefixos:

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

{
  "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 (como Co-Authored-By) por padrão, que podem ser personalizados ou desabilitados
• Descrições de pull request são texto simples

Atribuição de commit padrão:

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

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

Atribuição de pull request padrão:

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

Exemplo:

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

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.

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

O comando executa com as mesmas variáveis de ambiente que hooks, incluindo CLAUDE_PROJECT_DIR. Recebe JSON via stdin com um campo query:

{"query": "src/comp"}

Produz caminhos de arquivo separados por nova linha para stdout (atualmente limitado a 15):

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

Exemplo:

#!/bin/bash
query=$(cat | jq -r '.query')
your-repo-file-index --query "$query" | head -20

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

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

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

A configuração aceita estas chaves:

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:

{
  "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, 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, a precedência é: gerenciadas pelo servidor > 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. Dentro da camada baseada em arquivo, arquivos drop-in e o arquivo base são mesclados juntos.

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

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, ou de um IDE JetBrains.

Por exemplo, se suas configurações de usuário permitem Bash(npm run *) mas as configurações compartilhadas de um projeto negam, a configuração do projeto tem precedência e o comando é bloqueado.

Verificar configurações ativas

Execute /status dentro do Claude Code para ver quais fontes de configuração estão ativas e de onde vêm. A saída mostra cada camada de configuração (gerenciada, usuário, projeto) junto com sua origem, como Enterprise managed settings (remote), Enterprise managed settings (plist), Enterprise managed settings (HKLM), Enterprise managed settings (HKCU), ou Enterprise managed settings (file). Se um arquivo de configuração contém erros, /status relata o problema para que você possa corrigi-lo.

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, com configurações mais específicas adicionando ou substituindo as mais amplas

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:

{
  "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 podem ser compartilhados 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.

Configuração de plugin

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

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

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 (não confirmadas)
• 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

Exemplo:

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

extraKnownMarketplaces

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:

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

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.

{
  "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 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/sistema de arquivos (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 - 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

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:

{ "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/tag/SHA), path (opcional: subdiretório)

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

Campos: url (obrigatório), ref (opcional: branch/tag/SHA), path (opcional: subdiretório)

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

Campos: url (obrigatório), headers (opcional: cabeçalhos HTTP para acesso autenticado)

4. Pacotes NPM:

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

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

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

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

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

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

{
  "strictKnownMarketplaces": []
}

Exemplo: permitir todos os marketplaces de um servidor git interno:

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

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

Diferença de formato:

strictKnownMarketplaces usa objetos de fonte diretos:

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

extraKnownMarketplaces requer marketplaces nomeados:

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

{
  "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 para documentação voltada para o usuário.

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.

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 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 para a lista completa.

Ferramentas disponíveis para Claude

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 para a lista completa e detalhes de comportamento da ferramenta Bash.

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