SpyBara
Go Premium

permissions.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

82 added, 10 removed.

2026
Mon 29 21:00 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Configurar permissões

Controle o que Claude Code pode acessar e fazer com regras de permissão refinadas, modos e políticas gerenciadas.

Claude Code suporta permissões refinadas para que você possa especificar exatamente o que o agente pode fazer e o que não pode. As configurações de permissão podem ser verificadas no controle de versão e distribuídas para todos os desenvolvedores da sua organização, bem como personalizadas por desenvolvedores individuais.

Sistema de permissões

Claude Code usa um sistema de permissões em camadas para equilibrar poder e segurança:

Tipo de ferramenta Exemplo Aprovação necessária Comportamento de "Sim, não pergunte novamente"
Somente leitura Leitura de arquivos, Grep Não N/A
Comandos Bash Execução de shell Sim Permanentemente por diretório de projeto e comando
Modificação de arquivo Edit/Write de arquivos Sim Até o final da sessão

Gerenciar permissões

Você pode visualizar e gerenciar as permissões de ferramentas do Claude Code com /permissions. Esta interface lista todas as regras de permissão e o arquivo settings.json do qual são originadas.

  • As regras Allow permitem que Claude Code use a ferramenta especificada sem aprovação manual.
  • As regras Ask solicitam confirmação sempre que Claude Code tenta usar a ferramenta especificada.
  • As regras Deny impedem que Claude Code use a ferramenta especificada.

As regras são avaliadas em ordem: deny, depois ask, depois allow. A primeira correspondência nessa ordem determina o resultado, e a especificidade da regra não altera a ordem. Uma regra deny ampla como Bash(aws *) bloqueia cada chamada correspondente, incluindo chamadas que também correspondem a uma regra allow mais estreita como Bash(aws s3 ls), portanto uma regra deny não pode carregar exceções de lista de permissões. A mesma precedência se aplica entre ask e allow: uma regra ask correspondente solicita confirmação mesmo quando uma regra allow mais específica também corresponde à mesma chamada.

As regras deny se comportam de forma diferente dependendo se nomeiam uma ferramenta ou definem o escopo de um padrão dentro de uma. Um nome de ferramenta simples como Bash remove a ferramenta do contexto do Claude completamente, então Claude nunca a vê. Uma regra com escopo como Bash(rm *) deixa a ferramenta disponível e bloqueia chamadas correspondentes quando Claude tenta usá-las.

Modos de permissão

Claude Code suporta vários modos de permissão que controlam como as ferramentas são aprovadas. Veja Permission modes para quando usar cada um. Defina o defaultMode em seus arquivos de configuração:

Modo Descrição
default Comportamento padrão: solicita permissão no primeiro uso de cada ferramenta
acceptEdits Aceita automaticamente edições de arquivo e comandos comuns do sistema de arquivos (mkdir, touch, mv, cp, etc.) para caminhos no diretório de trabalho ou additionalDirectories
plan Plan Mode: Claude lê arquivos e executa comandos shell somente leitura para explorar, mas não edita seus arquivos de origem
auto Aprova automaticamente chamadas de ferramentas com verificações de segurança em segundo plano que verificam se as ações se alinham com sua solicitação. Atualmente uma visualização de pesquisa
dontAsk Nega automaticamente ferramentas a menos que pré-aprovadas via /permissions ou regras permissions.allow
bypassPermissions Ignora prompts de permissão, exceto aqueles forçados por regras ask explícitas. Remoções de diretório raiz e diretório inicial como rm -rf / também ainda solicitam como um disjuntor

Para evitar que o modo bypassPermissions ou auto seja usado, defina permissions.disableBypassPermissionsMode ou permissions.disableAutoMode como "disable" em qualquer arquivo de configuração. Estes são mais úteis em configurações gerenciadas onde não podem ser substituídos.

Sintaxe de regra de permissão

As regras de permissão seguem o formato Tool ou Tool(specifier).

Corresponder todos os usos de uma ferramenta

Para corresponder todos os usos de uma ferramenta, use apenas o nome da ferramenta sem parênteses:

Regra Efeito
Bash Corresponde a todos os comandos Bash
WebFetch Corresponde a todas as solicitações de busca na web
Read Corresponde a todas as leituras de arquivo

