SpyBara
Go Premium

settings-reference.md 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC

This page contains 78 additions and 63 deletions.

2026
Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Mon 21 22:59 Tue 22 23:59 Thu 24 22:57 Fri 25 23:58

Todas as configurações

Referência completa para cada chave settings.json do Claude Code: onde cada uma vai, seu tipo e padrão, e um exemplo pronto para colar, com um índice de cada chave.

export const BackToIndex = ({href = '#all-settings', label = 'Back to index'}) => { const [show, setShow] = useState(false); useEffect(() => { const onScroll = () => setShow(window.scrollY > window.innerHeight); onScroll(); window.addEventListener('scroll', onScroll, { passive: true }); return () => window.removeEventListener('scroll', onScroll); }, []); return

<a className={'bti-btn' + (show ? ' bti-show' : '')} href={href} aria-hidden={!show} tabIndex={show ? 0 : -1}> {label}
; };

export const ReferenceFilter = ({placeholder, noun, facets, facetOrder, columnHelp, children}) => { const useLive = init => { const [v, setV] = useState(init); const ref = useRef(init); return [v, ref, x => { ref.current = x; setV(x); }]; }; const cap = s => s.charAt(0).toUpperCase() + s.slice(1); const plural = s => s.endsWith('y') ? s.slice(0, -1) + 'ies' : s + 's'; const facetNames = facets || ['category', 'topic', 'scope', 'where']; const orderOf = {}; Object.keys(facetOrder || ({})).forEach(k => { orderOf[k] = facetOrder[k].map(x => String(x).toLowerCase()); }); const rankIn = (col, v) => { const list = orderOf[col]; if (!list) return -1; const i = list.indexOf(String(v).toLowerCase()); return i < 0 ? list.length : i; }; const cmpValues = col => (a, b) => { const ra = rankIn(col, a); const rb = rankIn(col, b); if (ra !== rb) return ra - rb; return a < b ? -1 : a > b ? 1 : 0; }; const help = columnHelp || ({}); const FIRST_COL_HELP = 'Click an entry to open it.'; const optionLabel = (f, c) => c === 'All' ? 'All ' + plural(f.label.toLowerCase()) : c; const nounText = noun || 'entries'; const placeholderText = placeholder || 'Filter this reference'; const rootRef = useRef(null); const tablesRef = useRef(null); const searchRef = useRef(null); const menuRef = useRef({}); const [q, qRef, setQ] = useLive(''); const [sel, selRef, setSel] = useLive({}); const [sortBy, sortRef, setSortBy] = useLive(null); const [menuOpen, menuOpenRef, setMenu] = useLive(null); const [facetList, setFacetList] = useState([]); const [firstHead, setFirstHead] = useState(''); const [counts, setCounts] = useState({ shown: 0, total: 0 }); const [disabled, setDisabled] = useState(false); const menuBtn = name => menuRef.current[name] ? menuRef.current[name].querySelector(':scope > button') : null; const menuList = name => menuRef.current[name] ? menuRef.current[name].querySelector('[role="listbox"]') : null; const closeMenu = name => { setMenu(null); const btn = menuBtn(name); if (btn) btn.focus(); }; const focusSelected = name => { const list = menuList(name); if (!list) return; const btn = list.querySelector('button[aria-selected="true"]') || list.querySelector('button'); if (btn) btn.focus(); }; const setFacet = (name, value) => { setSel(Object.assign({}, selRef.current, { [name]: value })); apply(qRef.current); closeMenu(name); }; const sortTables = by => { (tablesRef.current || []).forEach(tab => { const t = tab.el; const idx = tab.heads.indexOf(by); const body = t.querySelector('tbody'); if (idx < 0 || !body) return; const rows = [...body.querySelectorAll('tr')]; const keyOf = r => r.children[idx] ? r.children[idx].textContent.trim().toLowerCase() : ''; const cmp = cmpValues(by); rows.map((r, i) => ({ r, i: Number(r.dataset.sfIndex !== undefined ? r.dataset.sfIndex : i), k: keyOf(r) })).sort((a, b) => cmp(a.k, b.k) || a.i - b.i).forEach(x => body.appendChild(x.r)); [...t.querySelectorAll('thead th')].forEach((h, i) => { const sortable = tab.heads[i] === tab.heads[0] || facetNames.indexOf(tab.heads[i]) > -1; if (sortable) h.setAttribute('aria-sort', i === idx ? 'ascending' : 'none'); else h.removeAttribute('aria-sort'); }); }); }; const scan = () => { const tables = []; let el = rootRef.current ? rootRef.current.nextElementSibling : null; while (el) { if (el.tagName === 'H2' || el.querySelector(':scope > h2')) break; const found = el.tagName === 'TABLE' ? [el] : [...el.querySelectorAll('table')]; found.forEach(t => { const headCells = [...t.querySelectorAll('thead th, thead td')]; const heads = headCells.map(h => h.textContent.trim().toLowerCase()); if (heads.length === 0) return; const facetIdx = {}; heads.forEach((h, i) => { if (facetNames.indexOf(h) > -1) facetIdx[h] = i; }); if (!t.dataset.sfDecorated) { t.dataset.sfDecorated = '1'; headCells.forEach((h, i) => { const text = i === 0 ? help[heads[0]] || FIRST_COL_HELP : help[heads[i]]; if (text) h.title = text; }); } const rows = [...t.querySelectorAll('tbody tr')].map((r, i) => { if (r.dataset.sfIndex === undefined) r.dataset.sfIndex = String(i); const cells = r.querySelectorAll('td'); const fv = {}; Object.keys(facetIdx).forEach(h => { fv[h] = cells[facetIdx[h]] ? cells[facetIdx[h]].textContent.trim() : ''; }); return { el: r, text: [...cells].map(c => c.textContent).join(' ').toLowerCase(), facets: fv, anchors: [...r.querySelectorAll('a[href^="#"]')].map(a => a.getAttribute('href').slice(1)), ids: [...r.querySelectorAll('[id]')].map(n => n.id) }; }); tables.push({ el: t, box: t.closest('[data-table-wrapper]') || t, rows, heads }); }); el = el.nextElementSibling; } tablesRef.current = tables; if (sortRef.current) sortTables(sortRef.current); return tables; }; const apply = query => { let tables = tablesRef.current || scan(); if (tables.some(t => !t.el.isConnected)) tables = scan(); const needle = query.trim().toLowerCase(); const sel = selRef.current; const activeFacets = Object.keys(sel).filter(h => sel[h] && sel[h] !== 'All'); const show = (el, on) => { const want = on ? '' : 'none'; if (el.style.display !== want) el.style.display = want; }; let total = 0; let shown = 0; const visibleTargets = new Set(); tables.forEach(t => { let tableVisible = 0; t.rows.forEach(row => { total += 1; const catOk = activeFacets.every(h => { const v = row.facets[h]; return v === sel[h] || v === '' || v === undefined; }); const match = catOk && (needle === '' || row.text.includes(needle)); show(row.el, match); if (match) { tableVisible += 1; row.anchors.forEach(a => visibleTargets.add(a)); } }); show(t.box, !(t.rows.length > 0 && tableVisible === 0)); shown += tableVisible; }); if (shown < total && visibleTargets.size > 0) { tables.forEach(t => { t.rows.forEach(row => { if (row.el.style.display === 'none' && row.ids.some(id => visibleTargets.has(id))) { show(row.el, true); show(t.box, true); shown += 1; } }); }); } setCounts({ shown, total }); return total; }; const deriveFacets = tables => { const seen = {}; tables.forEach(t => t.rows.forEach(r => { Object.keys(r.facets).forEach(h => { if (!seen[h]) seen[h] = []; if (r.facets[h] && seen[h].indexOf(r.facets[h]) === -1) seen[h].push(r.facets[h]); }); })); const list = facetNames.filter(h => seen[h] && seen[h].length > 0).map(h => ({ name: h, label: cap(h), values: seen[h].sort(cmpValues(h)) })); setFacetList(list); const first = tables[0] ? tables[0].heads[0] : ''; setFirstHead(first); if (!sortRef.current && first) { setSortBy(first); sortTables(first); } const init = {}; list.forEach(f => { init[f.name] = selRef.current[f.name] || 'All'; }); setSel(init); }; const onChange = value => { setQ(value); apply(value); }; const clearAll = () => { const next = {}; Object.keys(selRef.current).forEach(k => { next[k] = 'All'; }); setSel(next); setQ(''); apply(''); if (searchRef.current) searchRef.current.focus(); }; useEffect(() => { const tables = scan(); deriveFacets(tables); const total = apply(''); let retryTimer; if (total === 0) { retryTimer = setTimeout(() => { tablesRef.current = null; if (apply(qRef.current) > 0) deriveFacets(tablesRef.current); else setDisabled(true); }, 500); } const onKey = e => { if (e.key === 'Escape' && menuOpenRef.current !== null) closeMenu(menuOpenRef.current); if (!searchRef.current) return; if (e.metaKey || e.ctrlKey || e.altKey) return; const active = document.activeElement; const tag = active && active.tagName; const editable = active && active.isContentEditable; const interactive = tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || tag === 'BUTTON' || tag === 'A' || editable || active && active.getAttribute && active.getAttribute('role'); if (e.key === '/' && !interactive) { const r = rootRef.current ? rootRef.current.getBoundingClientRect() : null; if (r && r.bottom > 0 && r.top < (window.innerHeight || 0)) { e.preventDefault(); setMenu(null); searchRef.current.focus(); } } if (e.key === 'Escape' && menuOpenRef.current === null && active === searchRef.current) { onChange(''); searchRef.current.blur(); } }; const onDocClick = e => { const open = menuOpenRef.current; if (open !== null && menuRef.current[open] && !menuRef.current[open].contains(e.target)) setMenu(null); }; window.addEventListener('keydown', onKey); document.addEventListener('mousedown', onDocClick); return () => { if (retryTimer) clearTimeout(retryTimer); window.removeEventListener('keydown', onKey); document.removeEventListener('mousedown', onDocClick); (tablesRef.current || []).forEach(t => { t.box.style.display = ''; t.rows.forEach(row => { row.el.style.display = ''; }); }); }; }, []); useEffect(() => { if (menuOpen !== null) focusSelected(menuOpen); }, [menuOpen]); if (disabled) return null; const facetActive = Object.keys(sel).some(h => sel[h] && sel[h] !== 'All'); const sortOptions = [firstHead].concat(facetList.map(f => f.name)).filter((h, i, a) => h && a.indexOf(h) === i); return <> <div ref={rootRef} className="sf-root" style={{ margin: '16px 0 8px' }}> <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap', alignItems: 'center' }}> <div style={{ position: 'relative', flex: '1 1 260px', maxWidth: '480px' }}> <input ref={searchRef} value={q} onChange={e => onChange(e.target.value)} placeholder={placeholderText} aria-label={placeholderText} style={{ width: '100%', padding: '8px 56px 8px 12px', borderRadius: '8px', border: '1px solid var(--sf-border)', background: 'var(--sf-bg)', color: 'var(--sf-text)', fontSize: '14px', outline: 'none', boxSizing: 'border-box' }} /> {q ? <button type="button" onClick={() => { onChange(''); if (searchRef.current) searchRef.current.focus(); }} aria-label="Clear text" className="sf-end sf-x"> × : <span className="sf-end" style={{ fontFamily: 'var(--font-mono, ui-monospace, monospace)', fontSize: '11px', color: 'var(--sf-text-4)', border: '1px solid var(--sf-border)', borderRadius: '3px', padding: '0 5px', pointerEvents: 'none' }}> / }

{facetList.map(f => { const cur = sel[f.name] || 'All'; const isOpen = menuOpen === f.name; return <div key={f.name} ref={el => { menuRef.current[f.name] = el; }} style={{ position: 'relative' }}> <button type="button" onClick={() => setMenu(isOpen ? null : f.name)} onKeyDown={e => { if (e.key === 'ArrowDown') { e.preventDefault(); if (!isOpen) setMenu(f.name); else focusSelected(f.name); } }} aria-haspopup="listbox" aria-expanded={isOpen} style={{ display: 'flex', alignItems: 'center', gap: '8px', padding: cur !== 'All' ? '8px 30px 8px 12px' : '8px 12px', borderRadius: '8px', border: '1px solid ' + (cur !== 'All' ? 'var(--sf-accent)' : 'var(--sf-border)'), background: 'var(--sf-bg)', color: cur === 'All' ? 'var(--sf-text-3)' : 'var(--sf-text)', fontSize: '13.5px', cursor: 'pointer', whiteSpace: 'nowrap', maxWidth: '260px' }}> <span style={{ overflow: 'hidden', textOverflow: 'ellipsis' }}> {f.label + ': ' + optionLabel(f, cur)} <span aria-hidden="true" style={{ fontSize: '9px', color: 'var(--sf-text-4)', transform: isOpen ? 'rotate(180deg)' : 'none', transition: 'transform 120ms' }}> ▼ {cur !== 'All' && <button type="button" onClick={() => setFacet(f.name, 'All')} aria-label={'Clear ' + f.label + ' filter'} title={'Clear ' + f.label + ' filter'} className="sf-end sf-x"> × } {isOpen && <div role="listbox" aria-label={f.label} onKeyDown={e => { const items = [...e.currentTarget.querySelectorAll('button')]; const idx = items.indexOf(document.activeElement); if (e.key === 'ArrowDown') { e.preventDefault(); (items[idx + 1] || items[0]).focus(); } else if (e.key === 'ArrowUp') { e.preventDefault(); (items[idx - 1] || items[items.length - 1]).focus(); } else if (e.key === 'Home') { e.preventDefault(); if (items[0]) items[0].focus(); } else if (e.key === 'End') { e.preventDefault(); if (items[items.length - 1]) items[items.length - 1].focus(); } else if (e.key === 'Tab') { closeMenu(f.name); } }} style={{ position: 'absolute', top: 'calc(100% + 6px)', left: 0, zIndex: 1000, minWidth: '260px', maxHeight: '340px', overflowY: 'auto', background: 'var(--sf-bg)', border: '1px solid var(--sf-border)', borderRadius: '10px', boxShadow: '0 8px 24px rgba(0,0,0,0.12)', padding: '5px' }}> {['All'].concat(f.values).map(c => { const selected = cur === c; return <button key={c} role="option" aria-selected={selected} tabIndex={-1} onClick={() => setFacet(f.name, c)} style={{ display: 'flex', alignItems: 'center', gap: '8px', width: '100%', textAlign: 'left', padding: '7px 10px', borderRadius: '6px', border: 'none', background: 'transparent', color: selected ? 'var(--sf-accent)' : 'var(--sf-text)', fontWeight: selected ? 600 : 400, fontSize: '13.5px', cursor: 'pointer' }}> <span aria-hidden="true" style={{ width: '14px', color: 'var(--sf-accent)', flexShrink: 0 }}> {selected ? '✓' : ''} {optionLabel(f, c)} ; })}
}
; })} {sortOptions.length > 1 && <div role="group" aria-label="Sort by" style={{ display: 'flex', alignItems: 'center', gap: '4px', fontSize: '13px', color: 'var(--sf-text-3)', whiteSpace: 'nowrap' }}> <span style={{ marginRight: '4px' }}>Sort by {sortOptions.map(o => { const on = sortBy === o; return <button key={o} type="button" aria-pressed={on} onClick={() => { setSortBy(o); sortTables(o); }} style={{ padding: '6px 10px', borderRadius: '8px', border: '1px solid ' + (on ? 'var(--sf-accent)' : 'var(--sf-border)'), background: 'var(--sf-bg)', color: on ? 'var(--sf-text)' : 'var(--sf-text-3)', fontSize: '13px', cursor: 'pointer' }}> {o.charAt(0).toUpperCase() + o.slice(1)} ; })} } <div aria-live="polite" style={{ margin: '8px 0 0', fontSize: '13px', color: 'var(--sf-text-3)', minHeight: '1px' }}> {q.trim() === '' && !facetActive ? <>{counts.total} {nounText}</> : counts.shown === 0 ? <> {q.trim() === '' ? 'No ' + nounText + ' match the selected filters.' : facetActive ? 'No ' + nounText + ' match \u201c' + q + '\u201d with the selected filters.' : 'No ' + nounText + ' match \u201c' + q + '\u201d.'}{' '} <button type="button" onClick={clearAll} style={{ background: 'none', border: 'none', padding: 0, color: 'var(--sf-accent)', cursor: 'pointer', font: 'inherit', textDecoration: 'underline' }}> Clear filters {children ? <> {children}</> : null} </> : <> Showing {counts.shown} of {counts.total} {nounText} </>} </>; };

Esta página de referência lista cada chave que Claude Code lê de um arquivo de configurações, além do pequeno grupo de chaves que mantém em ~/.claude.json. Para escolher um arquivo ou verificar a precedência, comece com Arquivos de configurações e precedência.

Índice de configurações

Cada chave abaixo está vinculada à sua entrada. O escopo lista os arquivos em que pode estar: User é ~/.claude/settings.json, Project é .claude/settings.json, Local é .claude/settings.local.json, e Managed é o que sua organização implanta. Any file significa todos os quatro, e Global config significa ~/.claude.json.

<ReferenceFilter noun="settings" placeholder="Filter settings by key or purpose" facetOrder={{ scope: ["Any file", "User, local, or managed", "User or managed", "Managed", "Global config"] }} columnHelp={{ topic: "The section of this page that holds the entry. Use Sort by to group the table by topic.", scope: "Which settings files can set the key: user (~/.claude/settings.json), project (.claude/settings.json), local (.claude/settings.local.json), or managed (deployed by your organization). Global config keys are in ~/.claude.json instead.", }} />

Chave Descrição Tópico Escopo
advisorModel Escolha qual modelo responde quando Claude usa a ferramenta de assessor Modelo e respostas Any file
agent Inicie cada sessão como um subagente nomeado com seu prompt, ferramentas e modelo Agentes, sessões e worktrees Any file
agentPushNotifEnabled Permita que Claude envie uma notificação push para seu telefone quando decidir Remoto, desktop e notificações Any file
allowAllClaudeAiMcps Carregue os conectores claude.ai que Claude Code busca por conta própria junto com um managed-mcp.json implantado MCP Managed
allowedChannelPlugins Substitua a lista de permissões padrão de plugins de canal que podem enviar mensagens Plugins e skills Managed
allowedHttpHookUrls Limite quais URLs os hooks HTTP podem atingir Hooks e automação Any file
allowedMcpServers Lista de permissões de quais servidores MCP os usuários podem adicionar MCP Any file
allowManagedHooksOnly Execute apenas os hooks que sua organização implanta Hooks e automação Managed
allowManagedMcpServersOnly Faça a lista de permissões de MCP gerenciada ser a única que se aplica MCP Managed
allowManagedPermissionRulesOnly Faça as configurações gerenciadas serem a única fonte de regras de permissão Configurações de permissão Managed
alwaysThinkingEnabled Desative o pensamento estendido para cada sessão Modelo e respostas Any file
apiKeyHelper Gere a credencial de API com seu próprio comando Autenticação e provedores Any file
askUserQuestionTimeout Permita que uma pergunta sem resposta continue automaticamente após tempo ocioso Interface e terminal User or managed
attribution Personalize a atribuição que Claude Code adiciona a commits e pull requests Git e atribuição Any file
attribution.commit Altere ou oculte o trailer que Claude Code adiciona aos commits Git e atribuição Any file
attribution.pr Altere ou oculte a linha de atribuição nas descrições de pull request Git e atribuição Any file
attribution.sessionUrl Omita o link de sessão claude.ai dos commits de nuvem e Remote Control Git e atribuição Any file
autoCompactEnabled Desative ou ative a compactação automática Memória e contexto Any file
autoCompactWindow Defina o quão cheio o contexto fica antes de Claude Code compactar Memória e contexto Any file
autoConnectIde Conecte-se automaticamente a um VS Code ou JetBrains IDE em execução a partir de um terminal externo Configurações de config global Global config
autoContinueAtUsageLimit Aguarde na sessão aberta e continue a tarefa automaticamente após um limite de uso claude.ai ser redefinido Interface e terminal User or managed
autoInstallIdeExtension Desative a instalação automática da extensão IDE a partir de um terminal VS Code Configurações de config global Global config
autoMemoryDirectory Armazene a memória automática em um diretório de sua escolha Memória e contexto Any file
autoMemoryEnabled Desative ou ative a memória automática Memória e contexto Any file
autoMode Adicione suas próprias regras de permissão e negação ao classificador de modo automático Configurações de permissão User or managed
autoMode.classifyAllShell Envie cada comando shell através do classificador de modo automático, mesmo aqueles que uma regra de permissão estreita corresponde Configurações de permissão User or managed
autoScrollEnabled Siga a nova saída até o final na renderização em tela cheia Interface e terminal Any file
autoUpdatesChannel Siga o canal de lançamento estável em vez do mais recente Atualizações e versionamento Any file
availableModels Restrinja quais modelos as pessoas podem escolher Modelo e respostas Any file
awaySummaryEnabled Desative o resumo da sessão mostrado quando você volta ao terminal Remoto, desktop e notificações Any file
awsAuthRefresh Atualize as credenciais Bedrock expiradas em .aws com seu próprio comando Autenticação e provedores Any file
awsCredentialExport Forneça as credenciais Bedrock como JSON a partir de seu próprio comando Autenticação e provedores Any file
axScreenReader Renderize a saída amigável ao leitor de tela Interface e terminal Any file
bashEditDiffEnabled Registre os arquivos que um comando Bash alterou em cada modo de permissão Interface e terminal User or managed
bashOutputMaxChars Defina quanto da saída de um comando bem-sucedido Claude recebe inline Memória e contexto Any file
blockedMarketplaces Bloqueie as fontes do marketplace de plugins para sua organização Plugins e skills Managed
browserExternalPageTools Mantenha as ferramentas de Claude desativadas em páginas externas no painel desktop Browser Ferramentas Managed
channelsEnabled Permita canais para sua organização Plugins e skills Managed
claudeMd Injete instruções CLAUDE.md em toda a organização a partir de configurações gerenciadas Memória e contexto Managed
claudeMdExcludes Pule arquivos CLAUDE.md específicos quando a memória carrega Memória e contexto Any file
cleanupPeriodDays Escolha quantos dias Claude Code mantém transcrições antes de deletá-las Privacidade e telemetria Any file
companyAnnouncements Mostre os anúncios de sua organização na inicialização Interface e terminal Any file
copyOnSelect Desative a cópia automática de texto que você seleciona com o mouse na renderização em tela cheia e visualização de agente Configurações de config global Global config
crossSessionInbound Escolha se Claude Code entrega mensagens de suas outras sessões, mostra um aviso sem entregá-las, ou as recusa Agentes, sessões e worktrees Any file
defaultShell Escolha se Bash ou PowerShell executa os comandos shell que você digita com o prefixo ! Interface e terminal Any file
deniedMcpServers Bloqueie servidores MCP específicos por URL, comando ou nome MCP Any file
desktopSessionCleanupPeriodDays Defina um limite de idade em dias para transcrições de Claude Desktop e Cowork Privacidade e telemetria User or managed
dialogExpiry Defina quanto tempo Claude Code aguarda Remote Control ou um host SDK responder a um diálogo encaminhado antes de cancelar o diálogo Interface e terminal User or managed
diffTool Escolha se as alterações de arquivo propostas por Claude abrem no visualizador de diff do VS Code ou JetBrains ou permanecem no terminal Configurações de config global Global config
disableAgentView Desative agentes em segundo plano e visualização de agente Agentes, sessões e worktrees Any file
disableAllHooks Desative hooks, uma linha de status personalizada, e um comando de sugestão de arquivo @ personalizado de uma vez Hooks e automação Any file
disableArtifact Descontinuado; use enableArtifact para desativar a ferramenta Artifact Remoto, desktop e notificações Any file
disableAutoMode Remova o modo automático do ciclo de modo de permissão Configurações de permissão Any file
disableBrowserExternalNavigation Limite o painel desktop Browser para localhost para pessoas e Claude Ferramentas Managed
disableBundledSkills Desative as skills e workflows inclusos com Claude Code Plugins e skills Any file
disableClaudeAiConnectors Desative os conectores claude.ai para que Claude Code não os busque MCP Any file
disableCommandPluginSources Bloqueie plugins que instalam executando um comando declarado pelo marketplace Plugins e skills Managed
disableDeepLinkRegistration Impeça Claude Code de registrar o manipulador claude-cli:// Remoto, desktop e notificações Any file
disableDesktopLocalSessions Desative as sessões Desktop Code que executam no dispositivo, deixando SSH para outros hosts e nuvem Remoto, desktop e notificações Managed
disabledMcpjsonServers Rejeite servidores específicos do .mcp.json de um projeto MCP Any file
disableMobileSimulatorTools Bloqueie as ferramentas de Claude no painel desktop iOS Simulator Ferramentas Managed
disableRemoteControl Desative o Remote Control em todos os lugares onde pode começar Remoto, desktop e notificações Any file
disableSideloadFlags Rejeite os sinalizadores CLI que carregam plugins, subagentes e servidores MCP Configurações empresariais e gerenciadas Managed
disableSkillShellExecution Impeça skills e comandos personalizados de executar shell inline Plugins e skills Any file
disableWorkflows Desative workflows dinâmicos para todos; use enableWorkflows para você mesmo Hooks e automação Any file
editorMode Use atalhos de teclado vim no prompt de entrada Interface e terminal Any file
effortLevel Defina um nível de esforço padrão para modelos sem um nível salvo próprio Modelo e respostas Any file
emojiCompletionEnabled Desative as sugestões e substituição de emoji :shortcode: na entrada do prompt Interface e terminal Any file
enableAllProjectMcpServers Aprove cada servidor no arquivo .mcp.json do projeto sem um prompt MCP Any file
enableArtifact Desative a ferramenta Artifact com um false em qualquer arquivo; nenhum arquivo pode ativá-la novamente Remoto, desktop e notificações Any file
enabledMcpjsonServers Aprove servidores específicos do .mcp.json de um projeto MCP Any file
enabledPlugins Ative ou desative plugins individuais por escopo Plugins e skills Any file
enableWorkflows Ative ou desative workflows dinâmicos contra o padrão de seu plano Hooks e automação Any file
enforceAvailableModels Mantenha a escolha Padrão de /model dentro de sua lista de permissões availableModels Modelo e respostas Any file
env Defina variáveis de ambiente para cada sessão e seus subprocessos Memória e contexto Any file
externalEditorContext Mostre a última resposta de Claude como comentários quando você pressiona Ctrl+G para editar Configurações de config global Global config
extraKnownMarketplaces Registre marketplaces para um repositório ou uma organização Plugins e skills Any file
fallbackModel Nomeie modelos de backup para quando o primário estiver sobrecarregado Modelo e respostas Any file
fastMode Ative o modo rápido para sessões onde está disponível Modelo e respostas Any file
fastModePerSessionOptIn Exija que as pessoas ativem o modo rápido em cada sessão Modelo e respostas Any file
feedbackDrafts Controle se Claude enfileira rascunhos de feedback para você revisar Privacidade e telemetria User or managed
feedbackSurveyRate Altere a frequência com que a pesquisa de qualidade da sessão aparece Privacidade e telemetria Any file
fileCheckpointingEnabled Desative ou ative os snapshots de arquivo que /rewind restaura Memória e contexto Any file
fileSuggestion Forneça o preenchimento automático de arquivo @ a partir de seu próprio comando Interface e terminal Any file
footerLinksRegexes Transforme IDs de issue ou review na saída em links clicáveis abaixo da caixa de entrada Interface e terminal User or managed
forceLoginGatewayUrl Defina a URL do gateway à qual a tela de login se conecta Autenticação e provedores Managed
forceLoginMethod Restrinja o login a claude.ai, Claude Console, ou um gateway de nuvem Autenticação e provedores Any file
forceLoginOrgUUID Fixe os logins claude.ai à sua organização; apenas uma fonte gerenciada a impõe Autenticação e provedores Any file
forceRemoteSettingsRefresh Bloqueie a inicialização até que as configurações gerenciadas por servidor sejam buscadas recentemente Configurações empresariais e gerenciadas Managed
gatewayInternalNetworks Permita que /login alcance um gateway de nuvem no espaço IPv4 público que sua organização usa internamente Autenticação e provedores Managed
gcpAuthRefresh Atualize as credenciais do Google Cloud com seu próprio comando Autenticação e provedores Any file
hooks Execute seus próprios comandos como hooks em pontos do ciclo de vida de Claude Code Hooks e automação Any file
httpHookAllowedEnvVars Limite quais variáveis de ambiente os hooks HTTP podem colocar em cabeçalhos Hooks e automação Any file
includeCoAuthoredBy Descontinuado; use attribution para ocultar ou alterar a atribuição de commit e PR Git e atribuição Any file
includeGitInstructions Remova as instruções de commit e PR integradas do contexto de Claude Git e atribuição Any file
inputNeededNotifEnabled Receba uma notificação push quando Claude estiver esperando por você Remoto, desktop e notificações Any file
isolatePeerMachines Peça-lhe antes de Claude enviar mensagem para uma de suas sessões em outra máquina Agentes, sessões e worktrees Any file
keybindingFlavor Descontinuado e sem efeito; os atalhos de edição de palavras sempre seguem as convenções readline Interface e terminal Any file
language Faça Claude responder em um idioma diferente do inglês Modelo e respostas Any file
managedMcpServers Forneça servidores MCP remotos a cada usuário junto com os que eles adicionam MCP Managed
managedSourcesBehavior Componha cada fonte gerenciada que você implanta em vez de usar apenas a de maior prioridade Configurações empresariais e gerenciadas Managed
maxEffortLevel Limite o nível de esforço para cada modelo ou por modelo, em cada provedor Modelo e respostas Any file
minimumVersion Mantenha as atualizações automáticas de instalar qualquer coisa abaixo de uma versão Atualizações e versionamento Any file
model Altere o modelo com o qual Claude Code começa Modelo e respostas Any file
modelOverrides Mapeie IDs de modelo para os IDs do seu provedor, como ARNs do Bedrock Modelo e respostas Any file
modelPicker Escolha quais modelos o seletor /model lista, em sua própria ordem e com seus próprios rótulos Modelo e respostas User or managed
modelPricing Relate gastos nas taxas contratadas de sua organização em vez do preço de tabela Modelo e respostas Managed
modelSettings Mantenha um nível de esforço salvo por modelo, ou limite o esforço de um modelo Modelo e respostas Any file
otelHeadersHelper Gere cabeçalhos OpenTelemetry rotativos com seu próprio comando Autenticação e provedores Any file
outputStyle Altere o papel, tom e formato de saída de Claude com um estilo de saída Modelo e respostas Any file
parentSettingsBehavior Aplique ou descarte restrições que um host SDK ou IDE passa quando você implanta configurações gerenciadas Configurações empresariais e gerenciadas Managed
permissionExplainerEnabled Removido na v2.1.257, junto com a explicação do comando Ctrl+E nos prompts de permissão de shell Configurações de config global Global config
permissions Defina regras de permissão, pergunta e negação e o modo de permissão inicial Configurações de permissão Any file
permissions.additionalDirectories Dê a Claude acesso a arquivos em diretórios fora do atual Configurações de permissão Any file
permissions.allow Aprove usos de ferramentas listados sem um prompt Configurações de permissão Any file
permissions.ask Sempre solicite antes de usos de ferramentas listados Configurações de permissão Any file
permissions.blockReadsOutsideWorkingDirectories Faça as ferramentas de arquivo recusarem leituras fora dos diretórios de trabalho em cada modo de permissão Configurações de permissão Any file
permissions.defaultMode Defina o modo de permissão em que novas sessões começam Configurações de permissão Any file
permissions.deny Bloqueie usos de ferramentas listados, incluindo leituras de arquivos que contêm segredos Configurações de permissão Any file
permissions.disableBypassPermissionsMode Impeça qualquer pessoa de entrar no modo bypassPermissions Configurações de permissão Any file
plansDirectory Escolha onde o modo de plano escreve arquivos de plano Memória e contexto Any file
pluginConfigs Armazene as respostas que você deu ao diálogo de configuração de um plugin Plugins e skills User or managed
pluginSuggestionMarketplaces Escolha quais marketplaces podem exibir sugestões de instalação de plugin em /plugin Plugins e skills Managed
pluginTrustMessage Adicione seu próprio texto ao aviso de confiança de plugin Plugins e skills Managed
policyHelper Execute um executável que calcula configurações gerenciadas na inicialização Configurações empresariais e gerenciadas Managed
policyHelper.path Nomeie o executável auxiliar que Claude Code executa Configurações empresariais e gerenciadas Managed
policyHelper.refreshIntervalMs Execute novamente o auxiliar em segundo plano em um intervalo Configurações empresariais e gerenciadas Managed
policyHelper.timeoutMs Defina quanto tempo Claude Code aguarda o auxiliar Configurações empresariais e gerenciadas Managed
preferredNotifChannel Escolha um sino de terminal ou notificação de desktop para conclusão de tarefa Remoto, desktop e notificações Any file
prefersReducedMotion Reduza ou desative animações de spinner, shimmer e flash Interface e terminal Any file
processWrapper Execute os processos em segundo plano de Claude Code através de um inicializador corporativo no macOS e Linux Agentes, sessões e worktrees User or managed
promptCacheTtl Escolha o tempo de vida do cache de prompt para a conversa principal Modelo e respostas Any file
promptSuggestionEnabled Oculte as sugestões de prompt acinzentadas na caixa de entrada Interface e terminal Any file
prUrlTemplate Aponte links de PR para uma ferramenta de revisão de código interna em vez de github.com Git e atribuição Any file
remote.defaultEnvironmentId Escolha o ambiente de nuvem padrão para claude --cloud; um ID ccpool_ auto-hospedado é somente leitura a partir de configurações de usuário e gerenciadas e --settings Remoto, desktop e notificações Any file
remoteControlAtStartup Conecte o Remote Control automaticamente quando uma sessão começar Remoto, desktop e notificações Any file
requiredMaximumVersion Recuse-se a iniciar em uma versão mais recente do que sua organização permite Atualizações e versionamento Managed
requiredMinimumVersion Recuse-se a iniciar em uma versão mais antiga do que sua organização exige Atualizações e versionamento Managed
respectGitignore Mantenha arquivos ignorados pelo git fora do seletor de arquivo @ Interface e terminal Any file
respondToBashCommands Impeça Claude de responder após um comando shell ! ser executado Interface e terminal Any file
sandbox Isole comandos Bash do seu sistema de arquivos e rede no macOS, Linux e WSL2 Configurações de sandbox Any file
sandbox.allowAppleEvents Permita que comandos em sandbox enviem Apple Events no macOS Configurações de sandbox User or managed
sandbox.allowUnsandboxedCommands Permita que Claude tente novamente um comando bloqueado fora do sandbox, ou proíba-o Configurações de sandbox Any file
sandbox.autoAllowBashIfSandboxed Execute comandos em sandbox sem um prompt de permissão Configurações de sandbox Any file
sandbox.bwrapPath Aponte o sandbox para um binário bubblewrap fora de PATH Configurações de sandbox Managed
sandbox.credentials Oculte ou mascare arquivos de credenciais e variáveis dentro do sandbox Configurações de sandbox Any file
sandbox.credentials.allowPlaintextInject Permita que credenciais mascaradas alcancem serviços HTTP simples em redes de teste confiáveis Configurações de sandbox User or managed
sandbox.credentials.awsPairs Vincule variáveis de chave AWS com nomes personalizados em uma credencial para re-assinatura Configurações de sandbox User or managed
sandbox.credentials.envVars Desdefina ou mascare uma variável de ambiente dentro do sandbox Configurações de sandbox Any file
sandbox.credentials.files Bloqueie ou mascare leituras de um arquivo de credenciais dentro do sandbox Configurações de sandbox Any file
sandbox.credentials.sigv4 Escolha se solicitações SigV4A AWS de streaming, pré-assinadas ou falham ou passam Configurações de sandbox User or managed
sandbox.enabled Ative o sandboxing de Bash no macOS, Linux e WSL2 Configurações de sandbox Any file
sandbox.enableWeakerNestedSandbox Execute o sandbox do Linux dentro de um contêiner sem privilégios Configurações de sandbox Any file
sandbox.enableWeakerNetworkIsolation Permita que gh, gcloud e terraform verifiquem TLS atrás de um proxy MITM dentro do sandbox no macOS Configurações de sandbox Any file
sandbox.excludedCommands Nomeie comandos que Claude Code pode executar fora do sandbox Configurações de sandbox Any file
sandbox.failIfUnavailable Recuse-se a iniciar quando o sandbox não puder, em vez de executar sem sandbox Configurações de sandbox Any file
sandbox.filesystem Controle quais caminhos comandos em sandbox podem ler e escrever Configurações de sandbox Any file
sandbox.filesystem.allowManagedReadPathsOnly Impeça desenvolvedores de reabrir caminhos de leitura que sua organização bloqueou Configurações de sandbox Managed
sandbox.filesystem.allowRead Reabra a leitura dentro de uma região que denyRead bloqueia Configurações de sandbox Any file
sandbox.filesystem.allowWrite Adicione caminhos que comandos em sandbox podem escrever Configurações de sandbox Any file
sandbox.filesystem.denyRead Bloqueie comandos em sandbox de ler caminhos específicos Configurações de sandbox Any file
sandbox.filesystem.denyWrite Bloqueie comandos em sandbox de escrever em caminhos específicos Configurações de sandbox Any file
sandbox.filesystem.disabled Desative o isolamento de sistema de arquivos mantendo o isolamento de rede Configurações de sandbox User or managed
sandbox.ignoreViolations Silencie relatórios de violação para caminhos que um comando deve sondar Configurações de sandbox Any file
sandbox.network Controle quais hosts, portas e sockets comandos em sandbox alcançam Configurações de sandbox Any file
sandbox.network.allowAllUnixSockets Permita que comandos em sandbox se conectem a cada socket Unix Configurações de sandbox Any file
sandbox.network.allowedDomains Pré-permita domínios para que comandos em sandbox não solicitem permissão para eles Configurações de sandbox Any file
sandbox.network.allowLocalBinding Permita que comandos em sandbox se vinculem a portas localhost no macOS Configurações de sandbox Any file
sandbox.network.allowMachLookup Permita que ferramentas macOS em sandbox como o iOS Simulator ou Playwright alcancem seus serviços XPC Configurações de sandbox Any file
sandbox.network.allowManagedDomainsOnly Bloqueie a lista de permissões de rede para configurações gerenciadas Configurações de sandbox Managed
sandbox.network.allowUnixSockets Liste caminhos de socket Unix que comandos em sandbox podem usar no macOS Configurações de sandbox Any file
sandbox.network.deniedDomains Bloqueie domínios para comandos em sandbox, mesmo dentro de um curinga permitido Configurações de sandbox Any file
sandbox.network.httpProxyPort Roteie o tráfego HTTP do sandbox através de seu próprio proxy Configurações de sandbox Any file
sandbox.network.socksProxyPort Roteie o tráfego SOCKS do sandbox através de seu próprio proxy Configurações de sandbox Any file
sandbox.network.strictAllowlist Negue hosts fora da lista de permissões em vez de solicitar Configurações de sandbox User or managed
sandbox.network.tlsTerminate Faça o sandbox fazer proxy terminar TLS para que possa ler solicitações HTTPS Configurações de sandbox User or managed
sandbox.ripgrep Use seu próprio binário ripgrep dentro do sandbox Configurações de sandbox User or managed
sandbox.socatPath Aponte o proxy do sandbox para um binário socat fora de PATH Configurações de sandbox Managed
showClearContextOnPlanAccept Mostre uma opção "limpar contexto" na tela de aceitação de plano Interface e terminal Any file
showThinkingSummaries Veja resumos do pensamento de Claude em vez de um stub recolhido Modelo e respostas Any file
showTurnDuration Oculte a duração "Cooked for" após cada resposta Interface e terminal Any file
skillListingBudgetFraction Reserve mais ou menos contexto para a listagem de skills Memória e contexto Any file
skillListingMaxDescChars Limite o comprimento da descrição de cada skill na listagem de skills Memória e contexto Any file
skillOverrides Oculte ou recolha uma skill sem editar seu SKILL.md Plugins e skills Any file
skipAutoPermissionPrompt Pule o aviso único que Claude Code mostra quando você entra no modo automático por conta própria em vez de através do padrão integrado Configurações de permissão User or managed
skipDangerousModePermissionPrompt Pule o diálogo de confirmação antes do modo bypassPermissions Configurações de permissão User, local, or managed
skipWebFetchPreflight Pule a verificação de nome de host WebFetch quando Anthropic estiver inacessível Privacidade e telemetria Any file
spellcheck Sublinhe palavras com erros de ortografia na entrada do prompt com um verificador de ortografia que você instala Interface e terminal User or managed
spinnerTipsEnabled Oculte dicas no spinner enquanto Claude trabalha Interface e terminal Any file
spinnerTipsOverride Adicione suas próprias dicas à rotação do spinner, ou substitua as dicas integradas Interface e terminal Any file
spinnerVerbs Adicione ou substitua os verbos mostrados enquanto uma volta é executada Interface e terminal Any file
sshConfigs Adicione conexões SSH ao dropdown de ambiente Desktop Remoto, desktop e notificações User or managed
sshHostAllowlist Limite quais hosts as sessões SSH do Desktop podem alcançar Remoto, desktop e notificações Managed
statusLine Execute seu próprio comando para renderizar uma linha de status abaixo do prompt Interface e terminal Any file
strictKnownMarketplaces Lista de permissões das fontes de marketplace que os usuários podem adicionar e instalar Plugins e skills Managed
strictPluginOnlyCustomization Bloqueie skills, agentes, hooks e servidores MCP de fontes de usuário e projeto Plugins e skills Managed
strictPluginOnlyCustomization.agents Restrinja agentes a fontes de plugin e gerenciadas Plugins e skills Managed
strictPluginOnlyCustomization.hooks Restrinja hooks a fontes de plugin e gerenciadas Plugins e skills Managed
strictPluginOnlyCustomization.mcp Restrinja servidores MCP a fontes de plugin e gerenciadas Plugins e skills Managed
strictPluginOnlyCustomization.skills Restrinja skills a fontes de plugin e gerenciadas Plugins e skills Managed
subagentPromptCacheTtl Escolha o tempo de vida do cache de prompt para subagentes e outras solicitações fora da conversa principal Modelo e respostas Any file
subagentStatusLine Reescreva linhas na exibição de tarefa do subagente com seu próprio comando Interface e terminal Any file
switchModelsOnFlag Alterne modelos automaticamente ou pause quando um classificador de segurança sinalizar uma solicitação Modelo e respostas Any file
syncClaudeAiPlugins Pare de carregar os plugins ativados em sua conta claude.ai e pare de baixar novos Plugins e skills User, local, or managed
syncClaudeAiSkills Pare de carregar as skills ativadas em sua conta claude.ai e pare de baixar novas Plugins e skills User, local, or managed
syntaxHighlightingDisabled Desative o destaque de sintaxe em diffs e blocos de código Interface e terminal Any file
taskOutputMaxChars Removido na v2.1.277, junto com a ferramenta TaskOutput que dimensionava Memória e contexto Any file
teammateDefaultModel Removido na v2.1.234; veja Especificar companheiros de equipe e modelos para como Claude Code escolhe o modelo de um companheiro de equipe Configurações de config global Global config
teammateMode Escolha como companheiros de equipe de agente exibem Agentes, sessões e worktrees Any file
terminalProgressBarEnabled Oculte a barra de progresso do terminal em terminais que a suportam Interface e terminal Any file
terminalTitleFromRename Impeça /rename e --name de alterar o título da aba do terminal Interface e terminal Any file
theme Escolha o tema de cor da interface, integrado ou personalizado Interface e terminal Any file
timeFormat Mostre os horários na interface em um relógio de 12 horas ou 24 horas, em UTC, ou com um padrão strftime Interface e terminal Any file
timeZone Mostre os horários na interface em um fuso horário diferente do seu sistema Interface e terminal Any file
tui Escolha o renderizador tela cheia ou terminal clássico Interface e terminal Any file
ultracode Faça Claude planejar um workflow para cada tarefa substancial sem ser solicitado Modelo e respostas Any file
useAutoModeDuringPlan Permita que o classificador de modo automático revise comandos shell no modo de plano; defina false para obter prompts em vez disso Configurações de permissão User, local, or managed
verbose Mostre a saída completa da ferramenta em vez de resumos truncados; viewMode tem precedência quando ambos estão definidos Interface e terminal Any file
viewMode Inicie cada sessão na visualização padrão, detalhada ou focada Interface e terminal Any file
vimInsertModeRemaps Mapeie uma sequência de modo INSERT de duas teclas como jj para Escape Interface e terminal User or managed
voice Ative a ditação por voz e escolha modo de manutenção ou toque Interface e terminal Any file
voiceEnabled Ative a ditação por voz com a forma de chave única mais antiga Interface e terminal Any file
wheelScrollAccelerationEnabled Desative a aceleração de roda do mouse na renderização em tela cheia Interface e terminal Any file
workflowKeywordTriggerEnabled Permita que a palavra ultracode em um prompt inicie um workflow; defina false para digitá-la sem iniciar um Hooks e automação Any file
workflowSizeGuideline Defina a contagem de agentes que Claude visa em workflows dinâmicos Hooks e automação Any file
worktree Configure como Claude Code cria git worktrees Agentes, sessões e worktrees Any file
worktree.baseRef Ramifique novos worktrees a partir do branch padrão remoto ou seu HEAD local Agentes, sessões e worktrees Any file
worktree.bgIsolation Permita que sessões em segundo plano editem a cópia de trabalho sem um worktree Agentes, sessões e worktrees Any file
worktree.sparsePaths Verifique apenas os diretórios que você precisa em cada worktree Agentes, sessões e worktrees Any file
worktree.symlinkDirectories Crie symlinks de diretórios grandes em cada worktree em vez de duplicá-los Agentes, sessões e worktrees Any file
wslInheritsWindowsSettings Faça WSL ler configurações gerenciadas da cadeia de política do Windows Configurações empresariais e gerenciadas Managed

Modelo e respostas

Escolha quais modelos o Claude Code usa e como ele responde. Para saber como essas configurações interagem com o comando /model e variáveis de ambiente, consulte Configuração de modelo.

`advisorModel`

Escolha qual modelo responde quando Claude chama a ferramenta advisor do lado do servidor. Deixe-a sem definir para desativar o advisor. O advisor deve ser pelo menos tão capaz quanto seu modelo principal. Consulte Escolha um modelo advisor para os emparelhamentos aceitos e o que acontece quando você escolhe um que não é aceito.

Você normalmente não edita essa chave manualmente. Execute /advisor para abrir um seletor que mostra a escolha atual, os modelos que podem aconselhar e Sem advisor. Claude Code salva sua escolha nessa chave em ~/.claude/settings.json. Se você escolher em um cliente Remote Control ou em uma sessão anexada a um worker remoto, a escolha se aplica apenas a essa sessão e não altera essa chave.

Se sua conta exigir o consentimento de créditos de uso, aceite-o primeiro executando /model fable. Até fazer isso, escolher Fable em /advisor não salva nada e Claude Code diz para executar /model fable primeiro.

  • Escopo: Qualquer arquivo
  • Tipo: string, um dos aliases "fable", "opus" ou "sonnet", que resolvem para a versão padrão atual do Claude Code dessa família de modelos, ou um ID de modelo completo como "claude-opus-5-5"
  • Padrão: sem definir, então o advisor está desativado
  • Substituições por sessão: --advisor tem precedência sobre essa chave para uma sessão. CLAUDE_CODE_DISABLE_ADVISOR_TOOL desativa o advisor, e essa chave não pode ativá-lo novamente
{
  "advisorModel": "opus"
}

A chave não tem efeito em provedores onde o advisor não está disponível, como Amazon Bedrock e Claude Platform na AWS. "fable" requer acesso a Fable.

`alwaysThinkingEnabled`

Desative o pensamento estendido para cada sessão definindo isso como false. O pensamento está ativado por padrão, então true não muda nada. A maioria das pessoas define isso através de /config em vez de editar o arquivo.

Em modelos que sempre pensam, como Opus 5.5 e os modelos Fable, false não tem efeito. Em provedores de terceiros, Claude Code omite o parâmetro thinking em vez de desativar o pensamento, então modelos de raciocínio adaptativo podem ainda pensar. Com o pensamento desativado na API Anthropic, Claude Code envia esforço high em vez de um nível superior para modelos que sabe não aceitam essa combinação, como Opus 5.

  • Escopo: Qualquer arquivo
  • Tipo: Boolean
    • true: sem efeito; o pensamento já está ativado
    • false: Claude Code desativa o pensamento estendido para cada sessão
  • Padrão: sem definir, então o pensamento está ativado para modelos que o suportam
  • Substituições por sessão: MAX_THINKING_TOKENS tem precedência sobre essa chave para uma sessão: 0 desativa o pensamento, sob os mesmos limites de modelo e provedor que false, e um valor positivo ativa o pensamento mesmo quando essa chave é false. Em modelos de raciocínio adaptativo, o número em si é ignorado
{
  "alwaysThinkingEnabled": false
}

`availableModels`

Restrinja quais modelos as pessoas podem selecionar para a sessão principal, subagentes, skills e o advisor. Uma lista gerenciada restringe /model, --model e a chave model nos próprios arquivos de um desenvolvedor; um modelo fora dela não pode ser selecionado. Por si só, isso não afeta a opção Padrão; combine-o com enforceAvailableModels para isso.

  • Escopo: Qualquer arquivo. Implante-o em configurações gerenciadas para aplicá-lo a uma organização.
  • Tipo: array de aliases de modelo ou IDs
  • Padrão: sem definir, então cada modelo está disponível

Este exemplo permite que as pessoas selecionem apenas modelos Sonnet e Haiku:

{
  "availableModels": ["sonnet", "haiku"]
}

Consulte Restrinja a seleção de modelo.

`effortLevel`

Defina um nível de esforço padrão para modelos para os quais você não salvou um nível. Níveis mais baixos são mais rápidos e mais baratos em tarefas diretas, e níveis mais altos raciocinam mais profundamente em problemas complexos.

Quando você executa /effort low, medium, high ou xhigh em uma sessão interativa em sua máquina, Claude Code salva o nível para o modelo ativo em modelSettings em vez de escrever essa chave. Antes da v2.1.251, /effort escrevia essa chave.

Dentro do mesmo arquivo de configurações, Claude Code usa o nível salvo de um modelo em vez dessa chave. modelSettings indica a precedência entre arquivos.

Em uma sessão anexada a um worker remoto, em uma execução -p e no Agent SDK, /effort se aplica apenas a essa sessão. Ajuste o nível de esforço lista as escolhas interativas que também se aplicam apenas a essa sessão. A mensagem que /effort imprime diz qual aconteceu.

  • Escopo: Qualquer arquivo
  • Tipo: string, um de:
    • "low": o mínimo de raciocínio, para tarefas curtas, delimitadas, sensíveis à latência que não são sensíveis à inteligência
    • "medium": reduz o uso de tokens para trabalho sensível a custos que pode fazer trade-off de alguma inteligência
    • "high": equilibra o uso de tokens e inteligência
    • "xhigh": raciocínio mais profundo com maior gasto de tokens
  • Padrão: sem definir
  • Substituições por sessão: --effort tem precedência sobre essa chave para uma sessão, e CLAUDE_CODE_EFFORT_LEVEL tem precedência sobre ambas
{
  "effortLevel": "xhigh"
}

Em suas configurações de usuário, ~/.claude/settings.json, essa chave é a forma mais antiga que /effort escrevia antes de salvar níveis por modelo, e continua se aplicando onde se aplicava antes, em Opus 5, Fable 5.1 e modelos anteriores. Opus 5.5 e modelos lançados após ele a ignoram e começam em seu próprio padrão até você salvar um nível para eles, que /effort escreve em modelSettings. Em configurações de projeto, local e gerenciada, e com --settings, essa chave se aplica a cada modelo.

`enforceAvailableModels`

O seletor /model tem uma opção Padrão que resolve para seu modelo padrão da organização quando um se aplica, e caso contrário para o padrão do seu tipo de conta. Uma lista de permissões availableModels limita os modelos que você pode nomear, mas por si só deixa Padrão sozinho, então Padrão ainda pode resolver para um modelo fora da lista. Esta chave fecha essa lacuna. Requer Claude Code v2.1.175 ou posterior.

Quando sua organização implanta qualquer configuração gerenciada, Claude Code lê essa chave apenas da fonte gerenciada e a ignora em seus outros arquivos.

  • Escopo: Qualquer arquivo
  • Tipo: Boolean
    • true: quando Padrão resolveria para um modelo fora de availableModels, Claude Code o resolve para o primeiro modelo disponível na lista
    • false: Padrão resolve como usual, mesmo para um modelo fora de availableModels
  • Padrão: false

Este exemplo restringe seleções nomeadas a modelos Sonnet e Haiku e faz Padrão resolver para o primeiro deles que está disponível:

{
  "availableModels": ["sonnet", "haiku"],
  "enforceAvailableModels": true
}

Esta chave não tem efeito quando availableModels está sem definir ou vazio. Consulte Aplique a lista de permissões ao modelo Padrão. Requer Claude Code v2.1.175 ou posterior.

`fallbackModel`

Nomeie modelos de backup para Claude Code tentar, em ordem, quando seu modelo principal está sobrecarregado ou indisponível. Claude Code muda para o próximo modelo disponível na cadeia para o resto da volta e mostra um aviso. Sem uma cadeia, Claude Code tenta novamente o mesmo modelo e depois exibe o erro do servidor, e você tenta novamente ou muda de modelos você mesmo.

Uma mudança significa uma volta com um cache de prompt frio no modelo de fallback; sua próxima mensagem tenta o modelo principal primeiro novamente.

  • Escopo: Qualquer arquivo
  • Tipo: array de aliases de modelo ou IDs; "default" expande para o modelo padrão
  • Padrão: sem definir, então uma solicitação falhada não é tentada novamente em outro modelo
  • Substituições por sessão: --fallback-model tem precedência sobre essa chave para uma sessão

Este exemplo tenta Sonnet 5 primeiro, depois Haiku 4.5, quando seu modelo principal falha:

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

Diferentemente da maioria das configurações de array, essa chave não mescla entre arquivos de configurações: o arquivo de maior precedência que a define fornece toda a cadeia. Se seu arquivo de projeto define ["claude-sonnet-5"] e seu arquivo de usuário define ["claude-haiku-4-5"], a cadeia é apenas ["claude-sonnet-5"]. Claude Code mantém no máximo três modelos distintos permitidos da lista e ignora o resto. Consulte Cadeias de modelo de fallback.

`fastMode`

Ative o modo rápido para sessões onde está disponível, para trabalho interativo como iteração rápida ou depuração ao vivo onde você quer velocidade a um custo mais alto por token. Você normalmente não edita essa chave manualmente: executar /fast escreve fastMode: true em ~/.claude/settings.json, e executá-lo novamente para desativar o modo rápido remove a chave. O modo rápido funciona apenas em Opus 5.5, Opus 5 e Opus 4.8: ativá-lo de outro modelo o muda para Opus, e mudar para um modelo não suportado o desativa. Consulte Mude de modelos enquanto o modo rápido está ativado.

  • Escopo: Qualquer arquivo
  • Tipo: Boolean
    • true: Claude Code ativa o modo rápido para sessões onde está disponível
    • false: o modo rápido permanece desativado
  • Padrão: sem definir, então o modo rápido está desativado
  • Substituições por sessão: CLAUDE_CODE_DISABLE_FAST_MODE desativa o modo rápido para uma sessão, e essa chave não pode ativá-lo novamente
{
  "fastMode": true
}

`fastModePerSessionOptIn`

Normalmente, executar /fast salva fastMode nas configurações de usuário de uma pessoa, então o modo rápido está ativado no início de cada sessão posterior. Defina essa chave como true para parar isso: um fastMode: true salvo não ativa mais o modo rápido no início da sessão, e cada pessoa tem que executar /fast em cada sessão que o quer. Claude Code deixa a chave fastMode em seu arquivo, então desativar essa chave restaura o comportamento antigo.

Proprietários em planos Team ou Enterprise podem implantá-lo em toda a organização através de configurações gerenciadas pelo servidor. Quando as configurações gerenciadas definem a chave, /fast on é recusado fora de sessões de terminal interativas e relata que sua organização desativou o modo rápido. Isso cobre modo não interativo, a extensão VS Code e sessões na nuvem.

  • Escopo: Qualquer arquivo
  • Tipo: Boolean
    • true: um fastMode: true salvo não ativa mais o modo rápido no início da sessão, então cada pessoa executa /fast em cada sessão que o quer; um fastMode: true passado com --settings ainda conta para essa sessão a menos que as configurações gerenciadas definam essa chave
    • false: um fastMode: true salvo ativa o modo rápido no início de cada sessão posterior
  • Padrão: false
{
  "fastModePerSessionOptIn": true
}

Consulte Exija opt-in por sessão.

`language`

Faça Claude responder em um idioma diferente do inglês por padrão. Não há lista fixa para respostas: Claude Code passa o valor verbatim para Claude como uma instrução para sempre responder nesse idioma, então qualquer nome de idioma que Claude possa ler funciona. Claude Code não verifica o valor, então um nome digitado incorretamente chega a Claude como escrito em vez de produzir um erro. O mesmo valor define o idioma para ditado de voz, que tem uma lista fixa de idiomas de ditado suportados, e para títulos de sessão gerados automaticamente.

  • Escopo: Qualquer arquivo
  • Tipo: string, qualquer nome de idioma, como "japanese", "spanish" ou "french"; Claude Code não o valida
  • Padrão: sem definir; os títulos de sessão então correspondem ao idioma de sua conversa
{
  "language": "japanese"
}

`maxEffortLevel`

Limite o nível de esforço que uma sessão pode usar, deixando níveis mais baixos disponíveis. Qualquer nível mais alto funciona no limite em vez disso, incluindo um de /effort, o seletor /model, --effort, CLAUDE_CODE_EFFORT_LEVEL, a frontmatter effort de uma skill ou subagente, ou o padrão do próprio modelo. Claude Code aplica o limite em si antes de cada solicitação, então ele se mantém em cada provedor, incluindo Amazon Bedrock, Agent Platform do Google Cloud e Microsoft Foundry. Requer Claude Code v2.1.267 ou posterior.

  • Escopo: Qualquer arquivo. Implante-o em configurações gerenciadas para aplicá-lo a uma organização. Quando vários escopos definem um limite, o mais baixo se aplica, então um limite definido em um escopo não pode ser aumentado de outro
  • Tipo: string, um de "low", "medium", "high", "xhigh" ou "max". Um valor "max" não define limite
  • Padrão: sem definir, então nenhum limite se aplica
  • Efeito no ultracode: um limite abaixo de xhigh torna ultracode indisponível nos modelos aos quais o limite se aplica
  • Limites por modelo: adicione maxEffortLevel à entrada modelSettings de um modelo. Essa entrada substitui essa chave apenas para o modelo dentro da fonte de configurações que define ambas, como suas configurações de usuário ou uma fonte gerenciada. Defina "max" lá para isentar o modelo do limite dessa fonte; Claude Code ainda aplica limites de outras fontes

Este exemplo limita cada modelo a medium e isenta Sonnet 4.6:

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

Quando sua organização também define um limite de esforço para um modelo, o menor dos dois limites se aplica.

`model`

Defina o modelo que cada nova sessão usa, então você não tem que escolher um com /model cada vez. Defini-lo aqui não o impede de mudar no meio da sessão. Se seu admin definiu um modelo padrão da organização para substituir a seleção do usuário, você obtém esse modelo mesmo quando define essa chave em configurações de usuário, projeto ou local.

  • Escopo: Qualquer arquivo
  • Tipo: string, um alias de modelo ou ID de modelo completo
  • Padrão: sem definir, então Claude Code usa o modelo padrão de sua conta
  • Substituições por sessão: --model tem precedência sobre ANTHROPIC_MODEL, e ambos têm precedência sobre essa chave para uma sessão, incluindo sobre um model gerenciado; uma lista availableModels ainda se aplica à escolha
{
  "model": "claude-sonnet-5"
}

Um valor aqui supera ANTHROPIC_DEFAULT_MODEL, que Claude Code usa apenas quando nada mais seleciona um modelo.

`modelOverrides`

Mapeie IDs de modelo Anthropic para IDs de modelo específicos do provedor, como ARNs de perfil de inferência do Amazon Bedrock. Cada entrada do seletor de modelo então usa seu valor mapeado ao chamar a API do provedor. Administradores usam isso em Amazon Bedrock, Agent Platform do Google Cloud e Microsoft Foundry para rotear cada versão de modelo para um perfil de inferência específico, nome de versão ou implantação para governança, alocação de custos ou roteamento regional.

  • Escopo: Qualquer arquivo
  • Tipo: objeto mapeando ID de modelo para ID de modelo do provedor
  • Padrão: sem definir

Este exemplo roteia cada chamada para Opus 4.6 para o perfil de inferência Bedrock nomeado:

{
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456789012:inference-profile/example"
  }
}

Consulte Substitua IDs de modelo por versão.

`modelPicker`

Liste os modelos que o seletor /model oferece, na ordem que você os escreve e sob rótulos que você escolhe, então o seletor lista os modelos que sua organização executa, após o lineup integrado ou em vez dele. O model de cada linha é tomado verbatim, então aceita qualquer coisa que --model aceita: um alias como opus, um ID de modelo Anthropic ou um ID de formato de provedor para Amazon Bedrock, Agent Platform do Google Cloud, Microsoft Foundry ou um gateway LLM. Requer Claude Code v2.1.242 ou posterior.

  • Escopo: Usuário ou gerenciado. Claude Code lê a chave de configurações gerenciadas, --settings e configurações de usuário, e a ignora em configurações de projeto e local para que um repositório que você clone não possa rotular novamente o seletor. O maior dos três que define a chave fornece todo o lineup, e Claude Code nunca combina lineups de duas fontes.
  • Tipo: objeto com um array options de linhas e um Boolean replaceBuiltInOptions opcional
  • Padrão: sem definir, então o seletor mostra o lineup integrado

Este exemplo adiciona duas implantações Bedrock após o lineup integrado, sob nomes que sua equipe reconhece:

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}

Campos para `modelPicker`

A chave leva dois campos, um para as linhas em si e outro para se elas substituem o lineup integrado ou o adicionam.

Campo Tipo O que faz
options array de linhas, cada uma com um model obrigatório e um label e description opcionais As linhas que o seletor mostra, nesta ordem, exceto que uma linha acinzentada se move para o final. Sem um label, Claude Code intitula a linha com o nome integrado para um modelo que conhece, ou o ID do modelo caso contrário, e sem uma description escreve uma segunda linha genérica
replaceBuiltInOptions Boolean, padrão false Defina como true para mostrar apenas essas linhas, Padrão e uma linha para o modelo que a sessão já está usando. Deixe sem definir para adicionar essas linhas após o lineup integrado

Com replaceBuiltInOptions ativado, Claude Code oculta todas as outras linhas: o lineup integrado, as linhas que adiciona para entradas availableModels, os modelos que descoberta de gateway encontrou e ANTHROPIC_CUSTOM_MODEL_OPTION. Com ele desativado, Claude Code pula um modelo listado que o lineup integrado já cobre. Um rótulo muda o que o seletor mostra, não qual modelo Claude Code executa.

Uma lista de permissões availableModels ainda se aplica a essas linhas. Antes de adicionar um modelo listado à lista de permissões, leia Comportamento de mesclagem: um ID de modelo específico estreita a entrada curinga de sua família. Claude Code também verifica cada linha contra a sessão antes de mostrar o seletor:

  • Descartada: uma linha que Claude Code não pode servir, como um modelo aposentado ou um modelo ao qual sua organização não tem acesso
  • Acinzentada: uma linha que você não pode selecionar ainda, mostrada com o motivo
  • Nenhuma linha sobrevive: Claude Code mantém o lineup integrado, filtrado pela lista de permissões como usual

Claude Code descarta uma linha que não pode analisar e mantém o resto. Consulte Corrija um arquivo de configurações quebrado.

`modelPricing`

Relate gastos nas taxas que sua organização paga em vez de preço de lista. Defina-o quando sua organização tem taxas contratadas, então os valores em dólares que os desenvolvedores veem correspondem à sua fatura. Claude Code aplica as taxas em /usage, a linha de status, o total_cost_usd do Agent SDK, o limite --max-budget-usd e a métrica de custo OpenTelemetry e eventos. Você fornece as taxas: Claude Code não as lê de seu contrato ou do Claude Console. Requer Claude Code v2.1.242 ou posterior.

  • Escopo: Gerenciado. Implante a chave através de configurações gerenciadas pelo servidor, uma política MDM, um arquivo managed-settings.json ou um auxiliar de política. Claude Code a ignora em configurações de usuário, projeto e local, em --settings e no Windows no registro HKCU gravável pelo usuário. Com configurações gerenciadas pelo servidor, cada sessão relata custos ao preço de lista até que a busca de configurações dessa sessão tenha confirmado a configuração. Um aplicativo host que incorpora Claude Code e define CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST pode fornecer uma tabela própria através da opção SDK managedSettings, que Claude Code usa apenas quando nenhuma fonte gerenciada define a chave e apenas em Claude Code v2.1.246 ou posterior.
  • Tipo: objeto com um multiplier opcional e um mapa overrides opcional
  • Padrão: sem definir, então Claude Code relata preço de lista a menos que um aplicativo host forneça uma tabela

Defina multiplier sozinho para um desconto fixo, overrides sozinho para taxas por modelo ou ambos.

Este exemplo define taxas contratadas para Sonnet 4.6 e depois reduz cada figura, a linha Sonnet incluída, em 15%:

{
  "modelPricing": {
    "multiplier": 0.85,
    "overrides": {
      "claude-sonnet-4-6": {
        "input": 2.4,
        "output": 12,
        "cacheRead": 0.24,
        "cacheWrite": 3
      }
    }
  }
}

Defina multiplier acima de 1, até 10, para marcar cada figura para cima. Uma marcação requer Claude Code v2.1.271 ou posterior. Versões anteriores ignoram um multiplier acima de 1 com um aviso e mantêm o resto da configuração.

Para as etapas, incluindo como confirmar que as taxas estão em vigor, consulte Relate gastos em suas taxas contratadas.

Campos para `modelPricing`

Campo Tipo O que faz
multiplier número maior que 0 e no máximo 10 Dimensiona cada custo que Claude Code calcula, independentemente de uma linha overrides cobri-lo. Abaixo de 1 é um desconto, acima de 1 uma marcação
overrides mapa de ID de modelo para um objeto de taxa com input, output, cacheRead e cacheWrite, cada um de 0 a 10000 As taxas USD-por-milhão-de-tokens para esse modelo, todos os quatro obrigatórios. cacheWrite cobre tanto gravações de cache de cinco minutos quanto de uma hora. Consulte Quais modelos uma linha modelPricing se aplica a

Claude Code usa as taxas de uma linha exatamente como você as escreveu, sem adicionar a sobretaxa do modo rápido ou a taxa de inferência apenas para EUA. Se você também definir multiplier, Claude Code a aplica no topo das taxas da linha. Claude Code descarta uma linha com uma taxa que não pode analisar ou um multiplier que não pode analisar e mantém o resto; consulte Corrija um arquivo de configurações quebrado.

Quais modelos uma linha `modelPricing` se aplica a

Claude Code decide quais modelos uma linha se aplica a partir da chave da linha:

  • ID de um modelo integrado: uma chave que Claude Code usa para um modelo integrado, independentemente de essa chave ser o próprio ID do modelo, como claude-sonnet-4-6, ou seu ID Bedrock, Agent Platform ou Foundry. Claude Code aplica a linha a cada ID de snapshot datado e ID específico do provedor desse modelo.
  • Qualquer outra chave: uma chave que não é o ID de um modelo integrado, como um alias de modelo de gateway. Claude Code aplica a linha apenas a esse ID. Quando um ID de modelo corresponde exatamente a uma de suas chaves e também se enquadra em uma linha com chave de ID de modelo integrado, Claude Code usa a correspondência exata.
  • Um perfil de inferência de aplicação Bedrock: uma vez que Claude Code resolveu o perfil para o modelo ao qual roteia, através de seu mapa modelOverrides ou da busca bedrock:GetInferenceProfile, Claude Code aplica a linha desse modelo ao perfil.

`modelSettings`

Salve um nível de esforço para cada modelo que você usa. Requer Claude Code v2.1.251 ou posterior.

Em uma sessão interativa em sua máquina, quando você salva low, medium, high ou xhigh como seu padrão com /effort ou o controle deslizante de esforço do seletor /model, Claude Code escreve esse nível aqui sob o modelo que você está usando, então você raramente edita essa chave você mesmo. Quando você escolhe um desses níveis no seletor de modelo da extensão VS Code, Claude Code salva-o aqui da mesma forma. A entrada effortLevel lista as sessões onde /effort se aplica apenas a essa sessão.

Edite a chave manualmente para alterar ou remover um nível que você salvou.

Um effortLevel de um modelo aqui tem precedência sobre o effortLevel de nível superior no mesmo arquivo de configurações. Entre arquivos, Claude Code resolve cada modelo separadamente: o arquivo de configurações de maior precedência settings file que define um effortLevel para esse modelo ou o effortLevel de nível superior que se aplica a esse modelo decide, então um effortLevel em configurações gerenciadas supera um nível que você salvou em configurações de usuário. Ajuste o nível de esforço lista o que mais pode substituir um nível salvo, como --effort no lançamento.

Para limitar o esforço de um modelo em vez de definir seu nível, adicione um campo maxEffortLevel à entrada desse modelo. O campo requer Claude Code v2.1.267 ou posterior.

  • Escopo: Qualquer arquivo
  • Tipo: objeto mapeando um nome de modelo para um objeto com um campo effortLevel, um de "low", "medium", "high" ou "xhigh", um campo maxEffortLevel ou ambos
  • Padrão: sem definir

Claude Code escreve cada entrada sob o nome canônico do modelo, como claude-opus-5-5, e corresponde ao alias desse modelo, com sufixo de data, [1m] e IDs específicos do provedor reconhecidos à mesma entrada.

Este exemplo mantém Opus 5.5 em high enquanto outros modelos usam seus próprios níveis salvos ou padrão:

{
  "modelSettings": {
    "claude-opus-5-5": {
      "effortLevel": "high"
    }
  }
}

Execute /effort auto para limpar seu nível salvo para o modelo que você está usando. Claude Code deixa as outras entradas e qualquer effortLevel de nível superior em vigor.

`outputStyle`

Selecione um estilo de saída por nome. Um estilo de saída é um conjunto salvo de instruções que muda o papel, tom e formato de saída de Claude, como os estilos Explanatory e Learning integrados ou um que você escreveu você mesmo.

Se você alterar essa chave durante uma sessão, Claude usa o novo estilo começando com sua próxima mensagem. Para o que essa mensagem custa em cache de prompt, consulte Alterando estilo de saída. Antes da v2.1.251, a edição se aplicava apenas depois que você executava /clear ou iniciava uma nova sessão.

Este exemplo seleciona o estilo Explanatory integrado, que adiciona insights educacionais entre tarefas:

{
  "outputStyle": "Explanatory"
}

`promptCacheTtl`

Escolha quanto tempo o cache de prompt mantém a conversa principal. Esta chave se aplica a suas voltas interativas, -p e Agent SDK, juntamente com os auxiliares que Claude Code executa inline com elas. A vida útil de uma hora mantém o cache aquecido entre pausas mais longas, e a API cobra cada gravação de cache a uma taxa mais alta do que na vida útil de cinco minutos. Requer Claude Code v2.1.242 ou posterior.

Este exemplo mantém a conversa principal na vida útil de uma hora e deixa subagentes em cinco minutos:

{
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "5m"
}

Para o que cada vida útil custa, consulte Vida útil do cache.

`showThinkingSummaries`

Veja resumos do pensamento estendido de Claude em sessões interativas. Defina-o se você quer os resumos completos quando expande o pensamento com Ctrl+O. Quando sem definir ou false, a API Anthropic redige blocos de pensamento e Claude Code mostra um stub recolhido; provedores de terceiros não redagem.

  • Escopo: Qualquer arquivo
  • Tipo: Boolean
    • true: você vê resumos completos de pensamento quando expande o pensamento com Ctrl+O
    • false: a API Anthropic redige blocos de pensamento e Claude Code mostra um stub recolhido
  • Padrão: false
{
  "showThinkingSummaries": true
}

A redação muda apenas o que você vê, não o que o modelo gera. Para reduzir o gasto de pensamento, reduza o orçamento ou desative o pensamento em vez disso.

`subagentPromptCacheTtl`

Escolha quanto tempo o cache de prompt mantém as solicitações que Claude Code faz fora da conversa principal. Esta chave se aplica a subagentes, workflows e as próprias solicitações de background e auxiliar de Claude Code, como compactação e títulos de sessão. A vida útil de uma hora mantém o cache aquecido entre pausas mais longas, e a API cobra cada gravação de cache a uma taxa mais alta do que na vida útil de cinco minutos. Requer Claude Code v2.1.242 ou posterior.

Este exemplo dá aos subagentes e às outras solicitações fora da conversa principal a vida útil de uma hora:

{
  "subagentPromptCacheTtl": "1h"
}

Esta chave cobre as solicitações que promptCacheTtl não cobre, então defina ambas para escolher uma vida útil para cada solicitação que Claude Code faz. Para como o cache de um subagente difere do cache da conversa principal, consulte Subagentes e o cache.

`switchModelsOnFlag`

Escolha o que acontece quando um classificador de segurança sinaliza uma solicitação: mude para o modelo de fallback e continue, ou pause para que você possa escolher entre mudar e editar o prompt.

  • Escopo: Qualquer arquivo. Aparece em /config como Mude de modelos quando uma mensagem é sinalizada.
  • Tipo: Boolean
    • true: Claude Code muda para o modelo de fallback e continua
    • false: em uma sessão interativa Claude Code pausa para que você possa escolher entre mudar e editar o prompt; onde nenhum diálogo pode mostrar, como uma execução -p, a solicitação sinalizada termina como um erro
  • Padrão: true, mude automaticamente
{
  "switchModelsOnFlag": false
}

Consulte Pergunte antes de mudar.

`ultracode`

Inicie sessões com ultracode ativado. Com ele ativado, Claude planeja um workflow para cada tarefa substancial em vez de esperar você pedir. Claude planeja workflows apenas quando workflows dinâmicos estão habilitados para você, seu modelo suporta esforço xhigh e nenhum limite de esforço abaixo de xhigh se aplica. De qualquer forma, ultracode: true executa a sessão em esforço xhigh ou no limite quando um limite de esforço é mais baixo. Claude Code lê essa chave mas nunca a escreve: /effort ultracode ativa ultracode apenas para a sessão atual.

  • Escopo: Qualquer arquivo
  • Tipo: Boolean
    • true: sessões começam em esforço xhigh, com ultracode ativado quando workflows dinâmicos estão habilitados para você, seu modelo suporta xhigh e nenhum limite de esforço está abaixo de xhigh
    • false: sessões começam com ultracode desativado
  • Padrão: sem definir, então ultracode está desativado
  • Substituições por sessão: /effort ultracode ativa ultracode para uma sessão sem essa chave. O sinalizador --effort ultracode também o ativa para uma sessão e requer Claude Code v2.1.203 ou posterior
{
  "ultracode": true
}

Ultracode executa a sessão em esforço xhigh e tem precedência sobre effortLevel e entradas modelSettings. Se um limite de esforço abaixo de xhigh se aplica ao modelo, como uma configuração maxEffortLevel, a sessão executa no limite em vez disso e ultracode permanece desativado. Claude então não planeja workflows por conta própria, e /effort não oferece ultracode. Uma solicitação de controle apply_flag_settings do Agent SDK também aceita a chave.

Configurações de permissão

Decida o que Claude pode fazer sem perguntar, em qual modo de permissão uma sessão começa e o que o classificador do modo automático permite. Para a sintaxe de regras e o modelo de permissão, consulte Configurar permissões.

`allowManagedPermissionRulesOnly`

Torne as configurações gerenciadas a única fonte de regras de permissão. Claude Code então ignora as regras allow, ask e deny em arquivos de usuário, projeto, local e --settings, ignora --allowedTools, oculta as opções de sempre permitir nos prompts de permissão e para de salvar novas regras.

Quando configurações pai de um host de incorporação se aplicam, Claude Code as trata como parte da camada gerenciada. Ele descarta suas regras allow e additionalDirectories, e mantém suas regras deny e ask exceto regras Read e Edit cujo padrão começa com !. Um host não pode esculpir caminhos fora das regras gerenciadas com uma regra !, independentemente de você definir esta chave.

As regras --disallowedTools e as regras deny e ask da sessão atual ainda se aplicam, inclusive após Claude Code recarregar as configurações no meio da sessão. Elas apenas restringem, portanto não podem ampliar o que as regras gerenciadas concedem. Antes da v2.1.257, Claude Code descartava essas regras de linha de comando e de sessão no primeiro recarregamento de configurações.

Para o que um padrão ! em uma regra --disallowedTools ou de sessão pode esculpir, consulte Regras Read e Edit.

  • Escopo: Managed
  • Tipo: Booleano
    • true: as configurações gerenciadas se tornam a única fonte de regras de permissão
    • false: Claude Code aplica regras de permissão de arquivos de usuário, projeto, local e --settings além das gerenciadas
  • Padrão: não definido, portanto Claude Code aplica regras de permissão de configurações de usuário, projeto e local e de --settings, além das gerenciadas
{
  "allowManagedPermissionRulesOnly": true
}

Esta chave não bloqueia a lista de permissões do servidor MCP; para isso, defina allowManagedMcpServersOnly. Consulte Configurações apenas gerenciadas.

`autoMode`

Adicione suas próprias regras ao que o classificador do modo automático bloqueia e permite. Use-o para informar ao classificador quais repositórios, buckets e domínios sua organização confia, para que ele pare de bloquear operações internas rotineiras. O classificador é fornecido com regras de permissão e bloqueio integradas. Inclua a string literal "$defaults" em um array para manter essas regras integradas nessa posição e adicione as suas ao redor; deixe-a de fora para substituí-las pelas suas.

Este exemplo mantém as regras soft_deny integradas, através de "$defaults", e adiciona uma mais que bloqueia terraform apply:

{
  "autoMode": {
    "soft_deny": ["$defaults", "Never run terraform apply"]
  }
}

Quando mais de um desses arquivos define o mesmo array, Claude Code concatena as entradas. Para o formato de regra e como cada array é aplicado, consulte Configurar modo automático.

`autoMode.classifyAllShell`

Envie cada comando Bash e PowerShell através do classificador do modo automático enquanto o modo automático está ativo. Por padrão, o modo automático suspende apenas regras de permissão que poderiam executar código arbitrário: regras de ferramenta inteira e curinga como Bash(*), e prefixos de interpretador ou wrapper de shell como Bash(python *). Um comando que qualquer outra regra de permissão corresponde, como Bash(npm test), pula o classificador a menos que ele carregue domínios permitidos por comando. Quando pula, um argumento destrutivo que o prefixo da regra não antecipou pode passar despercebido. Definir esta chave suspende cada regra de shell de permissão para a sessão para que o classificador veja cada comando. Requer Claude Code v2.1.193 ou posterior.

  • Escopo: User or managed. Leia onde autoMode é lido.
  • Tipo: Booleano
    • true: enquanto o modo automático está ativo, Claude Code envia cada comando Bash e PowerShell através do classificador e suspende suas regras de shell de permissão; fora do modo automático as regras ainda se aplicam
    • false: o modo automático suspende apenas regras de permissão que poderiam executar código arbitrário, como Bash(*) e Bash(python *); um comando que qualquer outra regra de permissão corresponde pula o classificador a menos que ele carregue domínios permitidos por comando, e cada outro comando de shell passa por ele
  • Padrão: false
{
  "autoMode": {
    "classifyAllShell": true
  }
}

Consulte Rotear todos os comandos de shell através do classificador. Requer Claude Code v2.1.193 ou posterior.

`disableAutoMode`

Remova o modo automático do ciclo Shift+Tab. Qualquer sessão que de outra forma começaria em modo automático, seja de --permission-mode auto, um arquivo de configurações ou o padrão integrado, começa em default em vez disso. Administradores o definem em configurações gerenciadas para impedir que desenvolvedores em sua organização usem o modo automático.

  • Escopo: Any file. Mais útil em configurações gerenciadas, onde os usuários não podem substituí-lo. Também aceito sob permissions como permissions.disableAutoMode.
  • Tipo: a string "disable"
  • Padrão: não definido
{
  "disableAutoMode": "disable"
}

`permissions`

Controle quais ferramentas Claude pode usar sem perguntar, quais sempre solicitam e quais são bloqueadas, e defina o modo de permissão em que uma sessão começa. Cada chave permissions.* abaixo se aninha sob este objeto.

  • Escopo: Any file
  • Tipo: objeto com allow, ask, deny, additionalDirectories, blockReadsOutsideWorkingDirectories, defaultMode, disableBypassPermissionsMode e disableAutoMode
  • Padrão: não definido

Este exemplo aprova comandos npm run sem perguntar, solicita antes de git push, bloqueia leituras de .env e inicia sessões em acceptEdits:

{
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)"],
    "defaultMode": "acceptEdits"
  }
}

Os três arrays de regras compartilham uma sintaxe; consulte Sintaxe de regra de permissão sob permissions.allow. Para como as regras de permissão de diferentes arquivos se combinam, consulte como as regras de permissão se mesclam entre escopos; para como as chaves de configurações em geral se combinam, consulte Precedência de configurações no guia de configurações.

`useAutoModeDuringPlan`

Escolha se Claude Code usa o classificador do modo automático para revisar comandos de shell no modo de plano. Com o padrão true, o classificador revisa cada comando durante o planejamento quando o modo automático está disponível e você não vê nenhum prompt. Defina false para obter um prompt de permissão para cada comando fora do conjunto integrado somente leitura. Aparece em /config como Use auto mode during plan.

  • Escopo: User, local, or managed. Um repositório não pode desativá-lo para você.
  • Tipo: Booleano
    • true: o mesmo que não definido; quando o modo automático está disponível, o classificador revisa cada comando de shell durante o planejamento em vez de solicitar a você. Um false em qualquer um desses arquivos ainda o desativa
    • false: você obtém um prompt de permissão para cada comando fora do conjunto integrado somente leitura
  • Padrão: true
{
  "useAutoModeDuringPlan": false
}

`permissions.allow`

Liste os usos de ferramentas que Claude Code aprova sem perguntar a você. Em uma regra MCP, * pode aparecer apenas no nome da ferramenta após o prefixo mcp__<server>__, como mcp__github__get_*; não pode aparecer no nome do servidor.

  • Escopo: Any file
  • Tipo: array de strings de regra de permissão
  • Padrão: não definido
  • Substituições por sessão: --allowedTools adiciona regras de permissão para uma sessão, e uma regra de bloqueio de qualquer arquivo de configurações ainda bloqueia uma ferramenta que ela nomeia

Este exemplo aprova git diff e permite que Claude Code leia seu .zshrc sem perguntar:

{
  "permissions": {
    "allow": ["Bash(git diff *)", "Read(~/.zshrc)"]
  }
}

Claude Code aplica regras allow do .claude/settings.json de um projeto apenas depois que você aceita o diálogo de confiança do espaço de trabalho para essa pasta.

Sintaxe de regra de permissão

As regras de permissão seguem o formato Tool ou Tool(specifier). Claude Code avalia as regras deny primeiro, depois ask, depois allow, e a primeira correspondência decide independentemente de quão específica cada regra é; consulte a ordem de avaliação de regra de permissão.

Cada linha mostra uma forma de regra e o que ela corresponde.

Regra O que ela corresponde
Bash Cada comando Bash
Bash(npm run *) Comandos começando com npm run
Read(./.env) Leituras do arquivo .env
WebFetch(domain:example.com) Solicitações de busca para example.com

Para a sintaxe de regra completa, incluindo comportamento de curinga, padrões específicos de ferramenta para Read, Edit, WebFetch, MCP e regras de Agent, e as limitações de segurança de padrões Bash, consulte Sintaxe de regra de permissão.

`permissions.ask`

Liste os usos de ferramentas que solicitam sua confirmação mesmo em um modo de permissão que de outra forma os aprovaria, como acceptEdits ou bypassPermissions. No modo dontAsk, Claude Code nega um uso de ferramenta correspondente em vez de solicitar.

  • Escopo: Any file
  • Tipo: array de strings de regra de permissão
  • Padrão: não definido
{
  "permissions": {
    "ask": ["Bash(git push *)"]
  }
}

`permissions.deny`

Liste os usos de ferramentas que Claude Code bloqueia. Use-o para arquivos que contêm chaves de API, segredos ou valores de ambiente: Claude Code exclui arquivos correspondentes da descoberta de arquivos e resultados de pesquisa, nega leituras deles e bloqueia as ferramentas Edit e Write nos caminhos correspondentes.

As regras de bloqueio Read e Edit se aplicam às ferramentas de arquivo integradas de Claude, aos comandos de arquivo que Claude Code reconhece em Bash, como cat, head, tail, sed e tee, e aos destinos de redirecionamentos de Bash como > file e < file; elas não se aplicam a um comando que lê arquivos sem nomeá-los, como grep -r pattern ., ou a subprocessos arbitrários, portanto para aplicação em nível de SO ative a sandbox.

  • Escopo: Any file
  • Tipo: array de strings de regra de permissão
  • Padrão: não definido
  • Substituições por sessão: --disallowedTools adiciona regras de bloqueio para uma sessão ao lado desta chave

Este exemplo nega leituras de arquivos .env, o diretório secrets e um arquivo de credenciais, e bloqueia comandos curl:

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

Os nomes de ferramentas aceitam padrões glob, portanto "*" nega cada ferramenta e "mcp__*" nega cada ferramenta MCP. Claude Code ignora uma regra de bloqueio para a ferramenta EndConversation enquanto qualquer outra ferramenta ainda estiver disponível para Claude. Uma regra de bloqueio Bash corresponde ao comando como Claude o escreve, portanto Bash(curl *) não para /usr/bin/curl ou sh -c 'curl …'; consulte o que uma regra Bash não corresponde. Esta chave substitui a configuração ignorePatterns descontinuada.

`permissions.additionalDirectories`

Dê a Claude acesso a arquivos em diretórios fora do que você começou, como diretórios de trabalho adicionais. A maioria da configuração .claude/ não é descoberta desses diretórios.

  • Escopo: Any file
  • Tipo: array de caminhos de diretório
  • Padrão: não definido
  • Substituições por sessão: --add-dir e /add-dir adicionam diretórios para uma sessão ao lado desta chave
{
  "permissions": {
    "additionalDirectories": ["../docs/"]
  }
}

Como as regras allow, as entradas no .claude/settings.json de um projeto entram em vigor apenas depois que você aceita o diálogo de confiança do espaço de trabalho para essa pasta.

`permissions.blockReadsOutsideWorkingDirectories`

Impeça Claude de ler caminhos fora dos diretórios de trabalho da sessão com as ferramentas Read, Grep, Glob e LSP, em cada modo de permissão incluindo bypassPermissions. Um comando Bash que lê um caminho correspondente através de um comando de arquivo que Claude Code reconhece, como cat, solicita a você mesmo no modo automático e no modo bypassPermissions. Requer Claude Code v2.1.257 ou posterior.

Um comando Bash que o analisador de shell não consegue rastrear, como um que muda de diretório mais de uma vez ou executa um subshell, solicita a você mesmo no modo automático e no modo bypassPermissions. O prompt aparece mesmo quando o comando não nomeia nenhum caminho fora dos diretórios de trabalho. Este prompt não se aplica quando o comando é executado na sandbox e a sandbox aplica o bloqueio.

Claude Code também escreve true aqui quando você escolhe bloquear tais leituras no prompt do modo automático antes da primeira leitura fora dos diretórios de trabalho.

  • Escopo: Any file. Se qualquer fonte de configurações definir true, o bloqueio se aplica, portanto um arquivo verificado de um repositório pode ativar o bloqueio para um projeto, mas não pode levantar um bloqueio que você definiu.
  • Tipo: Booleano
    • true: leituras de arquivo fora dos diretórios de trabalho são bloqueadas
    • false: o mesmo que não definido; um true em qualquer outro arquivo de configurações ainda bloqueia
  • Padrão: não definido, portanto leituras fora dos diretórios de trabalho seguem seu modo de permissão e regras
{
  "permissions": {
    "blockReadsOutsideWorkingDirectories": true
  }
}

Se apenas o arquivo de configurações verificado de um repositório adicionar um diretório, o bloqueio ainda se aplica a leituras lá. Quando autoMemoryDirectory vem do .claude/settings.json do projeto, ou de um .claude/settings.local.json tratado como fornecido pelo repositório, Claude Code não carrega nenhuma memória automática desse diretório e não salva nenhuma nele. Os arquivos que Claude Code em si precisa permanecem legíveis, como suas skills, plugins, regras, agents, comandos e o arquivo de memória CLAUDE.md sob ~/.claude/.

Quando a sandbox está ativada, o bloqueio também nega aos comandos em sandbox acesso de leitura a diretórios iniciais e raízes de volume montado fora dos diretórios de trabalho. Uma repetição que precisa de aprovação para executar fora da sandbox solicita a você mesmo no modo bypassPermissions. Os arquivos que uma ferramenta lê do seu diretório inicial, como ~/.gitconfig, são negados com o resto; reabra um caminho específico com sandbox.filesystem.allowRead quando uma ferramenta precisa dele.

Quando o diretório de trabalho da sessão é um git worktree vinculado, incluindo um que Claude Code entrou no meio da sessão, o diretório .git comum do repositório permanece legível e gravável para comandos em sandbox, para que o git continue funcionando lá.

`permissions.defaultMode`

Defina o modo de permissão em que novas sessões começam. Quando você deixa não definido, as sessões começam no padrão integrado para seu plano e superfície.

  • Escopo: Any file. auto e bypassPermissions não entram em vigor a partir de configurações de projeto ou local, portanto defina-os em ~/.claude/settings.json em vez disso. Antes da v2.1.257, bypassPermissions entrava em vigor a partir de qualquer arquivo. Para conversas que a extensão VS Code inicia, Claude Code lê apenas valores de usuário, gerenciados e --settings.
  • Tipo: string, uma de:
    • "default": Claude Code executa apenas leituras sem perguntar
    • "acceptEdits": Claude Code também executa edições de arquivo e comandos comuns do sistema de arquivos como mkdir e mv sem perguntar
    • "plan": Claude Code lê e planeja, mas bloqueia edições até que você aprove um plano
    • "auto": Claude Code executa tudo, com verificações de segurança em segundo plano
    • "dontAsk": Claude Code nega automaticamente cada chamada que de outra forma solicitaria; leituras, outras ações que não precisam de aprovação e ferramentas pré-aprovadas ainda são executadas
    • "bypassPermissions": Claude Code executa tudo sem perguntar
    • "manual": um alias para "default", em Claude Code v2.1.200 ou posterior
  • Padrão: não definido
  • Substituições por sessão: --permission-mode e seu equivalente --dangerously-skip-permissions para bypassPermissions têm precedência sobre esta chave para uma sessão
{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

As regras de permissão se sobrepõem a cada modo: as regras deny bloqueiam em cada modo, incluindo bypassPermissions. Consulte Modos de permissão. manual nomeia o modo de permissão rotulado Manual na CLI e na extensão VS Code; o alias requer Claude Code v2.1.200 ou posterior. Em sessões na nuvem, Claude Code honra apenas acceptEdits, plan, default e auto desta chave. Para conversas que a extensão VS Code inicia, consulte qual configuração a extensão lê para o modo de permissão inicial.

`permissions.disableBypassPermissionsMode`

Impeça que qualquer pessoa entre no modo bypassPermissions. Claude Code então rejeita o sinalizador --dangerously-skip-permissions e ignora uma definição de agent permissionMode: bypassPermissions, portanto o subagent é executado com o modo de permissão da sessão pai.

  • Escopo: Any file. Normalmente definido em configurações gerenciadas para aplicar a política organizacional.
  • Tipo: a string "disable"
  • Padrão: não definido
  • Substituições por sessão: esta chave tem precedência sobre --dangerously-skip-permissions, que Claude Code rejeita enquanto a chave está definida
{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

Antes da v2.1.223, Claude Code aplicava o modo de permissão do frontmatter mesmo com bypass desativado.

`skipAutoPermissionPrompt`

Pule o aviso único descrevendo o modo automático que Claude Code mostra quando você entra no modo automático pela primeira vez, por exemplo através de suas próprias configurações ou do seletor de modo, em vez de quando o padrão integrado inicia uma sessão nele. Claude Code mostra esse aviso uma vez e depois registra que foi mostrado, portanto esta chave só importa onde o aviso ainda não apareceu.

  • Escopo: User or managed. Um repositório não pode defini-lo para você.
  • Tipo: Booleano
    • true: Claude Code pula o aviso
    • false: o mesmo que não definido; o aviso aparece uma vez a menos que outro desses arquivos defina true
  • Padrão: não definido, portanto o aviso aparece uma vez
{
  "skipAutoPermissionPrompt": true
}

`skipDangerousModePermissionPrompt`

Pule o diálogo de confirmação que Claude Code mostra antes de uma sessão entrar no modo bypassPermissions, seja de --dangerously-skip-permissions ou de defaultMode: "bypassPermissions". Claude Code escreve true aqui em suas configurações de usuário quando você aceita esse diálogo uma vez.

  • Escopo: User, local, or managed. Um repositório não confiável não pode pular o diálogo para você.
  • Tipo: Booleano
    • true: Claude Code pula o diálogo de confirmação antes de uma sessão entrar no modo bypassPermissions
    • false: o mesmo que não definido; o diálogo aparece a menos que outro desses arquivos defina true
  • Padrão: não definido, portanto o diálogo aparece
{
  "skipDangerousModePermissionPrompt": true
}

Configurações de sandbox

Isole os comandos que Claude executa do seu sistema de arquivos, da sua rede e das suas credenciais. Para saber como o sandboxing funciona e os requisitos de plataforma, consulte Sandboxing.

`sandbox`

Isole os comandos Bash que Claude executa do seu sistema de arquivos e rede com sandboxing. Ative o sandbox com enabled, depois restrinja ou amplie o que os comandos em sandbox podem acessar com os sub-objetos filesystem, network e credentials. O sandbox é executado em macOS, Linux e WSL2.

  • Scope: Any file
  • Type: object com enabled, failIfUnavailable, autoAllowBashIfSandboxed, excludedCommands, allowUnsandboxedCommands, enableWeakerNestedSandbox, enableWeakerNetworkIsolation, allowAppleEvents, bwrapPath, socatPath, ignoreViolations e ripgrep, além dos objetos filesystem, network e credentials
  • Default: não definido, então Claude Code executa comandos sem sandbox

Isso ativa o sandbox, ignora prompts de permissão para comandos em sandbox, executa docker fora do sandbox, abre dois caminhos de escrita extras, oculta seu arquivo de credenciais AWS e pré-autoriza GitHub e npm:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

Claude Code obtém o valor de uma chave booleana do escopo de configurações com maior precedência que a define, então um enabled ou failIfUnavailable gerenciado substitui qualquer coisa que um desenvolvedor defina. Ele mescla chaves de array em todos os escopos de configurações que a sessão carrega, então um desenvolvedor pode anexar entradas; consulte Keep developers from widening the policy para os bloqueios somente gerenciados. Para exigir o sandbox para uma organização, consulte Enforce sandboxing with managed settings.

`sandbox.enabled`

Ative sandboxing para comandos Bash. Quando você escolhe um modo no painel /sandbox, Claude Code escreve essa chave em .claude/settings.local.json para o projeto atual; defina-a em ~/.claude/settings.json para fazer sandbox em todos os projetos.

  • Scope: Any file
  • Type: Boolean
    • true: Claude Code faz sandbox dos comandos Bash
    • false: Comandos Bash são executados sem sandbox
  • Default: false
{
  "sandbox": {
    "enabled": true
  }
}

No Linux e WSL2, o sandbox precisa de bubblewrap e socat; consulte Set up Linux and WSL2. Quando o sandbox não consegue iniciar, Claude Code mostra um aviso e executa comandos sem sandbox, a menos que você também defina failIfUnavailable.

`sandbox.failIfUnavailable`

Faça Claude Code sair com um erro na inicialização quando sandbox.enabled é true mas o sandbox não consegue iniciar, porque uma dependência está faltando ou a plataforma não é suportada. Sem isso, Claude Code mostra um aviso e executa comandos sem sandbox. Use-o em configurações gerenciadas quando sua organização exigir sandboxing como uma barreira rígida.

  • Scope: Any file
  • Type: Boolean
    • true: Claude Code sai com um erro na inicialização quando sandbox.enabled é true mas o sandbox não consegue iniciar
    • false: Claude Code mostra um aviso e executa comandos sem sandbox
  • Default: false

Isso faz com que cada máquina gerenciada faça sandbox dos comandos ou recuse iniciar:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true
  }
}

Consulte Enforce sandboxing with managed settings.

`sandbox.autoAllowBashIfSandboxed`

Deixe Claude Code executar comandos Bash em sandbox sem um prompt de permissão. Comandos que não conseguem ser executados no sandbox ainda passam pelo fluxo de permissão regular, e regras deny e regras ask com escopo de conteúdo como Bash(git push *) ainda se aplicam; uma regra ask Bash simples é ignorada para comandos em sandbox. Defina-o como false para enviar comandos em sandbox também pelo fluxo de permissão regular, que a aba Mode do /sandbox chama modo de permissões regular.

  • Scope: Any file
  • Type: Boolean
    • true: Claude Code executa comandos Bash em sandbox sem um prompt de permissão, sujeito a regras deny e regras ask com escopo de conteúdo; CLAUDE_CODE_SUBPROCESS_ENV_SCRUB desativa a auto-autorização
    • false: comandos em sandbox passam pelo fluxo de permissão regular, então suas regras de autorização e modo de permissão decidem. A aba Mode do /sandbox chama isso modo de permissões regular
  • Default: true

Isso mantém o sandbox ativado e envia comandos em sandbox pelo fluxo de permissão regular:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false
  }
}

Consulte Sandbox modes para saber o que o modo auto-autorização ainda solicita e como se comporta em modo de plano.

`sandbox.excludedCommands`

Nomeie comandos que Claude Code executa fora do sandbox, como ferramentas que não funcionam sob ele. Cada entrada usa a mesma sintaxe do conteúdo de uma regra de permissão Bash(...): um comando exato, um prefixo como docker * ou um padrão curinga.

Suas entradas tiram uma chamada Bash do sandbox apenas quando cobrem cada comando nela, e algumas formas de chamada permanecem em sandbox mesmo assim. Uma entrada docker * sozinha não tira npm ci && docker build . do sandbox.

  • Scope: Any file
  • Type: array de padrões de comando
  • Default: não definido, então nenhum comando é excluído
{
  "sandbox": {
    "excludedCommands": ["docker *"]
  }
}

Claude Code mantém uma chamada Bash em sandbox quando ela tem uma destas formas, entre outras:

  • Um comando começando com sudo, eval ou xargs
  • Um cd, pushd ou popd, onde quer que apareça na chamada
  • Uma substituição de comando, um subshell ou um bloco de fluxo de controle como if ou for
  • Um redirecionamento, como docker build . > build.log, outro que não apenas duplica um descritor de arquivo, como 2>&1 faz
  • Um nome de comando que vem de uma variável

Por exemplo, cd build && docker compose up permanece em sandbox sob uma entrada docker *, e adicionar uma entrada cd não muda isso.

Comandos excluídos ainda passam pelo fluxo de permissão regular. Exclusão é uma conveniência, não uma barreira de segurança: prefira filesystem.allowWrite quando uma ferramenta só precisa escrever em algum lugar específico. Claude Code mescla entradas em todos os escopos de configurações que a sessão carrega, e não há bloqueio somente gerenciado para essa lista, então mantenha uma lista gerenciada estreita.

`sandbox.allowUnsandboxedCommands`

Deixe Claude tentar novamente um comando fora do sandbox com o parâmetro dangerouslyDisableSandbox depois que o sandbox o bloqueia. Defina-o como false para que Claude Code ignore esse parâmetro completamente e cada comando que Claude executa deve estar em sandbox ou aparecer em excludedCommands. A aba Overrides do /sandbox mostra esse estado como Strict sandbox mode. Use false em configurações gerenciadas para políticas que exigem sandboxing rigoroso.

  • Scope: Any file
  • Type: Boolean
    • true: Claude pode tentar novamente um comando fora do sandbox com o parâmetro dangerouslyDisableSandbox depois que o sandbox o bloqueia
    • false: Claude Code ignora esse parâmetro, então cada comando que Claude executa está em sandbox ou aparece em excludedCommands
  • Default: true

Isso impõe modo de sandbox rigoroso para todos que as configurações gerenciadas cobrem:

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false
  }
}

Uma tentativa sem sandbox passa pelo fluxo de permissão regular, com um prompt em modo Manual. Consulte The unsandboxed retry escape hatch.

Para ver quando comandos que você digita você mesmo no prompt de modo shell ! são executados em sandbox, consulte strict sandbox mode.

`sandbox.filesystem`

Controle quais caminhos os comandos em sandbox podem ler e escrever. Por padrão, eles podem escrever no diretório de trabalho, no diretório temporário da sessão e em diretórios que você adiciona com --add-dir, /add-dir ou permissions.additionalDirectories, e podem ler o resto do sistema de arquivos, incluindo arquivos de credenciais. Amplie ou restrinja isso com as quatro listas de caminhos, ou desative a camada do sistema de arquivos com disabled. Consulte Filesystem isolation para os limites padrão.

  • Scope: Any file
  • Type: object com arrays allowWrite, denyWrite, denyRead e allowRead, além dos booleanos allowManagedReadPathsOnly e disabled
  • Default: não definido, então os limites padrão de leitura e escrita se aplicam

Isso permite que comandos em sandbox escrevam em um diretório de compilação e seu kubeconfig, e oculta seu arquivo de credenciais AWS:

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    }
  }
}

Claude Code impõe essas listas no limite do sandbox do SO, então elas se aplicam a cada subprocesso que um comando em sandbox inicia, como kubectl, terraform ou npm. Claude Code adiciona suas regras de permissão às mesmas listas: regras Edit allow e deny para allowWrite e denyWrite, regras Read deny para denyRead e regras WebFetch(domain:...) allow e deny para as listas de domínio network.

A menos que um bloqueio somente gerenciado seja definido, Claude Code mescla cada lista nos arquivos de configurações que a sessão carrega. allowManagedReadPathsOnly limita allowRead a entradas de configurações gerenciadas, e allowManagedDomainsOnly faz o mesmo para domínios permitidos.

Configure sandboxing cobre fontes que você exclui com --setting-sources. Quando você edita uma lista durante uma sessão, Claude Code aplica a mudança à sessão em execução.

Prefixos de caminho do sandbox

Caminhos em allowWrite, denyWrite, denyRead, allowRead e credentials.files são resolvidos por seu prefixo:

Prefixo Significado Exemplo
/ Caminho absoluto da raiz do sistema de arquivos /tmp/build permanece /tmp/build
~/ Relativo ao diretório inicial ~/.kube se torna $HOME/.kube
./ ou sem prefixo Relativo à raiz do projeto para configurações de projeto, ou a ~/.claude para configurações de usuário ./output em .claude/settings.json é resolvido para <project-root>/output

O prefixo //path para caminhos absolutos também funciona. Se você usar /path com barra única esperando resolução relativa ao projeto, mude para ./path. Essa sintaxe difere das regras de permissão Read e Edit, que usam //path para absoluto e /path para relativo ao projeto: caminhos do sistema de arquivos do sandbox usam convenções padrão, então /tmp/build é um caminho absoluto.

Claude Code remove uma barra final de um caminho de diretório, então ~/.aws e ~/.aws/ correspondem ao mesmo diretório. Antes da v2.1.224, Claude Code passava a barra final para o sandbox, e Claude ainda podia ler ou escrever caminhos sob uma entrada denyRead ou denyWrite escrita com uma.

Claude Code também remove um /** final, então ~/build/** e ~/build cobrem o mesmo diretório. Se um curinga como * funciona depende de qual lista a entrada está e da plataforma:

  • allowWrite e denyWrite: em macOS, curingas funcionam. No Linux e WSL2, o sandbox monta caminhos concretos, então Claude Code ignora uma entrada que contém *, ? ou [ uma vez que o /** final é removido, e essa entrada não tem efeito. Claude Code adiciona os caminhos de suas regras de permissão Edit a essas listas, então o mesmo limite se aplica a elas, e a aba Config do /sandbox avisa sobre regras de permissão Edit e Read que contêm curingas.
  • denyRead e allowRead: curingas funcionam em todas as plataformas. No Linux e WSL2, Claude Code expande uma entrada de leitura para os caminhos concretos que ela corresponde, o que não faz para as listas de escrita.

`sandbox.filesystem.allowWrite`

Adicione caminhos onde comandos em sandbox podem escrever, além do diretório de trabalho, do diretório temporário da sessão e dos diretórios que você adicionou com --add-dir, /add-dir ou permissions.additionalDirectories. Use-o quando um subprocesso como kubectl ou uma ferramenta de compilação precisa escrever fora do projeto.

Isso permite que uma compilação escreva sob /tmp/build e deixa kubectl atualizar seu kubeconfig:

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"]
    }
  }
}

Claude Code mescla entradas em todos os escopos de configurações que a sessão carrega: caminhos de usuário, projeto, local e gerenciado se combinam em vez de se substituírem, e Claude Code adiciona os caminhos de suas regras de permissão Edit(...) allow. Uma entrada allowWrite não pode levantar um caminho protegido.

`sandbox.filesystem.denyWrite`

Bloqueie comandos em sandbox de escrever em caminhos específicos, incluindo caminhos dentro de um diretório que é de outra forma gravável.

Isso impede que comandos em sandbox alterem a configuração do sistema ou instalem binários:

{
  "sandbox": {
    "filesystem": {
      "denyWrite": ["/etc", "/usr/local/bin"]
    }
  }
}

Claude Code mescla entradas em todos os escopos de configurações que a sessão carrega e adiciona os caminhos de suas regras de permissão Edit(...) deny.

`sandbox.filesystem.denyRead`

Bloqueie comandos em sandbox de ler caminhos específicos, como arquivos de credenciais que a política de leitura padrão exporia de outra forma. Para proteger um arquivo de credenciais e mantê-lo utilizável através do proxy do sandbox, consulte sandbox.credentials em vez disso.

{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/.aws/credentials"]
    }
  }
}

Claude Code mescla entradas em todos os escopos de configurações que a sessão carrega e adiciona os caminhos de suas regras de permissão Read(...) deny. Quando filesystem.disabled é true, Claude Code não impõe essas entradas.

`sandbox.filesystem.allowRead`

Reabra a leitura para caminhos específicos dentro de uma região que denyRead bloqueia, para construir acesso de leitura somente do espaço de trabalho. Uma entrada denyRead exata ou curinga permanece bloqueada dentro de um allowRead mais amplo, como a tabela de sobreposição mostra. Quando uma entrada denyRead curinga como ~/**/.env corresponde a um diretório, Claude Code bloqueia leituras de seu conteúdo também. Antes da v2.1.236 em macOS, Claude Code reabrira os caminhos que uma entrada denyRead curinga correspondia onde uma entrada allowRead mais ampla as cobria, e deixava o conteúdo de um diretório correspondido legível.

Isso bloqueia leituras de seu diretório inicial exceto o projeto em si:

{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

Claude Code resolve uma entrada . para a raiz do projeto em configurações de projeto e para ~/.claude em configurações de usuário. Claude Code mescla entradas em todos os arquivos de configurações que a sessão carrega, a menos que allowManagedReadPathsOnly seja definido.

`sandbox.filesystem.allowManagedReadPathsOnly`

Honre apenas as entradas allowRead que vêm de configurações gerenciadas, para que desenvolvedores não possam reabrir acesso de leitura a caminhos que sua organização bloqueou. Claude Code ainda mescla entradas denyRead de todos os escopos de configurações que a sessão carrega.

  • Scope: Managed
  • Type: Boolean
    • true: Claude Code honra apenas as entradas allowRead de configurações gerenciadas
    • false: entradas allowRead mesclam de todos os escopos de configurações que a sessão carrega
  • Default: false

Isso bloqueia leituras do diretório inicial, reabre ~/work e impede que desenvolvedores reabram qualquer outra coisa:

{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["~/work"],
      "allowManagedReadPathsOnly": true
    }
  }
}

Consulte Keep developers from widening the policy.

`sandbox.filesystem.disabled`

Ignore isolamento do sistema de arquivos mantendo isolamento de rede. Comandos em sandbox obtêm acesso irrestrito de leitura e escrita ao sistema de arquivos do host, e sua saída de rede permanece confinada a network.allowedDomains. Use-o quando você faz sandbox para controlar onde os comandos se conectam em vez do que eles escrevem. Requer Claude Code v2.1.216 ou posterior.

  • Scope: User or managed. Quando configurações gerenciadas configuram sandbox.filesystem de qualquer forma, ou listam uma entrada sandbox.credentials.files com "mode": "deny", apenas configurações gerenciadas podem defini-lo.
  • Type: Boolean
    • true: Claude Code ignora isolamento do sistema de arquivos e mantém isolamento de rede
    • false: isolamento do sistema de arquivos permanece ativado
  • Default: false, então isolamento do sistema de arquivos permanece ativado

Isso deixa o sistema de arquivos aberto e confina a saída de rede para GitHub e npm:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

Com a camada desativada, Claude Code não impõe entradas denyRead ou credentials.files deny, enquanto entradas credentials.envVars e entradas mask aplicadas continuam funcionando. autoAllowBashIfSandboxed ainda padrão para true, então defina-o como false para continuar solicitando. Consulte Disable filesystem isolation para a lista completa de fontes que podem defini-lo e o que muda quando o isolamento está desativado. Requer Claude Code v2.1.216 ou posterior.

`sandbox.ignoreViolations`

Silencie relatórios de violação de sandbox para caminhos que você espera que um comando sonde e seja recusado, como uma ferramenta que verifica /etc/hosts na inicialização, para que essas negações não apareçam como violações ou no que Claude vê. O sandbox ainda bloqueia o acesso; apenas o relatório é suprimido. As chaves são substrings para corresponder contra o comando, com * correspondendo a cada comando, e os valores são substrings da violação a ignorar para esse comando, como um caminho do sistema de arquivos.

  • Scope: Any file
  • Type: object mapeando uma substring de comando para um array de substrings de violação, geralmente caminhos
  • Default: não definido, então cada violação é relatada
{
  "sandbox": {
    "ignoreViolations": {
      "*": ["/etc/hosts"]
    }
  }
}

`sandbox.enableWeakerNestedSandbox`

Execute o sandbox do Linux dentro de um contêiner Docker sem privilégios, onde bubblewrap não consegue montar um /proc fresco. Em vez disso, o sandbox interno faz bind-mount do /proc existente do contêiner, o que expõe informações de processo que uma montagem fresca ocultaria. Isso reduz a segurança; use-o apenas quando o contêiner externo já fornece o isolamento que você precisa.

  • Scope: Any file
  • Type: Boolean
    • true: o sandbox interno faz bind-mount do /proc existente do contêiner em vez de montar um fresco
    • false: o sandbox monta um /proc fresco, o que não funciona em um contêiner Docker sem privilégios
  • Default: false
{
  "sandbox": {
    "enabled": true,
    "enableWeakerNestedSandbox": true
  }
}

Apenas Linux e WSL2. Consulte Bubblewrap fails to start inside a container.

`sandbox.enableWeakerNetworkIsolation`

Deixe comandos em sandbox em macOS alcançar o serviço de confiança TLS do sistema, com.apple.trustd.agent. Ferramentas baseadas em Go como gh, gcloud e terraform precisam disso para verificar certificados TLS quando você usa network.httpProxyPort com um proxy MITM e uma CA personalizada. Isso reduz a segurança abrindo um possível caminho de exfiltração de dados através do serviço de confiança.

  • Scope: Any file
  • Type: Boolean
    • true: comandos em sandbox em macOS podem alcançar com.apple.trustd.agent
    • false: comandos em sandbox em macOS não podem alcançar o serviço de confiança TLS do sistema
  • Default: false
{
  "sandbox": {
    "enabled": true,
    "enableWeakerNetworkIsolation": true
  }
}

Se você não usar um proxy MITM, liste as ferramentas que falham em excludedCommands em vez disso; consulte Go-based CLIs fail TLS verification on macOS.

`sandbox.allowAppleEvents`

Deixe comandos em sandbox em macOS enviar Apple Events, que open, osascript e ferramentas que abrem URLs em um navegador precisam; sem isso, eles falham com erro -600. Isso remove isolamento de execução de código: comandos em sandbox podem iniciar outros aplicativos sem sandbox sem prompt do usuário e podem enviar comandos AppleScript para aplicativos em execução como Terminal, sujeito ao prompt de consentimento de automação por aplicativo do macOS (TCC).

  • Scope: User or managed
  • Type: Boolean
    • true: comandos em sandbox em macOS podem enviar Apple Events
    • false: comandos em sandbox em macOS não podem enviar Apple Events, então open e osascript falham com erro -600
  • Default: false
{
  "sandbox": {
    "enabled": true,
    "allowAppleEvents": true
  }
}

Para manter isolamento e ainda executar uma ferramenta assim, adicione-a a excludedCommands em vez disso. Consulte Apple Events on macOS.

`sandbox.ripgrep`

Aponte o sandbox para um binário ripgrep seu em vez do que Claude Code usa, por exemplo, quando sua plataforma precisa de um rg construído diferentemente.

  • Scope: User or managed
  • Type: object com command, o caminho para o binário ripgrep, e args opcional, um array de argumentos para prepender
  • Default: não definido, então o sandbox usa o mesmo binário ripgrep que Claude Code. Esse é o binário agrupado, a menos que você defina USE_BUILTIN_RIPGREP para 0
{
  "sandbox": {
    "ripgrep": {
      "command": "/usr/local/bin/rg"
    }
  }
}

`sandbox.bwrapPath`

Aponte o sandbox para um binário bubblewrap instalado fora de PATH, como uma cópia fornecida em um host isolado. Claude Code usa o caminho tanto para a verificação de dependência de inicialização quanto quando envolve cada comando em sandbox.

  • Scope: Managed. Claude Code o lê apenas de configurações gerenciadas para que um arquivo de usuário, projeto ou local não possa apontar o sandbox para um binário diferente.
  • Type: string, um caminho absoluto; Claude Code descarta um caminho relativo e volta para busca em PATH
  • Default: não definido, então Claude Code encontra bwrap em PATH
{
  "sandbox": {
    "enabled": true,
    "bwrapPath": "/opt/admin/bwrap"
  }
}

Apenas Linux e WSL2.

`sandbox.socatPath`

Aponte o proxy de rede do sandbox para um binário socat instalado fora de PATH.

  • Scope: Managed
  • Type: string, um caminho absoluto; Claude Code descarta um caminho relativo e volta para busca em PATH
  • Default: não definido, então Claude Code encontra socat em PATH
{
  "sandbox": {
    "enabled": true,
    "socatPath": "/opt/admin/socat"
  }
}

Apenas Linux e WSL2.

`sandbox.credentials`

Declare os arquivos de credenciais e variáveis de ambiente para proteger de comandos em sandbox. Cada entrada nomeia um arquivo path ou uma variável name e um mode: deny oculta a credencial dentro do sandbox, e mask mostra comandos em sandbox um espaço reservado enquanto o proxy do sandbox substitui o valor real em solicitações de saída. Claude Code protege apenas as entradas que você lista; não há lista de negação de credenciais integrada.

  • Scope: Any file. Claude Code honra entradas mask, allowPlaintextInject, awsPairs e sigv4 apenas de configurações de usuário, configurações gerenciadas e a flag --settings.
  • Type: object com files, envVars, allowPlaintextInject, awsPairs e sigv4
  • Default: não definido, então nenhuma credencial é protegida

Isso oculta seu arquivo de credenciais AWS e remove GITHUB_TOKEN de comandos em sandbox:

{
  "sandbox": {
    "credentials": {
      "files": [{ "path": "~/.aws/credentials", "mode": "deny" }],
      "envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }]
    }
  }
}

A proteção de arquivo deny faz parte da camada do sistema de arquivos, então não se aplica quando você desativa isolamento do sistema de arquivos; a proteção de variável de ambiente ainda se aplica.

Entradas de credenciais inválidas em configurações gerenciadas

Quando uma entrada sandbox.credentials gerenciada falha na validação, Claude Code continua protegendo a credencial onde pode:

  • Uma entrada em files ou envVars que ainda tem um path ou name válido e um mode de mask ou deny, como uma cujo padrão extract não tem grupo de captura, é degradada para mode: "deny" com um aviso, então a credencial permanece bloqueada, não mascarada, até você corrigir a entrada. Uma entrada files degradada fixa filesystem.disabled como uma entrada deny explícita, e o aviso observa que seu bloqueio de leitura não é imposto se configurações gerenciadas desativarem isolamento do sistema de arquivos.
  • Uma entrada com um mode desconhecido ou um path ou name inválido é removida.
  • Cada caso avisa; se uma entrada é degradada ou removida, as entradas válidas restantes ainda são impostas, e um valor credentials totalmente inválido é descartado enquanto o resto de sandbox ainda se aplica.

Aplica-se em v2.1.191 e posterior; antes da v2.1.221, cada entrada inválida era removida. Para as outras chaves gerenciadas com manipulação por campo, consulte Invalid entries in managed settings.

`sandbox.credentials.files`

Proteja arquivos ou diretórios de credenciais de comandos em sandbox. Com "mode": "deny", Claude Code bloqueia leituras do caminho dentro do sandbox, o mesmo bloqueio de leitura que sandbox.filesystem.denyRead. Com "mode": "mask", comandos em sandbox em Linux e WSL2 leem uma cópia sentinela do arquivo, e o proxy do sandbox substitui o valor real em solicitações de saída para injectHosts dessa entrada; em macOS o arquivo é ilegível dentro do sandbox em vez disso. "mode": "mask" requer Claude Code v2.1.221 ou posterior.

  • Scope: Any file. Claude Code descarta entradas mask de .claude/settings.json de projeto e .claude/settings.local.json local.
  • Type: array de objetos, cada um com path e um mode de "deny" ou "mask", mais os campos mask opcionais para arquivos
  • Default: não definido, então nenhum arquivo de credenciais é protegido

Isso oculta seu arquivo de credenciais AWS e mascara o arquivo de hosts gh, substituindo o valor real apenas em solicitações para api.github.com:

{
  "sandbox": {
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.config/gh/hosts.yml", "mode": "mask", "injectHosts": ["api.github.com"] }
      ]
    }
  }
}

Caminhos usam os mesmos prefixos que as configurações sandbox.filesystem.*, e Claude Code mescla os arrays de todos os escopos de configurações que a sessão carrega. Protect credentials cobre o que ainda se aplica de fontes que você exclui com --setting-sources. mask entradas requerem Claude Code v2.1.221 ou posterior.

A substituição mask é executada apenas através do proxy do sandbox, então defina sandbox.network.tlsTerminate ou allowPlaintextInject para redes de teste HTTP simples. mask se aplica a um único arquivo, então liste cada arquivo de credenciais individualmente. Claude Code aceita mas ignora os campos mask em uma entrada deny. Mask credential files cobre quais fontes de configurações são honradas e quando uma entrada volta para deny.

Campos mask para arquivos

Uma entrada mask aceita esses campos opcionais. Sem extract ou decode, Claude Code substitui todo o conteúdo do arquivo por um sentinela. Em macOS com isolamento do sistema de arquivos ativado, Claude Code aplica uma entrada mask como deny antes de extract ou decode ser executado; consulte Mask credential files.

Campo Tipo O que faz
extract string, uma expressão regular com pelo menos um grupo de captura Mascara apenas o texto capturado pelo grupo 1 de cada correspondência, então o resto do arquivo permanece analisável. Com decode também definido, Claude Code verifica cada captura como um JWT possível em vez de substituí-lo imediatamente. Requer v2.1.221 ou posterior
onExtractNoMatch "warn", "deny" ou "error"; padrão "warn" O que acontece quando extract ou decode não encontra nada para mascarar. warn deixa o arquivo legível como está dentro do sandbox, deny o torna ilegível e error interrompe a configuração do sandbox até você corrigir a configuração. Claude Code trata deny como error quando o bloqueio de leitura não seria imposto, porque você desativa isolamento do sistema de arquivos ou uma entrada sandbox.filesystem.allowRead reabre o caminho. Requer v2.1.221 ou posterior; o caso decode requer v2.1.224 ou posterior
decode a string "jwt" Encontre JSON Web Tokens (JWTs) no arquivo, com um padrão integrado ou com extract quando definido, verifique cada candidato e substitua-o por um token falso estruturalmente válido, então código dentro do sandbox que decodifica o token continua funcionando. Quando nenhum candidato verifica, onExtractNoMatch governa o resultado. Requer v2.1.224 ou posterior
maskClaims array de strings, pelo menos um nome de claim; requer decode Mascara apenas os claims de carga útil de nível superior nomeados dentro de cada JWT verificado e reconstrói o token ao redor da carga útil modificada, então os outros claims permanecem legíveis. Quando nenhum claim nomeado corresponde, onExtractNoMatch governa o resultado. Requer v2.1.224 ou posterior
maskDuplicates Boolean, padrão false Também substitua cópias verbatim de cada valor mascarado em outro lugar no arquivo, como um segredo colado em um comentário. Claude Code corresponde substrings brutas, então reserve-o para segredos longos e de alta entropia. Consultado apenas quando extract ou decode está definido. Requer v2.1.221 ou posterior
injectHosts array de strings, cada um um host que sandbox.network.allowedDomains também admite Restrinja os hosts onde o proxy do sandbox substitui o valor real. Quando não definido, o proxy o substitui em solicitações para cada host em sandbox.network.allowedDomains. Requer v2.1.221 ou posterior

Isso mascara apenas o valor oauth_token no arquivo de hosts gh, substitui cada outra cópia dele no arquivo, torna o arquivo ilegível se o padrão não corresponder a nada e substitui o token real apenas em solicitações para api.github.com:

{
  "sandbox": {
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "maskDuplicates": true,
          "onExtractNoMatch": "deny",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

`sandbox.credentials.envVars`

Proteja variáveis de ambiente de comandos em sandbox. Com "mode": "deny", Claude Code remove a variável do ambiente de comandos em sandbox. Com "mode": "mask", comandos em sandbox veem um valor sentinela por sessão, e o proxy do sandbox substitui o valor real em solicitações de saída para injectHosts dessa entrada, então ferramentas como gh e npm continuam autenticando sem nunca manter a credencial real. "mode": "mask" requer Claude Code v2.1.199 ou posterior.

  • Scope: Any file. Claude Code descarta entradas mask de .claude/settings.json de projeto e .claude/settings.local.json local.
  • Type: array de objetos, cada um com name e um mode de "deny" ou "mask", mais os campos mask opcionais para variáveis de ambiente
  • Default: não definido, então nenhuma variável de ambiente é protegida

Isso remove NPM_TOKEN de comandos em sandbox e mascara GITHUB_TOKEN, substituindo o valor real apenas em solicitações para api.github.com:

{
  "sandbox": {
    "credentials": {
      "envVars": [
        { "name": "NPM_TOKEN", "mode": "deny" },
        { "name": "GITHUB_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] }
      ]
    }
  }
}

O name deve começar com uma letra ou sublinhado e conter apenas letras, dígitos e sublinhados. Claude Code mescla os arrays de todos os escopos de configurações que a sessão carrega e aplica deny quando a mesma variável aparece com ambos os modos. Protect credentials cobre o que ainda se aplica de fontes que você exclui com --setting-sources. mask entradas requerem Claude Code v2.1.199 ou posterior.

A substituição mask é executada apenas através do proxy do sandbox, então defina sandbox.network.tlsTerminate ou allowPlaintextInject para redes de teste HTTP simples; consulte Mask environment variables. Claude Code aceita mas ignora os campos mask em uma entrada deny.

Campos mask para variáveis de ambiente

Uma entrada mask aceita esses campos opcionais. Sem extract ou decode, Claude Code substitui todo o valor por um sentinela. extract e decode não podem ser combinados na mesma entrada.

Campo Tipo O que faz
extract string, uma expressão regular com pelo menos um grupo de captura Mascara apenas o texto capturado pelo grupo 1 de cada correspondência, como a senha dentro de uma string de conexão DATABASE_URL, então o resto do valor permanece analisável. Requer v2.1.224 ou posterior
onExtractNoMatch "warn", "deny" ou "error"; padrão "warn". Em uma entrada com decode, apenas "warn" é aceito O que acontece quando extract não corresponde a nada. warn passa a variável através desmascarada, deny a desdefine dentro do sandbox e error interrompe a configuração do sandbox até você corrigir a configuração. Requer v2.1.224 ou posterior
decode a string "jwt" Verifique se o valor inteiro é um JWT e substitua-o por um token falso estruturalmente válido, então código dentro do sandbox que decodifica o token continua funcionando; o proxy substitui o token real inteiro na saída. Um valor que não verifica passa através desmascarado com um aviso. Requer v2.1.224 ou posterior
maskClaims array de strings, pelo menos um nome de claim; requer decode Mascara apenas os claims de carga útil de nível superior nomeados dentro do JWT decodificado e reconstrói o token ao redor da carga útil modificada, então os outros claims permanecem legíveis. Quando nenhum claim nomeado corresponde, a variável passa através desmascarada com um aviso. Requer v2.1.224 ou posterior
injectHosts array de strings, cada um um host que sandbox.network.allowedDomains também admite Restrinja os hosts onde o proxy do sandbox substitui o valor real. Quando não definido, o proxy o substitui em solicitações para cada host em sandbox.network.allowedDomains. Escreva um destino IPv6 como o endereço comprimido nu, como "::1", não a forma entre colchetes; consulte IPv6 destinations in injectHosts. Requer v2.1.199 ou posterior

Isso mascara apenas a senha dentro de DATABASE_URL, desdefine a variável se o padrão não corresponder a nada e mascara um JWT em SERVICE_JWT enquanto deixa cada claim exceto api_key legível:

{
  "sandbox": {
    "credentials": {
      "envVars": [
        {
          "name": "DATABASE_URL",
          "mode": "mask",
          "extract": "://[^:]+:([^@]+)@",
          "onExtractNoMatch": "deny"
        },
        {
          "name": "SERVICE_JWT",
          "mode": "mask",
          "decode": "jwt",
          "maskClaims": ["api_key"]
        }
      ]
    }
  }
}

`sandbox.credentials.allowPlaintextInject`

Permita substituição mask em solicitações HTTP simples bem como HTTPS terminado em TLS. Em HTTP simples a identidade upstream não é verificada e a credencial viaja em texto claro, então deixe isso desativado fora de redes de teste confiáveis. Requer Claude Code v2.1.199 ou posterior.

  • Scope: User or managed
  • Type: Boolean
    • true: Claude Code permite substituição mask em solicitações HTTP simples bem como HTTPS terminado em TLS
    • false: Claude Code permite substituição mask apenas em HTTPS terminado em TLS
  • Default: false
{
  "sandbox": {
    "credentials": {
      "allowPlaintextInject": true
    }
  }
}

Requer Claude Code v2.1.199 ou posterior.

`sandbox.credentials.awsPairs`

Agrupe variáveis de ambiente mascaradas que formam uma credencial AWS para re-assinatura SigV4 quando sua credencial vive em variáveis com nomes não padrão. Claude Code vincula o trio convencional AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_SESSION_TOKEN automaticamente quando você mascara seus valores inteiros, então você precisa dessa chave apenas para outros nomes. Requer Claude Code v2.1.224 ou posterior.

  • Scope: User or managed
  • Type: array de objetos, cada um com accessKeyIdVar, secretAccessKeyVar e opcionalmente sessionTokenVar, nomeando entradas sandbox.credentials.envVars
  • Default: não definido, então apenas o trio convencional é emparelhado

Isso vincula três variáveis com nomes personalizados em uma credencial AWS para re-assinatura:

{
  "sandbox": {
    "credentials": {
      "awsPairs": [
        {
          "accessKeyIdVar": "MY_KEY_ID",
          "secretAccessKeyVar": "MY_SECRET_KEY",
          "sessionTokenVar": "MY_SESSION_TOKEN"
        }
      ]
    }
  }
}

Cada variável nomeada deve ser uma entrada mask de valor inteiro em sandbox.credentials.envVars, sem extract ou decode, e pode preencher apenas um slot em todos os pares.

`sandbox.credentials.sigv4`

Escolha o que o proxy do sandbox faz com formas de solicitação AWS que não consegue re-assinar: streaming para uploads de streaming aws-chunked, presigned para URLs pré-assinadas e sigv4a para assinaturas assimétricas SigV4A. Isso se aplica apenas a solicitações assinadas com a ID de chave de acesso de espaço reservado de um par mascarado. Requer Claude Code v2.1.224 ou posterior.

  • Scope: User or managed
  • Type: object com streaming, presigned e sigv4a, cada um de:
    • "deny": o proxy falha na solicitação
    • "passthrough": o proxy encaminha a solicitação assinada com o espaço reservado mascarado, então a ferramenta recebe a própria rejeição da AWS
  • Default: não definido, então cada forma é "deny"

Isso encaminha uploads de streaming em vez de falhá-los no proxy:

{
  "sandbox": {
    "credentials": {
      "sigv4": {
        "streaming": "passthrough"
      }
    }
  }
}

Com deny, o proxy falha na solicitação. Com passthrough, o proxy encaminha a solicitação com sua assinatura computada a partir do espaço reservado mascarado, então AWS a rejeita e a ferramenta chamadora recebe a própria resposta da AWS em vez de um erro de proxy.

`sandbox.network`

Controle quais hosts, portas e sockets os comandos em sandbox podem alcançar. O sandbox roteia o tráfego de saída através de um proxy que impõe essas listas; consulte Network isolation para saber como o proxy decide e quando solicita.

  • Scope: Any file. strictAllowlist, allowManagedDomainsOnly e tlsTerminate são lidos de menos fontes, como suas entradas dizem.
  • Type: object com as sub-chaves abaixo
  • Default: não definido, então nenhum domínio é pré-autorizado e o sandbox solicita cada novo host

Isso pré-autoriza GitHub e npm, bloqueia uploads.github.com e deixa comandos se vincularem a localhost:

{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "deniedDomains": ["uploads.github.com"],
      "allowLocalBinding": true
    }
  }
}

Claude Code mescla as sub-chaves de array em escopos de configurações e as deduplica, então um projeto pode adicionar domínios à sua lista de usuário. As regras de permissão WebFetch(domain:...) allow e deny permission rules alimentam as mesmas listas de allow e deny.

`sandbox.network.allowUnixSockets`

Liste os caminhos de socket Unix que comandos em sandbox podem se conectar em macOS. Claude Code ignora essa lista no Linux e WSL2, onde o filtro seccomp não consegue inspecionar caminhos de socket; use allowAllUnixSockets em vez disso.

  • Scope: Any file
  • Type: array de strings, cada um um caminho de socket
  • Default: não definido, então o sandbox macOS bloqueia cada socket Unix
{
  "sandbox": {
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"]
    }
  }
}

Um caminho de socket pode conceder acesso amplo: permitir /var/run/docker.sock, por exemplo, deixa um comando em sandbox controlar o daemon Docker. Consulte Security limitations.

`sandbox.network.allowAllUnixSockets`

Deixe comandos em sandbox se conectarem a cada socket Unix. No Linux e WSL2, o filtro seccomp do sandbox bloqueia chamadas socket(AF_UNIX, ...), então essa é a única maneira de permitir sockets Unix lá. Quando o filtro está faltando, que /sandbox relata em sua aba Dependencies, o sandbox não bloqueia chamadas de socket Unix. Consulte Set up Linux and WSL2 para onde o filtro vem.

  • Scope: Any file
  • Type: Boolean
    • true: comandos em sandbox podem se conectar a cada socket Unix
    • false: o sandbox bloqueia conexões de socket Unix: em macOS exceto os caminhos em allowUnixSockets e no Linux e WSL2 através do filtro seccomp quando está presente
  • Default: false
{
  "sandbox": {
    "network": {
      "allowAllUnixSockets": true
    }
  }
}

No WSL2, true também reabre o socket interop que inicia binários Windows como cmd.exe e powershell.exe.

`sandbox.network.allowLocalBinding`

Deixe comandos em sandbox se vincularem a portas localhost em macOS, por exemplo, para iniciar um servidor de desenvolvimento.

  • Scope: Any file
  • Type: Boolean
    • true: comandos em sandbox podem se vincular a portas localhost em macOS
    • false: comandos em sandbox em macOS não podem se vincular a portas localhost
  • Default: false
{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

`sandbox.network.allowMachLookup`

Liste nomes de serviço XPC e Mach adicionais que o sandbox macOS pode procurar. Ferramentas que se comunicam sobre XPC, como o iOS Simulator ou Playwright, precisam de seus serviços listados aqui.

  • Scope: Any file
  • Type: array de strings, cada um um nome de serviço; um único * final corresponde a um prefixo e "*" sozinho corresponde a cada serviço
  • Default: não definido

Isso permite cada serviço sob o prefixo com.apple.coresimulator.:

{
  "sandbox": {
    "network": {
      "allowMachLookup": ["com.apple.coresimulator.*"]
    }
  }
}

`sandbox.network.allowedDomains`

Pré-autorize domínios para tráfego de saída de comandos em sandbox, então o sandbox não solicita por eles. Curingas como *.example.com correspondem a subdomínios, e um sufixo :port opcional limita uma entrada a uma porta; uma entrada sem porta corresponde a cada porta.

  • Scope: Any file. Apenas configurações gerenciadas quando allowManagedDomainsOnly está definido.
  • Type: array de strings, cada um um domínio, padrão curinga ou literal IP, com um sufixo :port opcional
  • Default: não definido, então o sandbox solicita a primeira vez que um comando alcança um novo host

Isso pré-autoriza GitHub em cada porta, cada subdomínio npm e um host API em porta 443 apenas:

{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "api.example.com:443"]
    }
  }
}

Escreva literais IPv6 entre colchetes, com uma porta opcional: "[::1]" permite cada porta e "[::1]:443" uma porta. A forma entre colchetes requer Claude Code v2.1.229 ou posterior. Consulte IPv6 addresses in domain lists.

`sandbox.network.deniedDomains`

Bloqueie domínios para tráfego de saída de comandos em sandbox, usando a mesma sintaxe de curinga, porta e IPv6 que allowedDomains. Um domínio negado permanece bloqueado mesmo quando uma entrada allowedDomains também o corresponde.

  • Scope: Any file
  • Type: array de strings, cada um um domínio, padrão curinga ou literal IP, com um sufixo :port opcional
  • Default: não definido
{
  "sandbox": {
    "network": {
      "deniedDomains": ["sensitive.cloud.example.com"]
    }
  }
}

Claude Code mescla essa lista de cada fonte de configurações que a sessão carrega mesmo quando allowManagedDomainsOnly está definido, então um desenvolvedor pode sempre apertar a lista de negação. Para literais IPv6, consulte IPv6 addresses in domain lists.

Uma entrada escrita com o ponto final que marca um nome de domínio totalmente qualificado, como example.com., bloqueia as mesmas conexões que example.com.

`sandbox.network.strictAllowlist`

Negue acesso de comandos em sandbox a hosts fora da lista de permissões em vez de solicitar aprovação. A lista de permissões é allowedDomains mais domínios de regras WebFetch(domain:...) allow, ou apenas as entradas de configurações gerenciadas quando allowManagedDomainsOnly está definido. Requer Claude Code v2.1.219 ou posterior.

  • Scope: User or managed. Um repositório não pode ativá-lo ou desativá-lo.
  • Type: Boolean
    • true: Claude Code nega acesso de comandos em sandbox a hosts fora da lista de permissões
    • false: a menos que outro arquivo de configurações confiável defina true, Claude Code decide um host fora da lista de permissões por modo de permissão em vez de negá-lo imediatamente: em modo auto ele verifica o host contra os domínios permitidos por comando do comando, em modo dontAsk nega, em modo bypassPermissions e em sessões de modo de plano de terminal interativo onde bypass está disponível permite, e caso contrário pergunta a você
  • Default: false
{
  "sandbox": {
    "network": {
      "strictAllowlist": true
    }
  }
}

Claude Code impõe isso apenas para comandos em sandbox; ferramentas em processo como WebFetch ainda seguem suas regras de permissão. Quando qualquer uma das fontes honradas a define como true, ela permanece ativada. Consulte Network isolation. Requer Claude Code v2.1.219 ou posterior.

`sandbox.network.allowManagedDomainsOnly`

Bloqueie a lista de permissões de rede para o que as configurações gerenciadas definem. Claude Code então honra apenas allowedDomains e regras WebFetch(domain:...) allow de configurações gerenciadas, ignora domínios de configurações de usuário, projeto, local e --settings, e bloqueia um domínio não permitido automaticamente em vez de solicitar.

  • Scope: Managed
  • Type: Boolean
    • true: Claude Code honra apenas allowedDomains e regras WebFetch(domain:...) allow de configurações gerenciadas e bloqueia um domínio não permitido em vez de solicitar
    • false: domínios de configurações de usuário, projeto, local e --settings mesclam na lista de permissões
  • Default: false

Isso bloqueia a lista de permissões para GitHub e npm e ignora qualquer domínio que desenvolvedores adicionem:

{
  "sandbox": {
    "network": {
      "allowManagedDomainsOnly": true,
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

Domínios negados ainda mesclam de cada fonte que a sessão carrega. Consulte Keep developers from widening the policy.

`sandbox.network.httpProxyPort`

Aponte o sandbox para seu próprio proxy HTTP em vez do que Claude Code executa. Organizações fazem isso para inspecionar tráfego HTTPS, aplicar suas próprias regras de filtragem ou registrar cada solicitação. Quando não definido, Claude Code inicia seu próprio proxy para tráfego HTTP.

  • Scope: Any file
  • Type: number, uma porta TCP local
  • Default: não definido, então Claude Code executa seu próprio proxy
{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080
    }
  }
}

Defina socksProxyPort também se seu proxy deve carregar tráfego SOCKS também; com apenas um dos dois definido, Claude Code ainda executa seu próprio proxy para o outro protocolo. Consulte Custom proxy configuration.

`sandbox.network.socksProxyPort`

Aponte o sandbox para seu próprio proxy SOCKS5 em vez do que Claude Code executa. Quando não definido, Claude Code inicia seu próprio proxy para tráfego SOCKS.

  • Scope: Any file
  • Type: number, uma porta TCP local
  • Default: não definido, então Claude Code executa seu próprio proxy
{
  "sandbox": {
    "network": {
      "socksProxyPort": 8081
    }
  }
}

Consulte Custom proxy configuration.

`sandbox.network.tlsTerminate`

Faça o proxy do sandbox terminar TLS para que ele possa ler o conteúdo de solicitações HTTPS. Isso é experimental, e a substituição de credenciais mask requer isso. Defina {} para gerar uma autoridade de certificado efêmera para a sessão, ou defina caCertPath e caKeyPath para usar a sua própria.

  • Scope: User or managed. Um repositório não pode ativá-lo ou fornecer uma autoridade de certificado.
  • Type: object com caCertPath e caKeyPath strings opcionais, cada um um caminho de arquivo
  • Default: não definido, então o proxy não termina ou inspeciona TLS
{
  "sandbox": {
    "network": {
      "tlsTerminate": {}
    }
  }
}

Quando mais de uma fonte honrada a define, Claude Code usa o valor da fonte com maior precedência: configurações gerenciadas, depois a flag --settings, depois configurações de usuário. Requer Claude Code v2.1.199 ou posterior.

Memória e contexto

Controle o que Claude Code carrega no contexto, como ele compacta e onde mantém memória e planos. Veja Gerenciar contexto e Memória.

`autoCompactEnabled`

Faça Claude Code compactar a conversa automaticamente quando o contexto se aproximar do limite. Aparece em /config como Auto-compact, e alternar lá escreve essa chave nas suas configurações de usuário.

  • Scope: Any file
  • Type: Boolean
    • true: Claude Code compacta a conversa automaticamente quando o contexto se aproxima do limite
    • false: Claude Code não compacta automaticamente
  • Default: true
  • Per-session overrides: DISABLE_AUTO_COMPACT desativa auto-compact para uma sessão; qualquer um dos dois que o desativar, o outro não pode reativá-lo
{
  "autoCompactEnabled": false
}

O comando manual /compact continua funcionando enquanto auto-compact está desativado.

`autoCompactWindow`

Defina o quão cheio o contexto fica antes de Claude Code compactar automaticamente.

  • Scope: Any file
  • Type: número de tokens, de 100000 a 1000000. Claude Code limita o valor à janela de contexto do seu modelo; a visão geral de modelos lista a janela de cada modelo
  • Default: não definido, então Claude Code escolhe uma janela ajustada para seu modelo
  • Per-session overrides: --autocompact tem precedência sobre essa chave para uma sessão, e CLAUDE_CODE_AUTO_COMPACT_WINDOW tem precedência sobre ambas
{
  "autoCompactWindow": 500000
}

Defina com o comando /autocompact, que escreve essa chave nas suas configurações de usuário. Defina a janela auto-compact cobre como o comando, flag, variável e configuração interagem.

`autoMemoryDirectory`

Armazene memória automática em um diretório de sua escolha em vez do padrão por projeto.

  • Scope: Any file
  • Type: string, um caminho de diretório absoluto ou prefixado com ~/
  • Default: não definido, então Claude Code usa ~/.claude/projects/<project>/memory/
{
  "autoMemoryDirectory": "~/my-memory-dir"
}

A partir das configurações de projeto ou local, Claude Code honra essa chave sob a mesma regra de confiança de workspace que hooks, já que um repositório clonado pode fornecer esses arquivos.

`autoMemoryEnabled`

Ative ou desative memória automática. Quando false, Claude não lê ou escreve no diretório de memória automática. Você também pode alternar com /memory durante uma sessão, que escreve essa chave nas suas configurações de usuário.

  • Scope: Any file
  • Type: Boolean
    • true: o mesmo que não definido; memória automática permanece ativada a menos que algo que tenha precedência sobre essa chave a desative para a sessão, como --bare, modo seguro ou CLAUDE_CODE_DISABLE_AUTO_MEMORY
    • false: Claude não lê ou escreve no diretório de memória automática
  • Default: true
  • Per-session overrides: CLAUDE_CODE_DISABLE_AUTO_MEMORY tem precedência sobre essa chave para uma sessão, em qualquer direção
{
  "autoMemoryEnabled": false
}

`bashOutputMaxChars`

Defina quantos caracteres da saída de um comando Bash ou PowerShell bem-sucedido Claude recebe inline. Quando a saída passa do limite, Claude Code a salva em um arquivo e Claude recebe uma visualização curta mais o caminho do arquivo. Aumente o limite quando a saída do comando, como uma compilação detalhada ou um log completo de suite de testes, rotineiramente ultrapassa o padrão e você quer que Claude a leia sem abrir o arquivo. Requer Claude Code v2.1.261 ou posterior.

  • Scope: Any file
  • Type: número de caracteres, um inteiro positivo. Claude Code limita o valor ao intervalo 4000 a 128000
  • Default: não definido, então Claude recebe até 30.000 caracteres inline
{
  "bashOutputMaxChars": 100000
}

Quando você define essa chave, Claude Code ignora a variável de ambiente BASH_MAX_OUTPUT_LENGTH.

`claudeMd`

Injete instruções no estilo CLAUDE.md como memória gerenciada pela organização sem implantar um arquivo separado. Claude Code carrega o texto como uma entrada de memória gerenciada antes dos arquivos CLAUDE.md de usuário e projeto.

  • Scope: Managed
  • Type: string, o texto de um arquivo CLAUDE.md; escreva como você faria o arquivo, Markdown incluído, com quebras de linha como \n
  • Default: não definido

Este exemplo implanta duas regras como uma lista Markdown curta:

{
  "claudeMd": "# Engineering rules\n\n- Always run make lint before committing.\n- Never push directly to main."
}

Veja Implante CLAUDE.md em toda a organização.

`claudeMdExcludes`

Pule arquivos CLAUDE.md específicos quando Claude Code carrega memória. Em um grande monorepo, use para pular arquivos CLAUDE.md de outros times que não são relevantes para seu trabalho; Exclua arquivos CLAUDE.md irrelevantes no guia de grandes bases de código percorre esse caso. Padrões correspondem a caminhos de arquivo absolutos.

  • Scope: Any file
  • Type: array de strings, cada uma um padrão glob ou caminho absoluto
  • Default: não definido, então Claude Code carrega cada CLAUDE.md que encontra
{
  "claudeMdExcludes": ["**/vendor/**/CLAUDE.md"]
}

Exclusões se aplicam apenas a arquivos de memória de usuário, projeto e local; arquivos CLAUDE.md de política gerenciada não podem ser excluídos.

`env`

Defina variáveis de ambiente para cada sessão e para os subprocessos que Claude Code inicia a partir dela. A maioria das variáveis na referência de variáveis de ambiente pode ir aqui, que é como você aplica uma a cada sessão ou a implanta para seu time. Configurações de projeto e local não podem definir algumas delas.

  • Scope: Any file
  • Type: objeto mapeando nomes de variáveis para valores de string
  • Default: não definido

Este exemplo desativa compactação automática e roteia solicitações de API através de um proxy:

{
  "env": {
    "DISABLE_AUTO_COMPACT": "1",
    "ANTHROPIC_BASE_URL": "https://proxy.example.com"
  }
}

Como valores `env` interagem com seu shell

  • Um valor aqui sobrescreve a mesma variável exportada em seu shell, e quando mais de um arquivo de configurações define uma variável, a precedência mais alta se aplica. Variáveis que Claude Code ignora em env lista as exceções para configurações de projeto e local.
  • Para cancelar uma exportação de shell, defina a variável como "". Claude Code trata um valor vazio como não definido para seleção de provedor, e subprocessos herdam o valor vazio.
  • NO_COLOR e FORCE_COLOR definidos aqui chegam apenas aos subprocessos. Para alterar as cores da própria interface de Claude Code, defina-as em seu shell antes de iniciar claude.
  • Valores aqui são texto simples no arquivo de configurações e chegam a cada subprocesso que Claude Code inicia. Para um token de portador OTLP que gira, use otelHeadersHelper; para credenciais de API, use apiKeyHelper.

Quando Claude Code aplica valores `env`

  • Das configurações de usuário, --settings e configurações gerenciadas: na inicialização, e novamente na sessão em execução quando uma alteração salva modifica o env mesclado.
  • Das configurações de projeto e local: depois que você confia no workspace, ou na inicialização no modo -p, que nunca mostra o diálogo de confiança, e novamente quando uma alteração salva modifica o env mesclado.
  • Variáveis que Claude Code classifica como seguras, como seleção de modelo, timeouts e limites, e alternadores de recursos: na inicialização de cada arquivo de configurações, além das variáveis que configurações de projeto e local não podem definir.
  • Depois que você move a sessão com /cd em v2.1.246 ou posterior: os valores env do novo diretório de projeto e local, além dos do diretório anterior.

Variáveis que Claude Code ignora em `env`

  • Configurações de projeto e local não podem definir variáveis que um repositório verificado não deveria controlar; defina-as em seu shell, configurações de usuário ou configurações gerenciadas. Claude Code descarta cada uma, além de alguns valores que desativam telemetria, e registra um aviso que você pode ver com claude --debug. Elas incluem:

    • Variáveis que escolhem onde Claude Code armazena ou escreve seus próprios arquivos: CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR e as variáveis de diretório do sistema operacional como HOME, TMPDIR, TMP, TEMP e a família XDG_*.

    • Variáveis que exportam conteúdo de sessão: OTEL_LOG_RAW_API_BODIES e o par de rastreamento beta detalhado ENABLE_BETA_TRACING_DETAILED e BETA_TRACING_ENDPOINT.

    • As variáveis do exportador OpenTelemetry que ativam telemetria, escolhem para onde ela vai ou escolhem qual conteúdo ela captura:

      • CLAUDE_CODE_ENABLE_TELEMETRY, mais o par de telemetria aprimorada beta CLAUDE_CODE_ENHANCED_TELEMETRY_BETA e ENABLE_ENHANCED_TELEMETRY_BETA
      • Os seletores de exportador OTEL_LOGS_EXPORTER, OTEL_METRICS_EXPORTER e OTEL_TRACES_EXPORTER
      • As variáveis de conteúdo OTEL_LOG_USER_PROMPTS, OTEL_LOG_ASSISTANT_RESPONSES, OTEL_LOG_TOOL_CONTENT e OTEL_LOG_TOOL_DETAILS
      • Variáveis OTEL_EXPORTER_OTLP_* cujos nomes terminam em _ENDPOINT, _HEADERS, _PROTOCOL, _CERTIFICATE, _CLIENT_KEY ou _INSECURE, nas formas genérica e por sinal, como OTEL_EXPORTER_OTLP_ENDPOINT e OTEL_EXPORTER_OTLP_METRICS_HEADERS
      • OTEL_EXPORTER_PROMETHEUS_HOST e OTEL_EXPORTER_PROMETHEUS_PORT

      Apenas esses valores ainda se aplicam das configurações de projeto e local, porque desativam algo: none para os três seletores de exportador, e um valor desativado como 0 para OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_CONTENT e OTEL_LOG_TOOL_DETAILS. Tal valor sobrescreve a mesma variável em suas configurações de usuário, mas não uma que o ambiente do qual você inicia Claude Code, um arquivo --settings ou configurações gerenciadas definem.

      Quando um arquivo de configurações de projeto ou local define uma variável neste grupo, uma sessão interativa local mostra um aviso na inicialização. Execute /status ou claude doctor para ver quais Claude Code ignorou e quais desativaram telemetria; ambos listam nomes, nunca valores. Uma execução não interativa com -p ou uma sessão do Agent SDK não mostra aviso, então verifique se seu coletor ainda recebe dados depois que você atualizar. Se não receber, defina as variáveis em suas configurações de usuário, configurações gerenciadas, o ambiente do trabalho ou um arquivo que você passa com --settings.

      Ignorar este grupo em configurações de projeto e local requer Claude Code v2.1.282 ou posterior.

    • Variáveis que alteram como Claude Code inicia ou sincroniza, como CLAUDE_CODE_PROCESS_WRAPPER, CLAUDE_CODE_SYNC_SKILLS, CLAUDE_CODE_SYNC_PLUGINS, CLAUDE_CODE_PLUGIN_CACHE_DIR e CLAUDE_CODE_PLUGIN_SEED_DIR.

    Antes de v2.1.251, configurações de projeto e local podiam definir as variáveis nesta lista que escolhem onde Claude Code escreve seus arquivos ou que exportam conteúdo de sessão, exceto HOME e XDG_CONFIG_HOME.

  • Variáveis de identidade que os ambientes de hospedagem de Claude Code possuem, como CLAUDE_CODE_REMOTE e CLAUDE_CODE_ACCOUNT_UUID, são ignoradas de cada arquivo.

  • CLAUDE_CODE_MESSAGING_SOCKET e CLAUDE_CODE_MESSAGING_TOKEN, que Claude Code exporta a si mesmo, são ignoradas de cada arquivo. Ignorar a variável de socket requer Claude Code v2.1.224 ou posterior, e ignorar o token requer v2.1.228 ou posterior.

  • CLAUDE_CODE_PROJECT_DIR_NAME, que Claude Code lê apenas do ambiente de inicialização, é ignorada de cada arquivo; requer v2.1.234 ou posterior.

  • CLAUDE_CODE_RESTRICTED, que Claude Code lê apenas do ambiente de inicialização, é ignorada de cada arquivo.

`fileCheckpointingEnabled`

Faça Claude Code tirar snapshots de arquivos antes de cada edição para que /rewind possa restaurá-los. Aparece em /config como Rewind code (checkpoints), e alternar lá escreve essa chave nas suas configurações de usuário.

  • Scope: Any file
  • Type: Boolean
    • true: Claude Code tira snapshots de arquivos antes de cada edição para que /rewind possa restaurá-los
    • false: Claude Code não tira snapshots de arquivos, então /rewind não pode restaurá-los
  • Default: true
  • Per-session overrides: CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING desativa checkpointing para uma sessão; qualquer um dos dois que o desativar, o outro não pode reativá-lo
{
  "fileCheckpointingEnabled": false
}

Em uma execução -p ou uma sessão do Agent SDK, Claude Code ignora essa chave. O SDK ativa checkpointing com sua opção enableFileCheckpointing, e uma execução -p simples precisa de CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true. Veja File checkpointing in the Agent SDK.

`plansDirectory`

Escolha onde Claude Code armazena os arquivos de plano que escreve em plan mode. Claude Code resolve o caminho relativo à raiz do projeto e mantém o padrão quando o caminho se resolve fora dela.

  • Scope: Any file
  • Type: string, um caminho relativo à raiz do projeto
  • Default: não definido, então Claude Code usa ~/.claude/plans
{
  "plansDirectory": "./plans"
}

`skillListingBudgetFraction`

A cada turno, Claude vê uma listagem de suas skills com suas descrições, e Claude Code limita essa listagem a uma parte da janela de contexto. Quando a listagem está acima do limite, Claude Code mantém o nome de cada skill mas descarta as descrições das skills menos usadas, para que Claude ainda possa invocar essas skills mas seja menos provável escolher uma por conta própria. Aumente essa chave para manter mais descrições visíveis ao custo de mais contexto por turno.

  • Scope: Any file
  • Type: número, uma fração maior que 0 e no máximo 1
  • Default: 0.01, que reserva 1% da janela de contexto
{
  "skillListingBudgetFraction": 0.02
}

Para ver quanto contexto a listagem usa e quais skills contribuem mais, execute /doctor.

`skillListingMaxDescChars`

A cada turno, Claude vê uma listagem de suas skills que mostra o texto description e when_to_use de cada skill. Essa chave limita quantos caracteres desse texto Claude Code mostra por skill; texto mais longo é cortado no limite.

  • Scope: Any file
  • Type: número de caracteres, um inteiro positivo
  • Default: 1536
{
  "skillListingMaxDescChars": 2048
}

Aumente para manter descrições longas intactas ao custo de mais contexto por turno; diminua para caber mais skills sob skillListingBudgetFraction.

`taskOutputMaxChars`

Até v2.1.276, você definia essa chave para o número de caracteres da saída de uma tarefa de background que Claude recebia inline quando lia a tarefa com a ferramenta TaskOutput.

Interface e terminal

Altere como Claude Code aparece e se comporta no seu terminal: tema, modo de editor, linha de status, spinner, notificações dentro da sessão e acessibilidade. Veja Configuração de terminal.

`askUserQuestionTimeout`

Deixe um diálogo AskUserQuestion sem resposta continuar automaticamente após um período de tempo ocioso, enviando quaisquer opções que você já tivesse selecionado. Defina isso quando você se afastar e quiser que Claude continue sem você. Com o padrão, as perguntas aguardam até que você as responda. Requer Claude Code v2.1.200 ou posterior.

  • Scope: User or managed
  • Type: string, um de "60s", "5m", "10m", ou "never"
  • Default: "never"
  • Per-session overrides: CLAUDE_AFK_TIMEOUT_MS tem precedência sobre esta chave para uma sessão
{
  "askUserQuestionTimeout": "5m"
}

Aparece em /config como Question auto-continue timeout, que escreve esta chave nas configurações do usuário; Claude Code oculta a linha enquanto configurações gerenciadas ou a flag --settings definem a chave. Requer Claude Code v2.1.200 ou posterior.

`autoContinueAtUsageLimit`

Depois que um limite de uso do claude.ai interrompe sua sessão, aguarde na sessão aberta e continue a tarefa automaticamente após a redefinição. Veja Desativar continuação automática. Requer Claude Code v2.1.234 ou posterior.

  • Scope: User or managed. Leia a partir das configurações do usuário, --settings e configurações gerenciadas apenas. Quando nenhum desses define a chave, um arquivo de configurações de projeto ou local que a define desativa o recurso em vez de ser ignorado.
  • Type: Boolean
    • true: depois que um limite de uso do claude.ai interrompe sua sessão, Claude Code aguarda na sessão aberta e continua a tarefa automaticamente após a redefinição
    • false: Claude Code não inicia a espera por conta própria. Você ainda pode iniciar uma espera você mesmo no menu de opções de limite de uso
  • Default: true
{
  "autoContinueAtUsageLimit": false
}

Aparece em /config como Continue automatically at usage limit, que escreve esta chave nas configurações do usuário; Claude Code oculta a linha enquanto configurações gerenciadas ou a flag --settings definem a chave.

`autoScrollEnabled`

Siga a nova saída até o final da conversa em renderização em tela cheia. Desative-a para permanecer onde você rolou enquanto Claude continua trabalhando; prompts de permissão ainda rolam para a visualização.

  • Scope: Any file
  • Type: Boolean
    • true: a conversa segue a nova saída até o final
    • false: você permanece onde rolou enquanto Claude continua trabalhando; prompts de permissão ainda aparecem abaixo da transcrição
  • Default: true
{
  "autoScrollEnabled": false
}

Aparece em /config como Auto-scroll quando a renderização em tela cheia está ativada, que escreve esta chave nas configurações do usuário.

`axScreenReader`

Renderize saída amigável ao leitor de tela: texto simples sem bordas decorativas ou animações. O modo leitor de tela usa o renderizador clássico, portanto a configuração tui não tem efeito enquanto está ativo; sessões em segundo plano anexadas ainda renderizam em tela cheia.

  • Scope: Any file
  • Type: Boolean
    • true: Claude Code renderiza texto simples sem bordas decorativas ou animações, usando o renderizador clássico
    • false: Claude Code renderiza normalmente
  • Default: unset, portanto o modo leitor de tela está desativado
  • Per-session overrides: --ax-screen-reader tem precedência sobre CLAUDE_AX_SCREEN_READER, e ambos têm precedência sobre esta chave para uma sessão
{
  "axScreenReader": true
}

`bashEditDiffEnabled`

Escolha se Claude Code registra quais arquivos foram alterados em um repositório Git enquanto um comando Bash é executado. Quando registra, você vê seu diff no terminal após o comando, e seus hooks PostToolUse Bash recebem a lista de arquivos alterados.

Um arquivo listado nem sempre é um que o comando alterou. Uma alteração que outro programa ou outra chamada Bash fez enquanto o comando era executado também pode aparecer lá.

Defina a chave como true para registrá-los em todos os modos de permissão. Requer Claude Code v2.1.269 ou posterior.

  • Scope: User or managed. Um true conta apenas a partir de suas configurações de usuário, JSON passado com --settings, ou configurações gerenciadas, portanto um true em um arquivo .claude/settings.json ou .claude/settings.local.json de um repositório não pode ativar o registro. Um false em qualquer arquivo de repositório ainda o desativa a menos que um arquivo de precedência mais alta defina true.
  • Type: Boolean
  • Default: unset, portanto Claude Code registra alterações no modo auto e modo bypassPermissions quando direciona Claude a editar arquivos através de Bash
  • Per-session overrides: CLAUDE_CODE_BASH_EDIT_DIFF tem precedência sobre esta chave para uma sessão
{
  "bashEditDiffEnabled": true
}

`companyAnnouncements`

Mostre os anúncios da sua organização aos usuários na inicialização. Quando você lista mais de um, Claude Code escolhe um aleatoriamente para cada sessão; no primeiro lançamento de uma pessoa, ele mostra a primeira entrada.

  • Scope: Any file
  • Type: array de strings
  • Default: unset, portanto nenhum anúncio é exibido
{
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.example.com"
  ]
}

`defaultShell`

Escolha se Bash ou PowerShell executa os comandos shell que você digita com o prefixo ! na caixa de entrada, aqueles que Claude Code executa diretamente e adiciona à sessão.

"powershell" funciona apenas enquanto a ferramenta PowerShell está ativada. A ferramenta está ativada por padrão no Windows sem Git Bash, e no Windows com Git Bash para contas claude.ai e Console. Em sessões do Amazon Bedrock, da Plataforma de Agentes do Google Cloud e do Microsoft Foundry, e no macOS, Linux e WSL, defina CLAUDE_CODE_USE_POWERSHELL_TOOL=1 para ativar a ferramenta. Defina essa variável como 0 para desativar a ferramenta.

  • Scope: Any file
  • Type: string, um de:
    • "bash": Claude Code executa seus comandos ! em Bash
    • "powershell": Claude Code executa seus comandos ! em PowerShell
  • Default: "bash", ou "powershell" no Windows quando Bash não está disponível
{
  "defaultShell": "powershell"
}

Se o shell que você nomeou não estiver disponível, Claude Code usa o outro: "powershell" volta para Bash quando a ferramenta PowerShell está desativada, e "bash" volta para PowerShell quando Bash não está instalado.

`dialogExpiry`

Defina o prazo para diálogos que Claude Code encaminha para um cliente remoto, como um host Remote Control ou SDK, e para o diálogo de aprovação de uma mensagem entre sessões retida. No Claude Code v2.1.236 ou posterior, o mesmo prazo limita o prompt de consentimento de créditos de uso Fable no meio da sessão em uma sessão que pode não ter ninguém no terminal. Quando nenhuma resposta chega antes do prazo, Claude Code cancela o diálogo e continua com seu padrão sem ação. Requer Claude Code v2.1.224 ou posterior.

{
  "dialogExpiry": "10m"
}

Prompts de permissão e perguntas AskUserQuestion usam seus próprios fluxos e não são regidos por este prazo. Aparece em /config como Dialog expiry, que escreve esta chave nas configurações do usuário; a linha requer Claude Code v2.1.232 ou posterior, e Claude Code a oculta enquanto configurações gerenciadas ou a flag --settings definem a chave.

`editorMode`

Escolha o modo de vinculação de teclas para o prompt de entrada.

  • Scope: Any file
  • Type: string, um de:
    • "normal": atalhos de teclado padrão na entrada do prompt
    • "vim": edição no estilo vim com modos NORMAL, INSERT e VISUAL
  • Default: "normal"
{
  "editorMode": "vim"
}

Aparece em /config como Editor mode, que escreve esta chave nas configurações do usuário.

`emojiCompletionEnabled`

Mostre sugestões de emoji quando você digita : mais um código abreviado na entrada do prompt, e substitua um código abreviado concluído como :heart: por seu emoji. Defina como false para desativar ambos.

  • Scope: Any file
  • Type: Boolean
    • true: Claude Code mostra sugestões de emoji após : e substitui um código abreviado concluído por seu emoji
    • false: Claude Code não sugere emoji nem substitui códigos abreviados
  • Default: true
{
  "emojiCompletionEnabled": false
}

Veja Códigos abreviados de emoji. Requer Claude Code v2.1.217 ou posterior.

`fileSuggestion`

Execute seu próprio comando para fornecer preenchimento automático de caminho de arquivo @ em vez da sugestão de arquivo integrada. A sugestão integrada usa travessia rápida do sistema de arquivos; um grande monorepo pode se sair melhor com indexação específica do projeto, como um índice de arquivo pré-construído.

  • Scope: Any file. Sob os portões de linha de status e sugestão de arquivo, Claude Code desativa o comando ou executa apenas um valor gerenciado, e ignora o seu sem aviso.
  • Type: objeto com type, sempre "command", e command, o comando shell a executar
  • Default: unset, portanto Claude Code usa a sugestão de arquivo integrada
{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

Depois de salvar isso, digite @ seguido por parte de um caminho no prompt: as sugestões vêm da saída do seu comando.

Entrada e saída do comando

Claude Code executa o comando com as mesmas variáveis de ambiente que hooks, incluindo CLAUDE_PROJECT_DIR, e para de aguardar após cinco segundos. O comando recebe JSON em stdin com um campo query contendo o que você digitou até agora:

{"query": "src/comp"}

Imprima caminhos de arquivo separados por nova linha em stdout. Claude Code mostra no máximo 15:

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

O script a seguir lê a consulta e a passa para um índice de arquivo de repositório:

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

`footerLinksRegexes`

Renderize badges clicáveis extras no rodapé abaixo da caixa de entrada quando um regex corresponde à saída de turno: resultados de ferramentas, incluindo conteúdo de arquivo e páginas buscadas, e respostas do próprio Claude. Use-o para transformar IDs impressos por CLIs de projeto, como ferramentas de revisão e rastreadores de problemas, em links de sessão.

  • Scope: User or managed
  • Type: array de objetos, cada um com type definido como "regex", um regex pattern, um template url, e um label opcional; placeholders {name} em url e label são preenchidos a partir de grupos de captura nomeados em pattern
  • Default: unset, portanto nenhum badge é renderizado

Este exemplo corresponde a chaves de problema como PROJ-1234 e constrói cada link a partir da chave capturada:

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

Com isso configurado, quando PROJ-1234 aparece em um resultado de ferramenta ou na resposta de Claude, um badge PROJ-1234 aparece no rodapé vinculando a https://issues.example.com/browse/PROJ-1234.

Restrições de badge

A URL, rótulo e contagem de badges de cada entrada são limitados da seguinte forma:

Restrição Comportamento
Origem da URL Os valores capturados são codificados em URL e a URL construída deve compartilhar a origem literal do template. Uma captura pode preencher um segmento de caminho ou valor de consulta, mas não pode alterar para onde o link aponta
Comprimento da URL URLs construídas com mais de 2048 caracteres são descartadas
Esquema de URL Deve ser https, http, ou um esquema de link profundo de editor ou espaço de trabalho reconhecido: vscode, vscode-insiders, cursor, windsurf, zed, jetbrains, idea, slack, linear, notion, figma
Rótulo Padrão para o texto correspondido e é truncado para 28 colunas de exibição
Contagem de badges No máximo 5 badges são renderizados. O mais antigo é deslocado por correspondências mais recentes e /clear os remove

Quando um turno é concluído, Claude Code corresponde cada regex pattern da entrada contra a saída do turno no thread principal, portanto um regex lento bloqueia a UI até que termine. Quantificadores aninhados como (a+)+$ podem levar exponencialmente tempo contra certas entradas e congelar a sessão, portanto mantenha cada pattern linear e evite aninhar + ou *.

Badges de rodapé são renderizados junto com uma linha de status personalizada quando uma está configurada; nenhum substitui o outro. Use uma linha de status para uma linha orientada por script que calcula seu próprio conteúdo a partir de dados de sessão, e badges de rodapé para transformar IDs da conversa em links sem um script.

`keybindingFlavor`

Na v2.1.238 até v2.1.260, defini-la como "readline" fez Ctrl+W deletar de volta ao espaço em branco anterior em vez de apenas a palavra anterior.

  • Scope: Any file
  • Type: string, "classic" ou "readline"
  • Default: unset

`prefersReducedMotion`

Reduza ou desative animações de interface, como o spinner, shimmer e efeitos de flash. Aparece em /config como Reduce motion.

  • Scope: Any file
  • Type: Boolean
    • true: Claude Code reduz ou desativa animações de interface, como o spinner, shimmer e efeitos de flash
    • false: o mesmo que unset; Claude Code mostra suas animações
  • Default: false
{
  "prefersReducedMotion": true
}

`promptSuggestionEnabled`

Mostre ou oculte sugestões de prompt, as previsões acinzentadas que aparecem na sua entrada de prompt. Defina como false, ou desative Prompt suggestions em /config, para ocultá-las.

  • Scope: Any file
  • Type: Boolean
    • true: você vê sugestões de prompt na sua entrada de prompt
    • false: Claude Code oculta sugestões de prompt
  • Default: true
  • Per-session overrides: CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION tem precedência sobre esta chave para uma sessão
{
  "promptSuggestionEnabled": false
}

Sugestões de prompt precisam de uma conta claude.ai ou Console com telemetria ativada. No Amazon Bedrock, na Plataforma de Agentes do Google Cloud e no Microsoft Foundry, ou com telemetria desativada, como por DISABLE_TELEMETRY, esta chave não tem efeito e apenas CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=1 as ativa.

`respectGitignore`

Controle se o seletor de arquivo @ deixa de fora arquivos que correspondem aos padrões .gitignore. Aparece em /config como Respect .gitignore in file picker.

  • Scope: Any file. Quando nenhum arquivo de configurações a define, Claude Code volta para respectGitignore em ~/.claude.json, que o toggle /config escreve.
  • Type: Boolean
    • true: o seletor de arquivo @ deixa de fora arquivos que correspondem aos padrões .gitignore
    • false: o seletor de arquivo @ inclui arquivos que correspondem aos padrões .gitignore
  • Default: true
{
  "respectGitignore": false
}

`respondToBashCommands`

Escolha se Claude responde depois que você executa um comando shell com o prefixo ! na caixa de entrada. Por padrão, Claude Code adiciona a saída do comando à conversa e Claude responde a ela. Defina esta chave como false para adicionar a saída ao contexto sem uma resposta, para que você possa executar vários comandos e perguntar sobre eles juntos.

  • Scope: Any file
  • Type: Boolean
    • true: Claude Code adiciona a saída do comando à conversa e Claude responde a ela
    • false: Claude Code adiciona a saída ao contexto sem uma resposta
  • Default: true
{
  "respondToBashCommands": false
}

Veja Shell mode com prefixo !.

`showClearContextOnPlanAccept`

Quando Claude termina um plano em modo de plano, ele mostra um menu de aprovação. O planejamento pode usar muito contexto, portanto esta chave adiciona uma primeira opção a esse menu, Yes, clear context and …, que aprova o plano, limpa o contexto da conversa e começa a implementar apenas a partir do plano. O resto do rótulo nomeia o modo de permissão em que a sessão continua, e mostra quanto do seu contexto o planejamento usou.

  • Scope: Any file
  • Type: Boolean
    • true: o menu de aprovação do plano obtém uma primeira opção, Yes, clear context and …, que aprova o plano e limpa o contexto da conversa
    • false: o menu de aprovação do plano não mostra nenhuma opção de limpar contexto
  • Default: false
{
  "showClearContextOnPlanAccept": true
}

`showTurnDuration`

Mostre ou oculte a mensagem de duração do turno após cada resposta, como "Cooked for 1m 6s · done 6:05 PM". O relógio após "done" mostra quando o turno terminou; timeFormat e timeZone controlam seu formato e zona. Aparece em /config como Show turn duration.

  • Scope: Any file. Um valor em ~/.claude.json de uma versão anterior se aplica quando nenhum arquivo de configurações a define.
  • Type: Boolean
    • true: você vê a mensagem de duração do turno após cada resposta
    • false: Claude Code oculta a mensagem de duração do turno
  • Default: true
{
  "showTurnDuration": false
}

`spellcheck`

Sublinhe palavras com erros de ortografia na entrada do prompt conforme você digita, usando um verificador de ortografia que você instala. Claude Code verifica apenas o texto na caixa de entrada. Verificar ortografia conforme você digita cobre a instalação de aspell, hunspell ou ispell e o que o verificador cobre. Requer Claude Code v2.1.235 ou posterior.

  • Scope: User or managed. O bloco do nível mais alto que a define se aplica como um todo.
  • Type: objeto com enabled (Boolean), checker ("aspell", "hunspell", "ispell", ou "auto"), language (string, passada para o verificador como seu nome de dicionário), e color (string, um nome de cor de terminal, #rrggbb, rgb(r,g,b), ansi256(n), ou ansi:<name>)
  • Default: unset, portanto a verificação de ortografia está desativada; checker padrão para "auto", o primeiro dos três encontrado em PATH; language padrão para o próprio dicionário do verificador; color padrão para a cor de erro do tema
{
  "spellcheck": { "enabled": true, "language": "en_GB" }
}

`spinnerTipsEnabled`

Enquanto Claude trabalha, a linha do spinner gira através de dicas curtas sobre recursos do Claude Code, como "Use Plan Mode para se preparar para uma solicitação complexa antes de fazer alterações. Pressione Shift+Tab duas vezes para ativar." Defina esta chave como false para ocultá-las. Aparece em /config como Show tips.

  • Scope: Any file
  • Type: Boolean
    • true: você vê dicas no spinner enquanto Claude está trabalhando
    • false: Claude Code oculta dicas do spinner
  • Default: true
{
  "spinnerTipsEnabled": false
}

`spinnerTipsOverride`

Adicione suas próprias dicas às dicas do spinner que Claude Code mostra enquanto Claude trabalha, ou substitua as dicas integradas pelas suas. Claude Code coloca suas dicas na mesma rotação que as integradas: ele escolhe a dica que não foi mostrada há mais tempo, pula dicas ainda em seu cooldown, e quebra empates por prioridade.

Se você definir spinnerTipsEnabled como false, Claude Code oculta todas as dicas, incluindo as suas.

  • Scope: Any file. Claude Code honra objetos de dica, tipsFile, label e excludeDefault das configurações do usuário, a flag --settings e configurações gerenciadas; a partir de configurações de projeto e local, ele lê apenas dicas de string simples.
  • Type: objeto com campos tips, tipsFile, label e excludeDefault, cada um opcional
  • Default: unset, portanto Claude Code mostra apenas as dicas integradas

Objetos de dica, tipsFile, label e a regra da linha Scope que configurações de projeto e local contribuem apenas com strings simples requerem Claude Code v2.1.247 ou posterior. Em versões anteriores, excludeDefault de um arquivo de projeto ou local também se aplica.

Cada entrada tips é uma string simples ou um objeto com estes campos:

Campo Obrigatório Descrição
id Sim Até 64 letras, dígitos, ., _, ou -. Claude Code baseia o histórico de exibição da dica nele, portanto o cooldown da dica sobrevive à reordenação da lista. De duas entradas com o mesmo id, Claude Code usa a primeira
text Sim A dica, uma linha de até 500 caracteres. Claude Code remove escapes ANSI e caracteres de controle e colapsa espaço em branco
cooldownSessions Não Sessões que Claude Code aguarda antes de mostrar a dica novamente, 0 a 1000, padrão 0
priority Não Ordem entre dicas que não foram mostradas igualmente há muito tempo, maior primeiro, -10 a 10, padrão 0

Claude Code lê uma string simples como uma dica com esses padrões e um id baseado em posição, portanto seu histórico de exibição é redefinido quando você reordena a lista. Dê a uma dica um id para manter seu histórico entre edições.

Claude Code lê no máximo 200 dicas entre tips e tipsFile, e descarta uma entrada inválida com um aviso de debug em vez de rejeitar o arquivo de configurações.

Use os campos restantes para nomear um arquivo de dicas, definir o prefixo e ocultar as dicas integradas:

  • tipsFile: um caminho absoluto ou ~/ para um arquivo JSON local contendo um array das mesmas entradas, ou um objeto com um array tips, até 256 KB. Claude Code lê o arquivo uma vez por processo, portanto carrega suas edições na próxima inicialização. Você não pode defini-lo através de configurações gerenciadas por servidor; implante tips inline lá, ou implante o caminho em um managed-settings.json em disco.
  • label: o prefixo que Claude Code mostra antes de dicas das configurações do usuário, --settings e configurações gerenciadas, até 40 caracteres. O padrão é Tip, o mesmo prefixo que as dicas integradas, e dicas de configurações de projeto e local sempre o usam.
  • excludeDefault: defina como true para ocultar as dicas integradas e mostrar apenas as suas. Quando Claude Code não consegue carregar nenhuma de suas dicas, por exemplo porque tipsFile não existe ou cada entrada é inválida, ele mantém a rotação integrada em vez de um spinner vazio.

Quando mais de um arquivo de configurações define a chave, Claude Code mostra dicas de todos eles e pega tipsFile, label e excludeDefault de qualquer um das configurações gerenciadas, a flag --settings e configurações do usuário que seja o de precedência mais alta que define cada um.

Este exemplo, em suas configurações do usuário, adiciona uma dica de string simples e uma dica de objeto à rotação sob o prefixo Acme tip:

{
  "spinnerTipsOverride": {
    "label": "Acme tip",
    "tips": [
      "Run /review before opening a PR",
      {
        "id": "gateway-errors",
        "text": "Seeing 5xx errors? Check the gateway status page first",
        "cooldownSessions": 5,
        "priority": 2
      }
    ]
  }
}

Cada campo no exemplo muda uma coisa sobre como Claude Code mostra as dicas:

  • label: Claude Code mostra ambas as dicas como Acme tip: ... em vez de Tip: ....
  • A string simples: Claude Code lhe dá os padrões, portanto pode aparecer novamente na próxima sessão.
  • id: Claude Code baseia o histórico de exibição da segunda dica em gateway-errors, portanto seu cooldown ainda se aplica depois que você adiciona ou reordena dicas.
  • cooldownSessions: depois que Claude Code mostra a dica gateway-errors, ele não mostra essa dica novamente até cinco sessões depois.
  • priority: quando a dica gateway-errors e outra dica não foram mostradas pelo mesmo número de sessões, por exemplo quando nenhuma foi mostrada ainda, Claude Code mostra gateway-errors primeiro. A string simples tem a prioridade padrão, 0.

Enquanto Claude trabalha, Claude Code mostra suas dicas no spinner com seu prefixo, como Acme tip: Run /review before opening a PR.

`spinnerVerbs`

Enquanto um turno está em progresso, o spinner mostra um verbo rotativo como "Accomplishing", "Architecting", ou "Baking". Use esta chave para adicionar seus próprios verbos a essa rotação ou substituir a lista integrada pela sua.

  • Scope: Any file
  • Type: objeto com um array verbs de strings e mode, um de:
    • "append": Claude Code adiciona seus verbos ao conjunto integrado
    • "replace": Claude Code mostra apenas seus verbos
  • Default: unset, portanto Claude Code usa os verbos integrados

Este exemplo adiciona dois verbos ao conjunto integrado:

{
  "spinnerVerbs": {
    "mode": "append",
    "verbs": ["Pondering", "Crafting"]
  }
}

No modo "replace" com um array verbs vazio, Claude Code mantém os verbos integrados.

`statusLine`

Execute seu próprio comando para renderizar uma linha de status abaixo do prompt com contexto como o modelo, custo ou branch git. Campos opcionais ajustam espaçamento, adicionam re-execuções periódicas e ocultam o indicador de modo vim integrado quando seu script renderiza vim.mode em si.

  • Scope: Any file. Quando allowManagedHooksOnly está ativado, ou disableAllHooks está definido fora das configurações gerenciadas, apenas o valor das configurações gerenciadas é executado.
  • Type: objeto com type definido como "command" e uma string command, mais padding opcional como um número de caracteres, refreshInterval como um número de segundos, mínimo 1, e hideVimModeIndicator como um Boolean
  • Default: unset, portanto nenhuma linha de status

Este exemplo imprime o nome do modelo e o uso de contexto, e adiciona dois caracteres de espaçamento horizontal:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",
    "padding": 2
  }
}

O exemplo precisa de jq instalado e é executado em um shell. Para equivalentes PowerShell e Git Bash, veja Configuração do Windows; para a configuração completa, veja Configurar manualmente uma linha de status.

`subagentStatusLine`

Quando Claude executa subagentes, Claude Code os lista em uma exibição de tarefa abaixo do prompt, uma linha por subagente mostrando name · description · token count. Esta chave permite que você execute seu próprio comando para reescrever essas linhas, por exemplo para mostrar o uso de contexto de cada subagente como uma porcentagem. Em cada atualização, Claude Code envia as linhas visíveis como um objeto JSON em stdin, com um array tasks carregando id, name, status, model, tokenCount de cada subagente e mais, e substitui a linha para cada id que você escreve de volta como uma linha {"id", "content"}. Linhas que você não escreve de volta mantêm a renderização padrão.

  • Scope: Any file. Quando allowManagedHooksOnly está ativado, ou disableAllHooks está definido fora das configurações gerenciadas, apenas o valor das configurações gerenciadas é executado.
  • Type: objeto com type definido como "command" e uma string command
  • Default: unset, portanto Claude Code renderiza as linhas padrão
{
  "subagentStatusLine": {
    "type": "command",
    "command": "jq -c '.tasks[] | {id, content: \"\\(.name): \\(.tokenCount) tokens\"}'"
  }
}

Veja Linhas de status de subagente.

`syntaxHighlightingDisabled`

Claude Code colore código por linguagem nos diffs, blocos de código e visualizações de arquivo que mostra no terminal, com seu highlighter integrado; nenhum plugin ou servidor de linguagem está envolvido. Defina esta chave como true para mostrá-los como texto simples em vez disso, por exemplo se as cores entrarem em conflito com seu tema de terminal ou desacelerem um leitor de tela.

  • Scope: Any file
  • Type: Boolean
    • true: Claude Code desativa o destaque de sintaxe em diffs, blocos de código e visualizações de arquivo
    • false: Claude Code destaca a sintaxe
  • Default: false
{
  "syntaxHighlightingDisabled": true
}

`terminalProgressBarEnabled`

Alguns terminais podem mostrar um indicador de progresso na aba ou na barra de tarefas para o programa em execução neles. Enquanto Claude está trabalhando, Claude Code relata um estado em progresso ao terminal, para que você possa ver de outra aba ou janela se a sessão ainda está ocupada. O indicador permanece visível após o turno terminar enquanto subagentes em segundo plano ou fluxos de trabalho dinâmicos ainda estão em execução, e é limpo assim que a sessão fica ociosa.

Claude Code o relata apenas em terminais que suportam o indicador: ConEmu, Ghostty 1.2.0 ou posterior, e iTerm2 3.6.6 ou posterior. Defina esta chave como false para impedir que Claude Code o relate. Aparece em /config como Terminal progress bar.

  • Scope: Any file. Um valor em ~/.claude.json de uma versão anterior se aplica quando nenhum arquivo de configurações a define.
  • Type: Boolean
    • true: você vê a barra de progresso do terminal em terminais que a suportam
    • false: Claude Code oculta a barra de progresso do terminal
  • Default: true
{
  "terminalProgressBarEnabled": false
}

`terminalTitleFromRename`

Claude Code define o título da aba do seu terminal. Por padrão, ele usa um título que gera a partir da conversa, e uma vez que você dá à sessão um nome com /rename ou --name, a aba mostra esse nome em vez disso. Defina esta chave como false para manter o título gerado na aba mesmo depois de nomear a sessão. O nome em si ainda se aplica, portanto /resume <name> e o seletor de sessão o encontram.

  • Scope: Any file
  • Type: Boolean
    • true: o título da aba do terminal mostra o nome da sessão que você definiu
    • false: a aba mantém o título que Claude Code gera a partir de sua conversa
  • Default: true
{
  "terminalTitleFromRename": false
}

Para impedir que Claude Code atualize o título do terminal completamente, defina CLAUDE_CODE_DISABLE_TERMINAL_TITLE como 1 em vez disso.

`theme`

Escolha o tema de cor para a interface. Aparece em /config como Theme.

  • Scope: Any file. Um valor em ~/.claude.json de uma versão anterior se aplica quando nenhum arquivo de configurações a define.
  • Type: string, um de:
    • "auto": corresponde ao fundo claro ou escuro do seu terminal
    • "dark": o tema escuro
    • "light": o tema claro
    • "dark-daltonized": o tema escuro com cores amigáveis ao daltônico
    • "light-daltonized": o tema claro com cores amigáveis ao daltônico
    • "dark-ansi": o tema escuro usando apenas a paleta de cores ANSI do seu terminal
    • "light-ansi": o tema claro usando apenas a paleta de cores ANSI do seu terminal
    • "custom:<slug>" ou "custom:<plugin-name>:<slug>": um tema personalizado de ~/.claude/themes/ ou um plugin
  • Default: "dark"
{
  "theme": "light-daltonized"
}

Veja Criar um tema personalizado.

`timeFormat`

Escolha como Claude Code escreve os horários que mostra na interface, como o done 6:05 PM no final de cada mensagem de duração de turno e os timestamps no visualizador de transcrição. Para escolher uma predefinição, execute /config e defina Time format. Requer Claude Code v2.1.257 ou posterior.

  • Scope: Any file
  • Type: string, um de:
    • "auto": o mesmo que unset; cada hora mantém seu formato integrado, que segue sua localidade na mensagem de duração de turno
    • "12-hour": um relógio de 12 horas
    • "24-hour": um relógio de 24 horas
    • "24-hour-utc": um relógio de 24 horas em UTC com Z após os minutos, como 18:05Z; Claude Code ignora timeZone para esta predefinição
    • Um padrão strftime como "%H:%M": Claude Code escreve cada hora com o padrão. Qualquer valor que contenha um % é um padrão, e qualquer outro valor fora das predefinições conta como "auto"
  • Default: "auto"
{
  "timeFormat": "24-hour"
}

/config oferece apenas as predefinições, portanto para usar um padrão strftime, adicione a chave a um arquivo de configurações. Este exemplo mostra cada hora como um relógio de 24 horas de dois dígitos:

{
  "timeFormat": "%H:%M"
}

A mensagem de duração de turno e o visualizador de transcrição então mostram horários como 18:05. No visualizador de transcrição, o padrão é o timestamp inteiro, portanto adicione diretivas de data quando quiser a data lá. Este exemplo coloca a data na frente do relógio:

{
  "timeFormat": "%Y-%m-%d %H:%M"
}

As mesmas superfícies então mostram horários como 2026-09-01 18:05.

`timeZone`

Mostre os horários na interface em um fuso horário diferente do seu sistema. Defina como um nome de fuso horário IANA, como "UTC" ou "Europe/Dublin". Os horários que timeFormat controla então mostram nesta zona. Se timeFormat for "24-hour-utc", os horários permanecem em UTC e Claude Code ignora esta chave. /config não tem linha para esta chave, portanto defina em um arquivo de configurações. Requer Claude Code v2.1.257 ou posterior.

  • Scope: Any file
  • Type: string, um nome de fuso horário IANA. Quando Claude Code não reconhece o nome, usa seu fuso horário do sistema
  • Default: unset, portanto os horários mostram em seu fuso horário do sistema
{
  "timeZone": "Europe/Dublin"
}

`tui`

Escolha o renderizador de UI do terminal. Use "fullscreen" para o renderizador alt-screen sem cintilação com scrollback virtualizado, ou "default" para o renderizador clássico de tela principal. Executar /tui fullscreen ou /tui default escreve esta chave para você.

  • Scope: Any file
  • Type: string, um de:
    • "default": o renderizador clássico de tela principal
    • "fullscreen": o renderizador alt-screen sem cintilação com scrollback virtualizado
  • Default: unset, portanto Claude Code escolhe o renderizador para você
  • Per-session overrides: CLAUDE_CODE_NO_FLICKER e CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN têm precedência sobre esta chave para uma sessão: CLAUDE_CODE_NO_FLICKER=1 ativa tela cheia, e CLAUDE_CODE_NO_FLICKER=0 ou CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 a desativa; quando ambos estão definidos, Claude Code a desativa
{
  "tui": "fullscreen"
}

Sob tmux -CC ou sobre SSH para Windows, Claude Code mantém o renderizador clássico a menos que você defina CLAUDE_CODE_NO_FLICKER=1. Sessões em segundo plano abertas de agent view sempre usam o renderizador em tela cheia independentemente desta configuração.

`verbose`

Por padrão, a transcrição colapsa cada chamada de ferramenta para um resumo curto, como o comando que Claude executou e uma contagem de linhas de sua saída, e você pressiona Ctrl+O para alternar a transcrição inteira para a visualização expandida quando quiser os detalhes. Defina esta chave como true para mostrar a entrada e saída completas de cada chamada de ferramenta inline conforme acontece, o que é útil quando você está depurando um hook, um servidor MCP ou um comando shell longo. Aparece em /config como Verbose output.

  • Scope: Any file. Um valor em ~/.claude.json de uma versão anterior se aplica quando nenhum arquivo de configurações a define.
  • Type: Boolean
    • true: você vê saída completa de ferramenta
    • false: você vê resumos truncados de saída de ferramenta
  • Default: false
  • Per-session overrides: --verbose tem precedência sobre esta chave para uma sessão
{
  "verbose": true
}

Um valor viewMode ou uma seleção sticky /focus substitui esta chave a cada sessão.

`viewMode`

Defina a visualização de transcrição em que Claude Code começa: "default", "verbose", ou "focus". Quando definido, substitui tanto a seleção sticky /focus quanto a configuração verbose.

  • Scope: Any file
  • Type: string, um de:
    • "default": a transcrição normal com saída de ferramenta truncada
    • "verbose": a transcrição com saída de ferramenta completa
    • "focus": apenas seu último prompt, um resumo de uma linha de chamadas de ferramenta com diffstats de edição, e a resposta final. A visualização de foco precisa do renderizador em tela cheia
  • Default: unset, portanto a configuração verbose e sua última escolha /focus se aplicam
  • Per-session overrides: --verbose tem precedência sobre esta chave para uma sessão
{
  "viewMode": "focus"
}

`vimInsertModeRemaps`

Mapeie sequências de INSERT-mode de duas teclas para Escape no modo de editor vim. Cada chave é exatamente dois caracteres imprimíveis digitados em sequência, e "<Esc>" é o único alvo suportado; Claude Code ignora outras entradas. Requer Claude Code v2.1.208 ou posterior.

  • Scope: User or managed. Um repositório não pode remapear seus pressionamentos de tecla.
  • Type: objeto mapeando uma sequência de dois caracteres para "<Esc>"
  • Default: unset
{
  "vimInsertModeRemaps": {
    "jj": "<Esc>"
  }
}

Não tem efeito a menos que editorMode seja "vim". Veja Remapear sequências de tecla de INSERT-mode. Requer Claude Code v2.1.208 ou posterior.

`voice`

Ative ditado por voz e escolha como a tecla de ditado se comporta. Claude Code escreve este objeto para você quando você executa /voice.

  • Scope: Any file
  • Type: objeto com enabled como um Boolean, autoSubmit como um Boolean que se aplica apenas no modo hold, e mode, um de:
    • "hold": você segura a tecla de ditado enquanto fala e a solta para parar
    • "tap": você toca a tecla uma vez para começar a gravar e novamente para enviar
  • Default: unset, portanto o ditado está desativado; quando enabled é true e mode é unset, Claude Code usa "hold"

Este exemplo ativa o ditado e faz a tecla tocar uma vez para começar a gravar e novamente para enviar:

{
  "voice": {
    "enabled": true,
    "mode": "tap"
  }
}

autoSubmit envia o prompt quando você solta a tecla no modo hold. O ditado por voz requer uma conta claude.ai.

`voiceEnabled`

Ative o ditado por voz com o formulário Boolean único que precede o objeto voice. Quando ambos estão definidos, voice.enabled se aplica.

  • Scope: Any file
  • Type: Boolean
    • true: o ditado por voz está ativado quando você está conectado com uma conta claude.ai e a política da sua organização permite voz, a menos que voice.enabled esteja definido
    • false: o ditado por voz está desativado, a menos que voice.enabled esteja definido
  • Default: unset
{
  "voiceEnabled": true
}

`wheelScrollAccelerationEnabled`

Acelere a velocidade de rolagem da roda do mouse durante rolagens rápidas em renderização em tela cheia. Defina como false para uma taxa de rolagem constante por entalhe de roda.

  • Scope: Any file
  • Type: Boolean
    • true: Claude Code acelera a velocidade de rolagem da roda do mouse durante rolagens rápidas
    • false: Claude Code rola a uma taxa constante por entalhe de roda
  • Default: true
{
  "wheelScrollAccelerationEnabled": false
}

Git e atribuição

Controle a atribuição que Claude Code adiciona aos commits e pull requests e como funciona com git.

`attribution`

Personalize a atribuição que Claude Code adiciona aos commits git e pull requests. Os commits recebem um git trailer como Co-Authored-By por padrão; as descrições de pull request recebem texto simples. Defina cada parte separadamente com as sub-chaves abaixo.

Para ocultar toda a atribuição, defina attribution como false. Em um arquivo de configurações que versões anteriores também leem, defina commit e pr como strings vazias e sessionUrl como false em vez disso.

Este exemplo substitui a atribuição de commit, remove a atribuição de pull request e descarta o link da sessão:

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

Depois que você definir commit ou pr, Claude Code ignora a configuração includeCoAuthoredBy descontinuada e usa seu texto padrão para qualquer um dos dois que você deixou não definido.

Claude Code informa a Claude que suas próprias instruções sobre atribuição, como uma regra CLAUDE.md ou memory, têm precedência sobre essas linhas de commit e PR, a menos que a linha esteja definida em managed settings.

`includeCoAuthoredBy`

Use attribution em vez disso, que substitui esta chave e permite que você altere ou oculte o trailer de commit, o texto de pull request e o link da sessão separadamente. Claude Code ainda honra includeCoAuthoredBy: false de arquivos de configuração anteriores a attribution, mas o ignora depois que você define attribution.commit ou attribution.pr.

  • Escopo: Qualquer arquivo
  • Tipo: Boolean
    • true: o mesmo que não definido; Claude Code adiciona o trailer de commit e o texto de atribuição de pull request
    • false: Claude Code omite tanto o trailer de commit quanto o texto de atribuição de pull request, a menos que attribution defina commit ou pr, caso em que as regras de attribution se aplicam
  • Padrão: true
{
  "includeCoAuthoredBy": false
}

Para ocultar toda a atribuição, consulte attribution.

`includeGitInstructions`

Claude Code fornece a Claude duas partes relacionadas a git de contexto: suas instruções integradas sobre como escrever commits e pull requests, na descrição da ferramenta Bash, e um snapshot de status git do seu repositório. O snapshot contém o branch atual, o branch principal, saída de git status e commits recentes. Claude Code o lê quando uma conversa começa.

Defina esta chave como false para deixar ambas de fora, por exemplo quando você usa suas próprias skills de fluxo de trabalho git.

  • Escopo: Qualquer arquivo
  • Tipo: Boolean
    • true: Claude Code inclui suas instruções integradas de fluxo de trabalho de commit e pull request e o snapshot de status git. As sessões em nuvem nunca incluem o snapshot
    • false: Claude Code deixa ambas de fora
  • Padrão: true
  • Substituições por sessão: CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS tem precedência sobre esta chave para uma sessão
{
  "includeGitInstructions": false
}

`prUrlTemplate`

Aponte os links de PR que Claude Code renderiza, no badge de rodapé e em resumos de resultado de ferramenta, para uma ferramenta de revisão de código interna em vez de github.com. Claude Code substitui {host}, {owner}, {repo}, {number} e {url} da URL de PR. Os links de solicitação de merge GitLab em ambas as superfícies mantêm sua URL GitLab.

  • Escopo: Qualquer arquivo
  • Tipo: string, um template de URL usando qualquer um dos cinco placeholders
  • Padrão: não definido
{
  "prUrlTemplate": "https://reviews.example.com/{owner}/{repo}/pull/{number}"
}

Claude Code aplica o template apenas aos links que renderiza; um número de PR que Claude escreve em uma mensagem, como #123, permanece como Claude o escreveu. Uma URL que não tem a forma /pull/<number> é deixada inalterada.

`attribution.commit`

Defina o texto de atribuição que Claude Code adiciona aos commits git, incluindo qualquer trailer. Defina como uma string vazia para ocultar a atribuição de commit.

  • Escopo: Qualquer arquivo
  • Tipo: string
  • Padrão: não definido, então Claude Code adiciona Co-Authored-By: <name> <noreply@anthropic.com>. O nome é o modelo ativo da sessão, como Claude Sonnet 5.
    • Quando Claude Code reconhece o modelo como um modelo Claude mas não consegue confirmar sua versão exata, escreve Claude sozinho.
    • Quando não consegue corresponder o ID do modelo a nenhum modelo Claude, como um modelo de terceiros servido através de um ANTHROPIC_BASE_URL customizado, escreve Claude Code.

Este exemplo substitui o trailer padrão por uma linha customizada e um trailer Co-Authored-By customizado:

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

`attribution.pr`

Defina o texto de atribuição que Claude Code adiciona às descrições de pull request. Defina como uma string vazia para ocultar a atribuição de pull request.

  • Escopo: Qualquer arquivo
  • Tipo: string
  • Padrão: não definido, então Claude Code adiciona 🤖 Generated with [Claude Code](https://claude.com/claude-code)
{
  "attribution": {
    "pr": ""
  }
}

`attribution.sessionUrl`

Escolha se Claude Code anexa o link de sessão claude.ai quando faz commit ou abre um pull request de uma sessão cloud ou Remote Control. Claude Code adiciona o link como um trailer Claude-Session em commits e como um link em descrições de pull request. Defina como false para omitir o link.

  • Escopo: Qualquer arquivo
  • Tipo: Boolean
    • true: Claude Code anexa o link de sessão claude.ai quando faz commit ou abre um pull request de uma sessão cloud ou Remote Control
    • false: Claude Code omite o link
  • Padrão: true
{
  "attribution": {
    "sessionUrl": false
  }
}

Hooks e automação

Registre hooks, restrinja quais hooks são executados e controle fluxos de trabalho. Para eventos de hook e payloads, consulte a referência de hooks.

`allowedHttpHookUrls`

Limite quais URLs os HTTP hooks podem atingir. Quando você define essa chave, Claude Code executa um HTTP hook apenas se sua URL corresponder a um dos padrões e bloqueia o resto sem executá-los; um array vazio bloqueia todos os HTTP hooks.

  • Escopo: Qualquer arquivo. Arrays são mesclados entre arquivos de configurações.
  • Tipo: array de padrões de URL, com * como curinga
  • Padrão: não definido, portanto qualquer URL é permitida

Este exemplo permite qualquer URL sob https://hooks.example.com/ e qualquer URL http://localhost:

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

A correspondência de nome de host não diferencia maiúsculas de minúsculas e trata hooks.example.com., com o ponto final que marca um nome de domínio totalmente qualificado, da mesma forma que hooks.example.com, que é como o DNS os trata. A lista de permissões se aplica a hooks de todas as fontes, incluindo configurações gerenciadas.

`allowManagedHooksOnly`

Restrinja a execução de hooks apenas aos hooks que sua organização implanta.

  • Escopo: Gerenciado
  • Tipo: Booleano
    • true: apenas hooks gerenciados são executados, além de hooks do Agent SDK e hooks de plugins que suas configurações gerenciadas forçam a ativar. Consulte O que é executado sob allowManagedHooksOnly
    • false: hooks de todos os escopos de configurações e plugins são executados
  • Padrão: não definido, portanto hooks de todos os escopos de configurações e plugins são executados
{
  "allowManagedHooksOnly": true
}

O que é executado sob `allowManagedHooksOnly`

Quando você o define como true, Claude Code altera quais hooks e comandos semelhantes a hooks são carregados:

  • Hooks gerenciados e SDK são executados: hooks de configurações gerenciadas e hooks que o Agent SDK registra em processo
  • Hooks de plugins forçadamente ativados são executados: hooks de plugins que suas configurações gerenciadas forçam a ativar através de enabledPlugins. Claude Code corresponde ao ID completo plugin@marketplace, portanto um plugin com o mesmo nome de um marketplace diferente permanece bloqueado. Isso permite que você distribua hooks verificados através de um marketplace da organização enquanto bloqueia tudo o mais
  • Tudo o mais é bloqueado: hooks de usuário, projeto e local, hooks de outros plugins e hooks declarados no frontmatter do agente
  • Plugins com origem em comando são desativados: Claude Code também desativa plugins com uma command source, incluindo plugins forçadamente ativados em enabledPlugins gerenciado, a menos que você defina disableCommandPluginSources explicitamente como false
  • Comandos headersHelper do marketplace são bloqueados: Claude Code também bloqueia comandos headersHelper do marketplace a menos que disableCommandPluginSources seja explicitamente definido como false, exceto para um marketplace que as próprias configurações gerenciadas declaram. Requer Claude Code v2.1.238 ou posterior
  • Linha de status e sugestão de arquivo restringem-se a configurações gerenciadas: Claude Code lê statusLine, fileSuggestion e subagentStatusLine apenas de configurações gerenciadas, seguindo os gates de linha de status e sugestão de arquivo

O comando /goal não pode ser executado enquanto essa chave está definida, porque depende de hooks.

`disableAllHooks`

Desative hooks, qualquer linha de status personalizada e qualquer comando sugestão de arquivo personalizado. Use-o para desativar todos esses temporariamente sem deletá-los de suas configurações.

  • Escopo: Qualquer arquivo. Apenas configurações gerenciadas podem desativar hooks gerenciados.
  • Tipo: Booleano
    • true: Claude Code desativa hooks, qualquer linha de status personalizada e qualquer comando de sugestão de arquivo personalizado
    • false: hooks, a linha de status e o comando de sugestão de arquivo são executados
  • Padrão: não definido, portanto hooks são executados
{
  "disableAllHooks": true
}

O alcance depende de qual arquivo carrega a chave:

  • Em configurações gerenciadas: Claude Code desativa todos os hooks configurados, incluindo os gerenciados, e continua executando os hooks que o Agent SDK registra em processo
  • Em qualquer outro arquivo de configurações: Claude Code desativa hooks de usuário, projeto, local e plugin; hooks gerenciados, hooks do Agent SDK e hooks de plugins forçadamente ativados em enabledPlugins gerenciado continuam sendo executados

Manter hooks do Agent SDK em execução quando configurações gerenciadas definem essa chave requer Claude Code v2.1.242 ou posterior.

O comando /goal não pode ser executado enquanto hooks estão desativados, e o menu /hooks mostra um aviso em vez de seus hooks.

Gates de linha de status e sugestão de arquivo

Claude Code toma duas decisões para statusLine, fileSuggestion e subagentStatusLine, nesta ordem:

Sob restrição, Claude Code executa um valor gerenciado se um for implantado. Caso contrário, ele ignora seu valor sem aviso: a linha de status é desativada e o autocomplete @ volta para a sugestão de arquivo integrada.

`disableWorkflows`

Desative fluxos de trabalho dinâmicos e os comandos de fluxo de trabalho agrupados para todos que suas configurações alcançam, como uma organização através de configurações gerenciadas. Para ativar ou desativar fluxos de trabalho apenas para você, use enableWorkflows em vez disso, que o toggle Dynamic workflows em /config escreve em suas configurações de usuário.

  • Escopo: Qualquer arquivo
  • Tipo: Booleano
    • true: Claude Code desativa fluxos de trabalho dinâmicos e os comandos de fluxo de trabalho agrupados para todos que suas configurações alcançam
    • false: o mesmo que não definido; se fluxos de trabalho estão ativados então segue enableWorkflows e o padrão do seu plano
  • Padrão: false
  • Substituições por sessão: CLAUDE_CODE_DISABLE_WORKFLOWS desativa fluxos de trabalho por uma sessão; qualquer um dos dois que os desativa, o outro não pode ativá-los novamente
{
  "disableWorkflows": true
}

`enableWorkflows`

Ative ou desative fluxos de trabalho dinâmicos para você quando o padrão do seu plano não é o que você quer. Aparece em /config como Dynamic workflows, que escreve essa chave em suas configurações de usuário e a remove novamente quando você alterna de volta para o padrão do seu plano. Para desativar fluxos de trabalho para todos a partir de configurações gerenciadas, use disableWorkflows em vez disso.

  • Escopo: Qualquer arquivo
  • Tipo: Booleano
    • true: Claude Code ativa fluxos de trabalho dinâmicos para você
    • false: Claude Code desativa fluxos de trabalho dinâmicos para você
  • Padrão: não definido, portanto fluxos de trabalho estão ativados a menos que você esteja no plano Pro, onde estão desativados
  • Substituições por sessão: CLAUDE_CODE_DISABLE_WORKFLOWS desativa fluxos de trabalho por uma sessão, e true aqui não pode ativá-los novamente enquanto estiver definido
{
  "enableWorkflows": true
}

disableWorkflows e a política de fluxos de trabalho da sua organização também têm precedência: enableWorkflows: true não pode ativar fluxos de trabalho novamente enquanto qualquer fonte os desativa. Claude Code oculta a linha /config enquanto uma fonte diferente de suas configurações de usuário define enableWorkflows, ou define disableWorkflows como true.

`hooks`

Execute seus próprios comandos, prompts, agentes, requisições HTTP ou ferramentas MCP como hooks em pontos do ciclo de vida do Claude Code, como antes de uma chamada de ferramenta ou quando uma sessão inicia; a referência de hooks lista todos os eventos, seu payload e seus códigos de saída. Cada evento mapeia para uma lista de grupos de matcher, e cada grupo lista os handlers a executar quando o matcher se aplica.

  • Escopo: Qualquer arquivo. Hooks são mesclados entre arquivos em vez de se substituírem, e hooks de configurações gerenciadas não podem ser removidos de outros arquivos.
  • Tipo: objeto com chave por evento de hook; cada valor é um array de grupos { "matcher", "hooks" } cujas entradas hooks têm um type de "command", "prompt", "agent", "http" ou "mcp_tool"
  • Padrão: não definido, portanto nenhum hook é executado

Este exemplo executa um script antes de cada chamada de ferramenta Bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/check-bash.sh" }
        ]
      }
    ]
  }
}

Para cada evento, padrão de matcher e campo de handler, consulte a referência de hooks. Para desativar hooks, consulte disableAllHooks; para limitar hooks aos que sua organização implanta, consulte allowManagedHooksOnly.

`httpHookAllowedEnvVars`

Um HTTP hook pode colocar o valor de uma variável de ambiente em um cabeçalho de requisição, por exemplo um cabeçalho Authorization: Bearer $HOOK_TOKEN, mas apenas para variáveis que o hook lista em seu próprio allowedEnvVars. Esta chave define um limite externo nessa lista para cada HTTP hook: um hook pode usar uma variável apenas se tanto seu próprio allowedEnvVars quanto esta chave a nomearem. Use-a para impedir que um hook leia um segredo que não deveria, mesmo quando a definição do hook pede por isso.

  • Escopo: Qualquer arquivo. Arrays são mesclados entre arquivos de configurações.
  • Tipo: array de nomes de variáveis de ambiente
  • Padrão: não definido, portanto a lista allowedEnvVars de cada hook se aplica

Este exemplo limita a interpolação de cabeçalho a MY_TOKEN e HOOK_SECRET:

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

A lista de permissões se aplica a hooks de todas as fontes, incluindo configurações gerenciadas.

`workflowKeywordTriggerEnabled`

Escolha se digitar a palavra-chave ultracode em um prompt dispara um fluxo de trabalho dinâmico. Defina como false para digitar a palavra sem disparar um.

  • Escopo: Qualquer arquivo. Aparece em /config como Ultracode keyword trigger.
  • Tipo: Booleano
    • true: digitar ultracode em um prompt dispara um fluxo de trabalho dinâmico
    • false: você pode digitar a palavra sem disparar um
  • Padrão: true
{
  "workflowKeywordTriggerEnabled": false
}

A configuração de esforço ultracode, /workflows e comandos de fluxo de trabalho salvos não são afetados.

`workflowSizeGuideline`

Defina a contagem de agentes que Claude visa nos fluxos de trabalho dinâmicos que escreve. Claude Code envia o valor para Claude como conselho, não um limite imposto: "small" pede menos de 5 agentes, "medium" menos de 10 e "large" menos de 50. Escolha "small" quando você quer limitar o que um fluxo de trabalho gasta. Requer Claude Code v2.1.219 ou posterior.

  • Escopo: Qualquer arquivo. Um valor lá tem precedência sobre a escolha Dynamic workflow size em /config, que Claude Code armazena em ~/.claude.json, e Claude Code oculta essa linha enquanto um arquivo de configurações define a chave.
  • Tipo: string, um de:
    • "unrestricted": sem diretriz, portanto Claude dimensiona o fluxo de trabalho para a tarefa
    • "small": Claude visa menos de 5 agentes
    • "medium": Claude visa menos de 10 agentes
    • "large": Claude visa menos de 50 agentes
  • Padrão: "medium", ou "small" quando você está conectado em um plano Pro com Claude Code v2.1.271 ou posterior
{
  "workflowSizeGuideline": "small"
}

Requer Claude Code v2.1.219 ou posterior; na v2.1.202 até v2.1.218, defina a diretriz em /config em vez disso.

Plugins e skills

Ative plugins, registre marketplaces, restrinja quais fontes de plugin sua organização permite e controle quais skills são carregadas. Para instalar e construir plugins, consulte Plugins.

`disableBundledSkills`

Desative os skills e workflows inclusos no Claude Code. Claude Code remove completamente os skills e workflows agrupados, enquanto comandos integrados como /init permanecem digitáveis, mas ficam ocultos do modelo.

  • Scope: Any file
  • Type: Boolean
    • true: Claude Code remove skills e workflows agrupados e oculta comandos integrados como /init do modelo
    • false: skills agrupados são carregados
  • Default: não definido, portanto skills agrupados são carregados
  • Per-session overrides: CLAUDE_CODE_DISABLE_BUNDLED_SKILLS definido como 1 desativa skills agrupados por uma sessão; qualquer um dos dois que os desativar, o outro não pode reativá-los
{
  "disableBundledSkills": true
}

Skills de plugins, .claude/skills/ e .claude/commands/ não são afetados. /doctor permanece digitável como os comandos integrados; para ocultá-lo, defina DISABLE_DOCTOR_COMMAND em vez disso.

`disableSkillShellExecution`

Desative a execução de shell inline para blocos !`...` e ```! em skills e comandos personalizados de fontes de usuário, projeto, plugin ou diretório adicional. Claude Code substitui cada comando por [shell command execution disabled by policy] em vez de executá-lo.

  • Scope: Any file. Um true em configurações gerenciadas não pode ser substituído por false em outro lugar.
  • Type: Boolean
    • true: Claude Code substitui cada comando de shell inline por [shell command execution disabled by policy] em vez de executá-lo
    • false: shell inline é executado
  • Default: não definido, portanto shell inline é executado
{
  "disableSkillShellExecution": true
}

Skills agrupados e skills implantados através de configurações gerenciadas não são afetados.

`skillOverrides`

Oculte ou recolha um skill sem editar seu SKILL.md. Claude Code aplica o valor sob o nome de cada skill à lista de skills que Claude vê e ao seu autocompletar /.

  • Scope: Any file. O menu /skills escreve em .claude/settings.local.json.
  • Type: objeto mapeando nome do skill para um de:
    • "on": Claude vê o skill e você pode digitar /name
    • "name-only": Claude vê o skill pelo nome sem sua descrição
    • "user-invocable-only": Claude não vê o skill, mas você ainda pode digitar /name
    • "off": Claude não vê o skill e /name fica oculto do autocompletar
  • Default: não definido, portanto cada skill é "on"

Este exemplo lista legacy-context para Claude apenas pelo nome e oculta deploy de Claude e do autocompletar /:

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

Overrides não se aplicam a skills de plugin, que você gerencia através de /plugin.

Em configurações gerenciadas e arquivos passados com --settings, uma chave em um alias de skill agrupado, como checkup para /doctor, também se aplica ao skill; consulte como chaves de alias se combinam com chaves no próprio nome do skill.

`syncClaudeAiSkills`

Desative o download dos skills habilitados para sua conta claude.ai. Claude Code os baixa em ~/.claude/skills/synced/ em sessões de terminal onde você entra com sua conta claude.ai, interativas ou não interativas, e em sessões Cowork e cloud. Defina false para parar esse download e parar de carregar os skills que já sincronizou. Claude Code honra apenas false: true é o mesmo que não definido e não ativa a sincronização onde está desativada.

  • Scope: User, local, or managed, e arquivos passados com --settings. Um repositório não pode desativá-lo para você.
  • Type: Boolean
    • false: Claude Code para de baixar skills sincronizados e para de carregar os já em ~/.claude/skills/synced/. Em configurações de usuário ou gerenciadas, também os move para ~/.claude/skills/.trash/
    • true: o mesmo que não definido
  • Default: não definido, portanto sessões conectadas com sua conta claude.ai sincronizam seus skills

Este exemplo impede uma máquina de baixar os skills da conta em qualquer sessão:

{
  "syncClaudeAiSkills": false
}

`syncClaudeAiPlugins`

Desative o download dos plugins habilitados para sua conta claude.ai. Claude Code os baixa em ~/.claude/plugins/synced/ no início de sessões de terminal onde você entra com sua conta claude.ai e em sessões Cowork, e carrega cada um como <name>@synced. Defina false para parar esse download e parar de carregar os plugins que já sincronizou. Claude Code honra apenas false: true é o mesmo que não definido e não ativa a sincronização onde está desativada. Requer Claude Code v2.1.273 ou posterior.

  • Scope: User, local, or managed, e arquivos passados com --settings. Um repositório não pode desativá-lo para você.
  • Type: Boolean
    • false: Claude Code para de baixar plugins sincronizados e para de carregar os já em ~/.claude/plugins/synced/. Em configurações de usuário ou gerenciadas, também os move para ~/.claude/plugins/.trash/
    • true: o mesmo que não definido
  • Default: não definido, portanto sessões conectadas com sua conta claude.ai sincronizam seus plugins

Para desativar um plugin sincronizado em vez de todos eles, defina "<name>@synced": false em enabledPlugins.

Este exemplo impede uma máquina de baixar os plugins da conta em qualquer sessão:

{
  "syncClaudeAiPlugins": false
}

`allowedChannelPlugins`

Escolha quais plugins de channel podem enviar mensagens para sessões em sua organização. Quando você o define, Claude Code usa sua lista no lugar da lista de permissões padrão da Anthropic; cada entrada nomeia um plugin e o marketplace de onde vem.

  • Scope: Managed
  • Type: array de objetos, cada um com strings marketplace e plugin. Uma entrada pode ser uma string "plugin@marketplace" como "telegram@claude-plugins-official", que Claude Code trata como o objeto equivalente. A forma de string requer Claude Code v2.1.267 ou posterior; versões anteriores rejeitam todo o valor allowedChannelPlugins quando contém uma
  • Default: não definido, portanto Claude Code usa a lista de permissões padrão da Anthropic

Este exemplo ativa channels e permite apenas o plugin Telegram do marketplace oficial da Anthropic:

{
  "channelsEnabled": true,
  "allowedChannelPlugins": [
    { "marketplace": "claude-plugins-official", "plugin": "telegram" }
  ]
}

Um array vazio bloqueia cada plugin de channel.

Esta chave entra em vigor uma vez que channels passam pela porta channelsEnabled para a conta: em planos Team e Enterprise, e em contas Console com configurações gerenciadas, isso significa channelsEnabled: true. Consulte Restringir quais plugins de channel podem ser executados.

`blockedMarketplaces`

Bloqueie fontes de marketplace de plugin para sua organização. Claude Code verifica a lista de bloqueio ao adicionar marketplace e ao instalar, atualizar, atualizar e auto-atualizar plugin, portanto um marketplace que alguém adicionou antes de você definir a política não pode ser usado para buscar plugins. Fontes bloqueadas são verificadas antes do download, portanto nunca tocam o sistema de arquivos.

Se você definir esta chave no console de administração claude.ai, claude.ai também a aplica quando qualquer pessoa em sua organização adiciona um marketplace de um repositório git no claude.ai, como Como restrições funcionam descreve.

  • Scope: Managed
  • Type: array de objetos de fonte de marketplace, nas mesmas formas que strictKnownMarketplaces
  • Default: não definido, portanto nenhum marketplace é bloqueado

Este exemplo bloqueia um repositório GitHub como fonte de marketplace:

{
  "blockedMarketplaces": [
    { "source": "github", "repo": "untrusted/plugins" }
  ]
}

Uma entrada github pode usar a forma owner-wildcard "owner/*" para bloquear cada repositório sob esse proprietário GitHub, que requer Claude Code v2.1.223 ou posterior. Adicione { "source": "skills-dir" } para parar Claude Code carregando plugins @skills-dir de ~/.claude/skills/ sem restringir nenhum marketplace. Consulte Restrições de marketplace gerenciadas.

`channelsEnabled`

Permita channels para sua organização. Em planos Team e Enterprise do claude.ai, Claude Code bloqueia channels até você definir isso como true. Para contas do Anthropic Console que autenticam com uma chave API, channels são permitidos por padrão. Se sua organização implanta configurações gerenciadas, Claude Code bloqueia channels nessas contas também até você definir esta chave como true.

  • Scope: Managed
  • Type: Boolean
    • true: Claude Code permite channels para sua organização
    • false: o mesmo que não definido; se channels são bloqueados depende de seu plano, como o Default diz
  • Default: não definido; channels são bloqueados em planos Team e Enterprise e em contas Console com configurações gerenciadas, e permitidos em planos Pro e Max e em contas Console sem configurações gerenciadas
{
  "channelsEnabled": true
}

Para restringir quais plugins podem se registrar como channels uma vez ativados, defina allowedChannelPlugins. Consulte Controles empresariais.

`disableCommandPluginSources`

Bloqueie a fonte de plugin command, que instala um plugin executando um comando declarado pelo marketplace na máquina do usuário. Quando você o define como true, Claude Code nunca executa o comando, não instala ou atualiza plugins originários de comando, e para de carregar os já instalados. Defina como false para permitir explicitamente. Sempre que bloqueia fontes de comando, seja você o definindo como true ou deixando não definido sob allowManagedHooksOnly, também bloqueia comandos headersHelper do marketplace, exceto para um marketplace que as próprias configurações gerenciadas declaram. Requer Claude Code v2.1.229 ou posterior, e o bloqueio headersHelper requer v2.1.238 ou posterior.

  • Scope: Managed
  • Type: Boolean
    • true: Claude Code nunca executa o comando declarado pelo marketplace, não instala ou atualiza plugins originários de comando, e para de carregar os já instalados
    • false: Claude Code permite plugins originários de comando explicitamente
  • Default: não definido, portanto Claude Code segue allowManagedHooksOnly: uma organização que restringe execução de hook a configurações gerenciadas também obtém fontes de comando desativadas
{
  "disableCommandPluginSources": true
}

Requer Claude Code v2.1.229 ou posterior.

`pluginSuggestionMarketplaces`

Nomeie os marketplaces cujos plugins podem aparecer como sugestões de instalação contextual, em dicas de spinner e fixadas no topo da aba Discover do /plugin. A dica integrada de design de frontend de primeira parte não é afetada. Sugestões vêm da declaração relevance de cada plugin em sua entrada de marketplace.

  • Scope: Managed
  • Type: array de nomes de marketplace
  • Default: não definido, portanto nenhuma sugestão declarada por marketplace aparece
{
  "pluginSuggestionMarketplaces": ["acme-corp-plugins"]
}

Um nome entra em vigor apenas quando o marketplace é registrado na máquina e sua fonte registrada também é declarada nas mesmas configurações gerenciadas, seja como a entrada extraKnownMarketplaces para esse nome ou como uma entrada de strictKnownMarketplaces. Claude Code ignora um marketplace registrado de uma fonte diferente sob um nome na lista de permissões. O marketplace oficial é isento do requisito de fonte: permitir apenas seu nome é suficiente, já que esse nome só pode se registrar da fonte Anthropic oficial. Consulte Sugerir plugins por contexto.

`pluginTrustMessage`

Adicione o próprio texto de sua organização ao aviso de confiança de plugin que Claude Code mostra antes da instalação, por exemplo para confirmar que plugins de seu marketplace interno são verificados.

  • Scope: Managed
  • Type: string
  • Default: não definido, portanto Claude Code mostra apenas o aviso padrão
{
  "pluginTrustMessage": "All plugins from our marketplace are approved by IT"
}

`strictKnownMarketplaces`

Restrinja quais fontes de marketplace de plugin as pessoas em sua organização podem adicionar e instalar plugins. Claude Code aplica a lista de permissões ao adicionar marketplace e ao instalar, atualizar, atualizar e auto-atualizar plugin, antes de qualquer operação de rede ou sistema de arquivos, portanto um marketplace que alguém adicionou antes de você definir a política não pode ser usado para buscar plugins uma vez que sua fonte não corresponda mais. Usuários bloqueados veem um erro nomeando a política gerenciada.

Se você definir esta chave no console de administração claude.ai, claude.ai também a aplica quando qualquer pessoa em sua organização adiciona um marketplace de um repositório git no claude.ai, como Como restrições funcionam descreve.

  • Scope: Managed
  • Type: array de objetos de fonte de marketplace; consulte Tipos de fonte permitidos
  • Default: não definido, portanto usuários podem adicionar qualquer marketplace. Um array vazio é um bloqueio completo que bloqueia cada fonte de marketplace, incluindo o marketplace oficial da Anthropic

Este exemplo permite dois repositórios GitHub, um fixado à ref v2.0, e uma URL marketplace.json hospedada:

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

Você também pode escrever esta chave como allowedMarketplaces; Aliases de chave de marketplace descreve como Claude Code trata o alias e qual versão o aceita. Esta chave é uma porta de política: controla o que usuários podem adicionar, mas não registra nada. Para restringir e pré-registrar em um arquivo, consulte Combinar com extraKnownMarketplaces. Para a visualização voltada ao usuário, consulte Restrições de marketplace gerenciadas.

Tipos de fonte permitidos

Cada entrada abaixo mostra uma entrada de lista de permissões por tipo de fonte e os campos que aceita. A maioria dos tipos corresponde exatamente; hostPattern e pathPattern correspondem por regex, e entradas github podem usar um owner wildcard.

Source Example entry Fields
github { "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" } repo obrigatório; ref é um branch ou tag; path é um subdiretório
git { "source": "git", "url": "https://gitlab.example.com/tools/plugins.git", "ref": "production" } url obrigatório; ref e path como para github
url { "source": "url", "url": "https://plugins.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } } url obrigatório; headers adiciona cabeçalhos HTTP para acesso autenticado
file { "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" } path obrigatório, o caminho absoluto para um arquivo marketplace.json
directory { "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" } path obrigatório, o caminho absoluto para um diretório contendo .claude-plugin/marketplace.json
hostPattern { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" } hostPattern obrigatório, um regex correspondido em qualquer lugar no host do marketplace; ancorá-lo com ^ e $ para corresponder o host inteiro
pathPattern { "source": "pathPattern", "pathPattern": "^/opt/approved/" } pathPattern obrigatório, um regex correspondido em qualquer lugar no path de fontes file e directory; comece com ^ para fixar um prefixo
skills-dir { "source": "skills-dir" } Sem campos. Opta a varredura de plugin ~/.claude/skills/ de volta

Três tipos de fonte carregam regras além da tabela:

  • url: um marketplace de URL baixa apenas o arquivo marketplace.json, e Claude Code não busca arquivos de plugin por caminho relativo desse servidor, portanto seus plugins devem usar uma plugin source diferente de um caminho relativo, como uma URL de arquivo, que pode estar no mesmo host. Para plugins com caminhos relativos, use um marketplace baseado em Git. Consulte Plugins com caminhos relativos falham em marketplaces baseados em URL.

  • hostPattern: use-o para permitir cada marketplace em um GitHub Enterprise interno ou servidor GitLab sem listar cada repositório. Claude Code corresponde fontes github contra github.com, pega o hostname de fontes url, e o pega de fontes git dependendo da forma da git URL:

    • Uma URL com um esquema, como https:// ou ssh://: o hostname na URL.
    • Um endereço SSH sem esquema, na forma user@host:path do git, como git@git.example.com:tools/plugins.git: o host entre @ e :, que é o host ao qual git se conecta.
    • Qualquer outra forma sem esquema: sem host, portanto nenhuma entrada strictKnownMarketplaces hostPattern corresponde. Para uma hostPattern blockedMarketplaces, Claude Code pega um host de um conjunto mais amplo de formas, portanto uma entrada de lista de bloqueio ainda pode corresponder tal forma. Antes de v2.1.234, uma hostPattern strictKnownMarketplaces também correspondia algumas formas que git não trata como endereços SSH.

    Fontes file e directory não têm host e nunca correspondem a uma entrada hostPattern.

  • pathPattern: use-o para permitir marketplaces do sistema de arquivos ao lado de entradas hostPattern para fontes de rede. ".*" permite cada caminho local; um padrão mais estreito como "^/opt/approved/" restringe a um diretório.

Qualquer lista de permissões, mesmo uma vazia, também para Claude Code carregando plugins @skills-dir de ~/.claude/skills/. Adicione a entrada { "source": "skills-dir" } para continuar carregando-os; a entrada não tem significado fora desta chave e blockedMarketplaces.

Owner wildcards

Uma entrada github cujo valor repo é "<owner>/*" corresponde cada repositório sob esse proprietário GitHub. Owner wildcards requerem Claude Code v2.1.223 ou posterior e funcionam apenas em strictKnownMarketplaces e blockedMarketplaces. Em qualquer outro lugar uma fonte github aparece, como extraKnownMarketplaces ou /plugin marketplace add, o valor repo deve nomear um único repositório. Antes de v2.1.223, Claude Code comparava a entrada literalmente, portanto uma entrada de lista de permissões não correspondia a nenhum repositório e uma entrada de lista de bloqueio não bloqueava nada; entradas de repositório único são aplicadas em cada versão.

Esta entrada permite qualquer repositório de marketplace na organização acme-corp:

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

Apenas a posição de nome de repositório inteiro pode ser um wildcard. Claude Code ignora entradas como *, */plugins, ou acme-corp/tools-* como inválidas, portanto não correspondem a nenhum repositório.

As regras de correspondência diferem entre as duas configurações:

Rule strictKnownMarketplaces blockedMarketplaces
Matching source spellings Apenas forma owner/repo. Uma git URL que clona o mesmo repositório não corresponde Qualquer grafia, incluindo git URLs que resolvem para o mesmo repositório github.com
Owner case Sensível a maiúsculas/minúsculas, como correspondência de entrada exata Insensível a maiúsculas/minúsculas
ref Segue as regras de entrada exata: uma entrada com um ref corresponde apenas fontes com esse ref exato, e uma entrada sem um corresponde apenas fontes que não especificam um ref Uma entrada sem um ref bloqueia todos os refs dos repositórios que corresponde
path Mais flexível que as regras de entrada exata: uma entrada com um path requer esse valor exato, enquanto uma entrada sem um corresponde qualquer caminho dentro do repositório Uma entrada sem um path bloqueia todos os caminhos dos repositórios que corresponde

Correspondência exata

Para cada tipo de fonte exceto entradas github de owner-wildcard e as entradas hostPattern e pathPattern correspondidas por regex, Claude Code permite uma adição de usuário apenas quando a fonte de marketplace corresponde a uma entrada exatamente. Para as fontes baseadas em git github e git, correspondência exata inclui os campos opcionais:

  • O repo ou url deve corresponder exatamente
  • O campo ref deve corresponder exatamente, ou ambos devem ser indefinidos
  • O campo path deve corresponder exatamente, ou ambos devem ser indefinidos

Por exemplo, Claude Code trata cada par abaixo como duas fontes diferentes:

  • { "source": "github", "repo": "acme-corp/plugins" } e { "source": "github", "repo": "acme-corp/plugins", "ref": "main" }
  • { "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" } e { "source": "github", "repo": "acme-corp/plugins" }

Permitir apenas o marketplace oficial

Para permitir apenas o marketplace oficial da Anthropic e nada mais, liste seu repositório:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" }
  ]
}

Com esta entrada, Claude Code mantém um marketplace oficial já registrado disponível e, em uma máquina nova, registra o marketplace automaticamente na primeira vez que você inicia uma sessão de terminal interativa. O registro automático mais comumente perde:

  • Ambientes não interativos que executam antes da primeira sessão de terminal interativa da máquina.
  • Máquinas onde Claude Code já executou uma sessão de terminal interativa sob uma política que bloqueou o marketplace, como o bloqueio de array vazio. Claude Code registra a tentativa bloqueada e não tenta novamente após a política mudar.

Nessas máquinas, adicione o marketplace a extraKnownMarketplaces no mesmo managed-settings.json para que Claude Code o registre automaticamente, ou execute claude plugin marketplace add anthropics/claude-plugins-official.

Combinar com `extraKnownMarketplaces`

As duas chaves fazem trabalhos diferentes. Esta tabela as compara:

Aspect strictKnownMarketplaces extraKnownMarketplaces
Purpose Aplicação de política organizacional Conveniência de equipe
Settings file Apenas configurações gerenciadas Qualquer arquivo de configurações
Behavior Bloqueia adições não permitidas Registra marketplaces ausentes
When enforced Antes de operações de rede e sistema de arquivos Imediatamente de configurações de usuário ou gerenciadas; após o diálogo de confiança de workspace para arquivos de um repositório
Can be overridden Não, precedência mais alta Sim, por configurações de precedência mais alta
Source format Objeto de fonte direto Marketplace nomeado com um objeto source aninhado

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 um marketplace permitido eles mesmos com /plugin marketplace add. O marketplace oficial da Anthropic é o único que Claude Code registra automaticamente, e apenas quando a lista de permissões o permite. Permitir apenas o marketplace oficial lista as máquinas que perde.

`strictPluginOnlyCustomization`

Bloqueie skills, agents, hooks e servidores MCP de fontes de usuário e projeto, portanto podem vir apenas de plugins ou configurações gerenciadas. Combine com strictKnownMarketplaces para controlar a cadeia de suprimento de customização completa: a lista de permissões de marketplace controla quais plugins usuários podem instalar.

  • Scope: Managed
  • Type: true para bloquear todos os quatro tipos de customização, ou um array nomeando os tipos a bloquear, de "skills", "agents", "hooks" e "mcp"
  • Default: não definido, portanto nada é bloqueado

Este exemplo bloqueia skills e hooks e deixa agents e servidores MCP desbloqueados:

{
  "strictPluginOnlyCustomization": ["skills", "hooks"]
}

As quatro entradas de sub-chave abaixo listam o que cada superfície bloqueia e o que ainda carrega. Claude Code ignora nomes de superfície que não reconhece em vez de falhar no arquivo de configurações, portanto você pode adicionar novos nomes de superfície antes de cada cliente ter atualizado.

`strictPluginOnlyCustomization.skills`

Bloqueie a superfície skills. Claude Code para de carregar skills de ~/.claude/skills/ e .claude/skills/, comandos personalizados de ~/.claude/commands/ e .claude/commands/, skills sob diretórios --add-dir, e skills sincronizados de sua conta claude.ai, e continua carregando skills de plugin, skills agrupados e skills no diretório de política gerenciada.

{
  "strictPluginOnlyCustomization": ["skills"]
}

`strictPluginOnlyCustomization.agents`

Bloqueie a superfície agents. Claude Code para de carregar agents de ~/.claude/agents/ e .claude/agents/, e continua carregando agents de plugin, agents integrados e agents no diretório de política gerenciada.

{
  "strictPluginOnlyCustomization": ["agents"]
}

`strictPluginOnlyCustomization.hooks`

Bloqueie a superfície hooks. Claude Code para de executar hooks de configurações de usuário, projeto e local settings.json, e continua executando hooks de plugin e hooks em configurações gerenciadas.

{
  "strictPluginOnlyCustomization": ["hooks"]
}

`strictPluginOnlyCustomization.mcp`

Bloqueie a superfície mcp. Claude Code para de carregar servidores MCP de ~/.claude.json e .mcp.json, e continua carregando servidores MCP de plugin, servidores managed-mcp.json e servidores de managedMcpServers.

{
  "strictPluginOnlyCustomization": ["mcp"]
}

`enabledPlugins`

Ative ou desative plugins individuais, codificados por plugin-name@marketplace-name. Um plugin sem entrada em nenhum escopo volta para seu valor defaultEnabled. Quando você ativa ou desativa um plugin com /plugin ou claude plugin enable, Claude Code escreve esta chave para você.

  • Scope: Any file
  • Type: objeto mapeando plugin-name@marketplace-name para um Boolean
  • Default: não definido, portanto cada plugin segue seu valor defaultEnabled

Este exemplo ativa dois plugins do marketplace team-tools e desativa um de personal:

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

Cada escopo serve um propósito diferente:

  • User settings: suas preferências pessoais de plugin
  • Project settings: plugins compartilhados com todos no repositório
  • Local settings: overrides por máquina, gitignored quando Claude Code salva uma configuração lá
  • Managed settings: política em toda a organização. Um plugin definido como false aqui é bloqueado da instalação em cada escopo e oculto do marketplace

Configurações de projeto têm precedência sobre configurações de usuário, portanto definir um plugin como false em ~/.claude/settings.json não desativa um plugin que o .claude/settings.json do projeto ativa. Para optar por não participar de um plugin ativado pelo projeto em sua máquina, defina-o como false em .claude/settings.local.json. Plugins forçadamente ativados por configurações gerenciadas não podem ser desativados desta forma, já que configurações gerenciadas substituem configurações locais.

Ativar um plugin de uma fonte externa como um repositório GitHub ou pacote npm no .claude/settings.json de um projeto não o instala para outras pessoas. Em cada caminho que carrega plugins, Claude Code relata o plugin como não instalado até que cada usuário o instale eles mesmos.

`extraKnownMarketplaces`

Registre marketplaces de plugin adicionais por nome, para que pessoas que abram o repositório, ou todos que suas configurações gerenciadas alcançam, obtenham o marketplace sem adicioná-lo eles mesmos. Claude Code registra cada marketplace que ainda não conhece. Se um plugin que enabledPlugins nomeia dele instala depende da fonte do plugin e qual arquivo o ativa; essa entrada tem as regras.

  • Scope: Any file. Claude Code honra entradas no .claude/settings.json ou .claude/settings.local.json de um repositório apenas após você aceitar o diálogo de confiança de workspace para essa pasta; em uma pasta que você não confiou, incluindo uma execução -p lá, ignora-as sem mensagem.
  • Type: objeto mapeando um nome de marketplace para um objeto com um objeto source e um Boolean autoUpdate opcional
  • Default: não definido

Este exemplo registra um marketplace GitHub e um marketplace de uma URL git auto-hospedada:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/security/plugins.git"
      }
    }
  }
}

O que é executado antes de você confiar em uma pasta compara a porta de confiança com o outro conteúdo que um repositório pode fornecer. Você também pode escrever esta chave como additionalMarketplaces; consulte Aliases de chave de marketplace.

Defina "autoUpdate": true ao lado de source para fazer Claude Code atualizar esse marketplace e atualizar seus plugins instalados em segundo plano após a inicialização. Quando omitido, claude-plugins-official e a maioria dos outros marketplaces oficiais da Anthropic padrão para true, e marketplaces de terceiros padrão para false. Consulte Configurar auto-atualizações.

Quando mais de um arquivo de configurações define uma entrada de marketplace sob o mesmo nome, Claude Code usa a entrada do arquivo de precedência mais alta inteiro. Essa entrada substitui a entrada de precedência mais baixa e não herda nenhum de seus campos, portanto uma redefinição não pode combinar source.headers de credencial de um arquivo com uma URL que outro arquivo controla. Antes de v2.1.228, Claude Code mesclava entradas de mesmo nome campo por campo, portanto uma entrada em um arquivo de precedência mais alta poderia herdar campos que não definiu, incluindo headers de outro arquivo.

Tipos de fonte de marketplace

O objeto source toma uma destas formas:

  • github: um repositório GitHub, com repo
  • git: qualquer URL git, com url
  • url: uma URL direta para um arquivo marketplace.json, com url e headers opcional e headersHelper para acesso autenticado. headersHelper nomeia um comando que imprime cabeçalhos cujos valores são muito efêmeros para listar em headers, e requer Claude Code v2.1.238 ou posterior
  • file: um caminho local para um arquivo marketplace.json, com path
  • directory: um caminho do sistema de arquivos local, com path, apenas para desenvolvimento
  • settings: um marketplace inline declarado diretamente no arquivo de configurações sem um repositório hospedado, com name e plugins

O tipo de fonte git funciona com qualquer serviço de hospedagem git, incluindo GitLab auto-hospedado e Bitbucket. Claude Code clona o repositório com a mesma autenticação que git clone usaria nessa máquina: helpers de credencial configurados ou chaves SSH. Um token de provedor como GITHUB_TOKEN entra em vigor através de um helper de credencial que o lê. Consulte Repositórios privados para detalhes de configuração.

Para fontes github e git, Claude Code nunca baixa conteúdo de Git LFS quando clona o repositório de marketplace para adicioná-lo ou atualizá-lo. Arquivos rastreados por LFS são verificados como arquivos de ponteiro, e a saída de adição ou atualização relata quantos.

O campo skipLfs dentro do objeto source é aceito e não tem efeito. Antes de v2.1.274, Claude Code baixava conteúdo de LFS a menos que você definisse "skipLfs": true.

Para uma fonte url, defina headersHelper dentro do objeto source quando a credencial em headers expira e um comando tem que produzir uma nova. Requer Claude Code v2.1.238 ou posterior. Para o que o comando deve imprimir e onde Claude Code o executa, consulte Escrever o comando headersHelper, e para os casos onde Claude Code não o executa, consulte Quando Claude Code pula um comando headersHelper. Uma vez que você defina headersHelper em uma URL de marketplace https://, Claude Code executa o comando em dois pontos, reutilizando a saída de uma execução por até 60 segundos:

  • Antes de cada busca desse marketplace.json do marketplace, incluindo uma atualização posterior. Claude Code envia os cabeçalhos impressos com essa busca.
  • Antes de cada download de arquivo de plugin na origem da URL do marketplace, significando o mesmo esquema, host e porta. Claude Code envia a saída com esse download, e nenhum outro download obtém os cabeçalhos.

Claude Code ignora qualquer headersHelper definido no .claude/settings.json ou .claude/settings.local.json de um diretório que você adiciona com --add-dir, em uma fonte url e em uma entrada de plugin inline, e envia apenas os headers fixos definidos naquele arquivo. Como usuários aceitam um comando headersHelper cobre os outros arquivos de configurações.

Plugins listados em uma fonte settings devem referenciar fontes externas como GitHub ou npm, e o name deve corresponder à chave de marketplace. Você ainda ativa cada plugin separadamente em enabledPlugins. Este exemplo declara um plugin inline:

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "settings",
        "name": "team-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": {
              "source": "github",
              "repo": "acme-corp/code-formatter"
            }
          }
        ]
      }
    }
  }
}

Uma entrada de plugin sob source: 'settings' cuja própria source é um archive pode definir headers para o download de arquivo. Se o valor que você colocaria em headers é efêmero, como um token que seu registro cria sob demanda, defina um comando headersHelper em vez disso. Uma entrada pode definir ambos. Ambos os campos requerem Claude Code v2.1.238 ou posterior.

Claude Code envia os headers da entrada, e o que o comando imprime, com o download de arquivo daquele plugin e com nenhum outro download. Claude Code executa o comando apenas quando um usuário instala ou atualiza apenas aquele plugin. Três regras adicionais dependem de qual arquivo contém a entrada:

  • strict: diferentemente de uma entrada no marketplace.json de um marketplace, uma entrada em configurações não precisa de "strict": false, porque um arquivo de configurações não carrega campos de manifesto para inline. Consulte Modo strict.
  • Folder trust: para uma entrada no .claude/settings.json ou .claude/settings.local.json de um projeto, Claude Code executa o comando apenas após o usuário também ter confiado naquela pasta.
  • Header filter: Claude Code descarta nomes de cabeçalho de roteamento de solicitação e identidade de cliente de uma entrada no .claude/settings.json ou .claude/settings.local.json de um projeto, porque um repositório pode fornecer esses arquivos. Claude Code aplica o mesmo filtro a uma entrada de catálogo e a uma entrada no diretório de configurações --add-dir, e nenhum filtro a uma entrada em suas configurações de usuário, um arquivo --settings ou configurações gerenciadas.

Aliases de chave de marketplace

No Claude Code v2.1.232 ou posterior, você pode escrever extraKnownMarketplaces como additionalMarketplaces e strictKnownMarketplaces como allowedMarketplaces. Claude Code trata cada alias como segue:

  • Versões anteriores ignoram o alias, portanto mantenha a grafia canônica em um arquivo que versões mais antigas também leem, como um arquivo de configurações gerenciadas para uma frota com versões mistas de Claude Code.
  • Em qualquer arquivo de configurações que aceita a chave canônica, Claude Code lê o alias exatamente como lê a chave canônica.
  • Claude Code pode reescrever additionalMarketplaces para extraKnownMarketplaces quando atualiza o arquivo.
  • Se você definir ambas as grafias em um arquivo, Claude Code usa o valor canônico e ignora o alias.

`pluginConfigs`

Armazene as respostas não sensíveis que você dá ao diálogo de configuração userConfig de um plugin, codificadas por ID de plugin. Claude Code escreve esta chave para suas configurações de usuário quando você preenche o diálogo, portanto você não precisa editá-la manualmente. Claude Code armazena opções sensíveis no Keychain do macOS em vez disso, voltando para ~/.claude/.credentials.json quando o Keychain rejeita a escrita; em plataformas sem um keychain suportado, armazena em ~/.claude/.credentials.json.

  • Scope: User or managed
  • Type: objeto mapeando um ID de plugin para um objeto com um campo options, mapeando cada nome de opção para uma string, número, Boolean ou array de strings, e um campo mcpServers opcional mantendo valores de configuração de usuário por servidor na mesma forma
  • Default: não definido

Este exemplo armazena a opção api_endpoint para o plugin deployer de acme-tools:

{
  "pluginConfigs": {
    "deployer@acme-tools": {
      "options": {
        "api_endpoint": "https://api.example.com"
      }
    }
  }
}

Plugins integrados armazenam suas opções sob a mesma chave com um sufixo @builtin. Por exemplo, a configuração Project instructions que controla se Claude Code lê arquivos AGENTS.md é pluginConfigs["agents-md@builtin"].options.instructionFiles.

Claude Code ignora entradas de projeto e local porque substitui esses valores em configurações de hook de plugin, MCP e LSP, e um repositório clonado não deve ser capaz de fornecê-los. Antes de v2.1.207, configurações de projeto e local também eram lidas.

MCP

Controle quais servidores MCP o Claude Code se conecta e quais uma organização permite. Veja Conectar a ferramentas externas com MCP e Configuração MCP gerenciada.

`allowAllClaudeAiMcps`

Carregue os conectores claude.ai que o Claude Code busca por si mesmo junto com um managed-mcp.json implantado. Sem essa chave, managed-mcp.json assume controle exclusivo dos servidores MCP e suprime esses conectores.

  • Escopo: Managed. Os usuários não podem reativar conectores que o controle exclusivo suprimiu.
  • Tipo: Booleano
    • true: Claude Code carrega os conectores claude.ai junto com um managed-mcp.json implantado
    • false: um managed-mcp.json implantado assume controle exclusivo dos servidores MCP e suprime os conectores claude.ai que o Claude Code busca por si mesmo
  • Padrão: false, portanto um managed-mcp.json implantado suprime os conectores claude.ai que o Claude Code busca por si mesmo
{
  "allowAllClaudeAiMcps": true
}

allowedMcpServers e deniedMcpServers ainda se aplicam aos conectores que essa chave carrega. Os conectores entregues a uma sessão na nuvem cujo host carrega um managed-mcp.json, como um executor auto-hospedado, permanecem suprimidos. Veja Permitir conectores claude.ai junto com o conjunto gerenciado.

`allowedMcpServers`

Crie uma lista de permissões dos servidores MCP que as pessoas podem adicionar. O Claude Code bloqueia qualquer servidor que não corresponda a uma entrada onde quer que seja definido, incluindo servidores de plugins, servidores passados com --mcp-config e servidores do claude.ai.

Servidores integrados como Claude no Chrome, o servidor ide ao qual o Claude Code se conecta em um VS Code ou JetBrains IDE em execução, e servidores que a própria CLI configura estão isentos da lista de permissões, e a lista de negação ainda se aplica a eles. Servidores type: "sdk" em processo estão isentos de ambas as listas; o aplicativo que iniciou a sessão os registra.

Os servidores que sua organização entrega também estão isentos da lista de permissões, e a lista de negação ainda se aplica a eles. A isenção cobre cada entrada managedMcpServers e qualquer entrada managed-mcp.json cujos valores não usam expansão ${VAR}. Veja Como um servidor é avaliado para a ordem de verificação completa. Antes da v2.1.259, servidores do managed-mcp.json também tinham que corresponder.

  • Escopo: Any file. As entradas de cada arquivo se mesclam em uma lista de permissões, a menos que allowManagedMcpServersOnly esteja definido. Implante-o em configurações gerenciadas para aplicá-lo.
  • Tipo: matriz de objetos, cada um com exatamente uma chave: serverName, uma string limitada a letras, números, hífens e sublinhados; serverCommand, uma matriz do comando e seus argumentos correspondidos exatamente; ou serverUrl, um padrão de URL com curingas *
  • Padrão: não definido, portanto cada servidor é permitido; uma matriz vazia bloqueia cada servidor que os usuários adicionam

Este exemplo permite apenas o servidor stdio que o comando npx listado inicia:

{
  "allowedMcpServers": [
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] }
  ]
}

Uma entrada deniedMcpServers tem precedência, portanto um servidor em ambas as listas é bloqueado. Uma vez que a lista contém qualquer entrada serverCommand, um servidor stdio deve corresponder a uma entrada serverCommand, e uma vez que contém qualquer entrada serverUrl, um servidor remoto deve corresponder a uma entrada serverUrl: uma correspondência serverName não admite mais esse tipo de servidor. Veja Controle baseado em política com listas de permissões e negação.

`allowManagedMcpServersOnly`

Faça da lista de permissões gerenciada a única que se aplica. O Claude Code então lê allowedMcpServers apenas das configurações gerenciadas e ignora listas de permissões nas configurações de usuário, projeto e local; deniedMcpServers ainda se mescla de cada escopo de configurações, portanto os usuários ainda podem bloquear servidores para si mesmos. Os administradores o definem para que as próprias configurações de um usuário não possam ampliar o que a lista de permissões gerenciada permite.

  • Escopo: Managed
  • Tipo: Booleano
    • true: Claude Code lê allowedMcpServers apenas das configurações gerenciadas e ignora listas de permissões nas configurações de usuário, projeto e local
    • false: listas de permissões de cada escopo de configurações se mesclam
  • Padrão: false, portanto listas de permissões de cada escopo de configurações se mesclam

Este exemplo bloqueia a lista de permissões para configurações gerenciadas e permite apenas o servidor nomeado github:

{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverName": "github" }
  ]
}

Os usuários ainda podem adicionar servidores MCP por conta própria; apenas servidores que correspondem à lista de permissões gerenciada são carregados. Veja Restringir a lista de permissões apenas às configurações gerenciadas.

`deniedMcpServers`

Bloqueie servidores MCP específicos. O Claude Code recusa carregar um servidor correspondente onde quer que seja definido, incluindo servidores de plugins, servidores passados com --mcp-config, servidores do managed-mcp.json, servidores do managedMcpServers e os conectores claude.ai que ele busca por si mesmo. Servidores type: "sdk" em processo estão isentos; o aplicativo que iniciou a sessão os registra.

  • Escopo: Any file. As entradas de cada arquivo se mesclam em uma lista de negação, e allowManagedMcpServersOnly não muda isso. Implante-o em configurações gerenciadas para aplicá-lo.
  • Tipo: matriz de objetos, cada um com exatamente uma chave: serverName, uma string, portanto o nome de exibição de um conector claude.ai como "claude.ai Slack" funciona; serverCommand, uma matriz do comando e seus argumentos correspondidos exatamente; ou serverUrl, um padrão de URL com curingas *
  • Padrão: não definido, portanto nenhum servidor é bloqueado; uma matriz vazia também não bloqueia nada
{
  "deniedMcpServers": [
    { "serverName": "filesystem" }
  ]
}

A lista de negação tem precedência sobre allowedMcpServers, portanto um servidor em ambas as listas é bloqueado. Veja Controle baseado em política com listas de permissões e negação.

`disableClaudeAiConnectors`

Desative os conectores MCP claude.ai que o Claude Code busca por si mesmo, para que ele não os busque nem se conecte a eles. Um true em qualquer arquivo de configurações se aplica: um .claude/settings.json de projeto verificado pode optar por desativar esses conectores para um repositório, mas um false no nível do projeto não pode substituir um true no nível do usuário ou gerenciado.

  • Escopo: Any file
  • Tipo: Booleano
    • true: Claude Code não busca nem se conecta a esses conectores
    • false: o mesmo que não definido; Claude Code busca seus conectores a menos que outro arquivo de configurações ou ENABLE_CLAUDEAI_MCP_SERVERS os desative
  • Padrão: false, portanto Claude Code busca seus conectores
  • Substituições por sessão: ENABLE_CLAUDEAI_MCP_SERVERS definido como false desativa conectores para uma sessão; qualquer um dos dois que os desativa, o outro não pode ligá-los novamente
{
  "disableClaudeAiConnectors": true
}

Os servidores que você passa explicitamente com --mcp-config não são afetados. Para bloquear conectores individuais em vez de todos eles, use deniedMcpServers. Veja Desativar conectores claude.ai.

`disabledMcpjsonServers`

Rejeite servidores específicos definidos no arquivo .mcp.json de um projeto para que o Claude Code nunca se conecte a eles ou peça sua aprovação. Uma rejeição em qualquer arquivo de configurações se aplica, incluindo um .claude/settings.json de projeto verificado no repositório.

  • Escopo: Any file
  • Tipo: matriz de strings, os nomes dos servidores conforme aparecem em .mcp.json
  • Padrão: não definido
{
  "disabledMcpjsonServers": ["filesystem"]
}

O Claude Code escreve essa chave em .claude/settings.local.json quando você rejeita um servidor na caixa de diálogo de aprovação. claude mcp get <name> mostra um servidor rejeitado como ✘ Rejected (see disabledMcpjsonServers in settings). A rejeição tem precedência sobre enabledMcpjsonServers e enableAllProjectMcpServers.

`enableAllProjectMcpServers`

Aprove cada servidor MCP definido em arquivos .mcp.json de projeto sem um prompt. O Claude Code escreve essa chave em .claude/settings.local.json quando você escolhe aprovar todos os servidores na caixa de diálogo de aprovação.

  • Escopo: Any file. Em uma pasta cuja caixa de diálogo de confiança você não aceitou, o Claude Code a honra das configurações de usuário, configurações gerenciadas e --settings e a ignora no arquivo de projeto compartilhado, tanto na sessão quanto para claude mcp list e claude mcp get; Aprovações de servidor de projeto e confiança de espaço de trabalho diz quando um .claude/settings.local.json não rastreado conta também.
  • Tipo: Booleano
    • true: Claude Code aprova cada servidor MCP definido em arquivos .mcp.json de projeto sem um prompt
    • false: Claude Code pede que você aprove cada servidor. Em uma pasta confiável, um false em um arquivo de precedência mais alta substitui um true em um de precedência mais baixa; em uma pasta que você não confiou, um true em qualquer arquivo honrado é suficiente
  • Padrão: não definido, portanto Claude Code pede que você aprove cada servidor
{
  "enableAllProjectMcpServers": true
}

Uma entrada disabledMcpjsonServers ainda rejeita um servidor.

`enabledMcpjsonServers`

Aprove servidores específicos definidos em arquivos .mcp.json de projeto para que o Claude Code se conecte a eles sem perguntar. O Claude Code escreve essa chave em .claude/settings.local.json quando você aprova um servidor na caixa de diálogo de aprovação.

  • Escopo: Any file. Em uma pasta cuja caixa de diálogo de confiança você não aceitou, o Claude Code a honra das configurações de usuário, configurações gerenciadas e --settings e a ignora no arquivo de projeto compartilhado, tanto na sessão quanto para claude mcp list e claude mcp get; Aprovações de servidor de projeto e confiança de espaço de trabalho diz quando um .claude/settings.local.json não rastreado conta também.
  • Tipo: matriz de strings, os nomes dos servidores conforme aparecem em .mcp.json
  • Padrão: não definido

Este exemplo aprova os servidores memory e github do .mcp.json do projeto:

{
  "enabledMcpjsonServers": ["memory", "github"]
}

Uma entrada disabledMcpjsonServers ainda rejeita um servidor.

`managedMcpServers`

Forneça servidores MCP remotos para cada usuário a partir de configurações gerenciadas. Os usuários mantêm os servidores que adicionam por conta própria e não podem editar ou remover os que você fornece. Requer Claude Code v2.1.259 ou posterior.

  • Escopo: Managed. O Claude Code descarta a chave com um aviso nas configurações de usuário, projeto e local, e não a lê na guia Code do aplicativo Claude Desktop em uma implantação de terceiros ou nas sessões Cowork do aplicativo, onde o Claude Desktop fornece e bloqueia os servidores MCP dessas sessões.
  • Tipo: objeto com chave de nome do servidor. Cada entrada tem a forma .mcp.json para um servidor http ou sse: uma url https:// obrigatória e opcionalmente headers, oauth e as outras opções HTTP e SSE. O Claude Code descarta entradas que falham na validação, e O que uma entrada pode conter lista as condições
  • Padrão: não definido, portanto as configurações gerenciadas não fornecem servidores

Este exemplo fornece um servidor HTTP nomeado search:

{
  "managedMcpServers": {
    "search": {
      "type": "http",
      "url": "https://search.example.com/mcp"
    }
  }
}

Para precedência, como servidores fornecidos se combinam com managed-mcp.json e as listas de permissões e negação, e o que os usuários veem, veja Fornecer servidores através de configurações gerenciadas.

Agentes, sessões e worktrees

Defina o agente padrão, controle colegas de equipe e mensagens entre sessões, e configure worktrees. Veja Subagentes e Worktrees.

`agent`

Execute a thread principal como um subagente nomeado, para que Claude Code aplique o prompt do sistema, restrições de ferramentas e modelo desse subagente à sua sessão. A mesma chave define o agente padrão para sessões que você despacha de claude agents.

  • Escopo: Qualquer arquivo
  • Tipo: string, o nome de um agente integrado ou personalizado
  • Padrão: não definido, portanto a thread principal é executada como o agente padrão do Claude Code
  • Substituições por sessão: --agent tem precedência sobre esta chave para uma sessão
{
  "agent": "code-reviewer"
}

O próprio settings.json de um plugin também pode fornecer esta chave; veja Envie configurações padrão com seu plugin.

`crossSessionInbound`

Escolha o que esta sessão faz com mensagens chegando de suas outras sessões do Claude Code. Quando nenhum valor se aplica, Claude Code decide por mensagem das classes de modo de permissão das duas sessões. Requer Claude Code v2.1.224 ou posterior.

  • Escopo: Qualquer arquivo. Um valor de projeto ou local se aplica apenas quando é mais restritivo do que o valor de configurações gerenciadas, a flag --settings ou configurações de usuário fornecem.
  • Tipo: string, um de:
    • "accept": Claude Code entrega a mensagem ao Claude
    • "hold": Claude Code mostra um aviso para a mensagem sem entregá-la
    • "refuse": Claude Code descarta a mensagem
  • Padrão: não definido, portanto Claude Code decide por mensagem
{
  "crossSessionInbound": "hold"
}

Claude Code lê as configurações gerenciadas primeiro, depois a flag --settings, depois as configurações de usuário, e aplica o primeiro valor encontrado. refuse é mais restritivo do que hold, e hold é mais restritivo do que accept. Quando nenhuma das fontes confiáveis define um valor, um hold ou refuse de projeto ou local ainda se aplica, substituindo o padrão por mensagem. Em sessões com mensagens entre sessões, esta chave aparece em /config como Mensagens de suas outras sessões, que a escreve nas configurações de usuário; a linha requer Claude Code v2.1.232 ou posterior, e Claude Code a oculta enquanto a flag --settings ou as configurações gerenciadas definem a chave.

Claude Code avisa quando você define um valor que não reconhece. Enquanto esse valor estiver presente em um arquivo de usuário, projeto, local ou --settings, Claude Code retém mensagens de entrada, mesmo quando uma fonte que tem precedência define accept. Um refuse que outra fonte define ainda se aplica. Corrija ou remova o valor para limpar a retenção.

Quando o valor não reconhecido está em configurações gerenciadas, Claude Code o trata como refuse até que um administrador o corrija. Antes da v2.1.248, Claude Code ignorava um valor não reconhecido sem aviso.

`disableAgentView`

Desative agentes de fundo e visualização de agente: claude agents, --bg, /background e o supervisor sob demanda. Defina-o em configurações gerenciadas para aplicá-lo a uma organização.

  • Escopo: Qualquer arquivo
  • Tipo: Boolean
    • true: Claude Code desativa claude agents, --bg, /background e o supervisor sob demanda
    • false: a visualização de agente está disponível
  • Padrão: não definido, portanto a visualização de agente está disponível
  • Substituições por sessão: CLAUDE_CODE_DISABLE_AGENT_VIEW desativa a visualização de agente para uma sessão; qualquer um dos dois que a desativar, o outro não pode reativá-la
{
  "disableAgentView": true
}

`isolatePeerMachines`

Exija sua aprovação explícita antes que SendMessage do Claude alcance uma de suas sessões além desta máquina; veja Exigir aprovação para mensagens entre máquinas. O prompt de aprovação aparece mesmo no modo bypassPermissions.

  • Escopo: Qualquer arquivo. Um true de qualquer escopo se aplica, portanto um arquivo de projeto verificado pode ativar o requisito, mas não desativá-lo.
  • Tipo: Boolean
    • true: Claude Code pede sua aprovação antes que SendMessage do Claude alcance uma de suas sessões além desta máquina
    • false: mensagens entre máquinas não solicitam
  • Padrão: não definido, portanto mensagens entre máquinas não solicitam
{
  "isolatePeerMachines": true
}

A aprovação de SendMessage entre máquinas requer Claude Code v2.1.224 ou posterior.

`processWrapper`

No macOS e Linux, coloque um comando de inicializador corporativo na frente dos processos de fundo que Claude Code inicia. Claude Code executa o inicializador com sua própria linha de comando anexada, portanto o inicializador deve executar no Claude Code; veja Execute Claude Code atrás de um inicializador corporativo para o contrato do inicializador. Requer Claude Code v2.1.210 ou posterior.

  • Escopo: Usuário ou gerenciado
  • Tipo: string, o comando do inicializador como um prefixo argv, como um caminho absoluto com argumentos opcionais
  • Padrão: não definido, portanto os processos de fundo iniciam sem encapsulamento
  • Substituições por sessão: CLAUDE_CODE_PROCESS_WRAPPER tem precedência sobre esta chave para uma sessão
{
  "processWrapper": "/opt/corp/launcher --profile claude"
}

Claude Code ignora o inicializador no Windows e inicia cada processo sem encapsulamento. Requer Claude Code v2.1.210 ou posterior.

`teammateMode`

Escolha onde Claude Code mostra colegas de equipe da equipe de agentes: dentro do seu painel de terminal principal, ou em painéis divididos quando seu terminal os suporta. Veja Escolha um modo de exibição.

  • Escopo: Qualquer arquivo. Claude Code também lê um valor deixado em ~/.claude.json por versões antigas.
  • Tipo: string, um de:
    • "in-process": colegas de equipe são executados dentro do seu painel de terminal principal
    • "auto": painéis divididos quando você está executando dentro do tmux, ou dentro do iTerm2 com it2 no seu PATH ou tmux instalado; em processo caso contrário
    • "tmux": painéis divididos usando tmux ou iTerm2, detectados do seu terminal
    • "iterm2": painéis divididos nativos do iTerm2 através do CLI it2
  • Padrão: "in-process"
  • Substituições por sessão: --teammate-mode tem precedência sobre esta chave para uma sessão
{
  "teammateMode": "auto"
}

`worktree`

Configure como Claude Code cria e gerencia git worktrees para --worktree, a ferramenta EnterWorktree e subagentes isolados e sessões de fundo.

  • Escopo: Qualquer arquivo
  • Tipo: objeto com baseRef, symlinkDirectories, sparsePaths e bgIsolation
  • Padrão: não definido

Este exemplo ramifica novas worktrees do seu HEAD atual e cria links simbólicos de node_modules em cada uma:

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules"]
  }
}

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

`worktree.baseRef`

Escolha de qual ref novas worktrees se ramificam. "fresh" se ramifica de origin/<default-branch> para uma árvore limpa correspondente ao remoto; "head" se ramifica do seu HEAD local atual, portanto commits não enviados e estado de branch de recurso estão presentes na worktree.

  • Escopo: Qualquer arquivo
  • Tipo: string, um de:
    • "fresh": novas worktrees se ramificam de origin/<default-branch>
    • "head": novas worktrees se ramificam do seu HEAD local atual, incluindo commits não enviados
  • Padrão: "fresh"
{
  "worktree": {
    "baseRef": "head"
  }
}

Dentro de uma worktree vinculada, "head" resolve para o HEAD dessa worktree, não para o checkout principal.

`worktree.symlinkDirectories`

Crie links simbólicos de diretórios do repositório principal em cada worktree para que você não duplique diretórios grandes no disco.

  • Escopo: Qualquer arquivo
  • Tipo: array de strings, caminhos de diretório relativos à raiz do repositório
  • Padrão: não definido, portanto Claude Code não cria links simbólicos de nenhum diretório

Este exemplo cria links simbólicos de node_modules e .cache do repositório principal em cada nova worktree:

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"]
  }
}

`worktree.sparsePaths`

Faça checkout apenas dos diretórios listados em cada worktree através do git sparse-checkout. Claude Code escreve apenas esses diretórios mais arquivos no nível raiz no disco, o que é mais rápido em monorepos grandes; veja Faça checkout apenas dos diretórios que você precisa.

  • Escopo: Qualquer arquivo
  • Tipo: array de strings, caminhos de diretório relativos à raiz do repositório
  • Padrão: não definido, portanto cada worktree faz checkout de toda a árvore

Este exemplo faz checkout apenas de packages/my-app e shared/utils, mais arquivos no nível raiz, em cada worktree:

{
  "worktree": {
    "sparsePaths": ["packages/my-app", "shared/utils"]
  }
}

Enquanto uma worktree esparsa existe, git ativa extensions.worktreeConfig no .git/config compartilhado do repositório.

`worktree.bgIsolation`

Escolha como sessões de fundo isolam suas edições de arquivo. Com "worktree", Claude Code bloqueia Edit e Write no checkout principal até que a sessão chame EnterWorktree; com "none", trabalhos de fundo editam a cópia de trabalho diretamente. Defina "none" para um repositório onde git worktrees são impraticáveis.

  • Escopo: Qualquer arquivo
  • Tipo: string, um de:
    • "worktree": Claude Code bloqueia Edit e Write no checkout principal até que a sessão chame EnterWorktree
    • "none": trabalhos de fundo editam a cópia de trabalho diretamente
  • Padrão: "worktree"
{
  "worktree": {
    "bgIsolation": "none"
  }
}

Fora de um repositório git, um hook WorktreeCreate que falha libera o bloqueio para que a sessão possa editar o diretório de trabalho no local; essa liberação requer Claude Code v2.1.203 ou posterior.

Remoto, desktop e notificações

Configure o Controle Remoto, ambientes em nuvem, o aplicativo desktop e as notificações que o Claude Code envia quando precisa de você. Veja Controle Remoto.

`agentPushNotifEnabled`

Permita que o Claude envie uma notificação por push para seu telefone quando decidir que vale a pena enviar uma, por exemplo, quando uma tarefa longa termina. O Claude Code sincroniza essa escolha com sua conta, e as notificações chegam enquanto o Controle Remoto está conectado. Aparece em /config como Push quando Claude decidir.

  • Escopo: Qualquer arquivo. O Claude Code também lê um valor deixado em ~/.claude.json por versões antigas.
  • Tipo: Boolean
    • true: Claude pode enviar uma notificação por push para seu telefone quando decidir que vale a pena enviar uma
    • false: Claude não envia essas notificações
  • Padrão: false
{
  "agentPushNotifEnabled": true
}

Veja Notificações por push móvel.

`awaySummaryEnabled`

Mostre um resumo de sessão de uma linha quando você retorna ao terminal após alguns minutos ausente. Defina como false, ou desative Resumo da sessão em /config, para parar o resumo.

  • Escopo: Qualquer arquivo
  • Tipo: Boolean
    • true: você vê um resumo de sessão de uma linha quando retorna após alguns minutos ausente
    • false: Claude Code não mostra nenhum resumo
  • Padrão: não definido, então o resumo está ativado
  • Substituições por sessão: CLAUDE_CODE_ENABLE_AWAY_SUMMARY tem precedência sobre essa chave para uma sessão, em qualquer direção
{
  "awaySummaryEnabled": false
}

O Claude Code nunca mostra o resumo em modo não interativo.

`disableArtifact`

Use enableArtifact em vez disso para desativar a ferramenta Artifact, que publica a saída da sessão como uma página da web privada em claude.ai. Quando você desativa a linha Artifacts em /config, o Claude Code escreve enableArtifact em suas configurações de usuário e limpa essa chave.

  • Escopo: Qualquer arquivo
  • Tipo: Boolean
    • true: Claude Code desativa a ferramenta Artifact para cada sessão à qual o arquivo se aplica, e nenhum outro arquivo a ativa novamente. Antes da v2.1.242, um arquivo com precedência mais alta poderia substituir um true de um arquivo com precedência mais baixa em vez da chave agir como um bloqueio
    • false: ignorado; para deixar a ferramenta ativada, remova a chave
  • Padrão: não definido, então a ferramenta segue a disponibilidade de sua conta
  • Substituições por sessão: CLAUDE_CODE_DISABLE_ARTIFACT definido como 1 desativa a ferramenta para uma sessão
{
  "disableArtifact": true
}

Desativar artifacts lista todas as maneiras de desativar a ferramenta.

`disableDeepLinkRegistration`

Impeça que o Claude Code registre o manipulador de protocolo claude-cli:// com o sistema operacional, o que ele faz após você enviar o primeiro prompt de uma sessão interativa. Deep links permitem que ferramentas externas abram uma sessão do Claude Code com um prompt pré-preenchido. Defina isso em ambientes onde o registro do manipulador de protocolo é restrito ou gerenciado separadamente.

  • Escopo: Qualquer arquivo
  • Tipo: a string "disable"
  • Padrão: não definido, então Claude Code registra o manipulador
{
  "disableDeepLinkRegistration": "disable"
}

`disableDesktopLocalSessions`

Desative sessões de Code que executam no dispositivo no aplicativo desktop, para implantações onde os desenvolvedores devem trabalhar em máquinas remotas via SSH. Na aba Code, o ambiente Local permanece no menu suspenso de ambiente, mas fica acinzentado e não pode ser selecionado, com uma dica de ferramenta dizendo que sua organização o desativou; no Windows, a entrada WSL fica acinzentada da mesma forma, embora se as sessões WSL executam em um dispositivo gerenciado seja governado separadamente. Novas sessões usam como padrão a primeira conexão SSH se uma estiver configurada, e o aplicativo se recusa a iniciar ou retomar uma sessão no dispositivo, incluindo uma conexão SSH de volta para a mesma máquina. Sessões SSH para outros hosts e sessões em nuvem não são afetadas. O aplicativo desktop lê essa chave; o CLI do terminal a ignora. Requer Claude Desktop v1.37937.0 ou posterior.

  • Escopo: Gerenciado
  • Tipo: Boolean; apenas o Boolean JSON true tem efeito
    • true: o aplicativo desktop não oferece sessões de Code no dispositivo; sessões locais existentes permanecem listadas, mas não podem continuar
    • false: sessões locais permanecem disponíveis
  • Padrão: não definido, então sessões locais estão disponíveis
{
  "disableDesktopLocalSessions": true
}

O aplicativo desktop ignora qualquer outro valor, e um valor que não seja um Boolean, como a string "true" ou 1, também registra um aviso. Combine com sshConfigs para que os usuários cheguem a uma conexão funcionando, e com sshHostAllowlist para limitar quais hosts eles podem alcançar. Veja Sessões locais em dispositivos gerenciados.

O Claude Desktop fornece sessões de Code com política derivada de sua configuração de desktop, por exemplo, a lista de permissões de saída, sandbox do sistema de arquivos e restrições de MCP em implantações de terceiros. O Claude Code ignora essas configurações pai sempre que uma fonte de administrador está presente: configurações gerenciadas pelo servidor, uma política de MDM ou nível do SO, ou um arquivo de configurações gerenciadas. Implantar essa chave através de uma delas em um dispositivo que não tinha nenhuma antes, como em implantações de terceiros, portanto, impede que as políticas derivadas do desktop se apliquem. Deixe um host de incorporação adicionar política cobre quando as configurações pai ainda podem se mesclar; isso vale para qualquer chave que você implante dessa forma, não apenas essa.

`disableRemoteControl`

Desative o Controle Remoto: Claude Code então recusa claude remote-control, a flag --remote-control, auto-inicialização e o alternador em sessão, e relata que a política de sua organização o desativou. Coloque em configurações gerenciadas para aplicação de MDM por dispositivo.

  • Escopo: Qualquer arquivo
  • Tipo: Boolean
    • true: Claude Code recusa claude remote-control, a flag --remote-control, auto-inicialização e o alternador em sessão
    • false: Controle Remoto permanece disponível
  • Padrão: false
{
  "disableRemoteControl": true
}

`enableArtifact`

Desative a ferramenta Artifact, que publica a saída da sessão como uma página da web privada em claude.ai. Quando você desativa a linha Artifacts em /config, o Claude Code escreve essa chave em suas configurações de usuário, então você geralmente não a edita manualmente. Requer Claude Code v2.1.196 ou posterior.

  • Escopo: Qualquer arquivo. Cada arquivo pode desativar a ferramenta, e nenhum pode ativá-la novamente.
  • Tipo: Boolean
  • Padrão: não definido, então a ferramenta segue a disponibilidade de sua conta
{
  "enableArtifact": false
}

Enquanto uma fonte diferente de suas próprias configurações de usuário mantém a ferramenta desativada, o Claude Code oculta a linha Artifacts em /config, porque ativá-la lá não mudaria nada. Desativar artifacts lista todas as maneiras de desativar a ferramenta. Antes da v2.1.242, o Claude Code ignorava essa chave em configurações de projeto e locais, e um arquivo mais alto na pilha de precedência poderia ativar a ferramenta novamente sobre um false de um arquivo mais baixo.

`inputNeededNotifEnabled`

Receba uma notificação por push em seu telefone quando um prompt de permissão ou pergunta estiver aguardando sua entrada. O Claude Code envia essas apenas enquanto o Controle Remoto está conectado. Aparece em /config como Push quando ações forem necessárias.

  • Escopo: Qualquer arquivo. O Claude Code também lê um valor deixado em ~/.claude.json por versões antigas.
  • Tipo: Boolean
    • true: você recebe uma notificação por push em seu telefone quando um prompt de permissão ou pergunta está aguardando, enquanto o Controle Remoto está conectado
    • false: Claude Code não envia essas notificações
  • Padrão: false
{
  "inputNeededNotifEnabled": true
}

Veja Notificações por push móvel.

`preferredNotifChannel`

Escolha como o Claude Code o notifica quando uma tarefa é concluída ou um prompt de permissão está aguardando. Aparece em /config como Notificações locais.

  • Escopo: Qualquer arquivo. O Claude Code também lê um valor deixado em ~/.claude.json por versões antigas.
  • Tipo: string, uma de:
    • "auto": Claude Code envia uma notificação de desktop no iTerm2, Ghostty e Kitty, toca a campainha no Terminal.app apenas quando sua campainha audível está desativada, e não faz nada em outro lugar
    • "terminal_bell": Claude Code toca o caractere de campainha em qualquer terminal
    • "iterm2": Claude Code envia uma notificação de desktop do iTerm2
    • "iterm2_with_bell": Claude Code envia uma notificação de desktop do iTerm2 e toca a campainha
    • "kitty": Claude Code envia uma notificação de desktop do Kitty
    • "ghostty": Claude Code envia uma notificação de desktop do Ghostty
    • "notifications_disabled": Claude Code não envia notificação
  • Padrão: "auto"
{
  "preferredNotifChannel": "terminal_bell"
}

Com "auto", o Claude Code envia uma notificação de desktop no iTerm2, Ghostty e Kitty. No Terminal.app, ele toca o caractere de campainha apenas quando você desativou a campainha audível do Terminal, e em outros terminais não faz nada. Defina "terminal_bell" para tocar o caractere de campainha em qualquer terminal. Veja Obter uma campainha de terminal ou notificação.

`remote.defaultEnvironmentId`

Escolha o ambiente em nuvem padrão para sessões em nuvem que você cria a partir da CLI, como com claude --cloud. O Claude Code escreve essa chave em suas configurações de usuário quando você escolhe um ambiente com /remote-env.

  • Escopo: Qualquer arquivo. Para um ID de ambiente auto-hospedado, configurações de usuário ou gerenciadas, ou a flag --settings apenas.
  • Tipo: string, um ID de ambiente como env_... ou ccpool_...
  • Padrão: não definido, então Claude Code usa o ambiente hospedado pela Anthropic quando sua lista tem um, e caso contrário, o primeiro ambiente em sua lista que não é um ambiente de ponte de Controle Remoto, ou o primeiro ambiente quando todos são ambientes de ponte
  • Substituições por sessão: --environment tem precedência sobre essa chave para a sessão em nuvem que cria
{
  "remote": {
    "defaultEnvironmentId": "env_0123abcd"
  }
}

Um ID de ambiente hospedado pela Anthropic, que começa com env_, segue a precedência de configurações padrão, então um valor nas configurações de projeto de um repositório substitui sua escolha no nível de usuário. Um ID de ambiente auto-hospedado, que começa com ccpool_, é honrado apenas de configurações de usuário, configurações gerenciadas e a flag --settings; Claude Code ignora um nas configurações de projeto ou locais de um repositório, e /remote-env mostra qual valor foi ignorado, então um arquivo verificado não pode direcionar sessões para um ambiente auto-hospedado que você não escolheu.

`remoteControlAtStartup`

Conecte o Controle Remoto automaticamente quando cada sessão interativa inicia, em vez de esperar por /remote-control. Defina como true para ativar a conexão automática, false para desativá-la. Aparece em /config como Ativar Controle Remoto para todas as sessões.

  • Escopo: Qualquer arquivo. O Claude Code também lê um valor deixado em ~/.claude.json por versões antigas.
  • Tipo: Boolean
    • true: Claude Code conecta o Controle Remoto automaticamente quando cada sessão interativa inicia
    • false: Claude Code espera por /remote-control
  • Padrão: não definido, então a conexão automática segue o padrão de administrador de sua organização quando um está definido, e caso contrário, o padrão atual do Claude Code
  • Substituições por sessão: --remote-control ativa o Controle Remoto para uma sessão mesmo quando essa chave é false, e nenhuma flag o desativa para uma sessão
{
  "remoteControlAtStartup": true
}

Claude Code ignora um true de configurações de projeto ou locais, então um repositório pode desativar a conexão automática para seu checkout, mas não pode ativá-la. Para o comportamento completo por escopo, veja Ativar Controle Remoto para todas as sessões e as chaves de segurança onde o valor mais restritivo se aplica.

`sshConfigs`

Adicione conexões SSH ao menu suspenso do ambiente Desktop. Administradores a usam para distribuir conexões compartilhadas para uma equipe. Conexões que você define em configurações gerenciadas aparecem como gerenciadas, então os usuários podem selecioná-las, mas não podem editá-las ou deletá-las no aplicativo.

  • Escopo: Usuário ou gerenciado. O aplicativo desktop lê essa chave.
  • Tipo: array de objetos, cada um com id, name e sshHost obrigatórios e sshPort e sshIdentityFile opcionais
  • Padrão: não definido

Este exemplo adiciona uma conexão chamada Dev VM que se conecta a user@dev.example.com:

{
  "sshConfigs": [
    {
      "id": "dev-vm",
      "name": "Dev VM",
      "sshHost": "user@dev.example.com"
    }
  ]
}

`sshHostAllowlist`

Limite os hosts aos quais uma sessão SSH do Desktop pode se conectar. Apenas o aplicativo Desktop lê essa chave; a CLI não. Padrões são insensíveis a maiúsculas: * corresponde a qualquer host, *.example.com corresponde a example.com e cada subdomínio, e qualquer outra coisa é uma correspondência exata contra o nome do host após a resolução de ~/.ssh/config. Um array vazio desativa sessões SSH.

  • Escopo: Gerenciado
  • Tipo: array de padrões de nome de host
  • Padrão: não definido, então qualquer host é permitido

Este exemplo permite devboxes.example.com e seus subdomínios, mais o host exato bastion.example.com:

{
  "sshHostAllowlist": ["*.devboxes.example.com", "bastion.example.com"]
}

Autenticação e provedores

Forneça credenciais através de scripts auxiliares e, para organizações, force um método de login ou organização. Veja Autenticação.

`apiKeyHelper`

Execute seu próprio comando para produzir a credencial que Claude Code envia com solicitações de modelo. Claude Code executa o comando através do shell do sistema, /bin/sh no macOS e Linux e cmd no Windows, e envia sua saída como ambos os cabeçalhos X-Api-Key e Authorization: Bearer. Use-o para credenciais dinâmicas ou rotativas, como tokens de curta duração obtidos de um cofre.

  • Escopo: Qualquer arquivo
  • Tipo: string, uma linha de comando do shell
  • Padrão: não definido, portanto Claude Code não executa um auxiliar
{
  "apiKeyHelper": "/bin/generate_temp_api_key.sh"
}

Claude Code armazena em cache o valor e executa novamente o comando nestes casos:

  • Após o tempo de vida do cache, cinco minutos por padrão ou o intervalo que você define com CLAUDE_CODE_API_KEY_HELPER_TTL_MS.
  • Quando uma solicitação para a API Anthropic, diretamente ou através de um gateway LLM, falha com 401 ou 403.
  • Antes de enviar uma solicitação para a API Anthropic, diretamente ou através de um gateway LLM, quando a saída em cache é um JWT que expirou após o auxiliar produzi-lo. Requer Claude Code v2.1.246 ou posterior.

Os dois últimos casos se aplicam apenas quando a saída do auxiliar é a credencial que Claude Code envia e ANTHROPIC_AUTH_TOKEN não está definido.

Em sessões interativas, quando o comando vem das configurações do projeto ou local, Claude Code não o executa até que você aceite o prompt de confiança do workspace. Veja Gerenciamento de credenciais.

`awsAuthRefresh`

Execute seu próprio comando, como aws sso login, para atualizar as credenciais em seu diretório .aws quando as que Claude Code tem para Amazon Bedrock deixarem de funcionar. Claude Code verifica as credenciais atuais em relação ao STS primeiro e executa o comando apenas quando essa verificação falha, depois lê o diretório .aws atualizado.

  • Escopo: Qualquer arquivo
  • Tipo: string, uma linha de comando do shell
  • Padrão: não definido, portanto Claude Code não atualiza credenciais AWS para você
{
  "awsAuthRefresh": "aws sso login --profile myprofile"
}

Use esta chave quando seu fluxo de atualização escreve em .aws; use awsCredentialExport quando ele imprime credenciais. Veja configuração avançada de credenciais.

`awsCredentialExport`

Execute seu próprio comando que imprime credenciais AWS como JSON, para que Claude Code possa chamar Amazon Bedrock com credenciais que não residem em seu diretório .aws. Claude Code aceita a forma de saída aws sts e a forma plana aws configure export-credentials, e limita as credenciais ao seu próprio cliente Bedrock, portanto os comandos do shell que Claude Code executa ainda veem suas credenciais ambientes.

  • Escopo: Qualquer arquivo
  • Tipo: string, uma linha de comando do shell
  • Padrão: não definido, portanto Claude Code usa a cadeia de credenciais AWS ambiente
{
  "awsCredentialExport": "/bin/generate_aws_grant.sh"
}

Diferentemente de awsAuthRefresh, Claude Code sempre executa este comando quando está definido, sem verificar as credenciais ambiente primeiro. Veja configuração avançada de credenciais.

`forceLoginMethod`

Restrinja qual tipo de conta as pessoas podem usar para fazer login. Defina "claudeai" para permitir apenas contas claude.ai, "console" para permitir apenas contas Claude Console, ou "gateway" para enviar as pessoas para um gateway na nuvem em vez de um login de primeira parte. Os administradores o definem em configurações gerenciadas e o emparelham com forceLoginOrgUUID para manter os logins claude.ai dos desenvolvedores dentro de uma organização. Se você o definir como "claudeai" ou "console" em qualquer arquivo de configurações, Claude Code também para de oferecer o login Console sem chave nas sessões às quais esse arquivo se aplica.

  • Escopo: Qualquer arquivo. Claude Code honra "gateway" apenas de uma fonte gerenciada na máquina: managed-settings.json, a plist do macOS ou registro HKLM do Windows, ou um auxiliar de política. Ele trata "gateway" como não definido em configurações de usuário, projeto, local, HKCU e gerenciadas por servidor, a mesma regra que forceLoginGatewayUrl.
  • Tipo: string, um de:
    • "claudeai": apenas contas claude.ai podem fazer login
    • "console": apenas contas Claude Console podem fazer login
    • "gateway": Claude Code envia as pessoas para um gateway na nuvem em vez de um login de primeira parte
  • Padrão: não definido, portanto as pessoas escolhem um método de login
{
  "forceLoginMethod": "claudeai"
}

Cada caminho de login de primeira parte aplica a restrição, incluindo a extensão VS Code, o Agent SDK, claude setup-token e /install-github-app, exceto a tela de login interativa do terminal, acessada por /login ou onboarding de primeira execução, que pré-seleciona o método sem aplicá-lo. Antes da v2.1.212, apenas logins de terminal o aplicavam. Veja Restringir login à sua organização para como cada caminho de login, credenciais de ambiente e provedores de terceiros são tratados.

Quando uma fonte gerenciada na máquina define "gateway", Claude Code não usa um login restante, chave API ou credencial apiKeyHelper. Veja A política do administrador requer um login de gateway na nuvem para a mensagem que cada um produz. Se você selecionar um provedor de nuvem através de CLAUDE_CODE_USE_BEDROCK ou uma variável de ambiente similar, a sessão não precisa do login do gateway. Antes da v2.1.261, Claude Code usava um login restante nessas máquinas.

`forceLoginGatewayUrl`

Defina a URL do gateway à qual a tela /login Cloud gateway se conecta, para que as pessoas alcancem seu gateway na nuvem sem digitar seu endereço. A tela não tem campo de URL: com esta chave definida, ela mostra a URL do seu gateway e se conecta quando a pessoa pressiona Enter; sem ela, diz a elas para entrar em contato com seu administrador de TI.

Ou esta chave ou forceLoginMethod: "gateway" torna a máquina apenas gateway, portanto /login abre na tela Cloud gateway sem seletor de método de login. Veja A política do administrador requer um login de gateway na nuvem para o que acontece com um login de primeira parte restante ou chave API. Defina ambas as chaves para que a tela se conecte em vez de mostrar um erro.

  • Escopo: Gerenciado. Leia apenas de uma fonte na máquina: managed-settings.json, a plist do macOS ou registro HKLM do Windows, ou um auxiliar de política. Claude Code a ignora em configurações HKCU e gerenciadas por servidor.
  • Tipo: string, uma URL completa incluindo o esquema
  • Padrão: não definido, portanto a tela Cloud gateway mostra um erro dizendo às pessoas para entrar em contato com seu administrador de TI
{
  "forceLoginGatewayUrl": "https://claude-gateway.example.com"
}

Se o valor não for uma URL válida, a tela de login a relata, e o resto do arquivo de configurações gerenciadas ainda se aplica. Veja Defina a URL do gateway.

`forceLoginOrgUUID`

De uma fonte gerenciada, exija que logins de contas claude.ai pertençam a uma organização Anthropic, fornecida como um único UUID, ou a qualquer uma de várias organizações, fornecidas como um array. De qualquer arquivo de configurações, Claude Code também usa um único UUID para pré-selecionar essa organização durante um login claude.ai ou Claude Console, e não pré-seleciona nada para um array. Se você definir a chave em qualquer arquivo de configurações, Claude Code também para de oferecer o login Console sem chave nas sessões às quais esse arquivo se aplica e cria uma chave API.

  • Escopo: Qualquer arquivo. Apenas uma fonte gerenciada aplica a restrição; um único UUID em qualquer outro arquivo de configurações pré-seleciona a organização durante o login sem restringi-la.
  • Tipo: string, um UUID, ou array de strings, vários UUIDs
  • Padrão: não definido, portanto qualquer organização pode fazer login

Este exemplo aceita logins de qualquer uma de duas organizações sem pré-selecionar uma:

{
  "forceLoginOrgUUID": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]
}

Se uma fonte gerenciada define um array vazio, ou um valor que Claude Code não consegue analisar, Claude Code bloqueia cada login com uma mensagem de configuração incorreta.

Veja Restringir login à sua organização para como Claude Code trata logins Claude Console, os outros caminhos de login e credenciais de ambiente.

`gatewayInternalNetworks`

Declare os blocos IPv4 públicos dos quais sua organização numera sua rede interna, para que /login aceite um gateway na nuvem lá. Requer Claude Code v2.1.268 ou posterior.

Sem esta chave, /login se conecta a qualquer gateway em um endereço privado e nada mais. Com ela, /login também aceita um gateway dentro de um bloco listado, apenas sobre uma conexão direta. O endereço próprio da máquina nessa conexão também deve estar dentro do mesmo bloco.

  • Escopo: Gerenciado. Leia apenas de uma fonte na máquina: managed-settings.json, a plist do macOS ou registro HKLM do Windows, ou um auxiliar de política. Claude Code a ignora em configurações HKCU e gerenciadas por servidor.
  • Tipo: array de strings, no máximo quatro blocos IPv4 CIDR, cada um /8 a /32, não se sobrepondo um ao outro, e nenhum se sobrepondo ao espaço privado.
  • Padrão: não definido, portanto /login aceita apenas gateways em endereços privados
{
  "gatewayInternalNetworks": ["203.0.113.0/24"]
}

Substitua o intervalo de documentação no exemplo pelo seu próprio bloco. Claude Code recusa os intervalos de documentação, os intervalos que clientes VPN e NAT64 usam localmente, e espaço reservado que nenhuma rede é numerada, como multicast.

Se uma entrada for inválida, ou o valor não for uma lista de strings, /login nomeia o problema e recusa cada novo login de gateway na nuvem na máquina até que você corrija o valor. Os logins existentes continuam funcionando. Veja Permitir um gateway no espaço de endereço público que você possui para as regras completas e o que os desenvolvedores veem.

`gcpAuthRefresh`

Execute seu próprio comando para atualizar as Credenciais Padrão de Aplicativo do Google Cloud quando Claude Code descobrir que expiraram ou não podem ser carregadas, para que as solicitações da Plataforma de Agente do Google Cloud continuem funcionando sem você se autenticar novamente manualmente.

  • Escopo: Qualquer arquivo
  • Tipo: string, uma linha de comando do shell
  • Padrão: não definido, portanto o erro de credencial de Claude Code diz a você para executar gcloud auth application-default login você mesmo
{
  "gcpAuthRefresh": "gcloud auth application-default login"
}

Veja configuração avançada de credenciais.

`otelHeadersHelper`

Execute seu próprio comando para gerar os cabeçalhos que Claude Code envia com exportações OpenTelemetry, para backends cujos tokens giram. Claude Code o executa na inicialização e periodicamente depois disso, e espera um objeto JSON de valores de cabeçalho de string em stdout.

  • Escopo: Qualquer arquivo
  • Tipo: string, um caminho executável ou uma linha de comando do shell
  • Padrão: não definido, portanto Claude Code não adiciona cabeçalhos gerados por auxiliar
{
  "otelHeadersHelper": "/bin/generate_otel_headers.sh"
}

Defina o intervalo de atualização com CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS. Veja Cabeçalhos dinâmicos para os requisitos do script e o que acontece quando o auxiliar falha.

Atualizações e versionamento

Escolha um canal de atualização e, para organizações, fixe as versões que as pessoas podem executar. Consulte Atualizar Claude Code.

`autoUpdatesChannel`

Escolha qual canal de lançamento as atualizações automáticas em segundo plano e claude update seguem. Defina "stable" para uma versão que é tipicamente cerca de uma semana antiga e pula lançamentos com regressões maiores, ou "latest" para o lançamento mais recente.

  • Escopo: Any file. Defina-o em configurações gerenciadas para impor um canal em toda a sua organização.
  • Tipo: string, um de:
    • "latest": as atualizações seguem o lançamento mais recente
    • "stable": as atualizações seguem uma versão que é tipicamente cerca de uma semana antiga e pula lançamentos com regressões maiores
  • Padrão: não definido, então Claude Code segue "latest"
{
  "autoUpdatesChannel": "stable"
}

Claude Code escreve "stable" em suas configurações de usuário quando você o escolhe em Auto-update channel em /config, e remove a chave quando você volta para latest lá. claude install stable e claude install latest também salvam o canal que você nomeia. Mudar de "latest" para "stable" em /config pergunta se você deseja permitir um downgrade ou permanecer em sua versão atual; permanecer define minimumVersion. Instalações do Homebrew ignoram esta chave: o cask claude-code rastreia stable e claude-code@latest rastreia latest, e claude update defere para brew upgrade. Para desativar atualizações automáticas completamente, defina DISABLE_AUTOUPDATER em env.

`minimumVersion`

Impeça que atualizações automáticas em segundo plano e claude update instalem qualquer versão abaixo desta, para que mudar para o canal "stable" não o faça fazer downgrade de um build "latest" mais recente. Claude Code escreve esta chave para você quando você escolhe permanecer em sua versão atual ao mudar de canais em /config, e a limpa quando você volta para "latest".

  • Escopo: Any file. Defina-o em configurações gerenciadas para fixar um mínimo em toda a organização que as configurações de usuário e projeto não possam reduzir.
  • Tipo: string, um número de versão como "2.1.100"; um valor que não é uma versão válida é ignorado
  • Padrão: não definido, então as atualizações podem instalar qualquer versão que o canal oferece

Este exemplo segue o canal stable e recusa instalar qualquer versão abaixo de 2.1.100:

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.100"
}

Esta chave apenas restringe atualizações. Para fazer Claude Code recusar iniciar abaixo de uma versão, use requiredMinimumVersion em vez disso. Consulte Fixar uma versão mínima.

`requiredMaximumVersion`

Defina a versão mais recente do Claude Code que sua organização permite iniciar. Quando a versão em execução é mais recente, Claude Code sai na inicialização e diz ao usuário para instalar uma versão aprovada através do método aprovado de sua organização; claude install <version> também pode funcionar. Requer Claude Code v2.1.163 ou posterior.

  • Escopo: Managed. Claude Code não dá aviso quando ignora a chave em outro lugar.
  • Tipo: string, um número de versão como "2.1.150"; um valor que não é uma versão válida é ignorado
  • Padrão: não definido, então nenhum limite superior se aplica
{
  "requiredMaximumVersion": "2.1.150"
}

Atualizações automáticas em segundo plano e claude update pulam versões acima do limite, então uma instalação dentro do intervalo permanece dentro dele. claude update, claude install e claude doctor continuam funcionando acima do limite para que os usuários possam se recuperar. Emparelhe-o com requiredMinimumVersion para impor um intervalo.

`requiredMinimumVersion`

Defina a versão mais antiga do Claude Code que sua organização permite iniciar. Quando a versão em execução é mais antiga, Claude Code sai na inicialização e diz ao usuário para atualizar através do método aprovado de sua organização. A verificação é executada apenas na inicialização, então uma sessão que já está em execução continua. Requer Claude Code v2.1.163 ou posterior.

  • Escopo: Managed. Claude Code não dá aviso quando ignora a chave em outro lugar.
  • Tipo: string, um número de versão como "2.1.150"; um valor que não é uma versão válida é ignorado
  • Padrão: não definido, então nenhum piso se aplica
{
  "requiredMinimumVersion": "2.1.150"
}

claude update, claude install e claude doctor continuam funcionando abaixo do piso para que os usuários possam se recuperar. Diferentemente de minimumVersion, que apenas previne downgrades, esta chave bloqueia a inicialização. Emparelhe-o com requiredMaximumVersion para impor um intervalo.

Ferramentas

Desative ferramentas específicas no aplicativo de desktop Claude Code. A CLI do terminal ignora essas chaves. Para as próprias ferramentas, consulte Ferramentas disponíveis para Claude.

`browserExternalPageTools`

Impeça que Claude use suas ferramentas para ler ou agir em páginas externas no painel Navegador do aplicativo de desktop. As pessoas em sua organização ainda podem abrir sites externos por conta própria, e as visualizações de servidor de desenvolvimento local continuam funcionando com as ferramentas de Claude. O aplicativo de desktop lê essa chave; a CLI do terminal a ignora.

  • Escopo: Managed
  • Tipo: string, "disabled"; o aplicativo de desktop também aceita "disable", em ambos os casos
  • Padrão: não definido, portanto as ferramentas de Claude funcionam em páginas externas
{
  "browserExternalPageTools": "disabled"
}

Qualquer outro valor deixa as ferramentas de Claude ativadas, e uma string não vazia que não seja um dos dois valores aceitos registra um aviso. Para bloquear sites externos para pessoas e Claude igualmente, defina disableBrowserExternalNavigation em vez disso. Consulte Restringir navegação externa para sua organização.

`disableBrowserExternalNavigation`

Desative a navegação externa no painel Navegador do aplicativo de desktop para pessoas e Claude igualmente. As visualizações de servidor de desenvolvimento localhost continuam funcionando. O aplicativo de desktop lê essa chave; a CLI do terminal a ignora.

  • Escopo: Managed
  • Tipo: Booleano; apenas o Booleano JSON true tem efeito
    • true: o aplicativo de desktop desativa a navegação externa no painel Navegador para pessoas e Claude igualmente; as visualizações de localhost continuam funcionando
    • false: a navegação externa permanece ativada
  • Padrão: não definido, portanto a navegação externa está ativada
{
  "disableBrowserExternalNavigation": true
}

O aplicativo de desktop ignora qualquer outro valor, e um valor que não seja um Booleano, como a string "true" ou 1, também registra um aviso. Para deixar a navegação externa ativada mas manter as ferramentas de Claude desativadas em páginas externas, defina browserExternalPageTools em vez disso. Consulte Restringir navegação externa para sua organização.

`disableMobileSimulatorTools`

Bloqueie as ferramentas de Claude para o painel iOS Simulator do aplicativo de desktop. As pessoas mantêm o uso manual do painel; apenas o acesso de Claude é removido, e ninguém pode ativá-lo novamente de dentro do aplicativo. O aplicativo de desktop lê essa chave; a CLI do terminal a ignora.

  • Escopo: Managed
  • Tipo: Booleano; apenas o Booleano JSON true tem efeito
    • true: o aplicativo de desktop bloqueia as ferramentas de Claude para o painel iOS Simulator
    • false: as ferramentas de simulador de Claude seguem a alternância de configurações de cada pessoa no aplicativo de desktop
  • Padrão: não definido, portanto as ferramentas de simulador de Claude seguem a alternância de configurações de cada pessoa no aplicativo de desktop
{
  "disableMobileSimulatorTools": true
}

O aplicativo de desktop ignora qualquer outro valor, e um valor que não seja um Booleano, como a string "true" ou 1, também registra um aviso.

Privacidade e telemetria

Controle por quanto tempo o Claude Code mantém dados de sessão e o que envia. Os switches que desativam métricas de uso e relatórios de erro são variáveis de ambiente, não chaves de configuração: defina DISABLE_TELEMETRY, DISABLE_ERROR_REPORTING ou CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC na chave env ou no shell. Serviços de telemetria diz o que cada um para. Duas exceções desativam de um arquivo de configurações: feedbackDrafts abaixo para feedback redigido por Claude, e feedbackSurveyRate abaixo para a pesquisa de sessão.

`cleanupPeriodDays`

Defina quantos dias o Claude Code mantém transcrições de sessão e outros dados de aplicação antes de deletá-los. O Claude Code executa a exclusão como uma varredura em segundo plano após uma sessão iniciar, desde que possa determinar com segurança o período de retenção.

  • Escopo: Any file
  • Tipo: número de dias, um número inteiro, mínimo 1
  • Padrão: 30
{
  "cleanupPeriodDays": 20
}

Definir 0 falha na validação, então escolha um valor grande como 3650 para retenção prolongada. Para impedir que o Claude Code escreva transcrições, consulte Armazenamento em texto simples.

`desktopSessionCleanupPeriodDays`

Defina um limite de idade em dias para as transcrições de sessões que você iniciou ou continuou mais recentemente no Claude Desktop ou Cowork. Sem essa chave, o Claude Code mantém essas transcrições em qualquer idade. O Claude Code deleta cada uma assim que fica mais antiga que tanto esse limite quanto cleanupPeriodDays, então com cleanupPeriodDays em seu padrão de 30, um valor de 7 ainda as mantém por 30 dias. Quando configurações gerenciadas definem cleanupPeriodDays, esse período se aplica em vez disso e essa chave é ignorada. Requer Claude Code v2.1.248 ou posterior.

  • Escopo: User or managed. O Claude Code também lê a chave de um arquivo que você passa com --settings e a ignora em configurações de projeto e locais.
  • Tipo: número de dias, um número inteiro, mínimo 0
  • Padrão: 0, que não define limite de idade
{
  "desktopSessionCleanupPeriodDays": 90
}

`feedbackDrafts`

Controle feedback redigido por Claude: se Claude pode enfileirar rascunhos de feedback para você revisar, e se o Claude Code mostra um card quando Claude enfileira um.

  • Escopo: User or managed
  • Tipo: string, um de "notify", "quiet" ou "off"
    • "notify": O Claude Code mostra um card acima do prompt quando Claude enfileira um rascunho, até três cards em uma sessão por padrão
    • "quiet": Claude redige sem um card. Você vê a contagem de rascunhos enfileirados no rodapé do prompt e os revisa em /feedback
    • "off": O Claude Code remove a ferramenta SendFeedback, então Claude não pode enfileirar rascunhos
  • Padrão: "notify"
  • Substituições por sessão: CLAUDE_CODE_SEND_FEEDBACK definido como 0 desativa o recurso para uma sessão
{
  "feedbackDrafts": "quiet"
}

Aparece em /config como Claude-drafted feedback, que escreve essa chave em suas configurações de usuário. Você vê a linha /config apenas em sessões onde Claude pode redigir feedback; definir "off" não a oculta, então você pode ativar o recurso novamente a partir da mesma linha. Um valor em configurações gerenciadas tem precedência sobre sua configuração de usuário, então quando um administrador define essa chave, a linha mostra o valor gerenciado e alterá-lo não tem efeito. O Claude Code ignora essa chave em configurações de projeto e locais.

`feedbackSurveyRate`

Defina a probabilidade de que a pesquisa de qualidade de sessão apareça quando uma sessão for elegível para ela. Defina 0 para impedir que a pesquisa apareça.

  • Escopo: Any file
  • Tipo: número entre 0 e 1
  • Padrão: não definido, então o Claude Code usa a taxa que a Anthropic define remotamente, ou sua taxa integrada de 0.005 no Amazon Bedrock, na Agent Platform do Google Cloud e no Microsoft Foundry, que não recebem configuração remota
  • Substituições por sessão: CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY definido como 1 desativa a pesquisa para uma sessão qualquer que seja a taxa que essa chave define
{
  "feedbackSurveyRate": 0.05
}

A mesma taxa se aplica à pesquisa na extensão VS Code.

`skipWebFetchPreflight`

Pule a verificação de segurança de domínio WebFetch, que envia cada nome de host solicitado para api.anthropic.com antes de buscar. Defina true em ambientes que bloqueiam tráfego para Anthropic, como Amazon Bedrock, Agent Platform do Google Cloud ou implantações do Microsoft Foundry com saída restritiva.

  • Escopo: Any file
  • Tipo: Boolean
    • true: O Claude Code pula a verificação de segurança de domínio WebFetch
    • false: a verificação é executada antes da primeira busca para cada nome de host em uma sessão, e novamente para um nome de host cuja verificação anterior foi bloqueada ou falhou
  • Padrão: não definido, então a verificação é executada antes da primeira busca para cada nome de host em uma sessão
{
  "skipWebFetchPreflight": true
}

Com a verificação ignorada, WebFetch tenta qualquer URL sem consultar a lista de bloqueio, então emparelhe com regras de permissão WebFetch se precisar restringir quais domínios Claude pode alcançar.

Configurações empresariais e gerenciadas

Chaves que uma organização usa para calcular, atualizar e combinar configurações gerenciadas. Consulte Configurar configurações gerenciadas.

`disableSideloadFlags`

Rejeite os sinalizadores CLI --plugin-dir, --plugin-url, --agents e --mcp-config na inicialização, que os usuários poderiam passar para contornar strictKnownMarketplaces em uma única execução. Claude Code sai com um erro nomeando os sinalizadores rejeitados e aplica a mesma verificação a superfícies que iniciam o CLI com esses sinalizadores internamente, atualmente Cowork sessões locais no aplicativo desktop. Em sessões na nuvem, Claude Code descarta os servidores MCP que o servidor entregou através de --mcp-config, exceto entradas type: "sdk" em processo, e inicia a sessão. Requer Claude Code v2.1.193 ou posterior.

  • Escopo: Managed
  • Tipo: Booleano
    • true: Claude Code rejeita --plugin-dir, --plugin-url, --agents e --mcp-config na inicialização e sai com um erro nomeando-os, exceto que em sessões na nuvem ele descarta os servidores MCP que o servidor entregou através de --mcp-config, exceto entradas type: "sdk" em processo, e inicia a sessão
    • false: Claude Code aceita esses sinalizadores
  • Padrão: false
{
  "disableSideloadFlags": true
}

Claude Code ainda aceita um --mcp-config cujos servidores são todas entradas type: "sdk" em processo, então o Agent SDK e a extensão VS Code continuam funcionando. Os usuários ainda podem adicionar servidores com claude mcp add ou um arquivo .mcp.json; para controle por servidor, defina allowedMcpServers também. Requer Claude Code v2.1.193 ou posterior.

A mesma verificação cobre pastas de plugins nomeadas na variável de ambiente CLAUDE_CODE_PLUGIN_DIRS, que requer Claude Code v2.1.280 ou posterior. Quando a variável nomeia uma pasta, Claude Code sai com o mesmo erro, e o erro diz para desconfigurar a variável.

Em sessões na nuvem, Claude Code também ignora atualizações MCP entregues pelo servidor no meio da sessão, o caminho por trás da configuração de sessão na nuvem e SDK setMcpServers() que alcançam essas sessões. Entradas type: "sdk" em processo permanecem isentas lá também. Antes da v2.1.239, um --mcp-config entregue pelo servidor bloqueava uma sessão na nuvem de iniciar.

`forceRemoteSettingsRefresh`

Bloqueie a inicialização do CLI até que Claude Code tenha buscado recentemente configurações gerenciadas pelo servidor. Se a busca falhar, Claude Code sai em vez de continuar com configurações em cache ou nenhuma. Defina-o quando seu ambiente não puder aceitar nem mesmo uma breve janela em que uma sessão seja executada sem sua política gerenciada.

Quando a chave não está definida, Claude Code não bloqueia a inicialização na busca, embora quando o desenvolvedor se conecta na inicialização ele aguarde até cinco segundos pela busca. Uma sessão de gateway na nuvem sempre aguarda e sai se o gateway não puder ser alcançado.

  • Escopo: Managed. Claude Code honra um true de qualquer fonte gerenciada controlada por administrador, mesmo uma que não seja a fonte de prioridade mais alta.
  • Tipo: Booleano
    • true: Claude Code bloqueia a inicialização até ter buscado recentemente configurações gerenciadas pelo servidor e sai se a busca falhar
    • false: Claude Code não bloqueia a inicialização na busca, embora em uma inicialização de conexão ele aguarde até cinco segundos pela busca
  • Padrão: false
{
  "forceRemoteSettingsRefresh": true
}

Defina-o em um perfil MDM ou no arquivo de configurações gerenciadas para impor inicialização com falha fechada antes da primeira carga útil do servidor chegar. Claude Code aplica a verificação apenas em sessões que buscam configurações gerenciadas pelo servidor, então uma sessão que não as busca inicia sem aguardar. Os subcomandos claude auth estão isentos, então os usuários podem se autenticar novamente quando credenciais expiradas são o motivo da falha da busca. Consulte Impor inicialização com falha fechada.

`managedSourcesBehavior`

Escolha se Claude Code aplica apenas a fonte gerenciada de prioridade mais alta que sua organização entrega, ou combina todas as fontes de administrador que entrega. Por padrão, Claude Code pega a fonte de prioridade mais alta que carrega uma chave de política e ignora o resto. Uma chave de política é qualquer chave de configurações diferente desta e wslInheritsWindowsSettings. Portanto, uma vez que configurações gerenciadas pelo servidor ou uma política MDM entreguem uma chave de política, um arquivo managed-settings.json contribui apenas com as chaves que Claude Code lê de todas as fontes de administrador. Com "merge", todas as fontes de administrador que você entrega contribuem suas chaves para uma política combinada. Requer Claude Code v2.1.242 ou posterior.

Defina "merge" apenas onde todas as fontes classificadas abaixo da sua mais alta estão sob controle de um administrador, porque Claude Code então adiciona entradas de uma fonte inferior, como regras permissions.allow, à política.

  • Escopo: Managed. Claude Code lê essa chave da fonte de prioridade mais alta que carrega esta chave ou uma chave de política, e ignora essa chave em todas as fontes classificadas mais baixo, então uma fonte inferior não pode optar por se combinar com a fonte acima dela. Nem o registro HKCU do Windows nem configurações pai de um host de incorporação participam da mesclagem.
  • Tipo: string, um de:
    • "first-wins": a fonte de prioridade mais alta que carrega uma chave de política fornece a política, e fontes inferiores contribuem apenas com as chaves que Claude Code lê de todas as fontes de administrador
    • "merge": todas as fontes de administrador que você entrega contribuem suas chaves, combinadas pelas regras abaixo
  • Padrão: "first-wins"

Entregue a chave na fonte de prioridade mais alta que você implanta. Uma máquina que nunca recebe configurações gerenciadas pelo servidor precisa da chave em seu perfil MDM também, porque Claude Code lê a chave da fonte de prioridade mais alta que a carrega ou uma chave de política. Um arquivo managed-settings.json é a fonte de administrador classificada mais baixa, então "merge" definido lá não tem fonte abaixo dela para combinar. Em configurações gerenciadas pelo servidor, a chave se parece com isto:

{
  "managedSourcesBehavior": "merge"
}

Sob "merge", Claude Code combina cada chave por seu tipo. Esta tabela fornece a regra para cada tipo. As linhas de lista de restrição, valores tomados inteiros e apenas fonte mais alta nomeiam todas as chaves que cobrem, e as outras linhas fornecem exemplos:

Tipo de chave Como Claude Code a combina Chaves
Listas Combina entradas de todas as fontes permissions.allow, sandbox.network.allowedDomains e outras chaves de lista
Bloqueios Aplica o valor mais rigoroso que qualquer fonte define. Quando nenhuma fonte define um valor rigoroso, aplica um valor mais flexível apenas da fonte mais alta allowManagedPermissionRulesOnly, permissions.disableBypassPermissionsMode e outros bloqueios booleanos ou enum
Listas de restrição Pega a lista inteira da fonte mais alta que a define, sem adicionar entradas de fontes inferiores. Quando a fonte mais alta não define uma, pega inteira da próxima fonte abaixo availableModels, allowedMcpServers, strictKnownMarketplaces, allowedChannelPlugins e a cadeia fallbackModel
Valores tomados inteiros Pega o valor inteiro da fonte mais alta que o define, sem combinar entradas ou campos de fontes inferiores. Quando a fonte mais alta não o define, pega inteiro da próxima fonte abaixo sandbox.credentials.awsPairs, sandbox.ripgrep
Servidores MCP fornecidos Combina os nomes de servidor de todas as fontes. Quando duas fontes definem o mesmo nome, aplica a entrada inteira da fonte mais alta managedMcpServers
Lê apenas da fonte de prioridade mais alta Lê a chave apenas da fonte de prioridade mais alta que carrega uma chave de política, então o valor de uma fonte inferior é ignorado mesmo quando a fonte mais alta não define nenhum apiKeyHelper, awsAuthRefresh, awsCredentialExport, gcpAuthRefresh, otelHeadersHelper, proxyAuthHelper, forceLoginOrgUUID, os valores "claudeai" e "console" de forceLoginMethod, parentSettingsBehavior, modelPicker, policyHelper, permissions.defaultMode
env Mescla por variável em fontes de administrador, sob ambos "first-wins" e "merge" env
Todas as outras chaves Pega o valor da fonte mais alta que o define cleanupPeriodDays, model

Pegar sandbox.credentials.awsPairs e sandbox.ripgrep inteiros requer Claude Code v2.1.257 ou posterior.

Algumas chaves adicionam uma condição que a tabela não mostra:

  • policyHelper: Claude Code a honra apenas quando a fonte mais alta que carrega uma chave de política é uma política MDM ou um arquivo de configurações gerenciadas, então sob configurações gerenciadas pelo servidor ela não se aplica.
  • modelOverrides: emparelha com availableModels. Claude Code pega modelOverrides da fonte mais alta que a define, a menos que uma fonte mais alta defina availableModels sem modelOverrides. Nesse caso, ele ignora modelOverrides de todas as fontes.
  • forceLoginGatewayUrl, gatewayInternalNetworks e o valor "gateway" de forceLoginMethod: Claude Code nunca lê nenhum deles de configurações gerenciadas pelo servidor, então um valor lá não se aplica nem oculta um definido em uma política MDM ou arquivo de configurações gerenciadas. Entre as fontes de administrador na máquina, apenas a fonte classificada mais alta que carrega uma chave de política as fornece, independentemente de configurações gerenciadas pelo servidor também estarem presentes.

Para confirmar quais fontes se combinaram em uma máquina, execute /status e leia a linha Setting sources.

`parentSettingsBehavior`

Escolha se Claude Code aplica configurações gerenciadas fornecidas por um processo host de incorporação, como o Agent SDK ou uma extensão IDE, quando um nível gerenciado implantado por administrador também está presente. Com "first-wins", Claude Code descarta as configurações fornecidas pelo host; com "merge", ele as aplica sob o nível de administrador através de um filtro apenas restritivo. Defina "merge" quando um host precisa passar suas próprias restrições para as sessões que inicia, por exemplo Claude Desktop entregando uma lista de permissões de saída de um gateway.

  • Escopo: Managed. Claude Code a lê da fonte gerenciada controlada por administrador de prioridade mais alta.
  • Tipo: string, um de:
    • "first-wins": Claude Code descarta as configurações fornecidas pelo host quando um nível gerenciado implantado por administrador está presente
    • "merge": Claude Code aplica as configurações fornecidas pelo host sob o nível de administrador através de um filtro apenas restritivo
  • Padrão: "first-wins"
{
  "parentSettingsBehavior": "merge"
}

Esta chave não tem efeito quando nenhum nível gerenciado implantado por administrador existe: as configurações do host então se aplicam como o único nível gerenciado, ainda filtrado para valores restritivos. Para os limites do filtro e como as fontes gerenciadas interagem, consulte Configurações pai de hosts de incorporação e Restringir configurações pai.

`policyHelper`

Execute um executável que você implanta que calcula configurações gerenciadas na inicialização, para que você possa derivar política da postura do dispositivo, identidade ou um serviço remoto em vez de um arquivo estático. Claude Code executa o auxiliar antes de aceitar o primeiro prompt e trata as configurações que emite como as configurações gerenciadas para a sessão.

  • Escopo: Managed. Leia do plist macOS, do registro HKLM do Windows ou do arquivo de configurações gerenciadas. Claude Code lê a chave da fonte gerenciada de prioridade mais alta que carrega uma chave de política e executa o auxiliar apenas quando essa fonte é uma daquelas três; ele ignora a chave em configurações gerenciadas pelo servidor, no registro HKCU e em configurações pai fornecidas pelo host.
  • Tipo: objeto com path, timeoutMs e refreshIntervalMs
  • Padrão: não definido, então nenhum auxiliar é executado

Quando configurações gerenciadas pelo servidor entregam a política na inicialização, elas têm precedência sobre a fonte do auxiliar e o auxiliar não é executado.

Se uma busca de configurações posterior relatar que as configurações gerenciadas pelo servidor foram removidas, Claude Code executa o auxiliar nesse ponto em vez de aguardar a próxima inicialização. Sua saída governa o resto da sessão, e uma execução que falha encerra a sessão com a mesma mensagem que uma execução de inicialização falhada.

Este exemplo executa o auxiliar com um tempo limite de 5 segundos e o re-executa a cada cinco minutos:

{
  "policyHelper": {
    "path": "/usr/local/bin/claude-policy",
    "timeoutMs": 5000,
    "refreshIntervalMs": 300000
  }
}

Escreva a saída do auxiliar

Claude Code executa o auxiliar sem argumentos, define CLAUDE_CODE_VERSION em seu ambiente e lê um envelope JSON de stdout, limitado a 1 MiB.

Coloque as configurações sob uma chave managedSettings. Um objeto de configurações simples sem chave managedSettings analisa com managedSettings indefinido e não aplica nada, e Claude Code não relata nenhum erro:

{
  "managedSettings": {
    "permissions": { "deny": ["Read(//etc/secrets/**)"] }
  }
}

Quando o auxiliar emite managedSettings, esse objeto se torna a única fonte de configurações gerenciadas para a execução: Claude Code ignora as fontes MDM, arquivo e HKCU, lê as chaves entre fontes apenas da saída do auxiliar e nunca mescla configurações pai.

A verificação de inicialização forceRemoteSettingsRefresh é executada antes do auxiliar e lê qualquer fonte de administrador. Um auxiliar que sai com 0 com um envelope que omite managedSettings não contribui com nenhuma configuração gerenciada, e as outras fontes se aplicam como usual.

Falhas do auxiliar

Uma execução do auxiliar falha quando:

  • path quebra as regras em policyHelper.path.
  • Nenhum arquivo regular está em path. Claude Code verifica o arquivo antes de iniciar o auxiliar, dentro do mesmo orçamento timeoutMs, então uma montagem de rede sem resposta pode causar a falha da execução.
  • O auxiliar sai com não-zero, ainda está em execução quando timeoutMs decorre ou não inicia, por exemplo porque não é executável.
  • O auxiliar escreve mais de 1 MiB para stdout ou stderr.
  • stdout não é um único objeto JSON, ou seu managedSettings tem uma violação de esquema que Claude Code não pode reparar.

Quando a execução de inicialização falha, Claude Code imprime o motivo e se recusa a iniciar. Após uma saída com não-zero, o motivo inclui stderr do auxiliar, ou seu stdout quando stderr está vazio. Após um tempo limite, o motivo nomeia o limite timeoutMs e não inclui nenhuma saída do auxiliar. A recusa cobre sessões interativas, claude -p, sessões do Agent SDK, sessões em segundo plano e a maioria dos subcomandos.

A recusa é deliberada, então um auxiliar que precisa de resiliência de interrupção deve servir de seu próprio cache e sair com 0.

Quando uma atualização em segundo plano falha, Claude Code mantém a última política bem-sucedida em vigor, e /status mostra a atualização falhada com seu motivo até que uma atualização tenha sucesso. Cada atualização é executada sob o mesmo timeoutMs e regras de falha que a execução de inicialização.

Com --debug, Claude Code escreve stderr do auxiliar de cada execução para o log de depuração.

Claude Code relata um valor policyHelper inválido como uma entrada descartada e inicia a sessão nas configurações gerenciadas restantes sem executar um auxiliar. Valores inválidos incluem uma string de caminho simples e um timeoutMs abaixo de seu mínimo.

Para desativar um auxiliar, remova a chave da fonte que a define.

`policyHelper.path`

Nomeie o executável do auxiliar que Claude Code executa. Para o que acontece quando o caminho quebra as regras abaixo, consulte Falhas do auxiliar.

  • Escopo: Managed. Leia do plist macOS, do registro HKLM do Windows ou do arquivo de configurações gerenciadas, onde policyHelper é lido.
  • Tipo: string, um caminho absoluto em forma normalizada, sem segmentos . ou ..; no Windows, um caminho de letra de unidade ou UNC que termina em .exe
  • Padrão: nenhum; obrigatório quando policyHelper está definido
{
  "policyHelper": {
    "path": "/usr/local/bin/claude-policy"
  }
}

`policyHelper.timeoutMs`

Defina quanto tempo Claude Code aguarda o auxiliar antes de tratar a execução como falhada. Uma execução com tempo limite falha da mesma forma que uma saída com não-zero, então na inicialização Claude Code se recusa a iniciar.

  • Escopo: Managed. Leia do plist macOS, do registro HKLM do Windows ou do arquivo de configurações gerenciadas, onde policyHelper é lido.
  • Tipo: inteiro, milissegundos, mínimo 1000
  • Padrão: 10000
{
  "policyHelper": {
    "path": "/usr/local/bin/claude-policy",
    "timeoutMs": 5000
  }
}

`policyHelper.refreshIntervalMs`

Faça Claude Code re-executar o auxiliar em segundo plano em um intervalo para que mudanças de política alcancem uma sessão em execução. Quando uma atualização tem sucesso, sua saída substitui as configurações gerenciadas anteriores sem uma reinicialização; quando uma atualização falha, Claude Code mantém a política que já tem.

  • Escopo: Managed. Leia do plist macOS, do registro HKLM do Windows ou do arquivo de configurações gerenciadas, onde policyHelper é lido.
  • Tipo: inteiro, milissegundos: 0 para desabilitar atualização, caso contrário pelo menos 60000
  • Padrão: não definido, então Claude Code executa o auxiliar uma vez na inicialização

Este exemplo re-executa o auxiliar a cada cinco minutos:

{
  "policyHelper": {
    "path": "/usr/local/bin/claude-policy",
    "refreshIntervalMs": 300000
  }
}

`wslInheritsWindowsSettings`

Faça Claude Code no WSL ler configurações gerenciadas da cadeia de política do Windows, com HKLM e o arquivo de configurações gerenciadas do Windows tendo prioridade sobre /etc/claude-code e HKCU abaixo. Enquanto a cadeia está ativada, Claude Code lê /etc/claude-code apenas quando nenhum arquivo de configurações gerenciadas ou drop-in sob C:\Program Files\ClaudeCode\ entrega uma chave de política. Defina-o para estender a política que você já implanta no Windows para sessões WSL na mesma máquina, para que sigam as mesmas regras que sessões de host. Claude Code a honra apenas quando definida na chave de registro HKLM ou em um arquivo de configurações gerenciadas ou drop-in sob C:\Program Files\ClaudeCode\, ambos exigindo administrador do Windows para escrever.

  • Escopo: Managed. Em uma fonte do Windows controlada por administrador.
  • Tipo: Booleano
    • true: Claude Code no WSL lê configurações gerenciadas da cadeia de política do Windows e lê /etc/claude-code apenas quando nenhum arquivo de configurações gerenciadas ou drop-in sob C:\Program Files\ClaudeCode\ entrega uma chave de política
    • false: WSL lê apenas /etc/claude-code
  • Padrão: false, então WSL lê apenas /etc/claude-code
{
  "wslInheritsWindowsSettings": true
}

Uma vez que uma fonte de administrador ativa a cadeia, a política HKCU se une a ela no WSL apenas quando HKCU também define a chave como true. Essa cópia não ativa a cadeia por si só. Uma fonte do Windows que contém apenas essa chave não conta como uma fonte de política, então uma fonte de prioridade mais baixa ainda fornece a política. Esta chave não tem efeito no Windows nativo.

Configurações globais

Salve essas chaves em ~/.claude.json, não em um arquivo de configurações. Claude Code as ignora em qualquer outro lugar. Claude Code e /config escrevem a maioria delas para você, e você também pode editá-las manualmente.

`autoConnectIde`

Conecte a um IDE em execução automaticamente quando você inicia Claude Code a partir de um terminal externo. Aparece em /config como Auto-conectar ao IDE (terminal externo) quando você executa Claude Code fora de um terminal VS Code ou JetBrains.

  • Escopo: Global config
  • Tipo: Booleano
    • true: Claude Code se conecta a um IDE em execução automaticamente quando você o inicia a partir de um terminal externo
    • false: Claude Code não se conecta automaticamente a partir de um terminal externo; dentro de um terminal VS Code ou JetBrains, ou com --ide, ele ainda se conecta
  • Padrão: false
  • Substituições por sessão: CLAUDE_CODE_AUTO_CONNECT_IDE tem precedência sobre essa chave para uma sessão, em qualquer direção
{
  "autoConnectIde": true
}

Claude Code ignora essa chave em settings.json.

`autoInstallIdeExtension`

Instale a extensão Claude Code IDE automaticamente quando você executa Claude Code a partir de um terminal VS Code. Aparece em /config como Auto-instalar extensão IDE quando você executa Claude Code dentro de um terminal VS Code ou JetBrains.

  • Escopo: Global config
  • Tipo: Booleano
    • true: Claude Code instala a extensão IDE automaticamente quando você a executa a partir de um terminal VS Code
    • false: Claude Code não instala a extensão automaticamente
  • Padrão: true
  • Substituições por sessão: CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL definido como 1 pula a instalação para uma sessão mesmo quando essa chave é true
{
  "autoInstallIdeExtension": false
}

Claude Code ignora essa chave em settings.json.

`copyOnSelect`

Copie texto para sua área de transferência automaticamente quando você terminar de selecioná-lo com o mouse em renderização em tela cheia ou visualização de agente. Aparece em /config como Copiar ao selecionar enquanto a renderização em tela cheia está ativada.

  • Escopo: Global config
  • Tipo: Booleano
    • true: Claude Code copia texto para sua área de transferência quando você termina de selecioná-lo
    • false: selecionar texto deixa sua área de transferência inalterada, e você copia a seleção com um atalho de teclado em vez disso
  • Padrão: true
{
  "copyOnSelect": false
}

Claude Code ignora essa chave em settings.json.

`diffTool`

Escolha onde Claude Code mostra o diff de uma mudança Edit ou Write que ele propõe quando um IDE VS Code ou JetBrains está conectado: "auto" o abre no visualizador de diff do IDE, "terminal" o mantém no terminal. Aparece em /config como Diff tool apenas enquanto Claude Code está conectado a um IDE VS Code ou JetBrains.

  • Escopo: Global config
  • Tipo: string, um de:
    • "auto": Claude Code abre o diff no visualizador de diff do IDE quando um IDE VS Code ou JetBrains está conectado
    • "terminal": Claude Code mantém o diff no terminal
  • Padrão: "auto"
{
  "diffTool": "terminal"
}

Claude Code ignora essa chave em settings.json.

`externalEditorContext`

Quando você pressiona Ctrl+G, Claude Code abre o prompt que você está digitando em seu editor externo. Com essa chave ativada, o buffer do editor começa com a resposta anterior de Claude como linhas de comentário #, para que você possa lê-la enquanto escreve, e Claude Code remove essas linhas quando você salva. Aparece em /config como Mostrar última resposta no editor externo.

  • Escopo: Global config
  • Tipo: Booleano
    • true: o buffer do editor começa com a resposta anterior de Claude como linhas de comentário #, que Claude Code remove quando você salva
    • false: o buffer do editor abre apenas com seu prompt
  • Padrão: false
{
  "externalEditorContext": true
}

Com ela ativada, o buffer que Claude Code abre se parece com isto, e apenas o texto abaixo da linha marcadora é enviado como seu prompt:

# ─── Última resposta de Claude (para referência; removida ao salvar) ───
# Adicionei o loop de repetição a fetchUser em src/api.ts e um teste
# para o caso de timeout. Quer que eu conecte a mesma repetição a
# fetchOrders?
# ─── Escreva sua resposta abaixo desta linha ──────────────────────────

Sim, e limite a três tentativas.

Claude Code mantém as últimas 50 linhas da resposta e marca o corte com # … (saída anterior truncada).

Claude Code ignora essa chave em settings.json.

`permissionExplainerEnabled`

Até v2.1.256, você poderia pressionar Ctrl+E em um prompt de permissão Bash ou PowerShell para ver uma explicação gerada pelo modelo do comando, e definir essa chave como false para desativar esse atalho.

  • Escopo: Global config. Na v2.1.256 e anteriores.
  • Tipo: Booleano
  • Padrão: true

`teammateDefaultModel`

Até v2.1.233, você definia essa chave para o modelo de equipe de agente colegas de equipe que seu prompt não nomeou um modelo para: um alias como "sonnet", ou null para seguir o modelo do líder. Para o modelo que Claude Code escolhe para esses colegas de equipe agora, veja especificar colegas de equipe e modelos.

  • Escopo: Global config. Na v2.1.233 e anteriores.
  • Tipo: string, um alias de modelo ou ID de modelo completo, ou null
  • Padrão: não definido

Veja também