Bash(*) é equivalente a Bash e corresponde a todos os comandos Bash. Como uma regra de negação, ambas as formas removem a ferramenta do contexto do Claude.

Use especificadores para controle refinado

Adicione um especificador entre parênteses para corresponder a usos específicos de ferramentas:

Regra Efeito
Bash(npm run build) Corresponde ao comando exato npm run build
Read(./.env) Corresponde à leitura do arquivo .env no diretório atual
WebFetch(domain:example.com) Corresponde a solicitações de busca para example.com

Corresponder por parâmetro de entrada

As regras de negação e pergunta podem corresponder a um parâmetro de entrada de nível superior em qualquer ferramenta com Tool(param:value). A regra corresponde quando Claude chama a ferramenta com esse parâmetro definido para esse valor exato. Esta sintaxe é para regras de negação e pergunta; uma regra de permissão para um valor de parâmetro não estabeleceria que a chamada é segura em geral, portanto as regras de permissão continuam a usar a sintaxe de especificador própria de cada ferramenta. Isso funciona para qualquer parâmetro escalar que a ferramenta aceita:

Regra Corresponde
Agent(model:opus) Chamadas de Agent que solicitam o nível de modelo Opus
Agent(isolation:worktree) Chamadas de Agent que solicitam um git worktree
Bash(run_in_background:true) Chamadas Bash que executam em segundo plano

A correspondência de parâmetros segue estas regras:

  • O nome do parâmetro deve ser um campo direto da entrada da ferramenta, como model na ferramenta Agent. Campos aninhados dentro de um objeto ou array não são correspondíveis
  • Cada regra nomeia um parâmetro. Para controlar tanto model quanto isolation, escreva duas regras, Agent(model:opus) e Agent(isolation:worktree), em vez de combiná-las em uma regra
  • O valor suporta * como um caractere curinga que corresponde a qualquer sequência de caracteres, portanto Agent(isolation:*) corresponde a qualquer valor de isolamento explícito. Sem * a correspondência é exata
  • Um parâmetro que o modelo omite nunca é correspondido, portanto Agent(model:*) não corresponde a uma chamada que deixa model não definido
  • O valor é comparado com a entrada literal que Claude envia, antes de qualquer normalização. Agent(model:opus) corresponde ao alias opus mas não a um ID de modelo completo. Execute com --verbose para ver os nomes e valores exatos dos parâmetros em cada chamada de ferramenta
  • O espaço em branco ao redor do dois-pontos é ignorado

Campos que uma ferramenta já corresponde com suas próprias regras de canonicalização não são correspondíveis desta forma: command para Bash e PowerShell, file_path para Read, Edit e Write, path para Grep e Glob, notebook_path para NotebookEdit, e url para WebFetch. Uma regra como Bash(command:rm *) seria contornável por um comando composto, portanto Claude Code a ignora e emite um aviso de inicialização. Use Bash(rm *), Read(./path) ou WebFetch(domain:host) em vez disso.

Padrões com caracteres curinga

As regras Bash suportam padrões glob com *. Caracteres curinga podem aparecer em qualquer posição no comando. Esta configuração permite comandos npm e git commit enquanto bloqueia git push:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git * main)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

O espaço antes de * importa: Bash(ls *) corresponde a ls -la mas não a lsof, enquanto Bash(ls*) corresponde a ambos. O sufixo :* é uma maneira equivalente de escrever um caractere curinga à direita, portanto Bash(ls:*) corresponde aos mesmos comandos que Bash(ls *).

O diálogo de permissão escreve a forma separada por espaço quando você seleciona "Sim, não pergunte novamente" para um prefixo de comando. A forma :* é reconhecida apenas no final de um padrão. Em um padrão como Bash(git:* push), o dois-pontos é tratado como um caractere literal e não corresponderá a comandos git.

Caracteres curinga no nome da ferramenta

As regras de negação e pergunta também aceitam padrões glob na posição do nome da ferramenta. O padrão deve corresponder ao nome completo da ferramenta: "*" corresponde a todas as ferramentas, e "mcp__*" corresponde a todas as ferramentas MCP em todos os servidores. Uma ferramenta correspondida por uma regra de negação glob com nome simples é removida do contexto do Claude, o mesmo que um nome de ferramenta simples. Esta configuração nega todas as ferramentas MCP:

{
  "permissions": {
    "deny": [
      "mcp__*"
    ]
  }
}

As regras de permissão aceitam globs de nome de ferramenta apenas após um prefixo literal mcp__<server>__. O segmento do servidor deve estar livre de glob para que a regra nomeie um servidor específico que você configurou. mcp__puppeteer__* corresponde a todas as ferramentas do servidor puppeteer, e mcp__github__get_* corresponde às suas ferramentas get_. Um glob de permissão desancorado como "*", "B*" ou "mcp__*" é ignorado com um aviso e não aprova automaticamente nada.

Uma regra de negação ou pergunta cujo nome de ferramenta não corresponde a nenhuma ferramenta conhecida produz um aviso de inicialização para detectar erros de digitação. Nomes de ferramentas contendo _ ou * estão isentos da verificação.

O rótulo mostrado para uma ferramenta na transcrição e diálogo de permissão pode diferir do seu nome canônico. Por exemplo, a ferramenta rotulada Stop Task na transcrição tem o nome canônico TaskStop. As regras de permissão e correspondências de hook correspondem apenas ao nome canônico, portanto uma regra escrita como Stop Task não corresponde. Para regras de negação e pergunta, o aviso de inicialização acima detecta a incompatibilidade. Use os nomes canônicos listados na referência de ferramentas.

Regras de permissão específicas da ferramenta

Bash

As regras de permissão Bash suportam correspondência com caracteres curinga *. Caracteres curinga podem aparecer em qualquer posição no comando, incluindo no início, meio ou fim:

  • Bash(npm run build) corresponde ao comando Bash exato npm run build
  • Bash(npm run test *) corresponde a comandos Bash começando com npm run test
  • Bash(npm *) corresponde a qualquer comando começando com npm
  • Bash(* install) corresponde a qualquer comando terminando com install
  • Bash(git * main) corresponde a comandos como git checkout main e git log --oneline main

Um único * corresponde a qualquer sequência de caracteres incluindo espaços, portanto um caractere curinga pode abranger múltiplos argumentos. Bash(git *) corresponde a git log --oneline --all, e Bash(git * main) corresponde a git push origin main bem como git merge main.

Quando * aparece no final com um espaço antes dele (como Bash(ls *)), ele impõe um limite de palavra, exigindo que o prefixo seja seguido por um espaço ou fim de string. Por exemplo, Bash(ls *) corresponde a ls -la mas não a lsof. Em contraste, Bash(ls*) sem espaço corresponde a ambos ls -la e lsof porque não há restrição de limite de palavra.

Comandos compostos

Quando você aprova um comando composto com "Sim, não pergunte novamente", Claude Code salva uma regra separada para cada subcomando que requer aprovação, em vez de uma única regra para a string completa. Por exemplo, aprovar git status && npm test salva uma regra para npm test, portanto futuras invocações de npm test são reconhecidas independentemente do que precede o &&. Subcomandos como cd em um subdiretório geram sua própria regra Read para esse caminho. Até 5 regras podem ser salvas para um único comando composto.

Wrappers de processo

Antes de corresponder regras Bash, Claude Code remove um conjunto fixo de wrappers de processo para que uma regra como Bash(npm test *) também corresponda a timeout 30 npm test. Os wrappers reconhecidos são timeout, time, nice, nohup e stdbuf.

xargs simples também é removido, portanto Bash(grep *) corresponde a xargs grep pattern. A remoção se aplica apenas quando xargs não tem flags: uma invocação como xargs -n1 grep pattern é correspondida como um comando xargs, portanto regras escritas para o comando interno não a cobrem.

Esta lista de wrapper é integrada e não é configurável. Executores de ambiente de desenvolvimento como direnv exec, devbox run, mise exec, npx e docker exec não estão na lista. Porque essas ferramentas executam seus argumentos como um comando, uma regra como Bash(devbox run *) corresponde a tudo que vem após run, incluindo devbox run rm -rf .. Para aprovar trabalho dentro de um executor de ambiente, escreva uma regra específica que inclua tanto o executor quanto o comando interno, como Bash(devbox run npm test). Adicione uma regra por comando interno que você quer permitir.

Wrappers exec como watch, setsid, ionice e flock sempre solicitam e não podem ser auto-aprovados por uma regra de prefixo como Bash(watch *). O mesmo se aplica a find com -exec ou -delete: uma regra Bash(find *) não cobre essas formas. Para aprovar uma invocação específica, escreva uma regra de correspondência exata para a string de comando completa.

Comandos somente leitura

Claude Code reconhece um conjunto integrado de comandos Bash como somente leitura e os executa sem um prompt de permissão em cada modo. Estes incluem ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd e formas somente leitura de git. O conjunto não é configurável; para exigir um prompt para um desses comandos, adicione uma regra ask ou deny para ele.

Padrões glob sem aspas são permitidos para comandos cujas todas as flags são somente leitura, portanto ls *.ts e wc -l src/*.py são executados sem um prompt. Comandos com flags capazes de escrita ou execução, como find, sort, sed e git, ainda solicitam quando um glob sem aspas está presente porque o glob poderia expandir para uma flag como -delete.

Um cd em um caminho dentro do seu diretório de trabalho ou um diretório adicional também é somente leitura. Um comando composto como cd packages/api && ls é executado sem um prompt quando cada parte se qualifica por conta própria. Combinar cd com git em um comando composto sempre solicita, independentemente do diretório de destino.

PowerShell

As regras de permissão PowerShell usam a mesma forma que as regras Bash. Caracteres curinga com * correspondem em qualquer posição, o sufixo :* é equivalente a um * final, e um PowerShell simples ou PowerShell(*) corresponde a cada comando. Esta configuração permite comandos Get-ChildItem e git commit enquanto bloqueia Remove-Item:

{
  "permissions": {
    "allow": [
      "PowerShell(Get-ChildItem *)",
      "PowerShell(git commit *)"
    ],
    "deny": [
      "PowerShell(Remove-Item *)"
    ]
  }
}

Aliases comuns são canonicalizados antes da correspondência. Uma regra escrita para o nome do cmdlet também corresponde a seus aliases, portanto PowerShell(Get-ChildItem *) corresponde a gci, ls e dir também. A correspondência é insensível a maiúsculas e minúsculas.

Claude Code analisa o AST do PowerShell e verifica cada comando em um comando composto independentemente. Os operadores de pipeline |, separadores de instrução ; e nos operadores de cadeia PowerShell 7+ && e || dividem um comando composto em subcomandos. Uma regra deve corresponder a cada subcomando para que o comando composto seja permitido.

Read e Edit

As regras Edit se aplicam a todas as ferramentas integradas que editam arquivos. Claude faz uma tentativa de melhor esforço para aplicar regras Read a todas as ferramentas integradas que leem arquivos como Grep e Glob, a menções @file em seus prompts, e à seleção e contexto de arquivo aberto que um IDE conectado compartilha com Claude.

As regras Read e Edit seguem a especificação gitignore com quatro tipos de padrão distintos:

Padrão Significado Exemplo Corresponde
//path Caminho absoluto da raiz do sistema de arquivos Read(//Users/alice/secrets/**) /Users/alice/secrets/**
~/path Caminho do diretório home Read(~/Documents/*.pdf) /Users/alice/Documents/*.pdf
/path Caminho relativo à raiz do projeto Edit(/src/**/*.ts) <raiz do projeto>/src/**/*.ts
path ou ./path Caminho relativo ao diretório atual Read(*.env) <cwd>/*.env

No Windows, os caminhos são normalizados para forma POSIX antes da correspondência. C:\Users\alice se torna /c/Users/alice, portanto use //c/**/.env para corresponder arquivos .env em qualquer lugar nessa unidade. Para corresponder em todas as unidades, use //**/.env.

Exemplos:

  • Edit(/docs/**): edita em <projeto>/docs/ (NÃO /docs/ e NÃO <projeto>/.claude/docs/)
  • Read(~/.zshrc): lê o .zshrc do seu diretório home
  • Edit(//tmp/scratch.txt): edita o caminho absoluto /tmp/scratch.txt
  • Read(src/**): lê de <diretório-atual>/src/

Uma regra só corresponde a arquivos sob sua âncora, portanto a âncora determina o quão longe uma regra deny alcança. Nomes de arquivo simples seguem semântica gitignore e correspondem em qualquer profundidade, portanto Read(.env) e Read(**/.env) são equivalentes:

Regra deny Bloqueia Não bloqueia
Read(.env) ou Read(**/.env) qualquer .env no ou sob o diretório atual .env em um diretório pai ou outro projeto
Read(//**/.env) qualquer .env em qualquer lugar do sistema de arquivos nada; a regra é ancorada na raiz do sistema de arquivos

Quando Claude acessa um symlink, as regras de permissão verificam dois caminhos: o próprio symlink e o arquivo para o qual ele se resolve. As regras allow e deny tratam esse par de forma diferente: as regras allow voltam a solicitar, enquanto as regras deny bloqueiam imediatamente.

  • Regras allow: se aplicam apenas quando tanto o caminho do symlink quanto seu alvo correspondem. Um symlink dentro de um diretório permitido que aponta para fora dele ainda solicita.
  • Regras deny: se aplicam quando o caminho do symlink ou seu alvo correspondem. Um symlink que aponta para um arquivo negado é ele próprio negado.

Por exemplo, com Read(./project/**) permitido e Read(~/.ssh/**) negado, um symlink em ./project/key apontando para ~/.ssh/id_rsa é bloqueado: o alvo falha na regra allow e corresponde à regra deny.

WebFetch

As regras WebFetch usam um prefixo domain: e correspondem ao hostname da URL solicitada. A correspondência é insensível a maiúsculas e minúsculas, suporta caracteres curinga *, e remove um . final tanto da regra quanto do hostname para que example.com. e example.com sejam tratados da mesma forma.

  • WebFetch(domain:example.com) corresponde a solicitações para example.com
  • WebFetch(domain:*.example.com) corresponde a qualquer subdomínio em qualquer profundidade, como api.example.com ou a.b.example.com, mas não a example.com em si
  • WebFetch(domain:*) corresponde a cada domínio e é equivalente a uma regra WebFetch simples

Em qualquer posição que não seja um *. inicial ou um * simples, o caractere curinga corresponde apenas ao texto entre dois pontos. WebFetch(domain:example.*) corresponde a example.org, onde * se torna org, mas não a example.evil.com, onde * teria que se tornar evil.com e cruzar um ponto. Isso impede que um caractere curinga final corresponda a domínios que um atacante poderia registrar.

MCP

  • mcp__puppeteer corresponde a qualquer ferramenta fornecida pelo servidor puppeteer (nome configurado em Claude Code)
  • mcp__puppeteer__* sintaxe com caracteres curinga que também corresponde a todas as ferramentas do servidor puppeteer
  • mcp__puppeteer__puppeteer_navigate corresponde à ferramenta puppeteer_navigate fornecida pelo servidor puppeteer

Agent (subagents)

Use regras Agent(AgentName) para controlar quais subagents Claude pode usar:

  • Agent(Explore) corresponde ao subagent Explore
  • Agent(Plan) corresponde ao subagent Plan
  • Agent(my-custom-agent) corresponde a um subagent personalizado chamado my-custom-agent

Adicione estas regras ao array deny em suas configurações ou use a flag CLI --disallowedTools para desabilitar agentes específicos. Para desabilitar o agente Explore:

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

Cd

As regras Cd controlam para quais diretórios o comando /cd pode mover a sessão. Cd não é uma ferramenta invocável pelo modelo: Claude não pode chamá-la, e as regras se aplicam apenas quando você executa /cd você mesmo.

Uma regra deny Cd simples desabilita /cd inteiramente. Uma regra deny Cd(<path-pattern>) bloqueia alvos correspondentes. As regras deny verificam cada grafia do alvo, incluindo cada salto de symlink que ele se resolve através, portanto uma regra escrita para um caminho também bloqueia alvos que se resolvem para ele.

Adicionar qualquer regra allow Cd muda /cd para modo de lista de permissões: o diretório alvo resolvido deve corresponder a uma de suas regras allow, ou /cd recusa. Sem regras Cd configuradas, /cd mantém seu comportamento padrão e solicita que você confie em um diretório desconhecido.

Os padrões de caminho compartilham as âncoras //, ~/ e / das regras Read e Edit, mas a correspondência é ancorada ao caminho do diretório inteiro em vez de estilo gitignore. * corresponde a exatamente um segmento de caminho e ** corresponde entre segmentos. Um /** final também corresponde à sua raiz nomeada.

Regra Corresponde Não corresponde
Cd(~/code/*) ~/code/app ~/code/app/src, ~/code
Cd(~/code/**) ~/code e qualquer diretório sob ele diretórios fora de ~/code
Cd(**/node_modules) qualquer diretório node_modules em qualquer profundidade node_modules/pkg

Estender permissões com hooks

Os hooks do Claude Code fornecem uma maneira de registrar comandos de shell personalizados para realizar avaliação de permissão em tempo de execução. Quando Claude Code faz uma chamada de ferramenta, os hooks PreToolUse são executados antes do prompt de permissão. A saída do hook pode negar a chamada de ferramenta, forçar um prompt ou pular o prompt para deixar a chamada prosseguir.

As decisões do hook não contornam as regras de permissão. As regras deny e ask são avaliadas independentemente do que um hook PreToolUse retorna, portanto uma regra deny correspondente bloqueia a chamada e uma regra ask correspondente ainda solicita mesmo quando o hook retornou "allow" ou "ask". Isto preserva a precedência deny-first descrita em Gerenciar permissões, incluindo regras deny definidas em configurações gerenciadas.

Um hook de bloqueio também tem precedência sobre regras allow. Um hook que sai com código 2 interrompe a chamada de ferramenta antes das regras de permissão serem avaliadas, portanto o bloqueio se aplica mesmo quando uma regra allow permitiria a chamada. Para executar todos os comandos Bash sem prompts exceto por alguns que você quer bloqueados, adicione "Bash" à sua lista allow e registre um hook PreToolUse que rejeita esses comandos específicos. Veja Bloquear edições em arquivos protegidos para um script de hook que você pode adaptar.

Diretórios de trabalho

Por padrão, Claude tem acesso a arquivos no diretório onde foi iniciado. Você pode estender este acesso:

  • Durante a inicialização: use o argumento CLI --add-dir <path>
  • Durante a sessão: use o comando /add-dir
  • Configuração persistente: adicione a additionalDirectories em arquivos de configuração

Arquivos em diretórios adicionais seguem as mesmas regras de permissão do diretório de trabalho original: eles se tornam legíveis sem prompts, e as permissões de edição de arquivo seguem o modo de permissão atual.

Para alterar o diretório de trabalho primário da sessão em vez de adicionar outro, use /cd. O comando /cd requer Claude Code v2.1.169 ou posterior. Diferentemente de /add-dir, ele realoca a sessão: o CLAUDE.md do novo diretório é carregado e --resume encontra a sessão a partir daí.

Diretórios adicionais concedem acesso a arquivos, não configuração

Adicionar um diretório estende onde Claude pode ler e editar arquivos. Não faz desse diretório uma raiz de configuração completa: a maioria da configuração .claude/ não é descoberta de diretórios adicionais, embora alguns tipos sejam carregados como exceções.

Essas exceções se aplicam apenas a diretórios adicionados com o sinalizador --add-dir ou o comando /add-dir. Diretórios listados em permissions.additionalDirectories em um arquivo de configuração concedem apenas acesso a arquivos e não carregam nenhuma das configurações abaixo.

Os seguintes tipos de configuração são carregados de diretórios --add-dir:

Configuração Carregado de --add-dir
Skills em .claude/skills/ Sim, com recarga ao vivo
Subagentes em .claude/agents/ Sim
Configurações de plugin em .claude/settings.json Apenas enabledPlugins e extraKnownMarketplaces
Arquivos CLAUDE.md, .claude/rules/ e CLAUDE.local.md Apenas quando CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 está definido. CLAUDE.local.md adicionalmente requer a fonte de configuração local, que é ativada por padrão

Comandos e estilos de saída são descobertos do diretório de trabalho atual e seus pais, seu diretório de usuário em ~/.claude/ e configurações gerenciadas. Hooks e outras chaves settings.json são carregadas da pasta .claude/ do diretório de trabalho atual sem fallback de diretório pai, juntamente com seu ~/.claude/settings.json de usuário e configurações gerenciadas. Para compartilhar essa configuração entre projetos, use uma destas abordagens:

  • Configuração em nível de usuário: coloque arquivos em ~/.claude/agents/, ~/.claude/output-styles/ ou ~/.claude/settings.json para torná-los disponíveis em cada projeto
  • Plugins: empacote e distribua configuração como um plugin que as equipes podem instalar
  • Inicie do diretório de configuração: execute Claude Code do diretório contendo a configuração .claude/ que você deseja

Como as permissões interagem com sandboxing

Permissões e sandboxing são camadas de segurança complementares:

  • Permissões controlam quais ferramentas Claude Code pode usar e quais arquivos ou domínios pode acessar. Elas se aplicam a todas as ferramentas (Bash, Read, Edit, WebFetch, MCP e outras).
  • Sandboxing fornece imposição em nível de SO que restringe o acesso do Bash à rede e sistema de arquivos. Aplica-se apenas a comandos Bash e seus processos filhos.

Use ambos para defesa em profundidade:

  • As regras deny de permissão bloqueiam Claude de até tentar acessar recursos restritos
  • As restrições de sandbox impedem que comandos Bash alcancem recursos fora dos limites definidos, mesmo se uma injeção de prompt contornar a tomada de decisão de Claude
  • As restrições de sistema de arquivos no sandbox combinam as configurações sandbox.filesystem com regras deny de Read e Edit; ambas são mescladas no limite final do sandbox
  • As restrições de rede combinam regras de permissão WebFetch com as listas allowedDomains e deniedDomains do sandbox

Quando o sandboxing é ativado com autoAllowBashIfSandboxed: true, que é o padrão, comandos Bash em sandbox são executados sem solicitar mesmo se suas permissões incluem uma regra ask simples Bash, ou o formulário equivalente Bash(*): o limite do sandbox substitui esse prompt de ferramenta inteira. Regras ask com escopo de conteúdo como Bash(git push *) ainda forçam um prompt, regras deny explícitas ainda se aplicam, e comandos rm ou rmdir que visam /, seu diretório inicial ou outros caminhos críticos do sistema ainda acionam um prompt. Comandos que não serão executados em sandbox, como comandos excluídos, respeitam a regra ask simples Bash como de costume. Veja modos de sandbox para alterar este comportamento.

Configurações gerenciadas

Para organizações que precisam de controle centralizado sobre a configuração do Claude Code, administradores podem implantar configurações gerenciadas que não podem ser substituídas por configurações de usuário ou projeto. Estas configurações de política seguem o mesmo formato que arquivos de configuração regulares e podem ser entregues através de políticas MDM/nível de SO, arquivos de configuração gerenciados ou configurações gerenciadas por servidor. Veja arquivos de configuração para mecanismos de entrega e locais de arquivo.

Configurações apenas gerenciadas

As seguintes configurações são lidas apenas de configurações gerenciadas. Colocá-las em arquivos de configuração de usuário ou projeto não tem efeito.

Configuração Descrição
allowAllClaudeAiMcps Quando true, conectores claude.ai carregam junto com um managed-mcp.json implantado em vez de serem suprimidos por seu controle exclusivo. Veja Configuração MCP gerenciada
allowedChannelPlugins Lista de permissão de plugins de canal que podem enviar mensagens. Substitui a lista de permissão padrão da Anthropic quando definida. Requer channelsEnabled: true. Veja Restringir quais plugins de canal podem ser executados
allowManagedHooksOnly Quando true, apenas hooks gerenciados, hooks SDK e hooks de plugins força-ativados em configurações gerenciadas enabledPlugins são carregados. Hooks de usuário, projeto e todos os outros plugins são bloqueados
allowManagedMcpServersOnly Quando true, apenas allowedMcpServers de configurações gerenciadas são respeitados. deniedMcpServers ainda se mescla de todas as fontes. Veja Configuração MCP gerenciada
allowManagedPermissionRulesOnly Quando true, impede que configurações de usuário e projeto definam regras de permissão allow, ask ou deny. Apenas regras em configurações gerenciadas se aplicam. Não afeta a lista de permissão do servidor MCP; para isso, defina allowManagedMcpServersOnly
blockedMarketplaces Lista de bloqueio de fontes de marketplace. Fontes bloqueadas são verificadas antes do download, portanto nunca tocam o sistema de arquivos. Veja restrições de marketplace gerenciadas
channelsEnabled Permitir channels para a organização. Veja controles empresariais para o padrão em cada plano
forceRemoteSettingsRefresh Quando true, bloqueia a inicialização da CLI até que as configurações gerenciadas remotas sejam buscadas recentemente e sai se a busca falhar. Veja imposição fail-closed
pluginTrustMessage Mensagem personalizada anexada ao aviso de confiança de plugin mostrado antes da instalação
sandbox.filesystem.allowManagedReadPathsOnly Quando true, apenas caminhos filesystem.allowRead de configurações gerenciadas são respeitados. denyRead ainda se mescla de todas as fontes
sandbox.network.allowManagedDomainsOnly Quando true, apenas allowedDomains e regras allow WebFetch(domain:...) de configurações gerenciadas são respeitados. Domínios não permitidos são bloqueados automaticamente sem solicitar ao usuário. Domínios negados ainda se mesclam de todas as fontes
strictKnownMarketplaces Controla quais marketplaces de plugin os usuários podem adicionar e instalar plugins. Veja restrições de marketplace gerenciadas
strictPluginOnlyCustomization Bloqueia skills, agents, hooks e servidores MCP de fontes de usuário e projeto, para que possam vir apenas de plugins ou configurações gerenciadas. true bloqueia todas as quatro superfícies; um array como ["skills", "hooks"] bloqueia apenas as nomeadas. Veja strictPluginOnlyCustomization
wslInheritsWindowsSettings Quando true na chave de registro HKLM do Windows ou C:\Program Files\ClaudeCode\managed-settings.json, WSL lê configurações gerenciadas da cadeia de política do Windows além de /etc/claude-code. Veja Arquivos de configuração

disableBypassPermissionsMode é tipicamente colocado em configurações gerenciadas para impor política organizacional, mas funciona de qualquer escopo. Um usuário pode defini-lo em suas próprias configurações para se bloquear do modo bypass.

Precedência de configurações

As regras de permissão seguem a mesma precedência de configurações que todas as outras configurações do Claude Code:

  1. Configurações gerenciadas: não podem ser substituídas por nenhum outro nível, incluindo argumentos de linha de comando
  2. Argumentos de linha de comando: substituições de sessão temporária
  3. Configurações de projeto local (.claude/settings.local.json)
  4. Configurações de projeto compartilhado (.claude/settings.json)
  5. Configurações de usuário (~/.claude/settings.json)

Se uma ferramenta for negada em qualquer nível, nenhum outro nível pode permitir. Por exemplo, uma negação de configurações gerenciadas não pode ser substituída por --allowedTools, e --disallowedTools pode adicionar restrições além do que as configurações gerenciadas definem.

Os hosts de incorporação podem fornecer política gerenciada adicional por meio da opção managedSettings do SDK quando parentSettingsBehavior está definido como "merge"; os valores do incorporador podem apertar a política, mas não afrouxá-la.

Por exemplo, se as configurações de usuário permitirem uma permissão e as configurações de projeto a negarem, a regra de negação a bloqueia. O inverso também é verdadeiro: uma negação no nível de usuário bloqueia uma permissão no nível de projeto, porque as regras de negação de qualquer escopo são avaliadas antes das regras de permissão.

Configurações de exemplo

Este repositório inclui configurações de configuração inicial para cenários de implantação comuns. Use-as como pontos de partida e ajuste-as para suas necessidades.

Veja também

  • Settings: referência de configuração completa incluindo a tabela de configurações de permissão
  • Configure auto mode: diga ao classificador do modo auto qual infraestrutura sua organização confia
  • Sandboxing: isolamento de rede e sistema de arquivos em nível de SO para comandos Bash
  • Authentication: configure o acesso do usuário ao Claude Code
  • Security: salvaguardas de segurança e melhores práticas
  • Hooks: automatize fluxos de trabalho e estenda avaliação de permissão