diff --git a/zh-CN/settings-reference.md b/zh-CN/settings-reference.md new file mode 100644 index 0000000000000000000000000000000000000000..5080c1d2d2d73ba4b8589fc459459f9090d190e5 --- /dev/null +++ b/zh-CN/settings-reference.md @@ -0,0 +1,6509 @@ +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. + +# 所有设置 + +> Claude Code settings.json 的完整参考：每个键的位置、类型和默认值，以及可直接粘贴的示例，包含每个键的索引。 + +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
+ + + + {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 <> + +
+
+
+ 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 ? : + / + } +
+ {facetList.map(f => { + const cur = sel[f.name] || 'All'; + const isOpen = menuOpen === f.name; + return
{ + menuRef.current[f.name] = el; + }} style={{ + position: 'relative' + }}> + + {cur !== 'All' && } + {isOpen &&
{ + 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 ; + })} +
} +
; + })} + {sortOptions.length > 1 &&
+ Sort by + {sortOptions.map(o => { + const on = sortBy === o; + return ; + })} +
} +
+
+ {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.'}{' '} + + {children ? <> {children} : null} + : <> + Showing {counts.shown} of {counts.total} {nounText} + } +
+
+ ; +}; + + + +本参考页面列出了 Claude Code 从设置文件读取的每个键，以及它保存在 `~/.claude.json` 中的[短键组](#global-config-settings)。要选择文件或检查优先级，请从[设置文件和优先级](/docs/zh-CN/settings)开始。 + + + + + + + +

+ 设置索引 +

+ +下面的每个键都链接到其条目。范围列出了[文件](/docs/zh-CN/settings#settings-files-and-who-they-affect)，其中可以使用该键：`User` 是 `~/.claude/settings.json`，`Project` 是 `.claude/settings.json`，`Local` 是 `.claude/settings.local.json`，`Managed` 是[您的组织部署的内容](/docs/zh-CN/managed-settings)。`Any file` 表示所有四个文件，`Global config` 表示 [`~/.claude.json`](#global-config-settings)。 + + + +| 键 | 描述 | 主题 | 范围 | +| :---------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- | :---------------------- | +| [`advisorModel`](#advisormodel) | 选择当 Claude 使用[顾问工具](/docs/zh-CN/advisor)时哪个模型来回答 | 模型和响应 | Any file | +| [`agent`](#agent) | 将每个会话作为具有其提示、工具和模型的命名[子代理](/docs/zh-CN/sub-agents)启动 | 代理、会话和工作树 | Any file | +| [`agentPushNotifEnabled`](#agentpushnotifenabled) | 让 Claude 在决定时向您的手机发送[推送通知](/docs/zh-CN/remote-control#mobile-push-notifications) | 远程、桌面和通知 | Any file | +| [`allowAllClaudeAiMcps`](#allowallclaudeaimcps) | 加载[claude.ai 连接器](/docs/zh-CN/mcp)，Claude Code 与部署的 [`managed-mcp.json`](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json) 一起自行获取 | MCP | Managed | +| [`allowedChannelPlugins`](#allowedchannelplugins) | 替换可以推送消息的[频道插件](/docs/zh-CN/channels#restrict-which-channel-plugins-can-run)的默认允许列表 | 插件和技能 | Managed | +| [`allowedHttpHookUrls`](#allowedhttphookurls) | 限制[HTTP hooks](/docs/zh-CN/hooks)可以针对的 URL | Hooks 和自动化 | Any file | +| [`allowedMcpServers`](#allowedmcpservers) | 允许列表用户可以添加的[MCP 服务器](/docs/zh-CN/mcp) | MCP | Any file | +| [`allowManagedHooksOnly`](#allowmanagedhooksonly) | 仅运行您的组织部署的[hooks](/docs/zh-CN/hooks) | Hooks 和自动化 | Managed | +| [`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly) | 使托管的 [MCP](/docs/zh-CN/mcp) 允许列表成为唯一适用的列表 | MCP | Managed | +| [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly) | 使[托管设置](/docs/zh-CN/managed-settings)成为[权限规则](/docs/zh-CN/permissions#managed-settings)的唯一设置来源 | 权限设置 | Managed | +| [`alwaysThinkingEnabled`](#alwaysthinkingenabled) | 为每个会话关闭[扩展思考](/docs/zh-CN/model-config#extended-thinking) | 模型和响应 | Any file | +| [`apiKeyHelper`](#apikeyhelper) | 使用您自己的命令生成 [API 凭证](/docs/zh-CN/authentication#credential-management) | 身份验证和提供商 | Any file | +| [`askUserQuestionTimeout`](#askuserquestiontimeout) | 让未回答的问题在空闲时间后[自动继续](/docs/zh-CN/tools-reference#question-auto-continue-timeout) | 界面和终端 | User or managed | +| [`attribution`](#attribution) | 自定义 Claude Code 添加到提交和拉取请求的属性 | Git 和属性 | Any file | +| [`attribution.commit`](#attribution-commit) | 更改或隐藏 Claude Code 添加到提交的预告片 | Git 和属性 | Any file | +| [`attribution.pr`](#attribution-pr) | 更改或隐藏拉取请求描述中的属性行 | Git 和属性 | Any file | +| [`attribution.sessionUrl`](#attribution-sessionurl) | 从[云](/docs/zh-CN/claude-code-on-the-web)和[远程控制](/docs/zh-CN/remote-control)提交中省略 claude.ai 会话链接 | Git 和属性 | Any file | +| [`autoCompactEnabled`](#autocompactenabled) | 打开或关闭[自动压缩](/docs/zh-CN/context-window) | 内存和上下文 | Any file | +| [`autoCompactWindow`](#autocompactwindow) | 设置上下文在 Claude Code [压缩](/docs/zh-CN/context-window)之前有多满 | 内存和上下文 | Any file | +| [`autoConnectIde`](#autoconnectide) | 从外部终端自动连接到运行的 [VS Code](/docs/zh-CN/vs-code) 或 [JetBrains](/docs/zh-CN/jetbrains#from-external-terminals) IDE | 全局配置设置 | Global config | +| [`autoContinueAtUsageLimit`](#autocontinueatusagelimit) | 在打开的会话中等待，并在 claude.ai 使用限制重置后[自动继续任务](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset) | 界面和终端 | User or managed | +| [`autoInstallIdeExtension`](#autoinstallideextension) | 关闭从 VS Code 终端自动安装 [IDE 扩展](/docs/zh-CN/vs-code#install-the-extension) | 全局配置设置 | Global config | +| [`autoMemoryDirectory`](#automemorydirectory) | 在您选择的目录中存储[自动内存](/docs/zh-CN/memory#auto-memory) | 内存和上下文 | Any file | +| [`autoMemoryEnabled`](#automemoryenabled) | 打开或关闭[自动内存](/docs/zh-CN/memory#auto-memory) | 内存和上下文 | Any file | +| [`autoMode`](#automode) | 向[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器添加您自己的允许和拒绝规则 | 权限设置 | User or managed | +| [`autoMode.classifyAllShell`](#automode-classifyallshell) | 通过[自动模式分类器](/docs/zh-CN/permission-modes#what-the-classifier-blocks-by-default)发送每个 shell 命令，即使是狭窄允许规则匹配的命令 | 权限设置 | User or managed | +| [`autoScrollEnabled`](#autoscrollenabled) | 在全屏渲染中[跟随新输出](/docs/zh-CN/fullscreen#auto-follow)到底部 | 界面和终端 | Any file | +| [`autoUpdatesChannel`](#autoupdateschannel) | 遵循稳定[发布频道](/docs/zh-CN/setup#configure-release-channel)而不是最新版本 | 更新和版本控制 | Any file | +| [`availableModels`](#availablemodels) | [限制人们可以选择的模型](/docs/zh-CN/model-config#restrict-model-selection) | 模型和响应 | Any file | +| [`awaySummaryEnabled`](#awaysummaryenabled) | 关闭当您回到终端时显示的[会话回顾](/docs/zh-CN/interactive-mode#session-recap) | 远程、桌面和通知 | Any file | +| [`awsAuthRefresh`](#awsauthrefresh) | 使用您自己的命令刷新 `.aws` 中过期的 [Bedrock 凭证](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration) | 身份验证和提供商 | Any file | +| [`awsCredentialExport`](#awscredentialexport) | 从您自己的命令以 JSON 形式提供 [Bedrock 凭证](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration) | 身份验证和提供商 | Any file | +| [`axScreenReader`](#axscreenreader) | 渲染[屏幕阅读器友好的输出](/docs/zh-CN/accessibility) | 界面和终端 | Any file | +| [`bashOutputMaxChars`](#bashoutputmaxchars) | 设置成功命令的[输出](/docs/zh-CN/tools-reference#output-limits)有多少 Claude 内联接收 | 内存和上下文 | Any file | +| [`blockedMarketplaces`](#blockedmarketplaces) | 为您的组织阻止[插件市场](/docs/zh-CN/plugin-marketplaces)来源 | 插件和技能 | Managed | +| [`browserExternalPageTools`](#browserexternalpagetools) | 在[桌面](/docs/zh-CN/desktop)浏览器窗格中的外部页面上关闭 Claude 的工具 | 工具 | Managed | +| [`channelsEnabled`](#channelsenabled) | 为您的组织允许[频道](/docs/zh-CN/channels#enable-channels-for-your-organization) | 插件和技能 | Managed | +| [`claudeMd`](#claudemd) | 从托管设置注入组织范围的 [CLAUDE.md](/docs/zh-CN/memory#deploy-organization-wide-claude-md) 指令 | 内存和上下文 | Managed | +| [`claudeMdExcludes`](#claudemdexcludes) | 在内存加载时跳过特定的 [CLAUDE.md](/docs/zh-CN/memory#exclude-specific-claude-md-files) 文件 | 内存和上下文 | Any file | +| [`cleanupPeriodDays`](#cleanupperioddays) | 选择 Claude Code 在删除[记录](/docs/zh-CN/data-usage#data-retention)之前保留多少天 | 隐私和遥测 | Any file | +| [`companyAnnouncements`](#companyannouncements) | 在启动时显示您的组织的公告 | 界面和终端 | Any file | +| [`copyOnSelect`](#copyonselect) | 关闭在[全屏渲染](/docs/zh-CN/fullscreen#use-the-mouse)和代理视图中用鼠标选择的文本的自动复制 | 全局配置设置 | Global config | +| [`crossSessionInbound`](#crosssessioninbound) | 选择 Claude Code 是否传递[来自您其他会话的消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)、显示通知而不传递它们，或拒绝它们 | 代理、会话和工作树 | Any file | +| [`defaultShell`](#defaultshell) | 选择 Bash 或 PowerShell 是否运行您使用 [`!` 前缀](/docs/zh-CN/interactive-mode#shell-mode-with-prefix)键入的 shell 命令 | 界面和终端 | Any file | +| [`deniedMcpServers`](#deniedmcpservers) | 按 URL、命令或名称阻止特定的 [MCP 服务器](/docs/zh-CN/mcp) | MCP | Any file | +| [`desktopSessionCleanupPeriodDays`](#desktopsessioncleanupperioddays) | 为[Claude Desktop 和 Cowork 记录](/docs/zh-CN/claude-directory#cleaned-up-automatically)设置年龄限制（天数） | 隐私和遥测 | User or managed | +| [`dialogExpiry`](#dialogexpiry) | 设置 Claude Code 在取消对话之前等待[远程控制](/docs/zh-CN/remote-control)或 SDK 主机回答转发对话的时间 | 界面和终端 | User or managed | +| [`diffTool`](#difftool) | 选择 Claude 提议的文件更改是在 [VS Code](/docs/zh-CN/vs-code) 或 [JetBrains](/docs/zh-CN/jetbrains#features) diff 查看器中打开还是保留在终端中 | 全局配置设置 | Global config | +| [`disableAgentView`](#disableagentview) | 关闭后台代理和[代理视图](/docs/zh-CN/agent-view) | 代理、会话和工作树 | Any file | +| [`disableAllHooks`](#disableallhooks) | 一次关闭 [hooks](/docs/zh-CN/hooks)、自定义[状态行](/docs/zh-CN/statusline)和自定义 [`@` 文件建议](/docs/zh-CN/interactive-mode#quick-commands)命令 | Hooks 和自动化 | Any file | +| [`disableArtifact`](#disableartifact) | 已弃用；使用 `enableArtifact` 关闭[工件工具](/docs/zh-CN/artifacts) | 远程、桌面和通知 | Any file | +| [`disableAutoMode`](#disableautomode) | 从权限模式循环中删除[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) | 权限设置 | Any file | +| [`disableBrowserExternalNavigation`](#disablebrowserexternalnavigation) | 将[桌面](/docs/zh-CN/desktop)浏览器窗格限制为 localhost，供人员和 Claude 使用 | 工具 | Managed | +| [`disableBundledSkills`](#disablebundledskills) | 关闭 Claude Code 附带的[技能](/docs/zh-CN/skills#bundled-skills)和[工作流](/docs/zh-CN/workflows) | 插件和技能 | Any file | +| [`disableClaudeAiConnectors`](#disableclaudeaiconnectors) | 关闭 [claude.ai 连接器](/docs/zh-CN/mcp#disable-claude-ai-connectors)，以便 Claude Code 不会获取它们 | MCP | Any file | +| [`disableCommandPluginSources`](#disablecommandpluginsources) | 阻止通过运行市场声明的命令安装的[插件](/docs/zh-CN/plugins) | 插件和技能 | Managed | +| [`disableDeepLinkRegistration`](#disabledeeplinkregistration) | 停止 Claude Code 注册 [`claude-cli://` 处理程序](/docs/zh-CN/deep-links) | 远程、桌面和通知 | Any file | +| [`disableDesktopLocalSessions`](#disabledesktoplocalsessions) | 关闭在设备上运行的[桌面代码会话](/docs/zh-CN/desktop#local-sessions-on-managed-devices)，仅保留 SSH 到其他主机和云 | 远程、桌面和通知 | Managed | +| [`disabledMcpjsonServers`](#disabledmcpjsonservers) | 拒绝项目的 [`.mcp.json`](/docs/zh-CN/mcp#project-scope) 中的特定服务器 | MCP | Any file | +| [`disableMobileSimulatorTools`](#disablemobilesimulatortools) | 在[桌面](/docs/zh-CN/desktop) iOS 模拟器窗格中阻止 Claude 的工具 | 工具 | Managed | +| [`disableRemoteControl`](#disableremotecontrol) | 在可以启动的任何地方关闭[远程控制](/docs/zh-CN/remote-control) | 远程、桌面和通知 | Any file | +| [`disableSideloadFlags`](#disablesideloadflags) | 拒绝侧加载[插件](/docs/zh-CN/plugins)、[子代理](/docs/zh-CN/sub-agents)和 [MCP 服务器](/docs/zh-CN/mcp)的 CLI 标志 | 企业和托管设置 | Managed | +| [`disableSkillShellExecution`](#disableskillshellexecution) | 停止[技能](/docs/zh-CN/skills)和自定义命令运行内联 shell | 插件和技能 | Any file | +| [`disableWorkflows`](#disableworkflows) | 为所有人关闭[动态工作流](/docs/zh-CN/workflows)；为自己使用 `enableWorkflows` | Hooks 和自动化 | Any file | +| [`editorMode`](#editormode) | 在输入提示中使用 [vim 快捷键](/docs/zh-CN/interactive-mode#vim-editor-mode) | 界面和终端 | Any file | +| [`effortLevel`](#effortlevel) | 为没有保存级别的模型设置默认[努力级别](/docs/zh-CN/model-config#adjust-effort-level) | 模型和响应 | Any file | +| [`emojiCompletionEnabled`](#emojicompletionenabled) | 关闭提示输入中的 [`:shortcode:` 表情符号建议和替换](/docs/zh-CN/interactive-mode#emoji-shortcodes) | 界面和终端 | Any file | +| [`enableAllProjectMcpServers`](#enableallprojectmcpservers) | 批准项目 [`.mcp.json`](/docs/zh-CN/mcp#project-server-approvals-and-workspace-trust) 文件中的每个服务器，无需提示 | MCP | Any file | +| [`enableArtifact`](#enableartifact) | 使用任何文件中的 `false` 关闭[工件工具](/docs/zh-CN/artifacts)；没有文件可以将其打开 | 远程、桌面和通知 | Any file | +| [`enabledMcpjsonServers`](#enabledmcpjsonservers) | 批准项目的 [`.mcp.json`](/docs/zh-CN/mcp#project-server-approvals-and-workspace-trust) 中的特定服务器 | MCP | Any file | +| [`enabledPlugins`](#enabledplugins) | 按范围打开或关闭单个[插件](/docs/zh-CN/plugins) | 插件和技能 | Any file | +| [`enableWorkflows`](#enableworkflows) | 根据您的计划默认值打开或关闭[动态工作流](/docs/zh-CN/workflows) | Hooks 和自动化 | Any file | +| [`enforceAvailableModels`](#enforceavailablemodels) | 保持 [`/model` 默认选择](/docs/zh-CN/model-config#enforce-the-allowlist-for-the-default-model)在您的 `availableModels` 允许列表内 | 模型和响应 | Any file | +| [`env`](#env) | 为每个会话及其子进程设置[环境变量](/docs/zh-CN/env-vars#in-settings-files) | 内存和上下文 | Any file | +| [`externalEditorContext`](#externaleditorcontext) | 当您按 [Ctrl+G](/docs/zh-CN/interactive-mode#general-controls) 编辑时，将 Claude 的最后响应显示为注释 | 全局配置设置 | Global config | +| [`extraKnownMarketplaces`](#extraknownmarketplaces) | 为存储库或组织注册[市场](/docs/zh-CN/plugin-marketplaces) | 插件和技能 | Any file | +| [`fallbackModel`](#fallbackmodel) | 为主模型过载时命名[备份模型](/docs/zh-CN/model-config#fallback-model-chains) | 模型和响应 | Any file | +| [`fastMode`](#fastmode) | 为可用的会话打开[快速模式](/docs/zh-CN/fast-mode) | 模型和响应 | Any file | +| [`fastModePerSessionOptIn`](#fastmodepersessionoptin) | 要求人们在每个会话中打开[快速模式](/docs/zh-CN/fast-mode) | 模型和响应 | Any file | +| [`feedbackDrafts`](#feedbackdrafts) | 控制 Claude 是否为您排队[反馈草稿](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)以供审查 | 隐私和遥测 | User or managed | +| [`feedbackSurveyRate`](#feedbacksurveyrate) | 更改[会话质量调查](/docs/zh-CN/data-usage#session-quality-surveys)出现的频率 | 隐私和遥测 | Any file | +| [`fileCheckpointingEnabled`](#filecheckpointingenabled) | 打开或关闭 [`/rewind`](/docs/zh-CN/checkpointing) 恢复的文件快照 | 内存和上下文 | Any file | +| [`fileSuggestion`](#filesuggestion) | 从您自己的命令提供 [`@` 文件自动完成](/docs/zh-CN/interactive-mode#quick-commands) | 界面和终端 | Any file | +| [`footerLinksRegexes`](#footerlinksregexes) | 将输出中的问题或审查 ID 变成输入框下方的[可点击链接](/docs/zh-CN/statusline#clickable-links) | 界面和终端 | User or managed | +| [`forceLoginGatewayUrl`](#forcelogingatewayurl) | 设置登录屏幕连接到的[网关 URL](/docs/zh-CN/claude-apps-gateway#set-the-gateway-url) | 身份验证和提供商 | Managed | +| [`forceLoginMethod`](#forceloginmethod) | [限制登录](/docs/zh-CN/authentication#restrict-login-to-your-organization)到 claude.ai、Claude Console 或[云网关](/docs/zh-CN/claude-apps-gateway) | 身份验证和提供商 | Any file | +| [`forceLoginOrgUUID`](#forceloginorguuid) | [将 claude.ai 登录固定到您的组织](/docs/zh-CN/authentication#restrict-login-to-your-organization)；仅托管源强制执行 | 身份验证和提供商 | Any file | +| [`forceRemoteSettingsRefresh`](#forceremotesettingsrefresh) | 阻止启动，直到[服务器托管设置](/docs/zh-CN/server-managed-settings)被新鲜获取 | 企业和托管设置 | Managed | +| [`gcpAuthRefresh`](#gcpauthrefresh) | 使用您自己的命令刷新 [Google Cloud 凭证](/docs/zh-CN/google-vertex-ai#advanced-credential-configuration) | 身份验证和提供商 | Any file | +| [`hooks`](#hooks) | 在 Claude Code 生命周期中的点运行您自己的命令作为 [hooks](/docs/zh-CN/hooks) | Hooks 和自动化 | Any file | +| [`httpHookAllowedEnvVars`](#httphookallowedenvvars) | 限制[HTTP hooks](/docs/zh-CN/hooks)可以在标头中放入的环境变量 | Hooks 和自动化 | Any file | +| [`includeCoAuthoredBy`](#includecoauthoredby) | 已弃用；使用 `attribution` 隐藏或更改提交和 PR 属性 | Git 和属性 | Any file | +| [`includeGitInstructions`](#includegitinstructions) | 从[系统提示](/docs/zh-CN/sub-agents#what-loads-at-startup)中删除内置的提交和 PR 指令 | Git 和属性 | Any file | +| [`inputNeededNotifEnabled`](#inputneedednotifenabled) | 当 Claude 在等待您时获得[推送通知](/docs/zh-CN/remote-control#mobile-push-notifications) | 远程、桌面和通知 | Any file | +| [`isolatePeerMachines`](#isolatepeermachines) | 在 Claude [向您在另一台机器上的会话发送消息](/docs/zh-CN/cross-session-messaging#require-approval-for-cross-machine-messages)之前询问您 | 代理、会话和工作树 | Any file | +| [`keybindingFlavor`](#keybindingflavor) | 已弃用且无效；单词编辑快捷键始终[遵循 readline 约定](/docs/zh-CN/interactive-mode#make-ctrl-w-delete-back-to-whitespace) | 界面和终端 | Any file | +| [`language`](#language) | 让 Claude 用英语以外的语言回应 | 模型和响应 | Any file | +| [`managedMcpServers`](#managedmcpservers) | 为每个用户提供远程 [MCP 服务器](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings)以及他们添加的服务器 | MCP | Managed | +| [`managedSourcesBehavior`](#managedsourcesbehavior) | 组合您部署的每个[托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)，而不是仅使用优先级最高的源 | 企业和托管设置 | Managed | +| [`maxEffortLevel`](#maxeffortlevel) | 在每个模型或每个提供商上限制每个模型的[努力级别](/docs/zh-CN/model-config#adjust-effort-level) | 模型和响应 | Any file | +| [`minimumVersion`](#minimumversion) | 保持[自动更新](/docs/zh-CN/setup#pin-a-minimum-version)不安装低于版本的任何内容 | 更新和版本控制 | Any file | +| [`model`](#model) | 更改 Claude Code 启动时使用的[模型](/docs/zh-CN/model-config#set-a-default-model-for-new-sessions) | 模型和响应 | Any file | +| [`modelOverrides`](#modeloverrides) | [将模型 ID 映射](/docs/zh-CN/model-config#override-model-ids-per-version)到您的提供商的 ID，例如 Bedrock ARN | 模型和响应 | Any file | +| [`modelPicker`](#modelpicker) | 选择 [`/model` 选择器](/docs/zh-CN/model-config#available-models)列出的模型，按您自己的顺序和您自己的标签 | 模型和响应 | User or managed | +| [`modelPricing`](#modelpricing) | 按您的组织合同费率而不是列表价格报告支出 | 模型和响应 | Managed | +| [`modelSettings`](#modelsettings) | 为每个模型保留保存的[努力级别](/docs/zh-CN/model-config#adjust-effort-level)，或限制一个模型的努力 | 模型和响应 | Any file | +| [`otelHeadersHelper`](#otelheadershelper) | 使用您自己的命令生成旋转的 [OpenTelemetry](/docs/zh-CN/monitoring-usage#dynamic-headers) 标头 | 身份验证和提供商 | Any file | +| [`outputStyle`](#outputstyle) | 使用[输出样式](/docs/zh-CN/output-styles)更改 Claude 的角色、语气和输出格式 | 模型和响应 | Any file | +| [`parentSettingsBehavior`](#parentsettingsbehavior) | 应用或删除[SDK 或 IDE 主机](/docs/zh-CN/managed-settings#let-an-embedding-host-add-policy)在您部署[托管设置](/docs/zh-CN/managed-settings)时传递的限制 | 企业和托管设置 | Managed | +| [`permissionExplainerEnabled`](#permissionexplainerenabled) | 在 v2.1.257 中删除，以及 shell 权限提示上的 `Ctrl+E` 命令说明 | 全局配置设置 | Global config | +| [`permissions`](#permissions) | 设置允许、询问和拒绝规则以及启动[权限模式](/docs/zh-CN/permission-modes) | 权限设置 | Any file | +| [`permissions.additionalDirectories`](#permissions-additionaldirectories) | 给予 Claude 文件访问权限到[当前目录外的目录](/docs/zh-CN/permissions#working-directories) | 权限设置 | Any file | +| [`permissions.allow`](#permissions-allow) | 批准列出的[工具使用](/docs/zh-CN/permissions#permission-rule-syntax)而无需提示 | 权限设置 | Any file | +| [`permissions.ask`](#permissions-ask) | 始终在列出的[工具使用](/docs/zh-CN/permissions#permission-rule-syntax)之前提示 | 权限设置 | Any file | +| [`permissions.blockReadsOutsideWorkingDirectories`](#permissions-blockreadsoutsideworkingdirectories) | 使文件工具在每个权限模式下拒绝在[工作目录](/docs/zh-CN/permissions#working-directories)外的读取 | 权限设置 | Any file | +| [`permissions.defaultMode`](#permissions-defaultmode) | 设置新会话启动的[权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in) | 权限设置 | Any file | +| [`permissions.deny`](#permissions-deny) | 阻止列出的[工具使用](/docs/zh-CN/permissions#permission-rule-syntax)，包括保存秘密的文件的读取 | 权限设置 | Any file | +| [`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) | 防止任何人进入 [bypassPermissions 模式](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode) | 权限设置 | Any file | +| [`plansDirectory`](#plansdirectory) | 选择[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)写入计划文件的位置 | 内存和上下文 | Any file | +| [`pluginConfigs`](#pluginconfigs) | 存储您给[插件](/docs/zh-CN/plugins)的配置对话框的答案 | 插件和技能 | User or managed | +| [`pluginSuggestionMarketplaces`](#pluginsuggestionmarketplaces) | 选择哪些[市场](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions)可以在 `/plugin` 中显示插件安装建议 | 插件和技能 | Managed | +| [`pluginTrustMessage`](#plugintrustmessage) | 向[插件](/docs/zh-CN/plugins)信任警告添加您自己的文本 | 插件和技能 | Managed | +| [`policyHelper`](#policyhelper) | 运行在启动时计算[托管设置](/docs/zh-CN/managed-settings#compute-the-policy-with-a-helper-program)的可执行文件 | 企业和托管设置 | Managed | +| [`policyHelper.path`](#policyhelper-path) | 命名 Claude Code 运行的[辅助可执行文件](/docs/zh-CN/managed-settings#compute-the-policy-with-a-helper-program) | 企业和托管设置 | Managed | +| [`policyHelper.refreshIntervalMs`](#policyhelper-refreshintervalms) | 在后台按间隔重新运行[辅助程序](/docs/zh-CN/managed-settings#compute-the-policy-with-a-helper-program) | 企业和托管设置 | Managed | +| [`policyHelper.timeoutMs`](#policyhelper-timeoutms) | 设置 Claude Code 等待[辅助程序](/docs/zh-CN/managed-settings#compute-the-policy-with-a-helper-program)的时间 | 企业和托管设置 | Managed | +| [`preferredNotifChannel`](#preferrednotifchannel) | 为任务完成选择[终端铃声或桌面通知](/docs/zh-CN/terminal-config#get-a-terminal-bell-or-notification) | 远程、桌面和通知 | Any file | +| [`prefersReducedMotion`](#prefersreducedmotion) | [减少或关闭](/docs/zh-CN/accessibility#accessibility-settings)旋转、闪烁和闪光动画 | 界面和终端 | Any file | +| [`processWrapper`](#processwrapper) | 在 macOS 和 Linux 上通过[企业启动器](/docs/zh-CN/corporate-launcher)运行 Claude Code 的后台进程 | 代理、会话和工作树 | User or managed | +| [`promptCacheTtl`](#promptcachettl) | 为主对话选择[提示缓存生命周期](/docs/zh-CN/prompt-caching#cache-lifetime) | 模型和响应 | Any file | +| [`promptSuggestionEnabled`](#promptsuggestionenabled) | 隐藏输入框中灰显的[提示建议](/docs/zh-CN/interactive-mode#prompt-suggestions) | 界面和终端 | Any file | +| [`prUrlTemplate`](#prurltemplate) | 将 PR 链接指向内部代码审查工具而不是 github.com | Git 和属性 | Any file | +| [`remote.defaultEnvironmentId`](#remote-defaultenvironmentid) | 为 `claude --cloud` 选择默认的[云环境](/docs/zh-CN/cloud-environments)；自托管 `ccpool_` ID 仅从用户和托管设置以及 `--settings` 读取 | 远程、桌面和通知 | Any file | +| [`remoteControlAtStartup`](#remotecontrolatstartup) | 当会话启动时自动连接[远程控制](/docs/zh-CN/remote-control#enable-remote-control-for-all-sessions) | 远程、桌面和通知 | Any file | +| [`requiredMaximumVersion`](#requiredmaximumversion) | [拒绝在](/docs/zh-CN/setup#pin-a-minimum-version)您的组织允许的版本更新的版本上启动 | 更新和版本控制 | Managed | +| [`requiredMinimumVersion`](#requiredminimumversion) | [拒绝在](/docs/zh-CN/setup#pin-a-minimum-version)您的组织要求的版本更旧的版本上启动 | 更新和版本控制 | Managed | +| [`respectGitignore`](#respectgitignore) | 将 gitignored 文件保留在 [`@` 文件选择器](/docs/zh-CN/interactive-mode#quick-commands)之外 | 界面和终端 | Any file | +| [`respondToBashCommands`](#respondtobashcommands) | 停止 Claude 在 [`!` shell 命令](/docs/zh-CN/interactive-mode#shell-mode-with-prefix)运行后响应 | 界面和终端 | Any file | +| [`sandbox`](#sandbox) | 在 macOS、Linux 和 WSL2 上[隔离 Bash 命令](/docs/zh-CN/sandboxing)与您的文件系统和网络 | 沙箱设置 | Any file | +| [`sandbox.allowAppleEvents`](#sandbox-allowappleevents) | 让[沙箱化](/docs/zh-CN/sandboxing)命令在 macOS 上发送 Apple Events | 沙箱设置 | User or managed | +| [`sandbox.allowUnsandboxedCommands`](#sandbox-allowunsandboxedcommands) | 让 Claude 在[沙箱](/docs/zh-CN/sandboxing#the-unsandboxed-retry-escape-hatch)外重试被阻止的命令，或禁止它 | 沙箱设置 | Any file | +| [`sandbox.autoAllowBashIfSandboxed`](#sandbox-autoallowbashifsandboxed) | 运行[沙箱化](/docs/zh-CN/sandboxing#auto-allow-mode)命令而无需权限提示 | 沙箱设置 | Any file | +| [`sandbox.bwrapPath`](#sandbox-bwrappath) | 将[沙箱](/docs/zh-CN/sandboxing)指向 `PATH` 外的 bubblewrap 二进制文件 | 沙箱设置 | Managed | +| [`sandbox.credentials`](#sandbox-credentials) | 在[沙箱](/docs/zh-CN/sandboxing#protect-credentials)内隐藏或掩盖凭证文件和变量 | 沙箱设置 | Any file | +| [`sandbox.credentials.allowPlaintextInject`](#sandbox-credentials-allowplaintextinject) | 让[掩盖的凭证](/docs/zh-CN/sandboxing#mask-credentials)到达受信任的测试网络上的纯 HTTP 服务 | 沙箱设置 | User or managed | +| [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs) | 将自定义命名的 AWS 密钥变量链接到一个凭证以进行[重新签名](/docs/zh-CN/sandboxing#re-sign-aws-requests) | 沙箱设置 | User or managed | +| [`sandbox.credentials.envVars`](#sandbox-credentials-envvars) | 在[沙箱](/docs/zh-CN/sandboxing#mask-environment-variables)内取消设置或掩盖环境变量 | 沙箱设置 | Any file | +| [`sandbox.credentials.files`](#sandbox-credentials-files) | 在[沙箱](/docs/zh-CN/sandboxing#mask-credential-files)内阻止或掩盖凭证文件的读取 | 沙箱设置 | Any file | +| [`sandbox.credentials.sigv4`](#sandbox-credentials-sigv4) | 选择流式传输、预签名或 [SigV4A AWS 请求](/docs/zh-CN/sandboxing#re-sign-aws-requests)是否失败或通过 | 沙箱设置 | User or managed | +| [`sandbox.enabled`](#sandbox-enabled) | 在 macOS、Linux 和 WSL2 上打开 [Bash 沙箱](/docs/zh-CN/sandboxing#get-started) | 沙箱设置 | Any file | +| [`sandbox.enableWeakerNestedSandbox`](#sandbox-enableweakernestedsandbox) | 在无特权容器内运行 Linux [沙箱](/docs/zh-CN/sandboxing) | 沙箱设置 | Any file | +| [`sandbox.enableWeakerNetworkIsolation`](#sandbox-enableweakernetworkisolation) | 让 `gh`、`gcloud` 和 `terraform` 在[沙箱](/docs/zh-CN/sandboxing#troubleshooting)内的 MITM 代理后面验证 TLS | 沙箱设置 | Any file | +| [`sandbox.excludedCommands`](#sandbox-excludedcommands) | 命名始终在[沙箱](/docs/zh-CN/sandboxing)外运行的命令 | 沙箱设置 | Any file | +| [`sandbox.failIfUnavailable`](#sandbox-failifunavailable) | 当[沙箱](/docs/zh-CN/sandboxing)无法启动时拒绝启动，而不是运行未沙箱化的 | 沙箱设置 | Any file | +| [`sandbox.filesystem`](#sandbox-filesystem) | 控制[沙箱化](/docs/zh-CN/sandboxing#filesystem-isolation)命令可以读写的路径 | 沙箱设置 | Any file | +| [`sandbox.filesystem.allowManagedReadPathsOnly`](#sandbox-filesystem-allowmanagedreadpathsonly) | 停止开发人员重新打开您的组织阻止的[读取路径](/docs/zh-CN/sandboxing#keep-developers-from-widening-the-policy) | 沙箱设置 | Managed | +| [`sandbox.filesystem.allowRead`](#sandbox-filesystem-allowread) | 重新打开在 [`denyRead`](#sandbox-filesystem-denyread) 阻止的区域内的读取 | 沙箱设置 | Any file | +| [`sandbox.filesystem.allowWrite`](#sandbox-filesystem-allowwrite) | 添加[沙箱化](/docs/zh-CN/sandboxing)命令可以写入的路径 | 沙箱设置 | Any file | +| [`sandbox.filesystem.denyRead`](#sandbox-filesystem-denyread) | 阻止[沙箱化](/docs/zh-CN/sandboxing)命令读取特定路径 | 沙箱设置 | Any file | +| [`sandbox.filesystem.denyWrite`](#sandbox-filesystem-denywrite) | 阻止[沙箱化](/docs/zh-CN/sandboxing)命令写入特定路径 | 沙箱设置 | Any file | +| [`sandbox.filesystem.disabled`](#sandbox-filesystem-disabled) | [关闭文件系统隔离](/docs/zh-CN/sandboxing#disable-filesystem-isolation)同时保持网络隔离 | 沙箱设置 | User or managed | +| [`sandbox.ignoreViolations`](#sandbox-ignoreviolations) | 沉默命令预期探测的路径的违规报告 | 沙箱设置 | Any file | +| [`sandbox.network`](#sandbox-network) | 控制[沙箱化](/docs/zh-CN/sandboxing#network-isolation)命令可以到达的主机、端口和套接字 | 沙箱设置 | Any file | +| [`sandbox.network.allowAllUnixSockets`](#sandbox-network-allowallunixsockets) | 让[沙箱化](/docs/zh-CN/sandboxing)命令连接到每个 Unix 套接字 | 沙箱设置 | Any file | +| [`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) | 预先允许域，以便[沙箱化](/docs/zh-CN/sandboxing)命令不会提示它们 | 沙箱设置 | Any file | +| [`sandbox.network.allowLocalBinding`](#sandbox-network-allowlocalbinding) | 让[沙箱化](/docs/zh-CN/sandboxing)命令在 macOS 上绑定到 localhost 端口 | 沙箱设置 | Any file | +| [`sandbox.network.allowMachLookup`](#sandbox-network-allowmachlookup) | 让 macOS [沙箱化](/docs/zh-CN/sandboxing)工具（如 iOS 模拟器或 Playwright）到达其 XPC 服务 | 沙箱设置 | Any file | +| [`sandbox.network.allowManagedDomainsOnly`](#sandbox-network-allowmanageddomainsonly) | 将网络允许列表锁定到[托管设置](/docs/zh-CN/sandboxing#keep-developers-from-widening-the-policy) | 沙箱设置 | Managed | +| [`sandbox.network.allowUnixSockets`](#sandbox-network-allowunixsockets) | 列出[沙箱化](/docs/zh-CN/sandboxing)命令可以在 macOS 上使用的 Unix 套接字路径 | 沙箱设置 | Any file | +| [`sandbox.network.deniedDomains`](#sandbox-network-denieddomains) | 为[沙箱化](/docs/zh-CN/sandboxing)命令阻止域，即使在允许的通配符内 | 沙箱设置 | Any file | +| [`sandbox.network.httpProxyPort`](#sandbox-network-httpproxyport) | 通过您自己的代理路由[沙箱](/docs/zh-CN/sandboxing#custom-proxy-configuration) HTTP 流量 | 沙箱设置 | Any file | +| [`sandbox.network.socksProxyPort`](#sandbox-network-socksproxyport) | 通过您自己的代理路由[沙箱](/docs/zh-CN/sandboxing#custom-proxy-configuration) SOCKS 流量 | 沙箱设置 | Any file | +| [`sandbox.network.strictAllowlist`](#sandbox-network-strictallowlist) | 拒绝[允许列表](/docs/zh-CN/sandboxing#network-isolation)外的主机，而不是提示 | 沙箱设置 | User or managed | +| [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) | 让[沙箱](/docs/zh-CN/sandboxing#network-isolation)代理终止 TLS，以便它可以读取 HTTPS 请求 | 沙箱设置 | User or managed | +| [`sandbox.ripgrep`](#sandbox-ripgrep) | 在[沙箱](/docs/zh-CN/sandboxing)内使用您自己的 ripgrep 二进制文件 | 沙箱设置 | User or managed | +| [`sandbox.socatPath`](#sandbox-socatpath) | 将[沙箱](/docs/zh-CN/sandboxing)代理指向 `PATH` 外的 `socat` 二进制文件 | 沙箱设置 | Managed | +| [`showClearContextOnPlanAccept`](#showclearcontextonplanaccept) | 在[计划接受屏幕](/docs/zh-CN/permission-modes#review-and-approve-a-plan)上显示"清除上下文"选项 | 界面和终端 | Any file | +| [`showThinkingSummaries`](#showthinkingsummaries) | 查看 Claude 的[思考](/docs/zh-CN/model-config#extended-thinking)摘要而不是折叠的存根 | 模型和响应 | Any file | +| [`showTurnDuration`](#showturnduration) | 隐藏每个响应后的"烹饪"持续时间 | 界面和终端 | Any file | +| [`skillListingBudgetFraction`](#skilllistingbudgetfraction) | 为[技能列表](/docs/zh-CN/skills#skill-descriptions-are-cut-short)保留更多或更少的上下文 | 内存和上下文 | Any file | +| [`skillListingMaxDescChars`](#skilllistingmaxdescchars) | 在[技能列表](/docs/zh-CN/skills#skill-descriptions-are-cut-short)中限制每个技能的描述长度 | 内存和上下文 | Any file | +| [`skillOverrides`](#skilloverrides) | [隐藏或折叠技能](/docs/zh-CN/skills#override-skill-visibility-from-settings)而无需编辑其 SKILL.md | 插件和技能 | Any file | +| [`skipAutoPermissionPrompt`](#skipautopermissionprompt) | 跳过 Claude Code 在您自己进入[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)而不是通过内置默认值时显示的一次性通知 | 权限设置 | User or managed | +| [`skipDangerousModePermissionPrompt`](#skipdangerousmodepermissionprompt) | 在[bypassPermissions 模式](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)之前跳过确认对话 | 权限设置 | User, local, or managed | +| [`skipWebFetchPreflight`](#skipwebfetchpreflight) | 当 Anthropic 无法到达时跳过 [WebFetch 主机名检查](/docs/zh-CN/tools-reference#webfetch-tool-behavior) | 隐私和遥测 | Any file | +| [`spellcheck`](#spellcheck) | 在提示输入中用您安装的[拼写检查器](/docs/zh-CN/interactive-mode#check-spelling-as-you-type)为拼写错误的单词加下划线 | 界面和终端 | User or managed | +| [`spinnerTipsEnabled`](#spinnertipsenabled) | 在 Claude 工作时隐藏旋转器中的提示 | 界面和终端 | Any file | +| [`spinnerTipsOverride`](#spinnertipsoverride) | 向旋转器轮换添加您自己的提示，或替换内置提示 | 界面和终端 | Any file | +| [`spinnerVerbs`](#spinnerverbs) | 添加或替换在转弯运行时显示的动词 | 界面和终端 | Any file | +| [`sshConfigs`](#sshconfigs) | 将 [SSH 连接](/docs/zh-CN/desktop#pre-configure-ssh-connections-for-your-team)添加到桌面环境下拉列表 | 远程、桌面和通知 | User or managed | +| [`sshHostAllowlist`](#sshhostallowlist) | 限制[桌面 SSH 会话](/docs/zh-CN/desktop#restrict-which-ssh-hosts-users-can-connect-to)可以到达的主机 | 远程、桌面和通知 | Managed | +| [`statusLine`](#statusline) | 运行您自己的命令来呈现提示下方的[状态行](/docs/zh-CN/statusline) | 界面和终端 | Any file | +| [`strictKnownMarketplaces`](#strictknownmarketplaces) | 允许列表用户可以添加和安装的[市场](/docs/zh-CN/plugin-marketplaces)来源 | 插件和技能 | Managed | +| [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | 阻止[技能](/docs/zh-CN/skills)、[代理](/docs/zh-CN/sub-agents)、[hooks](/docs/zh-CN/hooks) 和 [MCP 服务器](/docs/zh-CN/mcp)来自用户和项目来源 | 插件和技能 | Managed | +| [`strictPluginOnlyCustomization.agents`](#strictpluginonlycustomization-agents) | 将[代理](/docs/zh-CN/sub-agents)锁定到插件和托管来源 | 插件和技能 | Managed | +| [`strictPluginOnlyCustomization.hooks`](#strictpluginonlycustomization-hooks) | 将[hooks](/docs/zh-CN/hooks)锁定到插件和托管来源 | 插件和技能 | Managed | +| [`strictPluginOnlyCustomization.mcp`](#strictpluginonlycustomization-mcp) | 将 [MCP 服务器](/docs/zh-CN/mcp)锁定到插件和托管来源 | 插件和技能 | Managed | +| [`strictPluginOnlyCustomization.skills`](#strictpluginonlycustomization-skills) | 将[技能](/docs/zh-CN/skills)锁定到插件和托管来源 | 插件和技能 | Managed | +| [`subagentPromptCacheTtl`](#subagentpromptcachettl) | 为子代理和主对话外的其他请求选择[提示缓存生命周期](/docs/zh-CN/prompt-caching#cache-lifetime) | 模型和响应 | Any file | +| [`subagentStatusLine`](#subagentstatusline) | 使用您自己的命令重写[子代理](/docs/zh-CN/sub-agents)任务显示中的行 | 界面和终端 | Any file | +| [`switchModelsOnFlag`](#switchmodelsonflag) | 当[安全分类器](/docs/zh-CN/model-config#ask-before-switching)标记请求时自动切换模型或暂停 | 模型和响应 | Any file | +| [`syncClaudeAiSkills`](#syncclaudeaiskills) | 停止下载[在您的 claude.ai 帐户上启用的技能](/docs/zh-CN/skills#how-synced-skills-behave)并隐藏已同步的技能 | 插件和技能 | User, local, or managed | +| [`syntaxHighlightingDisabled`](#syntaxhighlightingdisabled) | 关闭 diffs 和代码块中的语法突出显示 | 界面和终端 | Any file | +| [`taskOutputMaxChars`](#taskoutputmaxchars) | 设置[后台任务](/docs/zh-CN/tools-reference#background-commands)的输出有多少 Claude 内联接收 | 内存和上下文 | Any file | +| [`teammateDefaultModel`](#teammatedefaultmodel) | 在 v2.1.234 中删除；请参阅[指定队友和模型](/docs/zh-CN/agent-teams#specify-teammates-and-models)了解 Claude Code 如何选择队友的模型 | 全局配置设置 | Global config | +| [`teammateMode`](#teammatemode) | 选择[代理团队队友显示](/docs/zh-CN/agent-teams#choose-a-display-mode)的方式 | 代理、会话和工作树 | Any file | +| [`terminalProgressBarEnabled`](#terminalprogressbarenabled) | 在支持它的终端中隐藏终端进度条 | 界面和终端 | Any file | +| [`terminalTitleFromRename`](#terminaltitlefromrename) | 停止 [`/rename`](/docs/zh-CN/sessions#name-your-sessions) 和 `--name` 更改终端选项卡标题 | 界面和终端 | Any file | +| [`theme`](#theme) | 选择界面[颜色主题](/docs/zh-CN/terminal-config#match-the-color-theme)，内置或自定义 | 界面和终端 | Any file | +| [`timeFormat`](#timeformat) | 在 12 小时或 24 小时制、UTC 或 strftime 模式下显示界面中的时间 | 界面和终端 | Any file | +| [`timeZone`](#timezone) | 在时区而不是系统时区显示界面中的时间 | 界面和终端 | Any file | +| [`tui`](#tui) | 选择[全屏](/docs/zh-CN/fullscreen)或经典终端渲染器 | 界面和终端 | Any file | +| [`ultracode`](#ultracode) | 让 Claude 为每个实质性任务规划[工作流](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)而无需被要求 | 模型和响应 | Any file | +| [`useAutoModeDuringPlan`](#useautomodeduringplan) | 让[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器在[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)中审查 shell 命令；设置 `false` 以获取提示 | 权限设置 | User, local, or managed | +| [`verbose`](#verbose) | 显示[完整工具输出](/docs/zh-CN/cli-reference#cli-flags)而不是截断的摘要；当两者都设置时 `viewMode` 优先 | 界面和终端 | Any file | +| [`viewMode`](#viewmode) | 在[默认、详细或焦点视图](/docs/zh-CN/cli-reference#cli-flags)中启动每个会话 | 界面和终端 | Any file | +| [`vimInsertModeRemaps`](#viminsertmoderemaps) | 将两键 [INSERT 模式序列](/docs/zh-CN/interactive-mode#remap-insert-mode-key-sequences)（如 `jj`）映射到 Escape | 界面和终端 | User or managed | +| [`voice`](#voice) | 打开[语音听写](/docs/zh-CN/voice-dictation)并选择按住或点击模式 | 界面和终端 | Any file | +| [`voiceEnabled`](#voiceenabled) | 使用较旧的单键形式打开[语音听写](/docs/zh-CN/voice-dictation) | 界面和终端 | Any file | +| [`wheelScrollAccelerationEnabled`](#wheelscrollaccelerationenabled) | 在全屏渲染中关闭[鼠标滚轮加速](/docs/zh-CN/fullscreen#mouse-wheel-scrolling) | 界面和终端 | Any file | +| [`workflowKeywordTriggerEnabled`](#workflowkeywordtriggerenabled) | 让提示中的单词 `ultracode` 启动[工作流](/docs/zh-CN/workflows)；设置 `false` 以在不启动的情况下键入它 | Hooks 和自动化 | Any file | +| [`workflowSizeGuideline`](#workflowsizeguideline) | 设置 Claude 在[动态工作流](/docs/zh-CN/workflows)中的目标代理数 | Hooks 和自动化 | Any file | +| [`worktree`](#worktree) | 配置 Claude Code 如何创建 git [worktrees](/docs/zh-CN/worktrees) | 代理、会话和工作树 | Any file | +| [`worktree.baseRef`](#worktree-baseref) | 从远程默认分支或本地 HEAD 分支新[worktrees](/docs/zh-CN/worktrees) | 代理、会话和工作树 | Any file | +| [`worktree.bgIsolation`](#worktree-bgisolation) | 让后台会话编辑工作副本而无需[worktree](/docs/zh-CN/worktrees) | 代理、会话和工作树 | Any file | +| [`worktree.sparsePaths`](#worktree-sparsepaths) | 在每个[worktree](/docs/zh-CN/worktrees)中仅检出您需要的目录 | 代理、会话和工作树 | Any file | +| [`worktree.symlinkDirectories`](#worktree-symlinkdirectories) | 将大型目录符号链接到每个[worktree](/docs/zh-CN/worktrees)中，而不是复制它们 | 代理、会话和工作树 | Any file | +| [`wslInheritsWindowsSettings`](#wslinheritswindowssettings) | 让 WSL 从 Windows 策略链读取[托管设置](/docs/zh-CN/managed-settings) | 企业和托管设置 | Managed | + +

+ 模型和响应 +

+ +选择 Claude Code 使用的模型以及它如何响应。关于这些设置如何与 `/model` 命令和环境变量交互，请参阅[模型配置](/docs/zh-CN/model-config)。 + +

+ `advisorModel` +

+ +选择当 Claude 调用服务器端[顾问工具](/docs/zh-CN/advisor)时哪个模型来回答。取消设置它以关闭顾问。顾问的能力必须至少与您的主模型一样强；当它不是时，Claude Code 会发送不带顾问的请求。请参阅[选择顾问模型](/docs/zh-CN/advisor#choose-an-advisor-model)。 + +您通常不会手动编辑此键。运行 `/advisor` 以打开一个选择器，显示当前选择、可以提供建议的模型和**无顾问**。Claude Code 将您的选择保存到 `~/.claude/settings.json` 中的此键。如果您从[远程控制](/docs/zh-CN/remote-control)客户端或附加到远程工作者的会话中选择，该选择仅适用于该会话，不会更改此键。 + +如果您的账户需要[使用额度同意](/docs/zh-CN/advisor#fable-advisor-and-usage-credits)，请先通过运行 `/model fable` 来接受它。在您这样做之前，在 `/advisor` 中选择 Fable 不会保存任何内容，Claude Code 会告诉您先运行 `/model fable`。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 字符串，别名之一 `"fable"`、`"opus"` 或 `"sonnet"`，它们解析为 Claude Code 当前该模型系列的默认版本，或完整模型 ID，如 `"claude-opus-5"` +* **默认值**: 未设置，因此顾问已关闭 +* **每会话覆盖**: `--advisor` 对此键的优先级更高，适用于一个会话。[`CLAUDE_CODE_DISABLE_ADVISOR_TOOL`](/docs/zh-CN/env-vars) 关闭顾问，此键无法将其重新打开 + +```json settings.json theme={null} +{ + "advisorModel": "opus" +} +``` + +该键对顾问[不可用](/docs/zh-CN/advisor#requirements)的提供商（如 Amazon Bedrock 和 AWS 上的 Claude Platform）没有影响。`"fable"` 需要[Fable 访问权限](/docs/zh-CN/advisor#choose-an-advisor-model)。 + +

+ `alwaysThinkingEnabled` +

+ +通过将其设置为 `false` 来为每个会话关闭[扩展思考](/docs/zh-CN/model-config#extended-thinking)。默认情况下思考是打开的，所以 `true` 不会改变任何内容。大多数人通过 `/config` 而不是编辑文件来设置这个。 + +在始终思考的模型上，例如 Fable 模型，`false` 没有效果。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，Claude Code 省略 `thinking` 参数而不是关闭思考，因此自适应推理模型可能仍然会思考。在 Anthropic API 上关闭思考时，Claude Code 会向它知道[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型（如 Opus 5）发送努力 `high` 而不是更高级别。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 布尔值 + * `true`: 无效果；思考已经打开 + * `false`: Claude Code 为每个会话关闭扩展思考 +* **默认值**: 未设置，因此对支持它的模型思考已打开 +* **每会话覆盖**: [`MAX_THINKING_TOKENS`](/docs/zh-CN/env-vars) 对此键的优先级更高，适用于一个会话：`0` 关闭思考，受相同的模型和提供商限制如 `false`，正值打开思考，即使此键是 `false`。在自适应推理模型上，数字本身被忽略 + +```json settings.json theme={null} +{ + "alwaysThinkingEnabled": false +} +``` + +

+ `availableModels` +

+ +限制人们可以为主会话、[子代理](/docs/zh-CN/sub-agents)、[技能](/docs/zh-CN/skills)和[顾问](/docs/zh-CN/advisor)选择的模型。托管列表限制 `/model`、`--model` 和开发者自己文件中的 `model` 键；列表外的模型无法选择。单独来说，这不会触及默认选项；将其与 [`enforceAvailableModels`](#enforceavailablemodels) 配对以实现这一点。 + +* **范围**: [`任何文件`](#scopes)。在托管设置中部署它以为组织强制执行。 +* **类型**: 模型别名或 ID 的数组 +* **默认值**: 未设置，因此每个模型都可用 + +此示例仅允许人们选择 Sonnet 和 Haiku 模型： + +```json settings.json theme={null} +{ + "availableModels": ["sonnet", "haiku"] +} +``` + +请参阅[限制模型选择](/docs/zh-CN/model-config#restrict-model-selection)。 + +

+ `effortLevel` +

+ +为您尚未保存级别的模型设置默认[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。较低的级别在直接任务上更快且更便宜，较高的级别在复杂问题上推理更深入。 + +当您在您的机器上的交互式会话中运行 `/effort low`、`medium`、`high` 或 `xhigh` 时，Claude Code 将该级别保存到 [`modelSettings`](#modelsettings) 下的活动模型，而不是写入此键。在 v2.1.251 之前，`/effort` 写入此键。 + +在同一设置文件中，Claude Code 使用模型的保存级别而不是此键。[`modelSettings`](#modelsettings) 说明跨文件优先级。 + +在附加到远程工作者的会话中，`/effort` 仅适用于该会话。在 `-p` 运行或 Agent SDK 中，它也仅适用于该会话，[除非对模型的默认努力有保留](/docs/zh-CN/model-config#non-interactive-effort)。[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level)列出也仅适用于该会话的交互式选择。`/effort` 打印的消息说明发生了什么。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 字符串，之一： + * `"low"`: 最少推理，用于短的、有范围的、延迟敏感的、不是智能敏感的任务 + * `"medium"`: 减少成本敏感工作的令牌使用，可以权衡一些智能 + * `"high"`: 平衡令牌使用和智能 + * `"xhigh"`: 更深入的推理，更高的令牌支出 +* **默认值**: 未设置 +* **每会话覆盖**: `--effort` 对此键的优先级更高，适用于一个会话，[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars) 对两者的优先级都更高 + +```json settings.json theme={null} +{ + "effortLevel": "xhigh" +} +``` + +在 Opus 4.7、Opus 4.8 和 Fable 5 上，Claude Code 保留该模型的默认努力，组织设置或内置；[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level)说明哪些设置级别的方式结束保留，哪些保留它。一旦保留结束，Claude Code 通过 [`modelSettings`](#modelsettings) 中说明的优先级解析努力。 + +

+ `enforceAvailableModels` +

+ +`/model` 选择器有一个**默认**选项，当适用时解析为您的[组织默认模型](/docs/zh-CN/model-config#organization-default-model)，否则解析为您的账户类型的默认值。[`availableModels`](#availablemodels) 允许列表限制您可以命名的模型，但单独来说它保留**默认**不变，因此**默认**仍然可以解析为列表外的模型。此键关闭了该漏洞。需要 Claude Code v2.1.175 或更高版本。 + +当您的组织部署任何托管设置时，Claude Code 仅从托管源读取此键，并在您的其他文件中忽略它。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 布尔值 + * `true`: 当**默认**会解析为 `availableModels` 外的模型时，Claude Code 将其解析为列表中第一个可用的模型 + * `false`: **默认**照常解析，即使是列表外的模型 +* **默认值**: `false` + +此示例将命名选择限制为 Sonnet 和 Haiku 模型，并使**默认**解析为其中第一个可用的： + +```json settings.json theme={null} +{ + "availableModels": ["sonnet", "haiku"], + "enforceAvailableModels": true +} +``` + +当 `availableModels` 未设置或为空时，此键没有效果。请参阅[为默认模型强制执行允许列表](/docs/zh-CN/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更高版本。 + +

+ `fallbackModel` +

+ +命名备用模型供 Claude Code 在您的主模型过载或不可用时按顺序尝试。Claude Code 切换到链中下一个可用的模型以完成该轮，并显示通知。没有链的情况下，Claude Code 重试同一模型，然后显示服务器的错误，您重试或自己切换模型。 + +切换意味着在备用模型上进行一轮冷[提示缓存](/docs/zh-CN/prompt-caching#switching-models)；您的下一条消息首先再次尝试主模型。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 模型别名或 ID 的数组；`"default"` 扩展为默认模型 +* **默认值**: 未设置，因此失败的请求不会在另一个模型上重试 +* **每会话覆盖**: `--fallback-model` 对此键的优先级更高，适用于一个会话 + +此示例在您的主模型失败时首先尝试 Sonnet 5，然后尝试 Haiku 4.5： + +```json settings.json theme={null} +{ + "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"] +} +``` + +与大多数数组设置不同，此键不会跨设置文件合并：最高优先级的定义它的文件提供整个链。如果您的项目文件设置 `["claude-sonnet-5"]` 而您的用户文件设置 `["claude-haiku-4-5"]`，链是 `["claude-sonnet-5"]` 仅。Claude Code 从列表中最多保留三个不同的允许模型，忽略其余的。请参阅[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)。 + +

+ `fastMode` +

+ +为可用的会话打开[快速模式](/docs/zh-CN/fast-mode)，用于交互式工作，如快速迭代或实时调试，您希望以更高的每令牌成本获得速度。您通常不会手动编辑此键：运行 `/fast` 将 `fastMode: true` 写入 `~/.claude/settings.json`，再次运行它以关闭快速模式会删除该键。快速模式仅在 Opus 5 和 Opus 4.8 上运行：从另一个模型打开它会切换您到 Opus，切换到不支持的模型会关闭它。请参阅[在快速模式打开时切换模型](/docs/zh-CN/fast-mode#switch-models-while-fast-mode-is-on)。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 布尔值 + * `true`: Claude Code 为可用的会话打开快速模式 + * `false`: 快速模式保持关闭 +* **默认值**: 未设置，因此快速模式已关闭 +* **每会话覆盖**: [`CLAUDE_CODE_DISABLE_FAST_MODE`](/docs/zh-CN/env-vars) 为一个会话关闭快速模式，此键无法将其重新打开 + +```json settings.json theme={null} +{ + "fastMode": true +} +``` + +

+ `fastModePerSessionOptIn` +

+ +通常，运行 `/fast` 将 [`fastMode`](#fastmode) 保存到一个人的用户设置，因此快速模式在之后每个会话的开始时打开。将此键设置为 `true` 以停止这种情况：保存的 `fastMode: true` 不再在会话开始时打开快速模式，每个人必须在他们想要它的每个会话中运行 `/fast`。Claude Code 在他们的文件中保留 `fastMode` 键，因此关闭此键会恢复旧行为。Team 或 Enterprise 计划的所有者可以通过[服务器托管设置](/docs/zh-CN/server-managed-settings)在组织范围内部署它。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 布尔值 + * `true`: 保存的 `fastMode: true` 不再在会话开始时打开快速模式，因此每个人在他们想要它的每个会话中运行 `/fast`；与 `--settings` 一起传递的 `fastMode: true` 仍然对该会话计数，除非托管设置设置此键 + * `false`: 保存的 `fastMode: true` 在之后每个会话的开始时打开快速模式 +* **默认值**: `false` + +```json settings.json theme={null} +{ + "fastModePerSessionOptIn": true +} +``` + +请参阅[需要每会话选择加入](/docs/zh-CN/fast-mode#require-per-session-opt-in)。 + +

+ `language` +

+ +默认情况下让 Claude 用英语以外的语言响应。响应没有固定列表：Claude Code 将值逐字添加到系统提示中，作为始终用该语言响应的指令，因此任何 Claude 可以读取的语言名称都有效。Claude Code 不检查该值，因此拼写错误的名称按原样到达 Claude，而不是产生错误。相同的值为[语音听写](/docs/zh-CN/voice-dictation#change-the-dictation-language)设置语言，它有一个固定的[支持的听写语言](/docs/zh-CN/voice-dictation#change-the-dictation-language)列表，以及自动生成的会话标题。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 字符串，任何语言名称，如 `"japanese"`、`"spanish"` 或 `"french"`；Claude Code 不验证它 +* **默认值**: 未设置；会话标题然后匹配您的对话语言 + +```json settings.json theme={null} +{ + "language": "japanese" +} +``` + +

+ `maxEffortLevel` +

+ +限制[努力级别](/docs/zh-CN/model-config#adjust-effort-level)会话可以使用，保留较低的级别可用。任何更高的级别都在上限处运行，包括来自 `/effort`、`/model` 选择器、`--effort`、[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars)、技能或子代理的 `effort` frontmatter 或模型自己的默认值。Claude Code 在每个请求之前应用上限本身，因此它在每个提供商上保留，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry。需要 Claude Code v2.1.267 或更高版本。 + +* **范围**: [`任何文件`](#scopes)。在托管设置中部署它以为组织强制执行。当多个范围设置上限时，最低的适用，因此在一个范围中设置的上限无法从另一个范围提高 +* **类型**: 字符串，之一 `"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。`"max"` 值不设置上限 +* **默认值**: 未设置，因此不适用上限 +* **对 ultracode 的影响**: 低于 `xhigh` 的上限使[ultracode](#ultracode)在上限适用的模型上不可用 +* **每模型上限**: 将 `maxEffortLevel` 添加到模型的 [`modelSettings`](#modelsettings) 条目。该条目仅在设置源（如您的用户设置或一个[托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)）中同时设置两者的范围内替换此键。在那里设置 `"max"` 以豁免该模型免受该源的上限；Claude Code 仍然应用来自其他源的上限 + +此示例将每个模型限制在 `medium`，并豁免 Sonnet 4.6： + +```json settings.json theme={null} +{ + "maxEffortLevel": "medium", + "modelSettings": { + "claude-sonnet-4-6": { + "maxEffortLevel": "max" + } + } +} +``` + +当您的组织也为模型设置[努力限制](/docs/zh-CN/model-config#organization-effort-limits)时，两个上限中较低的适用。 + +

+ `model` +

+ +设置每个新会话使用的模型，因此您不必每次都用 `/model` 选择一个。在此处设置它不会阻止您在会话中期切换。如果您的管理员设置了[组织默认模型](/docs/zh-CN/model-config#organization-default-model)以覆盖用户选择，即使您在用户、项目或本地设置中设置此键，您也会获得该模型。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 字符串，模型别名或完整模型 ID +* **默认值**: 未设置，因此 Claude Code 使用您账户的默认模型 +* **每会话覆盖**: `--model` 对 [`ANTHROPIC_MODEL`](/docs/zh-CN/env-vars) 的优先级更高，两者对此键的优先级都更高，适用于一个会话，包括对托管 `model`；[`availableModels`](#availablemodels) 列表仍然适用于选择 + +```json settings.json theme={null} +{ + "model": "claude-sonnet-5" +} +``` + +此处的值优先于 [`ANTHROPIC_DEFAULT_MODEL`](/docs/zh-CN/model-config#set-a-default-model-for-new-sessions)，Claude Code 仅在没有其他内容选择模型时使用。 + +

+ `modelOverrides` +

+ +将 Anthropic 模型 ID 映射到提供商特定的模型 ID，如 Amazon Bedrock 推理配置文件 ARN。然后每个模型选择器条目在调用提供商 API 时使用其映射值。管理员在[Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-CN/model-config#override-model-ids-per-version)上使用这个来将每个模型版本路由到特定的推理配置文件、版本名称或部署，以实现治理、成本分配或区域路由。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 将模型 ID 映射到提供商模型 ID 的对象 +* **默认值**: 未设置 + +此示例将 Opus 4.6 的每个调用路由到命名的 Bedrock 推理配置文件： + +```json settings.json theme={null} +{ + "modelOverrides": { + "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456789012:inference-profile/example" + } +} +``` + +请参阅[按版本覆盖模型 ID](/docs/zh-CN/model-config#override-model-ids-per-version)。 + +

+ `modelPicker` +

+ +列出 `/model` 选择器提供的模型，按您写入它们的顺序和您选择的标签下，因此选择器列出您的组织运行的模型，在内置阵容之后或代替它。每行的 `model` 逐字获取，因此它接受 `--model` 接受的任何内容：别名如 `opus`、Anthropic 模型 ID 或 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 网关的提供商格式 ID。需要 Claude Code v2.1.242 或更高版本。 + +* **范围**: [`用户或托管`](#scopes)。Claude Code 从托管设置、`--settings` 和用户设置读取键，并在项目和本地设置中忽略它，因此您克隆的存储库无法重新标记选择器。这三个中最高的设置键的提供整个阵容，Claude Code 从不合并来自两个源的阵容。 +* **类型**: 具有 `options` 数组的行和可选 `replaceBuiltInOptions` 布尔值的对象 +* **默认值**: 未设置，因此选择器显示内置阵容 + +此示例在内置阵容之后添加两个 Bedrock 部署，在您的团队识别的名称下： + +```json managed-settings.json theme={null} +{ + "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" + } + ] + } +} +``` + + + + + +

+ `modelPicker` 的字段 +

+ +该键采用两个字段，一个用于行本身，一个用于它们是替换内置阵容还是添加到它。 + +| 字段 | 类型 | 它做什么 | +| :---------------------- | :------------------------------------------------ | :--------------------------------------------------------------------------------------------------- | +| `options` | 行的数组，每个都有必需的 `model` 和可选的 `label` 和 `description` | 选择器显示的行，按此顺序，除了灰显的行移到底部。没有 `label`，Claude Code 用它知道的模型的内置名称标记行，或模型 ID 否则，没有 `description` 它写一个通用的第二行 | +| `replaceBuiltInOptions` | 布尔值，默认 `false` | 将其设置为 `true` 以仅显示这些行、**默认**和会话已在使用的模型的行。保留未设置以在内置阵容之后添加这些行 | + +打开 `replaceBuiltInOptions` 时，Claude Code 隐藏每个其他行：内置阵容、它为 [`availableModels`](#availablemodels) 条目添加的行、[网关发现](/docs/zh-CN/llm-gateway-protocol#model-discovery)找到的模型和 [`ANTHROPIC_CUSTOM_MODEL_OPTION`](/docs/zh-CN/model-config#add-a-custom-model-option)。关闭时，Claude Code 跳过内置阵容已覆盖的列出的模型。标签改变选择器显示的内容，而不是 Claude Code 运行的模型。 + +[`availableModels`](#availablemodels) 允许列表仍然适用于这些行。在将列出的模型添加到允许列表之前，请阅读[合并行为](/docs/zh-CN/model-config#merge-behavior)：特定模型 ID 缩小其系列的通配符条目。Claude Code 还在显示选择器之前检查每行与会话： + +* **删除**: Claude Code 无法提供的行，如已停用的模型或您的组织无权访问的模型 +* **灰显**: 您还无法选择的行，显示原因 +* **没有行存活**: Claude Code 保留内置阵容，按允许列表过滤如常 + +Claude Code 删除它无法解析的行并保留其余的。请参阅[修复损坏的设置文件](/docs/zh-CN/settings#fix-a-broken-settings-file)。 + +

+ `modelPricing` +

+ +按您的组织支付的费率而不是列表价格报告支出。当您的组织有合同费率时设置它，因此开发者看到的美元数字与您的账单匹配。Claude Code 在 `/usage`、[状态行](/docs/zh-CN/statusline)、Agent SDK 的 `total_cost_usd`、[`--max-budget-usd`](/docs/zh-CN/cli-reference) 限制和[OpenTelemetry](/docs/zh-CN/monitoring-usage) 成本指标和事件中应用费率。您提供费率：Claude Code 不从您的合同或 Claude 控制台读取它们。需要 Claude Code v2.1.242 或更高版本。 + +* **范围**: [`托管`](#scopes)。通过服务器托管设置、MDM 策略、`managed-settings.json` 文件或[策略助手](/docs/zh-CN/managed-settings#compute-the-policy-with-a-helper-program)部署键。Claude Code 在用户、项目和本地设置中忽略它，在 `--settings` 中，以及在 Windows 中的用户可写[HKCU 注册表](/docs/zh-CN/managed-settings#where-each-mechanism-stores-the-policy)中。使用服务器托管设置，每个会话以列表价格报告成本，直到该会话的[设置获取](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)已确认设置。嵌入 Claude Code 并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的主机应用程序可以通过 SDK [`managedSettings`](/docs/zh-CN/agent-sdk/typescript#options) 选项提供自己的表，Claude Code 仅在没有托管源设置键时使用，仅在 Claude Code v2.1.246 或更高版本中。 +* **类型**: 具有可选 `multiplier` 和可选 `overrides` 映射的对象 +* **默认值**: 未设置，因此 Claude Code 报告列表价格，除非主机应用程序提供表 + +此示例为 Sonnet 4.6 设置合同费率，然后将每个数字减少 15%，包括 Sonnet 行。单独设置 `multiplier` 以获得统一折扣，单独设置 `overrides` 以获得每模型费率，或两者： + +```json managed-settings.json theme={null} +{ + "modelPricing": { + "multiplier": 0.85, + "overrides": { + "claude-sonnet-4-6": { + "input": 2.4, + "output": 12, + "cacheRead": 0.24, + "cacheWrite": 3 + } + } + } +} +``` + +有关步骤，包括如何确认费率有效，请参阅[按您的合同费率报告支出](/docs/zh-CN/costs#report-spend-at-your-contracted-rates)。 + + + + + +

+ `modelPricing` 的字段 +

+ +| 字段 | 类型 | 它做什么 | +| :----------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ | +| `multiplier` | 大于 0 且最多 1 的数字 | 缩放 Claude Code 计算的每个成本，无论 `overrides` 行是否覆盖它 | +| `overrides` | 模型 ID 到具有 `input`、`output`、`cacheRead` 和 `cacheWrite` 的费率对象的映射，每个 0 到 10000 | 该模型的美元每百万令牌费率，全部四个必需。`cacheWrite` 涵盖五分钟和一小时缓存写入。请参阅[`modelPricing` 行适用于哪些模型](#which-models-a-modelpricing-row-applies-to) | + +Claude Code 完全按照您写入的方式使用行的费率，不添加快速模式附加费或[仅限美国推理费率](https://platform.claude.com/docs/en/about-claude/pricing)。如果您也设置 `multiplier`，Claude Code 在行的费率之上应用它。Claude Code 删除具有它无法解析的费率或无法解析的 `multiplier` 的行，并保留其余的；请参阅[修复损坏的设置文件](/docs/zh-CN/settings#fix-a-broken-settings-file)。 + +

+ `modelPricing` 行适用于哪些模型 +

+ +Claude Code 从行的键决定行适用于哪些模型： + +* **内置模型的 ID**: Claude Code 本身为内置模型使用的键，无论该键是模型自己的 ID，如 `claude-sonnet-4-6`，还是其 Bedrock、Agent Platform 或 Foundry ID。Claude Code 将行应用于该模型的每个日期快照 ID 和提供商特定 ID。 +* **任何其他键**: 不是内置模型 ID 的键，如网关模型别名。Claude Code 仅将行应用于该一个 ID。当模型 ID 完全匹配您的一个键，也落在由内置模型 ID 键入的行下时，Claude Code 使用精确匹配。 +* **Bedrock 应用推理配置文件**: 一旦 Claude Code 通过您的 [`modelOverrides`](#modeloverrides) 映射或 [`bedrock:GetInferenceProfile` 查找](/docs/zh-CN/amazon-bedrock#iam-configuration)将配置文件解析为它路由到的模型，Claude Code 将该模型的行应用于配置文件。 + +

+ `modelSettings` +

+ +为您使用的每个模型保存[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。在您的机器上的交互式会话中，当您用 `/effort` 或 `/model` 选择器的努力滑块将 `low`、`medium`、`high` 或 `xhigh` 保存为您的默认值时，Claude Code 在您使用的模型下将该级别写入此处，因此您很少手动编辑此键。[`effortLevel`](#effortlevel) 条目列出 `/effort` 仅适用于该会话的会话。需要 Claude Code v2.1.251 或更高版本。 + +手动编辑键以更改或删除您保存的级别。 + +此处模型的 `effortLevel` 优先于同一设置文件中的顶级 [`effortLevel`](#effortlevel)。跨文件，Claude Code 分别解析每个模型：最高优先级[设置文件](/docs/zh-CN/settings#settings-precedence)设置该模型的 `effortLevel` 或顶级 `effortLevel` 决定，因此托管设置中的 `effortLevel` 优先于您在用户设置中保存的级别。[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level)列出还可以覆盖保存级别的内容，如启动时的 `--effort`。 + +要限制一个模型的努力而不是设置其级别，将 [`maxEffortLevel`](#maxeffortlevel) 字段添加到该模型的条目。该字段需要 Claude Code v2.1.267 或更高版本。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 将模型名称映射到具有 `effortLevel` 字段的对象，之一 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`、[`maxEffortLevel`](#maxeffortlevel) 字段或两者 +* **默认值**: 未设置 + +Claude Code 在模型的规范名称下写入每个条目，如 `claude-opus-5`，并将该模型的别名、日期后缀、`[1m]` 和识别的提供商特定 ID 匹配到同一条目。 + +此示例将 Opus 5 保持在 `medium`，而其他模型使用它们自己的保存或默认级别： + +```json settings.json theme={null} +{ + "modelSettings": { + "claude-opus-5": { + "effortLevel": "medium" + } + } +} +``` + +运行 `/effort auto` 以清除您为正在使用的模型保存的级别。Claude Code 保留其他条目和任何顶级 `effortLevel`。 + +

+ `outputStyle` +

+ +按名称选择[输出样式](/docs/zh-CN/output-styles)。输出样式是一组保存的指令，改变 Claude 的角色、语气和输出格式，如内置的 Explanatory 和 Learning 样式或您自己写的。 + +如果您在会话期间更改此键，Claude 从您的下一条消息开始使用新样式。关于该消息在提示缓存中的成本，请参阅[更改输出样式](/docs/zh-CN/prompt-caching#changing-output-style)。在 v2.1.251 之前，编辑仅在您运行 `/clear` 或启动新会话后应用。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 字符串，[内置](/docs/zh-CN/output-styles#built-in-output-styles)或[自定义](/docs/zh-CN/output-styles#create-a-custom-output-style)输出样式的名称 +* **默认值**: 未设置，因此 Claude Code 使用默认样式 + +此示例选择内置的 Explanatory 样式，它在任务之间添加教育见解： + +```json settings.json theme={null} +{ + "outputStyle": "Explanatory" +} +``` + +

+ `promptCacheTtl` +

+ +选择[提示缓存](/docs/zh-CN/prompt-caching)保留主对话的时间长度。此键适用于您的交互式、`-p` 和 Agent SDK 轮，以及 Claude Code 与它们内联运行的助手。一小时的生命周期在较长的中断中保持缓存温暖，API [在五分钟生命周期的更高费率下为每个缓存写入计费](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。需要 Claude Code v2.1.242 或更高版本。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 字符串，之一： + * `"5m"`: 缓存保留五分钟 + * `"1h"`: 缓存保留一小时 +* **默认值**: 未设置，因此每个主对话请求获得[其默认生命周期](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets) +* **每会话覆盖**: [`FORCE_PROMPT_CACHING_5M`](/docs/zh-CN/env-vars) 优先于所有其他，然后 [`CLAUDE_CODE_PROMPT_CACHE_TTL`](/docs/zh-CN/env-vars)，然后此键，最后 [`ENABLE_PROMPT_CACHING_1H`](/docs/zh-CN/env-vars) + +此示例将主对话保持在一小时生命周期，并将子代理保留在五分钟： + +```json settings.json theme={null} +{ + "promptCacheTtl": "1h", + "subagentPromptCacheTtl": "5m" +} +``` + +关于每个生命周期的成本，请参阅[缓存生命周期](/docs/zh-CN/prompt-caching#cache-lifetime)。 + +

+ `showThinkingSummaries` +

+ +在交互式会话中查看 Claude 的[扩展思考](/docs/zh-CN/model-config#extended-thinking)摘要。如果您想在用 `Ctrl+O` 展开思考时看到完整摘要，请设置它。未设置或 `false` 时，Anthropic API 编辑思考块，Claude Code 显示折叠的存根；第三方提供商不编辑。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 布尔值 + * `true`: 当您用 `Ctrl+O` 展开思考时，您看到完整的思考摘要 + * `false`: Anthropic API 编辑思考块，Claude Code 显示折叠的存根 +* **默认值**: `false` + +```json settings.json theme={null} +{ + "showThinkingSummaries": true +} +``` + +编辑仅改变您看到的内容，而不是模型生成的内容。要减少思考支出，[降低预算或禁用思考](/docs/zh-CN/model-config#extended-thinking)。 + +

+ `subagentPromptCacheTtl` +

+ +选择[提示缓存](/docs/zh-CN/prompt-caching)保留 Claude Code 在主对话外进行的请求的时间长度。此键适用于[子代理](/docs/zh-CN/sub-agents)、[工作流](/docs/zh-CN/workflows)和 Claude Code 自己的后台和助手请求，如压缩和会话标题。一小时的生命周期在较长的中断中保持缓存温暖，API [在五分钟生命周期的更高费率下为每个缓存写入计费](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。需要 Claude Code v2.1.242 或更高版本。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 字符串，之一： + * `"5m"`: 缓存保留五分钟 + * `"1h"`: 缓存保留一小时 +* **默认值**: 未设置，因此这些请求中的每一个都获得[其默认生命周期](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets) +* **每会话覆盖**: [`FORCE_PROMPT_CACHING_5M`](/docs/zh-CN/env-vars) 优先于所有其他，然后 [`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`](/docs/zh-CN/env-vars)，然后此键，然后 [`ENABLE_PROMPT_CACHING_1H`](/docs/zh-CN/env-vars)，它要求每个请求的一小时生命周期。关于子代理自己的 frontmatter 值的排名，请参阅[自己选择 TTL](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself) + +此示例为子代理和主对话外的其他请求提供一小时生命周期： + +```json settings.json theme={null} +{ + "subagentPromptCacheTtl": "1h" +} +``` + +此键涵盖 [`promptCacheTtl`](#promptcachettl) 不涵盖的请求，因此设置两者以为 Claude Code 进行的每个请求选择生命周期。关于子代理的缓存与主对话的缓存的不同之处，请参阅[子代理和缓存](/docs/zh-CN/prompt-caching#subagents-and-the-cache)。 + +

+ `switchModelsOnFlag` +

+ +选择当[安全分类器标记请求](/docs/zh-CN/model-config#automatic-model-fallback)时会发生什么：切换到备用模型并继续，或暂停以便您可以在切换和编辑提示之间选择。 + +* **范围**: [`任何文件`](#scopes)。在 `/config` 中显示为**标记消息时切换模型**。 +* **类型**: 布尔值 + * `true`: Claude Code 切换到备用模型并继续 + * `false`: 在交互式会话中，Claude Code 暂停以便您可以在切换和编辑提示之间选择；在无法显示对话的地方，如 `-p` 运行，标记的请求以错误结束 +* **默认值**: `true`，自动切换 + +```json settings.json theme={null} +{ + "switchModelsOnFlag": false +} +``` + +请参阅[切换前询问](/docs/zh-CN/model-config#ask-before-switching)。 + +

+ `ultracode` +

+ +为[ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)可用的会话启动它。打开时，Claude 为每个实质性任务规划工作流，而不是等待您要求。Claude 仅在[动态工作流](/docs/zh-CN/workflows)为您启用、您的模型支持 `xhigh` 努力且没有[努力上限](/docs/zh-CN/model-config#organization-effort-limits)低于 `xhigh` 时规划工作流。无论如何，`ultracode: true` 在 `xhigh` 努力或当努力上限更低时在上限处运行会话。Claude Code 读取此键但从不写入它：`/effort ultracode` 仅为当前会话打开 ultracode。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 布尔值 + * `true`: 会话以 `xhigh` 努力启动，当动态工作流为您启用、您的模型支持 `xhigh` 且没有努力上限低于 `xhigh` 时，ultracode 打开 + * `false`: 会话以 ultracode 关闭启动 +* **默认值**: 未设置，因此 ultracode 已关闭 +* **每会话覆盖**: `/effort ultracode` 为一个会话打开 ultracode，不需要此键。`--effort ultracode` 也是，需要 Claude Code v2.1.203 或更高版本 + +```json settings.json theme={null} +{ + "ultracode": true +} +``` + +Ultracode 在 `xhigh` 努力处运行会话，优先于 `effortLevel` 和 [`modelSettings`](#modelsettings) 条目。如果[努力上限](/docs/zh-CN/model-config#organization-effort-limits)低于 `xhigh` 适用于模型，如 [`maxEffortLevel`](#maxeffortlevel) 设置，会话在上限处运行，ultracode 保持关闭。Claude 然后不自己规划工作流，`/effort` 不提供 `ultracode`。Agent SDK `apply_flag_settings` 控制请求也接受该键。 + +

+ 权限设置 +

+ +决定 Claude 在不询问的情况下可以做什么、会话以哪种权限模式启动，以及自动模式的分类器允许什么。有关规则语法和权限模型，请参阅[配置权限](/docs/zh-CN/permissions)。 + +

+ `allowManagedPermissionRulesOnly` +

+ +使托管设置成为权限规则的唯一设置源。Claude Code 随后会忽略用户、项目、本地和 `--settings` 文件中的 `allow`、`ask` 和 `deny` 规则，忽略 `--allowedTools`，隐藏权限提示中的始终允许选项，并停止保存新规则。 + +当[来自嵌入主机的父设置](/docs/zh-CN/managed-settings#let-an-embedding-host-add-policy)适用时，Claude Code 将其视为托管层的一部分：它保留其 `deny` 和 `ask` 规则，并删除其 `allow` 规则和 `additionalDirectories`。 + +`--disallowedTools` 规则和当前会话的 `deny` 和 `ask` 规则仍然适用，包括在 Claude Code 在会话中途重新加载设置后。它们仅限制，因此无法扩展托管规则授予的权限。在 v2.1.257 之前，Claude Code 在第一次设置重新加载时删除了这些命令行和会话规则。 + +* **作用域**: [`Managed`](#scopes) +* **类型**: 布尔值 + * `true`：托管设置成为权限规则的唯一设置源 + * `false`：Claude Code 除了应用托管规则外，还应用来自用户、项目、本地和 `--settings` 文件的权限规则 +* **默认值**: 未设置，因此 Claude Code 应用来自用户、项目和本地设置以及 `--settings` 的权限规则，以及托管规则 + +```json managed-settings.json theme={null} +{ + "allowManagedPermissionRulesOnly": true +} +``` + +此键不会锁定 MCP 服务器允许列表；为此，请设置 [`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly)。请参阅[仅托管设置](/docs/zh-CN/managed-settings#managed-only-settings)。 + +

+ `autoMode` +

+ +向[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器阻止和允许的内容添加您自己的规则。使用它告诉分类器您的组织信任哪些存储库、存储桶和域，以便它停止阻止常规内部操作。分类器附带[内置允许和拒绝规则](/docs/zh-CN/auto-mode-config#inspect-the-defaults-and-your-effective-config)。在数组中包含字面字符串 `"$defaults"` 以在该位置保留这些内置规则并在其周围添加您的规则；省略它以用您的规则替换它们。 + +* **作用域**: [`User or managed`](#scopes) +* **类型**: 包含 `environment`、`allow`、`soft_deny` 和 `hard_deny` 散文规则数组的对象，加上 [`classifyAllShell`](#automode-classifyallshell) 布尔值 +* **默认值**: 未设置，因此分类器仅使用其[内置规则](/docs/zh-CN/auto-mode-config#inspect-the-defaults-and-your-effective-config) + +此示例通过 `"$defaults"` 保留内置的 `soft_deny` 规则，并添加一个阻止 `terraform apply` 的规则： + +```json settings.json theme={null} +{ + "autoMode": { + "soft_deny": ["$defaults", "Never run terraform apply"] + } +} +``` + +当这些文件中的多个文件设置相同的数组时，Claude Code 会连接这些条目。有关规则格式以及如何应用每个数组，请参阅[配置自动模式](/docs/zh-CN/auto-mode-config)。 + +

+ `autoMode.classifyAllShell` +

+ +在自动模式处于活动状态时，通过自动模式分类器发送每个 Bash 和 PowerShell 命令。默认情况下，自动模式仅暂停可能运行任意代码的允许规则：工具范围和通配符规则（如 `Bash(*)`）以及解释器或 shell 包装器前缀（如 `Bash(python *)`）。任何其他允许规则匹配的命令（如 `Bash(npm test)`）会跳过分类器，规则的前缀未预期的破坏性参数可能会被看不见地通过。设置此键会为会话暂停每个 shell 允许规则，以便分类器看到每个命令。需要 Claude Code v2.1.193 或更高版本。 + +* **作用域**: [`User or managed`](#scopes)。在读取 [`autoMode`](#automode) 的任何地方读取。 +* **类型**: 布尔值 + * `true`：在自动模式处于活动状态时，Claude Code 通过分类器发送每个 Bash 和 PowerShell 命令，并暂停您的 shell 允许规则；在自动模式之外，规则仍然适用 + * `false`：自动模式仅暂停可能运行任意代码的允许规则，如 `Bash(*)` 和 `Bash(python *)`；任何其他允许规则匹配的命令会跳过分类器，每个其他 shell 命令都会通过它 +* **默认值**: `false` + +```json settings.json theme={null} +{ + "autoMode": { + "classifyAllShell": true + } +} +``` + +请参阅[通过分类器路由所有 shell 命令](/docs/zh-CN/auto-mode-config#route-all-shell-commands-through-the-classifier)。需要 Claude Code v2.1.193 或更高版本。 + +

+ `disableAutoMode` +

+ +从 `Shift+Tab` 循环中删除[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)。任何本应[以自动模式启动](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)的会话，无论是来自 `--permission-mode auto`、设置文件还是内置默认值，都会改为以 `default` 启动。管理员在托管设置中设置它以防止其组织中的开发人员使用自动模式。 + +* **作用域**: [`Any file`](#scopes)。在[托管设置](/docs/zh-CN/managed-settings)中最有用，用户无法覆盖它。也接受在 `permissions` 下作为 `permissions.disableAutoMode`。 +* **类型**: 字符串 `"disable"` +* **默认值**: 未设置 + +```json settings.json theme={null} +{ + "disableAutoMode": "disable" +} +``` + +

+ `permissions` +

+ +控制 Claude 可以在不询问的情况下使用哪些工具、哪些工具始终提示，以及哪些工具被阻止，并设置会话启动的[权限模式](/docs/zh-CN/permission-modes)。下面的每个 `permissions.*` 键都嵌套在此对象下。 + +* **作用域**: [`Any file`](#scopes) +* **类型**: 包含 `allow`、`ask`、`deny`、`additionalDirectories`、`blockReadsOutsideWorkingDirectories`、`defaultMode`、`disableBypassPermissionsMode` 和 `disableAutoMode` 的对象 +* **默认值**: 未设置 + +此示例在不询问的情况下批准 `npm run` 命令，在 `git push` 之前提示，阻止读取 `.env`，并在 `acceptEdits` 中启动会话： + +```json settings.json theme={null} +{ + "permissions": { + "allow": ["Bash(npm run *)"], + "ask": ["Bash(git push *)"], + "deny": ["Read(./.env)"], + "defaultMode": "acceptEdits" + } +} +``` + +这三个规则数组共享一个语法；请参阅 `permissions.allow` 下的[权限规则语法](#permission-rule-syntax)。有关来自不同文件的权限规则如何组合，请参阅[权限规则如何跨作用域合并](/docs/zh-CN/permissions#settings-precedence)；有关设置键如何组合，请参阅设置指南上的[设置优先级](/docs/zh-CN/settings#settings-precedence)。 + +

+ `useAutoModeDuringPlan` +

+ +选择 Claude Code 是否使用自动模式分类器在计划模式下审查 shell 命令。使用默认值 `true`，分类器在规划期间审查每个命令，当自动模式可用且您看不到提示时。设置 `false` 以获得内置只读集之外的每个命令的权限提示。在 `/config` 中显示为**在计划期间使用自动模式**。 + +* **作用域**: [`User, local, or managed`](#scopes)。存储库无法为您关闭它。 +* **类型**: 布尔值 + * `true`：与未设置相同；当自动模式可用时，分类器在规划期间审查每个 shell 命令，而不是提示您。任何这些文件中的 `false` 仍然会关闭它 + * `false`：您会获得内置只读集之外的每个命令的权限提示 +* **默认值**: `true` + +```json settings.json theme={null} +{ + "useAutoModeDuringPlan": false +} +``` + +

+ `permissions.allow` +

+ +列出 Claude Code 在不询问您的情况下批准的工具使用。在 MCP 规则中，`*` 只能出现在 `mcp____` 前缀之后的工具名称中，如 `mcp__github__get_*`；它不能出现在服务器名称中。 + +* **作用域**: [`Any file`](#scopes) +* **类型**: 权限规则字符串数组 +* **默认值**: 未设置 +* **每会话覆盖**: `--allowedTools` 为一个会话添加允许规则，来自任何设置文件的拒绝规则仍然会阻止它命名的工具 + +此示例批准 `git diff` 并让 Claude Code 读取您的 `.zshrc` 而不询问： + +```json settings.json theme={null} +{ + "permissions": { + "allow": ["Bash(git diff *)", "Read(~/.zshrc)"] + } +} +``` + +Claude Code 仅在您接受该文件夹的[工作区信任对话框](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)后，才应用项目的 `.claude/settings.json` 中的 `allow` 规则。 + +

+ 权限规则语法 +

+ +权限规则遵循格式 `Tool` 或 `Tool(specifier)`。Claude Code 首先评估 `deny` 规则，然后是 `ask`，然后是 `allow`，第一个匹配决定，无论每个规则有多具体；请参阅[权限规则评估顺序](/docs/zh-CN/permissions#manage-permissions)。 + +每行显示一个规则形状及其匹配的内容。 + +| 规则 | 它匹配的内容 | +| :----------------------------- | :------------------ | +| `Bash` | 每个 Bash 命令 | +| `Bash(npm run *)` | 以 `npm run` 开头的命令 | +| `Read(./.env)` | 读取 `.env` 文件 | +| `WebFetch(domain:example.com)` | 对 example.com 的获取请求 | + +有关完整的规则语法，包括通配符行为、Read、Edit、WebFetch、MCP 和 Agent 规则的工具特定模式，以及 Bash 模式的安全限制，请参阅[权限规则语法](/docs/zh-CN/permissions#permission-rule-syntax)。 + +

+ `permissions.ask` +

+ +列出即使在会否则批准它们的权限模式（如 `acceptEdits` 或 `bypassPermissions`）中也会提示您确认的工具使用。在 `dontAsk` 模式中，Claude Code 拒绝匹配的工具使用，而不是提示。 + +* **作用域**: [`Any file`](#scopes) +* **类型**: 权限规则字符串数组 +* **默认值**: 未设置 + +```json settings.json theme={null} +{ + "permissions": { + "ask": ["Bash(git push *)"] + } +} +``` + + + +

+ `permissions.deny` +

+ +列出 Claude Code 阻止的工具使用。将其用于保存 API 密钥、机密或环境值的文件：Claude Code 从文件发现和搜索结果中排除匹配的文件，拒绝读取它们，并在匹配的路径上阻止[编辑和写入工具](/docs/zh-CN/permissions#read-and-edit)。读取和编辑拒绝规则适用于 Claude 的内置文件工具、Claude Code 在 Bash 中识别的文件命令（如 `cat`、`head`、`tail` 和 `sed`）以及 Bash[重定向](/docs/zh-CN/permissions#redirections)的目标（如 `> file` 和 `< file`）；它们不适用于读取文件而不命名它们的命令（如 `grep -r pattern .`）或任意子进程，因此对于操作系统级别的强制执行，请[启用沙箱](/docs/zh-CN/sandboxing)。 + +* **作用域**: [`Any file`](#scopes) +* **类型**: 权限规则字符串数组 +* **默认值**: 未设置 +* **每会话覆盖**: `--disallowedTools` 为一个会话添加拒绝规则，与此键一起 + +此示例拒绝读取 `.env` 文件、`secrets` 目录和凭据文件，并阻止 `curl` 命令： + +```json settings.json theme={null} +{ + "permissions": { + "deny": [ + "Read(./.env)", + "Read(./.env.*)", + "Read(./secrets/**)", + "Read(./config/credentials.json)", + "Bash(curl *)" + ] + } +} +``` + +工具名称接受 glob 模式，因此 `"*"` 拒绝每个工具，`"mcp__*"` 拒绝每个 MCP 工具。只要任何其他工具仍然可用于 Claude，Claude Code 就会忽略 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 工具的拒绝规则。`Bash` 拒绝规则匹配 Claude 编写的命令，因此 `Bash(curl *)` 不会停止 `/usr/bin/curl` 或 `sh -c 'curl …'`；请参阅[Bash 规则不匹配的内容](/docs/zh-CN/permissions#bash-rule-limits)。此键替换已弃用的 `ignorePatterns` 配置。 + +

+ `permissions.additionalDirectories` +

+ +给予 Claude 对您启动的目录之外的目录的文件访问权限，作为额外的[工作目录](/docs/zh-CN/permissions#working-directories)。大多数 `.claude/` 配置[未从这些目录发现](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。 + +* **作用域**: [`Any file`](#scopes) +* **类型**: 目录路径数组 +* **默认值**: 未设置 +* **每会话覆盖**: `--add-dir` 和 `/add-dir` 为一个会话添加目录，与此键一起 + +```json settings.json theme={null} +{ + "permissions": { + "additionalDirectories": ["../docs/"] + } +} +``` + +与 `allow` 规则一样，项目的 `.claude/settings.json` 中的条目仅在您接受该文件夹的[工作区信任对话框](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)后才生效。 + +

+ `permissions.blockReadsOutsideWorkingDirectories` +

+ +阻止 Claude 在每个权限模式（包括 `bypassPermissions`）中使用 Read、Grep、Glob 和 LSP 工具读取会话[工作目录](/docs/zh-CN/permissions#working-directories)之外的路径。通过 Claude Code 识别的文件命令（如 `cat`）读取匹配路径的 Bash 命令会在自动模式和 `bypassPermissions` 模式中提示您。需要 Claude Code v2.1.257 或更高版本。 + +当您选择在[自动模式的提示中阻止此类读取（在第一次读取工作目录之外之前）](/docs/zh-CN/permission-modes#first-read-outside-the-working-directories)时，Claude Code 也会在此处写入 `true`。 + +* **作用域**: [`Any file`](#scopes)。如果任何设置源设置 `true`，则应用该块，因此存储库的签入文件可以为项目打开该块，但无法解除您设置的块。 +* **类型**: 布尔值 + * `true`：阻止工作目录之外的文件读取 + * `false`：与未设置相同；任何其他设置文件中的 `true` 仍然会阻止 +* **默认值**: 未设置，因此工作目录之外的读取遵循您的权限模式和规则 + +```json settings.json theme={null} +{ + "permissions": { + "blockReadsOutsideWorkingDirectories": true + } +} +``` + +如果仅存储库的签入设置文件添加目录，该块仍然适用于那里的读取。Claude Code 本身需要的文件保持可读，如您的技能、插件、规则、代理、命令以及 `~/.claude/` 下的 `CLAUDE.md` 内存文件。 + +当[沙箱](/docs/zh-CN/sandboxing)打开时，该块也会拒绝沙箱命令对工作目录之外的主目录和挂载卷根的读取访问。需要批准以[在沙箱外运行](/docs/zh-CN/sandboxing#the-unsandboxed-retry-escape-hatch)的重试会在 `bypassPermissions` 模式中提示您。工具从您的主目录读取的文件（如 `~/.gitconfig`）与其余文件一起被拒绝；当工具需要它时，使用 [`sandbox.filesystem.allowRead`](#sandbox-filesystem-allowread) 重新打开特定路径。 + +当会话的工作目录是链接的 [git worktree](/docs/zh-CN/worktrees)（包括 Claude Code 在会话中途进入的）时，存储库的公共 `.git` 目录对沙箱命令保持可读和可写，因此 git 在那里继续工作。 + +

+ `permissions.defaultMode` +

+ +设置新会话启动的[权限模式](/docs/zh-CN/permission-modes)。当您将其留空时，会话会以您的计划和表面的[内置默认值](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)启动。 + +* **作用域**: [`Any file`](#scopes)。`auto` 和 `bypassPermissions` 不会从项目或本地设置生效，因此改为在 `~/.claude/settings.json` 中设置它们。在 v2.1.257 之前，`bypassPermissions` 从任何文件生效。对于 VS Code 扩展启动的对话，Claude Code 仅读取用户、托管和 `--settings` 值。 +* **类型**: 字符串，以下之一： + * `"default"`：Claude Code 仅在不询问的情况下运行读取 + * `"acceptEdits"`：Claude Code 也在不询问的情况下运行文件编辑和常见文件系统命令（如 `mkdir` 和 `mv`） + * `"plan"`：Claude Code 读取和规划，但阻止编辑直到您批准计划 + * `"auto"`：Claude Code 运行所有内容，具有后台安全检查 + * `"dontAsk"`：Claude Code 自动拒绝每个会否则提示的调用；读取、不需要批准的其他操作以及预批准的工具仍然运行 + * `"bypassPermissions"`：Claude Code 在不询问的情况下运行所有内容 + * `"manual"`：`"default"` 的别名，在 Claude Code v2.1.200 或更高版本中 +* **默认值**: 未设置 +* **每会话覆盖**: `--permission-mode` 及其 `bypassPermissions` 的等效项 `--dangerously-skip-permissions` 对一个会话优先于此键 + +```json settings.json theme={null} +{ + "permissions": { + "defaultMode": "acceptEdits" + } +} +``` + +权限规则分层在每个模式之上：`deny` 规则在每个模式中阻止，包括 `bypassPermissions`。请参阅[权限模式](/docs/zh-CN/permission-modes)。`manual` 命名 CLI 和 VS Code 扩展中标记为"手动"的权限模式；别名需要 Claude Code v2.1.200 或更高版本。在网络上的 Claude Code 中，Claude Code 仅从此键中遵守 `acceptEdits`、`plan`、`default` 和 `auto`。对于 VS Code 扩展启动的对话，请参阅[扩展为启动权限模式读取的设置](/docs/zh-CN/permission-modes#switch-permission-modes)。 + +

+ `permissions.disableBypassPermissionsMode` +

+ +防止任何人进入 `bypassPermissions` 模式。Claude Code 随后会拒绝 `--dangerously-skip-permissions` 标志，并忽略[代理定义的](/docs/zh-CN/sub-agents#permission-modes) `permissionMode: bypassPermissions`，因此子代理使用父会话的权限模式运行。 + +* **作用域**: [`Any file`](#scopes)。通常在[托管设置](/docs/zh-CN/managed-settings)中设置以强制执行组织政策。 +* **类型**: 字符串 `"disable"` +* **默认值**: 未设置 +* **每会话覆盖**: 此键优先于 `--dangerously-skip-permissions`，在设置此键时 Claude Code 会拒绝它 + +```json settings.json theme={null} +{ + "permissions": { + "disableBypassPermissionsMode": "disable" + } +} +``` + +在 v2.1.223 之前，即使禁用绕过，Claude Code 也应用了 frontmatter 权限模式。 + +

+ `skipAutoPermissionPrompt` +

+ +跳过 Claude Code 在您自己首次进入自动模式时显示的一次性通知，描述[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，例如通过您自己的设置或模式选择器，而不是当内置默认值在其中启动会话时。Claude Code 显示该通知一次，然后记录它已显示，因此此键仅在通知尚未出现的地方重要。 + +* **作用域**: [`User or managed`](#scopes)。存储库无法为您设置它。 +* **类型**: 布尔值 + * `true`：Claude Code 跳过通知 + * `false`：与未设置相同；除非这些文件中的另一个设置 `true`，否则通知出现一次 +* **默认值**: 未设置，因此通知出现一次 + +```json settings.json theme={null} +{ + "skipAutoPermissionPrompt": true +} +``` + +

+ `skipDangerousModePermissionPrompt` +

+ +跳过 Claude Code 在会话进入 `bypassPermissions` 模式之前显示的确认对话框，无论是来自 `--dangerously-skip-permissions` 还是来自 `defaultMode: "bypassPermissions"`。当您接受该对话框一次时，Claude Code 在您的用户设置中写入 `true`。 + +* **作用域**: [`User, local, or managed`](#scopes)。不受信任的存储库无法为您跳过对话框。 +* **类型**: 布尔值 + * `true`：Claude Code 跳过会话进入 `bypassPermissions` 模式之前的确认对话框 + * `false`：与未设置相同；除非这些文件中的另一个设置 `true`，否则对话框出现 +* **默认值**: 未设置，因此对话框出现 + +```json settings.json theme={null} +{ + "skipDangerousModePermissionPrompt": true +} +``` + +

+ Sandbox 设置 +

+ +将 Claude 运行的命令与您的文件系统、网络和凭证隔离。有关沙箱工作原理和平台要求，请参阅 [Sandboxing](/docs/zh-CN/sandboxing)。 + +

+ `sandbox` +

+ +使用 [sandboxing](/docs/zh-CN/sandboxing) 将 Claude 运行的 Bash 命令与您的文件系统和网络隔离。使用 `enabled` 打开沙箱，然后使用 `filesystem`、`network` 和 `credentials` 子对象缩小或扩大沙箱命令可以接触的内容。沙箱在 macOS、Linux 和 WSL2 上运行。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 对象，包含 `enabled`、`failIfUnavailable`、`autoAllowBashIfSandboxed`、`excludedCommands`、`allowUnsandboxedCommands`、`enableWeakerNestedSandbox`、`enableWeakerNetworkIsolation`、`allowAppleEvents`、`bwrapPath`、`socatPath`、`ignoreViolations` 和 `ripgrep`，以及 `filesystem`、`network` 和 `credentials` 对象 +* **Default**: 未设置，因此 Claude Code 运行命令时不使用沙箱 + +这会打开沙箱，跳过沙箱命令的权限提示，在沙箱外运行 `docker`，打开两个额外的写入路径，隐藏您的 AWS 凭证文件，并预先允许 GitHub 和 npm： + +```json settings.json theme={null} +{ + "sandbox": { + "enabled": true, + "autoAllowBashIfSandboxed": true, + "excludedCommands": ["docker *"], + "filesystem": { + "allowWrite": ["/tmp/build", "~/.kube"], + "denyRead": ["~/.aws/credentials"] + }, + "network": { + "allowedDomains": ["github.com", "*.npmjs.org"] + } + } +} +``` + +Claude Code 从优先级最高的设置范围获取布尔键的值，因此托管的 `enabled` 或 `failIfUnavailable` 会覆盖开发人员设置的任何内容。它在会话加载的每个设置范围中合并数组键，因此开发人员可以追加条目；请参阅 [Keep developers from widening the policy](/docs/zh-CN/sandboxing#keep-developers-from-widening-the-policy) 了解仅限托管的锁。要为组织强制执行沙箱，请参阅 [Enforce sandboxing with managed settings](/docs/zh-CN/sandboxing#enforce-sandboxing-with-managed-settings)。 + +

+ `sandbox.enabled` +

+ +为 Bash 命令打开 [sandboxing](/docs/zh-CN/sandboxing)。当您在 `/sandbox` 面板中选择一个模式时，Claude Code 会将此键写入当前项目的 `.claude/settings.local.json`；在 `~/.claude/settings.json` 中设置它以对每个项目进行沙箱处理。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 布尔值 + * `true`: Claude Code 对 Bash 命令进行沙箱处理 + * `false`: Bash 命令在没有沙箱的情况下运行 +* **Default**: `false` + +```json settings.json theme={null} +{ + "sandbox": { + "enabled": true + } +} +``` + +在 Linux 和 WSL2 上，沙箱需要 `bubblewrap` 和 `socat`；请参阅 [Set up Linux and WSL2](/docs/zh-CN/sandboxing#set-up-linux-and-wsl2)。当沙箱无法启动时，Claude Code 会显示警告并在没有设置 [`failIfUnavailable`](#sandbox-failifunavailable) 的情况下运行未沙箱化的命令。 + +

+ `sandbox.failIfUnavailable` +

+ +当 `sandbox.enabled` 为 `true` 但沙箱无法启动时（因为缺少依赖项或不支持该平台），使 Claude Code 在启动时以错误退出。没有它，Claude Code 会显示警告并运行未沙箱化的命令。在托管设置中使用它，当您的组织要求沙箱作为硬门时。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 布尔值 + * `true`: 当 `sandbox.enabled` 为 `true` 但沙箱无法启动时，Claude Code 在启动时以错误退出 + * `false`: Claude Code 显示警告并运行未沙箱化的命令 +* **Default**: `false` + +这使每台托管机器对命令进行沙箱处理或拒绝启动： + +```json managed-settings.json theme={null} +{ + "sandbox": { + "enabled": true, + "failIfUnavailable": true + } +} +``` + +请参阅 [Enforce sandboxing with managed settings](/docs/zh-CN/sandboxing#enforce-sandboxing-with-managed-settings)。 + +

+ `sandbox.autoAllowBashIfSandboxed` +

+ +让 Claude Code 运行沙箱化的 Bash 命令而无需权限提示。无法在沙箱中运行的命令仍会通过常规权限流程，`deny` 规则和内容范围的 `ask` 规则（如 `Bash(git push *)` ）仍然适用；对于沙箱化命令，裸 `Bash` ask 规则被跳过。将其设置为 `false` 以也通过常规权限流程发送沙箱化命令，`/sandbox` **Mode** 选项卡称之为常规权限模式。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 布尔值 + * `true`: Claude Code 运行沙箱化的 Bash 命令而无需权限提示，受 `deny` 规则和内容范围的 `ask` 规则约束；`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 关闭自动允许 + * `false`: 沙箱化命令通过常规权限流程，因此您的允许规则和权限模式决定。`/sandbox` **Mode** 选项卡称之为常规权限模式 +* **Default**: `true` + +这保持沙箱打开并通过常规权限流程发送沙箱化命令： + +```json settings.json theme={null} +{ + "sandbox": { + "enabled": true, + "autoAllowBashIfSandboxed": false + } +} +``` + +请参阅 [Sandbox modes](/docs/zh-CN/sandboxing#sandbox-modes) 了解自动允许模式仍会提示什么以及它在计划模式中的行为。 + +

+ `sandbox.excludedCommands` +

+ +命名 Claude Code 始终在沙箱外运行的命令，例如在沙箱下不工作的工具。每个条目使用与 `Bash(...)` [permission rule](/docs/zh-CN/permissions#permission-rule-syntax) 内容相同的语法：精确命令、前缀（如 `docker *` ）或通配符模式。当复合命令的任何部分与条目匹配时，Claude Code 运行整个命令而不进行沙箱处理。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 命令模式数组 +* **Default**: 未设置，因此没有命令被排除 + +```json settings.json theme={null} +{ + "sandbox": { + "excludedCommands": ["docker *"] + } +} +``` + +排除的命令仍会通过常规权限流程。排除是一种便利，而不是安全边界：当工具只需要在特定位置写入时，优先使用 [`filesystem.allowWrite`](#sandbox-filesystem-allowwrite)。Claude Code 在会话加载的每个设置范围中合并条目，此列表没有仅限托管的锁，因此保持托管列表狭窄。 + +

+ `sandbox.allowUnsandboxedCommands` +

+ +让 Claude 在沙箱阻止后使用 `dangerouslyDisableSandbox` 参数在沙箱外重试命令。将其设置为 `false` 以使 Claude Code 完全忽略该参数，并且 Claude 运行的每个命令都必须进行沙箱处理或出现在 [`excludedCommands`](#sandbox-excludedcommands) 中。`/sandbox` **Overrides** 选项卡将该状态显示为 **Strict sandbox mode**。在托管设置中使用 `false` 以获得需要严格沙箱处理的策略。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 布尔值 + * `true`: Claude 可以在沙箱阻止后使用 `dangerouslyDisableSandbox` 参数在沙箱外重试命令 + * `false`: Claude Code 忽略该参数，因此 Claude 运行的每个命令都进行沙箱处理或出现在 `excludedCommands` 中 +* **Default**: `true` + +这为托管设置覆盖的每个人强制执行严格沙箱模式： + +```json managed-settings.json theme={null} +{ + "sandbox": { + "enabled": true, + "allowUnsandboxedCommands": false + } +} +``` + +未沙箱化的重试通过常规权限流程，在手动模式下带有提示。请参阅 [The unsandboxed retry escape hatch](/docs/zh-CN/sandboxing#the-unsandboxed-retry-escape-hatch)。 + +要查看您在 [`!` shell-mode prompt](/docs/zh-CN/interactive-mode#shell-mode-with-prefix) 处自己输入的命令何时运行沙箱化，请参阅 [strict sandbox mode](/docs/zh-CN/sandboxing#the-unsandboxed-retry-escape-hatch)。 + +

+ `sandbox.filesystem` +

+ +控制沙箱化命令可以读取和写入的路径。默认情况下，它们可以写入工作目录、会话临时目录以及使用 `--add-dir`、`/add-dir` 或 `permissions.additionalDirectories` 添加的目录，并可以读取文件系统的其余部分，包括凭证文件。使用四个路径列表扩大或缩小范围，或使用 `disabled` 关闭文件系统层。请参阅 [Filesystem isolation](/docs/zh-CN/sandboxing#filesystem-isolation) 了解默认边界。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 对象，包含 `allowWrite`、`denyWrite`、`denyRead` 和 `allowRead` 数组，以及 `allowManagedReadPathsOnly` 和 `disabled` 布尔值 +* **Default**: 未设置，因此应用默认读写边界 + +这让沙箱化命令写入构建目录和您的 kubeconfig，并隐藏您的 AWS 凭证文件： + +```json settings.json theme={null} +{ + "sandbox": { + "filesystem": { + "allowWrite": ["/tmp/build", "~/.kube"], + "denyRead": ["~/.aws/credentials"] + } + } +} +``` + +Claude Code 在操作系统沙箱边界强制执行这些列表，因此它们适用于沙箱化命令启动的每个子进程，例如 `kubectl`、`terraform` 或 `npm`，而不仅仅是 Claude 的文件工具。Claude Code 将您的 [permission rules](/docs/zh-CN/sandboxing#permission-rules) 添加到相同的列表：`Edit` 允许和拒绝规则到 `allowWrite` 和 `denyWrite`，`Read` 拒绝规则到 `denyRead`，以及 `WebFetch(domain:...)` 允许和拒绝规则到 [`network`](#sandbox-network) 域列表。 + +除非设置了仅限托管的锁，否则 Claude Code 在会话加载的设置文件中合并每个列表。[`allowManagedReadPathsOnly`](#sandbox-filesystem-allowmanagedreadpathsonly) 将 `allowRead` 限制为托管设置中的条目，[`allowManagedDomainsOnly`](#sandbox-network-allowmanageddomainsonly) 对允许的域执行相同操作。 + +[Configure sandboxing](/docs/zh-CN/sandboxing#configure-sandboxing) 涵盖您使用 `--setting-sources` 排除的源。当您在会话期间编辑列表时，Claude Code [applies the change to the running session](/docs/zh-CN/settings#when-edits-take-effect)。 + +

+ Sandbox 路径前缀 +

+ +`allowWrite`、`denyWrite`、`denyRead`、`allowRead` 和 [`credentials.files`](#sandbox-credentials-files) 中的路径按其前缀解析： + +| 前缀 | 含义 | 示例 | +| :-------- | :------------------------------------ | :---------------------------------------------------------------- | +| `/` | 从文件系统根目录的绝对路径 | `/tmp/build` 保持 `/tmp/build` | +| `~/` | 相对于主目录 | `~/.kube` 变为 `$HOME/.kube` | +| `./` 或无前缀 | 相对于项目根目录（用于项目设置）或 `~/.claude`（用于用户设置） | `.claude/settings.json` 中的 `./output` 解析为 `/output` | + +绝对路径的 `//path` 前缀也有效。如果您使用单斜杠 `/path` 期望项目相对解析，请切换到 `./path`。此语法与 [Read and Edit permission rules](/docs/zh-CN/permissions#read-and-edit) 不同，后者使用 `//path` 表示绝对路径，`/path` 表示项目相对路径：沙箱文件系统路径使用标准约定，因此 `/tmp/build` 是绝对路径。 + +Claude Code 从目录路径中删除尾部斜杠，因此 `~/.aws` 和 `~/.aws/` 匹配同一目录。在 v2.1.224 之前，Claude Code 将尾部斜杠传递给沙箱，Claude 仍然可以读取或写入使用一个尾部斜杠编写的 `denyRead` 或 `denyWrite` 条目下的路径。 + +Claude Code 也删除尾部 `/**`，因此 `~/build/**` 和 `~/build` 覆盖同一目录。通配符（如 `*` ）是否有效取决于条目所在的列表和平台： + +* **`allowWrite` 和 `denyWrite`**: 在 macOS 上，通配符有效。在 Linux 和 WSL2 上，沙箱挂载具体路径，因此 Claude Code 在删除尾部 `/**` 后跳过包含 `*`、`?` 或 `[` 的条目，该条目无效。Claude Code 将您的 `Edit` 权限规则中的路径添加到这些列表中，因此相同的限制适用于它们，`/sandbox` 的 **Config** 选项卡警告包含通配符的 `Edit` 和 `Read` 权限规则。 +* **`denyRead` 和 `allowRead`**: 通配符在每个平台上都有效。在 Linux 和WSL2 上，Claude Code 将读取条目扩展到它匹配的具体路径，对写入列表不执行此操作。 + +

+ `sandbox.filesystem.allowWrite` +

+ +添加沙箱化命令可以写入的路径，超出工作目录、会话临时目录以及使用 `--add-dir`、`/add-dir` 或 `permissions.additionalDirectories` 添加的目录。当子进程（如 `kubectl` 或构建工具）需要在项目外写入时使用它。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 路径字符串数组，使用 [sandbox path prefixes](#sandbox-path-prefixes) +* **Default**: 未设置，因此沙箱化命令可以写入工作目录、会话临时目录、使用 `--add-dir` 或 `/add-dir` 添加的目录以及 [`permissions.additionalDirectories`](#permissions-additionaldirectories) 中的目录 + +这让构建在 `/tmp/build` 下写入并让 `kubectl` 更新您的 kubeconfig： + +```json settings.json theme={null} +{ + "sandbox": { + "filesystem": { + "allowWrite": ["/tmp/build", "~/.kube"] + } + } +} +``` + +Claude Code 在会话加载的每个设置范围中合并条目：用户、项目、本地和托管路径组合而不是替换彼此，Claude Code 添加您的 `Edit(...)` 允许权限规则中的路径。`allowWrite` 条目不能提升 [protected path](/docs/zh-CN/sandboxing#protected-paths)。 + +

+ `sandbox.filesystem.denyWrite` +

+ +阻止沙箱化命令写入特定路径，包括在其他可写目录内的路径。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 路径字符串数组，使用 [sandbox path prefixes](#sandbox-path-prefixes) +* **Default**: 未设置 + +这防止沙箱化命令更改系统配置或安装二进制文件： + +```json settings.json theme={null} +{ + "sandbox": { + "filesystem": { + "denyWrite": ["/etc", "/usr/local/bin"] + } + } +} +``` + +Claude Code 在会话加载的每个设置范围中合并条目，并添加您的 `Edit(...)` 拒绝权限规则中的路径。 + +

+ `sandbox.filesystem.denyRead` +

+ +阻止沙箱化命令读取特定路径，例如默认读取策略会公开的凭证文件。要保护凭证文件并使其可通过沙箱代理使用，请改为参阅 [`sandbox.credentials`](#sandbox-credentials)。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 路径字符串数组，使用 [sandbox path prefixes](#sandbox-path-prefixes) +* **Default**: 未设置，因此沙箱化命令保持 [default read access](/docs/zh-CN/sandboxing#filesystem-isolation)，包括凭证文件，如 `~/.aws/credentials` + +```json settings.json theme={null} +{ + "sandbox": { + "filesystem": { + "denyRead": ["~/.aws/credentials"] + } + } +} +``` + +Claude Code 在会话加载的每个设置范围中合并条目，并添加您的 `Read(...)` 拒绝权限规则中的路径。当 [`filesystem.disabled`](#sandbox-filesystem-disabled) 为 `true` 时，Claude Code 不强制执行这些条目。 + +

+ `sandbox.filesystem.allowRead` +

+ +重新打开 [`denyRead`](#sandbox-filesystem-denyread) 阻止的区域内特定路径的读取，以构建仅工作区读取访问。精确或通配符 `denyRead` 条目在更广泛的 `allowRead` 内保持阻止，如 [overlap table](/docs/zh-CN/sandboxing#configure-sandboxing) 所示。当通配符 `denyRead` 条目（如 `~/**/.env` ）匹配目录时，Claude Code 也会阻止其内容的读取。在 v2.1.236 之前的 macOS 上，Claude Code 在更广泛的 `allowRead` 条目覆盖它们的任何地方重新打开通配符 `denyRead` 条目匹配的路径，并保持匹配目录的内容可读。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 路径字符串数组，使用 [sandbox path prefixes](#sandbox-path-prefixes) +* **Default**: 未设置 + +这阻止读取您的主目录，除了项目本身： + +```json settings.json theme={null} +{ + "sandbox": { + "filesystem": { + "denyRead": ["~/"], + "allowRead": ["."] + } + } +} +``` + +Claude Code 在项目设置中将 `.` 条目解析为项目根目录，在用户设置中解析为 `~/.claude`。Claude Code 在会话加载的每个设置文件中合并条目，除非设置了 [`allowManagedReadPathsOnly`](#sandbox-filesystem-allowmanagedreadpathsonly)。 + +

+ `sandbox.filesystem.allowManagedReadPathsOnly` +

+ +仅遵守来自托管设置的 [`allowRead`](#sandbox-filesystem-allowread) 条目，以便开发人员无法重新打开对您的组织阻止的路径的读取访问。Claude Code 仍然从会话加载的每个设置范围合并 `denyRead` 条目。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: 布尔值 + * `true`: Claude Code 仅遵守来自托管设置的 `allowRead` 条目 + * `false`: `allowRead` 条目从会话加载的每个设置范围合并 +* **Default**: `false` + +这阻止读取主目录，重新打开 `~/work`，并阻止开发人员重新打开任何其他内容： + +```json managed-settings.json theme={null} +{ + "sandbox": { + "filesystem": { + "denyRead": ["~/"], + "allowRead": ["~/work"], + "allowManagedReadPathsOnly": true + } + } +} +``` + +请参阅 [Keep developers from widening the policy](/docs/zh-CN/sandboxing#keep-developers-from-widening-the-policy)。 + +

+ `sandbox.filesystem.disabled` +

+ +跳过文件系统隔离，同时保持网络隔离。沙箱化命令获得对主机文件系统的无限制读写访问，其网络出口仍限制在 [`network.allowedDomains`](#sandbox-network-alloweddomains)。当您沙箱化以控制命令连接的位置而不是它们写入的内容时使用它。需要 Claude Code v2.1.216 或更高版本。 + +* **Scope**: [`User or managed`](#scopes)。当托管设置配置 `sandbox.filesystem` 时，或列出带有 `"mode": "deny"` 的 `sandbox.credentials.files` 条目时，只有托管设置可以设置它。 +* **Type**: 布尔值 + * `true`: Claude Code 跳过文件系统隔离并保持网络隔离 + * `false`: 文件系统隔离保持打开 +* **Default**: `false`，因此文件系统隔离保持打开 + +这使文件系统打开并将网络出口限制在 GitHub 和 npm： + +```json settings.json theme={null} +{ + "sandbox": { + "enabled": true, + "filesystem": { + "disabled": true + }, + "network": { + "allowedDomains": ["github.com", "*.npmjs.org"] + } + } +} +``` + +关闭该层后，Claude Code 不强制执行 `denyRead` 或 `credentials.files` `deny` 条目，而 `credentials.envVars` 条目和应用的 `mask` 条目保持工作。[`autoAllowBashIfSandboxed`](#sandbox-autoallowbashifsandboxed) 仍默认为 `true`，因此将其设置为 `false` 以保持提示。请参阅 [Disable filesystem isolation](/docs/zh-CN/sandboxing#disable-filesystem-isolation) 了解可以设置它的完整源列表以及隔离关闭时的变化。需要 Claude Code v2.1.216 或更高版本。 + +

+ `sandbox.ignoreViolations` +

+ +沉默沙箱违规报告，针对您期望命令探测并被拒绝的路径，例如在启动时检查 `/etc/hosts` 的工具，因此这些拒绝不会显示为违规或在 Claude 看到的内容中。沙箱仍然阻止访问；只有报告被抑制。键是与命令匹配的子字符串，`*` 匹配每个命令，值是该命令要忽略的违规子字符串，例如文件系统路径。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 对象，将命令子字符串映射到违规子字符串数组，通常是路径 +* **Default**: 未设置，因此报告每个违规 + +```json settings.json theme={null} +{ + "sandbox": { + "ignoreViolations": { + "*": ["/etc/hosts"] + } + } +} +``` + +

+ `sandbox.enableWeakerNestedSandbox` +

+ +在无特权 Docker 容器内运行 Linux 沙箱，其中 bubblewrap 无法挂载新的 `/proc`。相反，内部沙箱绑定挂载容器的现有 `/proc`，这暴露了新挂载会隐藏的进程信息。这降低了安全性；仅当外部容器已提供您需要的隔离时才使用它。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 布尔值 + * `true`: 内部沙箱绑定挂载容器的现有 `/proc` 而不是挂载新的 + * `false`: 沙箱挂载新的 `/proc`，在无特权 Docker 容器中不工作 +* **Default**: `false` + +```json settings.json theme={null} +{ + "sandbox": { + "enabled": true, + "enableWeakerNestedSandbox": true + } +} +``` + +仅限 Linux 和 WSL2。请参阅 [Bubblewrap fails to start inside a container](/docs/zh-CN/sandboxing#troubleshooting)。 + +

+ `sandbox.enableWeakerNetworkIsolation` +

+ +让 macOS 上的沙箱化命令到达系统 TLS 信任服务 `com.apple.trustd.agent`。基于 Go 的工具（如 `gh`、`gcloud` 和 `terraform` ）在您使用 [`network.httpProxyPort`](#sandbox-network-httpproxyport) 与 MITM 代理和自定义 CA 时需要它来验证 TLS 证书。这通过打开通过信任服务的潜在数据泄露路径来降低安全性。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 布尔值 + * `true`: macOS 上的沙箱化命令可以到达 `com.apple.trustd.agent` + * `false`: macOS 上的沙箱化命令无法到达系统 TLS 信任服务 +* **Default**: `false` + +```json settings.json theme={null} +{ + "sandbox": { + "enabled": true, + "enableWeakerNetworkIsolation": true + } +} +``` + +如果您不使用 MITM 代理，请改为在 [`excludedCommands`](#sandbox-excludedcommands) 中列出失败的工具；请参阅 [Go-based CLIs fail TLS verification on macOS](/docs/zh-CN/sandboxing#troubleshooting)。 + +

+ `sandbox.allowAppleEvents` +

+ +让 macOS 上的沙箱化命令发送 Apple Events，`open`、`osascript` 和在浏览器中打开 URL 的工具需要它；没有它们会失败，错误为 `-600`。这删除了代码执行隔离：沙箱化命令可以在没有用户提示的情况下启动其他应用程序，并可以向运行的应用程序（如 Terminal）发送 AppleScript 命令，受每个应用程序的 macOS 自动化同意提示 (TCC) 约束。 + +* **Scope**: [`User or managed`](#scopes) +* **Type**: 布尔值 + * `true`: macOS 上的沙箱化命令可以发送 Apple Events + * `false`: macOS 上的沙箱化命令无法发送 Apple Events，因此 `open` 和 `osascript` 失败，错误为 `-600` +* **Default**: `false` + +```json settings.json theme={null} +{ + "sandbox": { + "enabled": true, + "allowAppleEvents": true + } +} +``` + +要保持隔离并仍然运行一个这样的工具，请改为将其添加到 [`excludedCommands`](#sandbox-excludedcommands)。请参阅 [Apple Events on macOS](/docs/zh-CN/sandboxing#security-limitations)。 + +

+ `sandbox.ripgrep` +

+ +将沙箱指向您自己的 ripgrep 二进制文件，而不是 Claude Code 使用的，例如当您的平台需要不同构建的 `rg` 时。 + +* **Scope**: [`User or managed`](#scopes) +* **Type**: 对象，包含 `command`（ripgrep 二进制文件的路径）和可选的 `args`（要前置的参数数组） +* **Default**: 未设置，因此沙箱使用与 Claude Code 相同的 ripgrep 二进制文件。这是捆绑的二进制文件，除非您将 [`USE_BUILTIN_RIPGREP`](/docs/zh-CN/env-vars) 设置为 `0` + +```json settings.json theme={null} +{ + "sandbox": { + "ripgrep": { + "command": "/usr/local/bin/rg" + } + } +} +``` + +

+ `sandbox.bwrapPath` +

+ +将沙箱指向安装在 `PATH` 外的 bubblewrap 二进制文件，例如在气隙主机上的供应商副本。Claude Code 在启动依赖项检查和包装每个沙箱化命令时都使用该路径。 + +* **Scope**: [`Managed`](#scopes)。Claude Code 仅从托管设置读取它，以便用户、项目或本地文件无法将沙箱指向不同的二进制文件。 +* **Type**: 字符串，绝对路径；Claude Code 删除相对路径并回退到 `PATH` 查找 +* **Default**: 未设置，因此 Claude Code 在 `PATH` 上找到 `bwrap` + +```json managed-settings.json theme={null} +{ + "sandbox": { + "enabled": true, + "bwrapPath": "/opt/admin/bwrap" + } +} +``` + +仅限 Linux 和 WSL2。 + +

+ `sandbox.socatPath` +

+ +将沙箱网络代理指向安装在 `PATH` 外的 `socat` 二进制文件。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: 字符串，绝对路径；Claude Code 删除相对路径并回退到 `PATH` 查找 +* **Default**: 未设置，因此 Claude Code 在 `PATH` 上找到 `socat` + +```json managed-settings.json theme={null} +{ + "sandbox": { + "enabled": true, + "socatPath": "/opt/admin/socat" + } +} +``` + +仅限 Linux 和 WSL2。 + +

+ `sandbox.credentials` +

+ +声明凭证文件和环境变量以 [protect from sandboxed commands](/docs/zh-CN/sandboxing#protect-credentials)。每个条目命名文件 `path` 或变量 `name` 和 `mode`：`deny` 在沙箱内隐藏凭证，`mask` 向沙箱化命令显示占位符，同时 [sandbox proxy](/docs/zh-CN/sandboxing#mask-credentials) 在出站请求上替换真实值。Claude Code 仅保护您列出的条目；没有内置凭证拒绝列表。需要 Claude Code v2.1.187 或更高版本。 + +* **Scope**: [`Any file`](#scopes)。Claude Code 仅从用户设置、托管设置和 `--settings` 标志遵守 `mask` 条目、`allowPlaintextInject`、`awsPairs` 和 `sigv4`。 +* **Type**: 对象，包含 `files`、`envVars`、`allowPlaintextInject`、`awsPairs` 和 `sigv4` +* **Default**: 未设置，因此没有凭证被保护 + +这隐藏您的 AWS 凭证文件并从沙箱化命令中删除 `GITHUB_TOKEN`： + +```json settings.json theme={null} +{ + "sandbox": { + "credentials": { + "files": [{ "path": "~/.aws/credentials", "mode": "deny" }], + "envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }] + } + } +} +``` + +`deny` 文件保护是文件系统层的一部分，因此当您 [disable filesystem isolation](/docs/zh-CN/sandboxing#disable-filesystem-isolation) 时不适用；环境变量保护仍然适用。需要 Claude Code v2.1.187 或更高版本。 + +

+ 托管设置中的无效凭证条目 +

+ +当托管 `sandbox.credentials` 条目验证失败时，Claude Code 在可能的地方保持保护凭证： + +* `files` 或 `envVars` 中仍有有效 `path` 或 `name` 和 `mask` 或 `deny` 的 `mode` 的条目，例如其 `extract` 模式没有捕获组的条目，降级为 `mode: "deny"` 并带有警告，因此凭证保持阻止，而不是掩盖，直到您修复条目。降级的 `files` 条目像显式 `deny` 条目一样固定 [`filesystem.disabled`](/docs/zh-CN/sandboxing#disable-filesystem-isolation)，警告注意如果托管设置关闭文件系统隔离，其读取块不被强制执行。 +* 具有未知 `mode` 或无效 `path` 或 `name` 的条目被删除。 +* 每种情况都会警告；无论条目是降级还是删除，其余有效条目仍然被强制执行，完全无效的 `credentials` 值被删除，同时 `sandbox` 的其余部分仍然适用。 + +适用于 v2.1.191 及更高版本；在 v2.1.221 之前，每个无效条目都被删除。对于其他具有每字段处理的托管键，请参阅 [Invalid entries in managed settings](/docs/zh-CN/managed-settings#invalid-entries-in-managed-settings)。 + +

+ `sandbox.credentials.files` +

+ +保护凭证文件或目录免受沙箱化命令。使用 `"mode": "deny"`，Claude Code 阻止在沙箱内读取路径，与 [`sandbox.filesystem.denyRead`](#sandbox-filesystem-denyread) 相同的读取块。使用 `"mode": "mask"`，Linux 和 WSL2 上的沙箱化命令读取文件的哨兵副本，沙箱代理在对该条目的 `injectHosts` 的出站请求上替换真实值；在 macOS 上，文件在沙箱内不可读。需要 Claude Code v2.1.187 或更高版本，`"mode": "mask"` 需要 v2.1.221 或更高版本。 + +* **Scope**: [`Any file`](#scopes)。Claude Code 从项目 `.claude/settings.json` 和本地 `.claude/settings.local.json` 删除 `mask` 条目。 +* **Type**: 对象数组，每个包含 `path` 和 `"deny"` 或 `"mask"` 的 `mode`，加上可选的 [mask fields for files](#mask-fields-for-files) +* **Default**: 未设置，因此没有凭证文件被保护 + +这隐藏您的 AWS 凭证文件并掩盖 `gh` 主机文件，仅在对 `api.github.com` 的请求上替换真实值： + +```json settings.json theme={null} +{ + "sandbox": { + "credentials": { + "files": [ + { "path": "~/.aws/credentials", "mode": "deny" }, + { "path": "~/.config/gh/hosts.yml", "mode": "mask", "injectHosts": ["api.github.com"] } + ] + } + } +} +``` + +路径使用与 `sandbox.filesystem.*` 设置相同的 [prefixes](#sandbox-path-prefixes)，Claude Code 在会话加载的每个设置范围中合并数组。[Protect credentials](/docs/zh-CN/sandboxing#protect-credentials) 涵盖您使用 `--setting-sources` 排除的源仍然适用的内容。需要 Claude Code v2.1.187 或更高版本；`mask` 条目需要 v2.1.221 或更高版本。 + +`mask` 替换仅通过沙箱代理运行，因此设置 [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) 或 [`allowPlaintextInject`](#sandbox-credentials-allowplaintextinject) 用于纯 HTTP 测试网络。`mask` 适用于单个文件，因此单独列出每个凭证文件。Claude Code 接受但忽略 `deny` 条目上的 `mask` 字段。[Mask credential files](/docs/zh-CN/sandboxing#mask-credential-files) 涵盖遵守哪些设置源以及条目何时回退到 `deny`。 + + + + + + + + + + + + + +

+ 文件的掩盖字段 +

+ +`mask` 条目接受这些可选字段。没有 `extract` 或 `decode`，Claude Code 用一个哨兵替换整个文件内容。在启用文件系统隔离的 macOS 上，Claude Code 在 `extract` 或 `decode` 运行之前将 `mask` 条目应用为 `deny`；请参阅 [Mask credential files](/docs/zh-CN/sandboxing#mask-credential-files)。 + +| 字段 | 类型 | 它做什么 | +| :----------------- | :----------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `extract` | 字符串，至少有一个捕获组的正则表达式 | 仅掩盖每个匹配的第 1 组捕获的文本，因此文件的其余部分保持可解析。设置 `decode` 后，Claude Code 检查每个捕获作为可能的 JWT，而不是直接替换它。需要 v2.1.221 或更高版本 | +| `onExtractNoMatch` | `"warn"`、`"deny"` 或 `"error"`；默认 `"warn"` | 当 `extract` 或 `decode` 找不到要掩盖的内容时会发生什么。`warn` 在沙箱内保持文件可读，`deny` 使其不可读，`error` 停止沙箱设置直到您修复配置。当读取块不被强制执行时，Claude Code 将 `deny` 视为 `error`，因为您 [disable filesystem isolation](/docs/zh-CN/sandboxing#disable-filesystem-isolation) 或 [`sandbox.filesystem.allowRead`](#sandbox-filesystem-allowread) 条目重新打开路径。需要 v2.1.221 或更高版本；`decode` 情况需要 v2.1.224 或更高版本 | +| `decode` | 字符串 `"jwt"` | 在文件中查找 JSON Web Tokens (JWTs)，使用内置模式或设置 `extract` 时，验证每个候选，并用结构有效的假令牌替换它，因此沙箱内解码令牌的代码保持工作。当没有候选验证时，`onExtractNoMatch` 管理结果。需要 v2.1.224 或更高版本 | +| `maskClaims` | 字符串数组，至少一个声明名称；需要 `decode` | 仅掩盖每个验证的 JWT 内的命名顶级有效负载声明并围绕修改的有效负载重建令牌，因此其他声明保持可读。当没有命名声明匹配时，`onExtractNoMatch` 管理结果。需要 v2.1.224 或更高版本 | +| `maskDuplicates` | 布尔值，默认 `false` | 也替换文件中其他地方每个掩盖值的逐字副本，例如粘贴到注释中的秘密。Claude Code 匹配原始子字符串，因此为长的、高熵的秘密保留它。仅在设置 `extract` 或 `decode` 时咨询。需要 v2.1.221 或更高版本 | +| `injectHosts` | 字符串数组，每个是 [`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 也允许的主机 | 缩小沙箱代理替换真实值的主机。未设置时，代理在对 `sandbox.network.allowedDomains` 中每个主机的请求上替换它。需要 v2.1.221 或更高版本 | + +这仅掩盖 `gh` 主机文件中的 `oauth_token` 值，替换文件中它的每个其他副本，如果模式匹配不到任何内容则使文件不可读，并仅在对 `api.github.com` 的请求上替换真实令牌： + +```json settings.json theme={null} +{ + "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` +

+ +保护环境变量免受沙箱化命令。使用 `"mode": "deny"`，Claude Code 从沙箱化命令的环境中删除变量。使用 `"mode": "mask"`，沙箱化命令看到每个会话的哨兵值，沙箱代理在对该条目的 `injectHosts` 的出站请求上替换真实值，因此 `gh` 和 `npm` 等工具保持认证而无需持有真实凭证。需要 Claude Code v2.1.187 或更高版本，`"mode": "mask"` 需要 v2.1.199 或更高版本。 + +* **Scope**: [`Any file`](#scopes)。Claude Code 从项目 `.claude/settings.json` 和本地 `.claude/settings.local.json` 删除 `mask` 条目。 +* **Type**: 对象数组，每个包含 `name` 和 `"deny"` 或 `"mask"` 的 `mode`，加上可选的 [mask fields for environment variables](#mask-fields-for-environment-variables) +* **Default**: 未设置，因此没有环境变量被保护 + +这从沙箱化命令中删除 `NPM_TOKEN` 并掩盖 `GITHUB_TOKEN`，仅在对 `api.github.com` 的请求上替换真实值： + +```json settings.json theme={null} +{ + "sandbox": { + "credentials": { + "envVars": [ + { "name": "NPM_TOKEN", "mode": "deny" }, + { "name": "GITHUB_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] } + ] + } + } +} +``` + +`name` 必须以字母或下划线开头，仅包含字母、数字和下划线。Claude Code 在会话加载的每个设置范围中合并数组，当同一变量同时出现两种模式时应用 `deny`。[Protect credentials](/docs/zh-CN/sandboxing#protect-credentials) 涵盖您使用 `--setting-sources` 排除的源仍然适用的内容。需要 Claude Code v2.1.187 或更高版本；`mask` 条目需要 v2.1.199 或更高版本。 + +`mask` 替换仅通过沙箱代理运行，因此设置 [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) 或 [`allowPlaintextInject`](#sandbox-credentials-allowplaintextinject) 用于纯 HTTP 测试网络；请参阅 [Mask environment variables](/docs/zh-CN/sandboxing#mask-environment-variables)。Claude Code 接受但忽略 `deny` 条目上的 `mask` 字段。 + + + + + + + + + + + +

+ 环境变量的掩盖字段 +

+ +`mask` 条目接受这些可选字段。没有 `extract` 或 `decode`，Claude Code 用一个哨兵替换整个值。`extract` 和 `decode` 不能在同一条目上组合。 + +| 字段 | 类型 | 它做什么 | +| :----------------- | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `extract` | 字符串，至少有一个捕获组的正则表达式 | 仅掩盖每个匹配的第 1 组捕获的文本，例如 `DATABASE_URL` 连接字符串内的密码，因此值的其余部分保持可解析。需要 v2.1.224 或更高版本 | +| `onExtractNoMatch` | `"warn"`、`"deny"` 或 `"error"`；默认 `"warn"`。在带有 `decode` 的条目上，仅接受 `"warn"` | 当 `extract` 匹配不到任何内容时会发生什么。`warn` 未掩盖地传递变量，`deny` 在沙箱内取消设置它，`error` 停止沙箱设置直到您修复配置。需要 v2.1.224 或更高版本 | +| `decode` | 字符串 `"jwt"` | 验证整个值是 JWT 并用结构有效的假令牌替换它，因此沙箱内解码令牌的代码保持工作；代理在出口上替换整个真实令牌。不验证的值未掩盖地传递并带有警告。需要 v2.1.224 或更高版本 | +| `maskClaims` | 字符串数组，至少一个声明名称；需要 `decode` | 仅掩盖解码的 JWT 内的命名顶级有效负载声明并围绕修改的有效负载重建令牌，因此其他声明保持可读。当没有命名声明匹配时，变量未掩盖地传递并带有警告。需要 v2.1.224 或更高版本 | +| `injectHosts` | 字符串数组，每个是 [`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 也允许的主机 | 缩小沙箱代理替换真实值的主机。未设置时，代理在对 `sandbox.network.allowedDomains` 中每个主机的请求上替换它。将 IPv6 目标写为裸压缩地址，例如 `"::1"`，而不是括号形式；请参阅 [IPv6 destinations in `injectHosts`](/docs/zh-CN/sandboxing#ipv6-destinations-in-injecthosts)。需要 v2.1.199 或更高版本 | + +这仅掩盖 `DATABASE_URL` 内的密码，如果模式匹配不到任何内容则取消设置变量，并掩盖 `SERVICE_JWT` 中的 JWT，同时保持除 `api_key` 外的每个声明可读： + +```json settings.json theme={null} +{ + "sandbox": { + "credentials": { + "envVars": [ + { + "name": "DATABASE_URL", + "mode": "mask", + "extract": "://[^:]+:([^@]+)@", + "onExtractNoMatch": "deny" + }, + { + "name": "SERVICE_JWT", + "mode": "mask", + "decode": "jwt", + "maskClaims": ["api_key"] + } + ] + } + } +} +``` + +

+ `sandbox.credentials.allowPlaintextInject` +

+ +允许 `mask` 替换在纯 HTTP 请求以及 TLS 终止的 HTTPS 上。在纯 HTTP 上，上游身份未验证，凭证以明文形式传输，因此在受信任的测试网络外保持关闭。需要 Claude Code v2.1.199 或更高版本。 + +* **Scope**: [`User or managed`](#scopes) +* **Type**: 布尔值 + * `true`: Claude Code 允许 `mask` 替换在纯 HTTP 请求以及 TLS 终止的 HTTPS 上 + * `false`: Claude Code 仅允许 `mask` 替换在 TLS 终止的 HTTPS 上 +* **Default**: `false` + +```json settings.json theme={null} +{ + "sandbox": { + "credentials": { + "allowPlaintextInject": true + } + } +} +``` + +需要 Claude Code v2.1.199 或更高版本。 + +

+ `sandbox.credentials.awsPairs` +

+ +分组掩盖的环境变量，形成一个 AWS 凭证用于 [SigV4 re-signing](/docs/zh-CN/sandboxing#re-sign-aws-requests)，当您的凭证存在于具有非标准名称的变量中时。Claude Code 在您掩盖其整个值时自动链接常规 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 三元组，因此您仅在其他名称时需要此键。需要 Claude Code v2.1.224 或更高版本。 + +* **Scope**: [`User or managed`](#scopes) +* **Type**: 对象数组，每个包含 `accessKeyIdVar`、`secretAccessKeyVar` 和可选的 `sessionTokenVar`，命名 `sandbox.credentials.envVars` 条目 +* **Default**: 未设置，因此仅配对常规三元组 + +这将三个自定义命名的变量链接到一个 AWS 凭证以进行重新签名： + +```json settings.json theme={null} +{ + "sandbox": { + "credentials": { + "awsPairs": [ + { + "accessKeyIdVar": "MY_KEY_ID", + "secretAccessKeyVar": "MY_SECRET_KEY", + "sessionTokenVar": "MY_SESSION_TOKEN" + } + ] + } + } +} +``` + +每个命名的变量必须是 [`sandbox.credentials.envVars`](#sandbox-credentials-envvars) 中的整个值 `mask` 条目，没有 `extract` 或 `decode`，并且只能在所有对中填充一个槽。 + +

+ `sandbox.credentials.sigv4` +

+ +选择沙箱代理对 AWS 请求形式的处理，它 [can't re-sign](/docs/zh-CN/sandboxing#re-sign-aws-requests)：`streaming` 用于 aws-chunked 流上传，`presigned` 用于预签名 URL，`sigv4a` 用于 SigV4A 非对称签名。这仅适用于使用掩盖对的占位符访问密钥 ID 签名的请求。需要 Claude Code v2.1.224 或更高版本。 + +* **Scope**: [`User or managed`](#scopes) +* **Type**: 对象，包含 `streaming`、`presigned` 和 `sigv4a`，每个为以下之一： + * `"deny"`: 代理失败请求 + * `"passthrough"`: 代理转发使用掩盖占位符签名的请求，因此工具接收 AWS 自己的拒绝 +* **Default**: 未设置，因此每种形式都是 `"deny"` + +这转发流上传而不是在代理处失败它们： + +```json settings.json theme={null} +{ + "sandbox": { + "credentials": { + "sigv4": { + "streaming": "passthrough" + } + } + } +} +``` + +使用 `deny`，代理失败请求。使用 `passthrough`，代理转发使用掩盖占位符计算的签名的请求，因此 AWS 拒绝它，调用工具接收 AWS 自己的响应而不是代理错误。 + +

+ `sandbox.network` +

+ +控制沙箱化命令可以到达的主机、端口和套接字。沙箱通过强制执行这些列表的代理路由出站流量；请参阅 [Network isolation](/docs/zh-CN/sandboxing#network-isolation) 了解代理如何决定以及何时提示。 + +* **Scope**: [`Any file`](#scopes)。`strictAllowlist`、`allowManagedDomainsOnly` 和 `tlsTerminate` 从较少的源读取，如其条目所述。 +* **Type**: 对象，包含以下子键 +* **Default**: 未设置，因此没有域被预先允许，沙箱为每个新主机提示 + +这预先允许 GitHub 和 npm，阻止 `uploads.github.com`，并让命令绑定到 localhost： + +```json settings.json theme={null} +{ + "sandbox": { + "network": { + "allowedDomains": ["github.com", "*.npmjs.org"], + "deniedDomains": ["uploads.github.com"], + "allowLocalBinding": true + } + } +} +``` + +Claude Code 在设置范围中合并数组子键并删除重复项，因此项目可以向您的用户列表添加域。`WebFetch(domain:...)` 允许和拒绝 [permission rules](/docs/zh-CN/sandboxing#permission-rules) 馈送相同的允许和拒绝列表。 + +

+ `sandbox.network.allowUnixSockets` +

+ +列出 macOS 上沙箱化命令可以连接到的 Unix 套接字路径。Claude Code 在 Linux 和 WSL2 上忽略此列表，其中 seccomp 过滤器无法检查套接字路径；改为在那里使用 [`allowAllUnixSockets`](#sandbox-network-allowallunixsockets)。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 字符串数组，每个是套接字路径 +* **Default**: 未设置，因此 macOS 沙箱阻止每个 Unix 套接字 + +```json settings.json theme={null} +{ + "sandbox": { + "network": { + "allowUnixSockets": ["~/.ssh/agent-socket"] + } + } +} +``` + +套接字路径可以授予广泛的访问权限：例如，允许 `/var/run/docker.sock` 让沙箱化命令控制 Docker 守护程序。请参阅 [Security limitations](/docs/zh-CN/sandboxing#security-limitations)。 + +

+ `sandbox.network.allowAllUnixSockets` +

+ +让沙箱化命令连接到每个 Unix 套接字。在 Linux 和 WSL2 上，沙箱的 [seccomp filter](/docs/zh-CN/sandboxing#set-up-linux-and-wsl2) 阻止 `socket(AF_UNIX, ...)` 调用，因此这是在那里允许 Unix 套接字的唯一方式。当过滤器缺失时，`/sandbox` 在其 Dependencies 选项卡上报告，沙箱不阻止 Unix 套接字调用。请参阅 [Set up Linux and WSL2](/docs/zh-CN/sandboxing#set-up-linux-and-wsl2) 了解过滤器来自何处。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 布尔值 + * `true`: 沙箱化命令可以连接到每个 Unix 套接字 + * `false`: 沙箱阻止 Unix 套接字连接：在 macOS 上除了 `allowUnixSockets` 中的路径，在 Linux 和 WSL2 上通过 seccomp 过滤器（当存在时） +* **Default**: `false` + +```json settings.json theme={null} +{ + "sandbox": { + "network": { + "allowAllUnixSockets": true + } + } +} +``` + +在 WSL2 上，`true` 也重新打开启动 Windows 二进制文件（如 `cmd.exe` 和 `powershell.exe` ）的互操作套接字。 + +

+ `sandbox.network.allowLocalBinding` +

+ +让 macOS 上的沙箱化命令绑定到 localhost 端口，例如启动开发服务器。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 布尔值 + * `true`: macOS 上的沙箱化命令可以绑定到 localhost 端口 + * `false`: macOS 上的沙箱化命令无法绑定到 localhost 端口 +* **Default**: `false` + +```json settings.json theme={null} +{ + "sandbox": { + "network": { + "allowLocalBinding": true + } + } +} +``` + +

+ `sandbox.network.allowMachLookup` +

+ +列出 macOS 沙箱可能查找的其他 XPC 和 Mach 服务名称。通过 XPC 通信的工具，例如 iOS Simulator 或 Playwright，需要在此处列出其服务。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 字符串数组，每个是服务名称；单个尾部 `*` 匹配前缀，`"*"` 单独匹配每个服务 +* **Default**: 未设置 + +这允许 `com.apple.coresimulator.` 前缀下的每个服务： + +```json settings.json theme={null} +{ + "sandbox": { + "network": { + "allowMachLookup": ["com.apple.coresimulator.*"] + } + } +} +``` + +

+ `sandbox.network.allowedDomains` +

+ +预先允许来自沙箱化命令的出站流量的域，因此沙箱不会为它们提示。通配符（如 `*.example.com` ）匹配子域，可选的 `:port` 后缀将条目限制为一个端口；没有端口的条目匹配每个端口。 + +* **Scope**: [`Any file`](#scopes)。仅当设置 [`allowManagedDomainsOnly`](#sandbox-network-allowmanageddomainsonly) 时的托管设置。 +* **Type**: 字符串数组，每个是域、通配符模式或 IP 文字，带有可选的 `:port` 后缀 +* **Default**: 未设置，因此沙箱在命令首次到达新主机时提示 + +这预先允许 GitHub 在每个端口、每个 npm 子域和一个 API 主机仅在端口 443 上： + +```json settings.json theme={null} +{ + "sandbox": { + "network": { + "allowedDomains": ["github.com", "*.npmjs.org", "api.example.com:443"] + } + } +} +``` + +将 IPv6 文字写成括号形式，带有可选端口：`"[::1]"` 允许每个端口，`"[::1]:443"` 一个端口。括号形式需要 Claude Code v2.1.229 或更高版本。请参阅 [IPv6 addresses in domain lists](/docs/zh-CN/sandboxing#ipv6-addresses-in-domain-lists)。 + +

+ `sandbox.network.deniedDomains` +

+ +阻止来自沙箱化命令的出站流量的域，使用与 [`allowedDomains`](#sandbox-network-alloweddomains) 相同的通配符、端口和 IPv6 语法。被拒绝的域即使 `allowedDomains` 条目也匹配它也保持阻止。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 字符串数组，每个是域、通配符模式或 IP 文字，带有可选的 `:port` 后缀 +* **Default**: 未设置 + +```json settings.json theme={null} +{ + "sandbox": { + "network": { + "deniedDomains": ["sensitive.cloud.example.com"] + } + } +} +``` + +Claude Code 从会话加载的每个设置源合并此列表，即使设置了 `allowManagedDomainsOnly`，因此开发人员总是可以收紧拒绝列表。对于 IPv6 文字，请参阅 [IPv6 addresses in domain lists](/docs/zh-CN/sandboxing#ipv6-addresses-in-domain-lists)。 + +使用标记完全限定域名的尾部点编写的条目，例如 `example.com.`，阻止与 `example.com` 相同的连接。 + +

+ `sandbox.network.strictAllowlist` +

+ +拒绝沙箱化命令访问允许列表外的主机，而不是提示批准。允许列表是 [`allowedDomains`](#sandbox-network-alloweddomains) 加上来自 `WebFetch(domain:...)` 允许规则的域，或仅当设置 [`allowManagedDomainsOnly`](#sandbox-network-allowmanageddomainsonly) 时的托管设置条目。需要 Claude Code v2.1.219 或更高版本。 + +* **Scope**: [`User or managed`](#scopes)。存储库无法打开或关闭它。 +* **Type**: 布尔值 + * `true`: Claude Code 拒绝沙箱化命令访问允许列表外的主机 + * `false`: 除非另一个受信任的设置文件设置 `true`，Claude Code 根据权限模式而不是直接拒绝来决定允许列表外的主机：它在自动模式下运行分类器，在 `dontAsk` 模式下拒绝，在 `bypassPermissions` 模式下允许，在计划模式下当绕过可用时允许，否则询问您 +* **Default**: `false` + +```json settings.json theme={null} +{ + "sandbox": { + "network": { + "strictAllowlist": true + } + } +} +``` + +Claude Code 仅对沙箱化命令强制执行此；进程内工具（如 `WebFetch` ）仍然遵循其 [permission rules](/docs/zh-CN/sandboxing#permission-rules)。当任何遵守的源将其设置为 `true` 时，它保持打开。请参阅 [Network isolation](/docs/zh-CN/sandboxing#network-isolation)。需要 Claude Code v2.1.219 或更高版本。 + +

+ `sandbox.network.allowManagedDomainsOnly` +

+ +将网络允许列表锁定到托管设置定义的内容。Claude Code 然后仅遵守来自托管设置的 `allowedDomains` 和 `WebFetch(domain:...)` 允许规则，忽略来自用户、项目、本地和 `--settings` 设置的域，并自动阻止非允许的域而不是提示。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: 布尔值 + * `true`: Claude Code 仅遵守来自托管设置的 `allowedDomains` 和 `WebFetch(domain:...)` 允许规则，并自动阻止非允许的域而不是提示 + * `false`: 来自用户、项目、本地和 `--settings` 设置的域合并到允许列表中 +* **Default**: `false` + +这将允许列表锁定到 GitHub 和 npm，并忽略开发人员添加的任何域： + +```json managed-settings.json theme={null} +{ + "sandbox": { + "network": { + "allowManagedDomainsOnly": true, + "allowedDomains": ["github.com", "*.npmjs.org"] + } + } +} +``` + +被拒绝的域仍然从会话加载的每个源合并。请参阅 [Keep developers from widening the policy](/docs/zh-CN/sandboxing#keep-developers-from-widening-the-policy)。 + +

+ `sandbox.network.httpProxyPort` +

+ +将沙箱指向您自己的 HTTP 代理而不是 Claude Code 运行的。组织这样做以检查 HTTPS 流量、应用自己的过滤规则或记录每个请求。未设置时，Claude Code 为 HTTP 流量启动自己的代理。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 数字，本地 TCP 端口 +* **Default**: 未设置，因此 Claude Code 运行自己的代理 + +```json settings.json theme={null} +{ + "sandbox": { + "network": { + "httpProxyPort": 8080 + } + } +} +``` + +如果您的代理也应该携带 SOCKS 流量，也设置 [`socksProxyPort`](#sandbox-network-socksproxyport)；仅设置其中一个，Claude Code 仍然为另一个协议运行自己的代理。请参阅 [Custom proxy configuration](/docs/zh-CN/sandboxing#custom-proxy-configuration)。 + +

+ `sandbox.network.socksProxyPort` +

+ +将沙箱指向您自己的 SOCKS5 代理而不是 Claude Code 运行的。未设置时，Claude Code 为 SOCKS 流量启动自己的代理。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 数字，本地 TCP 端口 +* **Default**: 未设置，因此 Claude Code 运行自己的代理 + +```json settings.json theme={null} +{ + "sandbox": { + "network": { + "socksProxyPort": 8081 + } + } +} +``` + +请参阅 [Custom proxy configuration](/docs/zh-CN/sandboxing#custom-proxy-configuration)。 + +

+ `sandbox.network.tlsTerminate` +

+ +使沙箱代理终止 TLS，以便它可以读取 HTTPS 请求的内容。这是实验性的，`mask` [credential substitution](/docs/zh-CN/sandboxing#mask-credentials) 需要它。设置 `{}` 为会话生成临时证书颁发机构，或设置 `caCertPath` 和 `caKeyPath` 以使用您自己的。 + +* **Scope**: [`User or managed`](#scopes)。存储库无法打开它或提供证书颁发机构。 +* **Type**: 对象，包含可选的 `caCertPath` 和 `caKeyPath` 字符串，每个是文件路径 +* **Default**: 未设置，因此代理不终止或检查 TLS + +```json settings.json theme={null} +{ + "sandbox": { + "network": { + "tlsTerminate": {} + } + } +} +``` + +当多个遵守的源设置它时，Claude Code 使用来自最高优先级源的值：托管设置，然后是 `--settings` 标志，然后是用户设置。需要 Claude Code v2.1.199 或更高版本。 + + + +

+ 内存和上下文 +

+ +控制 Claude Code 加载到上下文中的内容、如何压缩以及在何处保存内存和计划。请参阅[管理上下文](/docs/zh-CN/context-window)和[内存](/docs/zh-CN/memory)。 + +

+ `autoCompactEnabled` +

+ +当上下文接近限制时，让 Claude Code [自动压缩对话](/docs/zh-CN/context-window#when-your-context-fills-up)。在 `/config` 中显示为**自动压缩**，在那里切换它会将此键写入您的用户设置。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`: 当上下文接近限制时，Claude Code 自动压缩对话 + * `false`: Claude Code 不自动压缩 +* **Default**: `true` +* **Per-session overrides**: [`DISABLE_AUTO_COMPACT`](/docs/zh-CN/env-vars) 为一个会话关闭自动压缩；两者中任何一个关闭它，另一个就无法将其打开 + +```json settings.json theme={null} +{ + "autoCompactEnabled": false +} +``` + +手动 `/compact` 命令在自动压缩关闭时继续工作。 + +

+ `autoCompactWindow` +

+ +设置在 Claude Code [自动压缩](/docs/zh-CN/context-window#when-your-context-fills-up)之前上下文窗口的填充程度。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 令牌数，从 `100000` 到 `1000000`。Claude Code 将值限制在您的模型的上下文窗口；[模型概览](https://platform.claude.com/docs/en/about-claude/models/overview)列出了每个模型的窗口 +* **Default**: 未设置，因此 Claude Code 选择为您的模型调整的窗口 +* **Per-session overrides**: [`--autocompact`](/docs/zh-CN/cli-reference#cli-flags) 对一个会话优先于此键，[`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/zh-CN/env-vars) 优先于两者 + +```json settings.json theme={null} +{ + "autoCompactWindow": 500000 +} +``` + +使用 [`/autocompact`](/docs/zh-CN/commands#all-commands) 命令设置它，该命令将此键写入您的用户设置。[设置自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)涵盖了命令、标志、变量和设置如何相互作用。 + +

+ `autoMemoryDirectory` +

+ +将[自动内存](/docs/zh-CN/memory#storage-location)存储在您选择的目录中，而不是每个项目的默认值。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 字符串，绝对路径或 `~/` 前缀的目录路径 +* **Default**: 未设置，因此 Claude Code 使用 `~/.claude/projects//memory/` + +```json settings.json theme={null} +{ + "autoMemoryDirectory": "~/my-memory-dir" +} +``` + +从项目或本地设置中，Claude Code 在与 [hooks 相同的工作区信任规则](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)下遵守此键，因为克隆的存储库可以提供这些文件。 + +

+ `autoMemoryEnabled` +

+ +打开或关闭[自动内存](/docs/zh-CN/memory#enable-or-disable-auto-memory)。当为 `false` 时，Claude 不会从自动内存目录读取或写入。您也可以在会话期间使用 `/memory` 切换它，这会将此键写入您的用户设置。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`: 与未设置相同；自动内存保持打开，除非优先于此键的内容为会话关闭它，例如 `--bare`、安全模式或 `CLAUDE_CODE_DISABLE_AUTO_MEMORY` + * `false`: Claude 不会从自动内存目录读取或写入 +* **Default**: `true` +* **Per-session overrides**: [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/docs/zh-CN/env-vars) 对一个会话优先于此键，无论哪个方向 + +```json settings.json theme={null} +{ + "autoMemoryEnabled": false +} +``` + +

+ `bashOutputMaxChars` +

+ +设置成功的 Bash 或 PowerShell 命令的[输出 Claude 内联接收](/docs/zh-CN/tools-reference#output-limits)的字符数。当输出超过限制时，Claude Code 将其保存到文件，Claude 接收简短预览加文件路径。当命令输出（例如详细构建或完整测试套件日志）经常超过默认值且您希望 Claude 在不打开文件的情况下读取它时，提高限制。需要 Claude Code v2.1.261 或更高版本。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 字符数，正整数。Claude Code 将值限制在 `4000` 到 `128000` 范围内 +* **Default**: 未设置，因此 Claude 内联接收最多 30,000 个字符 + +```json settings.json theme={null} +{ + "bashOutputMaxChars": 100000 +} +``` + +设置此键时，Claude Code 忽略 [`BASH_MAX_OUTPUT_LENGTH`](/docs/zh-CN/env-vars) 环境变量。 + +

+ `claudeMd` +

+ +注入 CLAUDE.md 风格的说明作为组织管理的内存，无需部署单独的文件。Claude Code 将文本作为托管内存条目加载，位于用户和项目 CLAUDE.md 文件之前。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: 字符串，CLAUDE.md 文件的文本；按照您编写文件的方式编写，包括 Markdown，行中断为 `\n` +* **Default**: 未设置 + +此示例将两个规则部署为简短的 Markdown 列表： + +```json managed-settings.json theme={null} +{ + "claudeMd": "# Engineering rules\n\n- Always run make lint before committing.\n- Never push directly to main." +} +``` + +请参阅[部署组织范围的 CLAUDE.md](/docs/zh-CN/memory#deploy-organization-wide-claude-md)。 + +

+ `claudeMdExcludes` +

+ +当 Claude Code 加载[内存](/docs/zh-CN/memory#exclude-specific-claude-md-files)时跳过特定的 `CLAUDE.md` 文件。在大型单体仓库中，使用它跳过来自与您的工作无关的其他团队的 CLAUDE.md 文件；大型代码库指南中的[排除无关的 CLAUDE.md 文件](/docs/zh-CN/large-codebases#exclude-irrelevant-claude-md-files)演示了该情况。模式与绝对文件路径匹配。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 字符串数组，每个都是 glob 模式或绝对路径 +* **Default**: 未设置，因此 Claude Code 加载它找到的每个 CLAUDE.md + +```json settings.json theme={null} +{ + "claudeMdExcludes": ["**/vendor/**/CLAUDE.md"] +} +``` + +排除仅适用于用户、项目和本地内存文件；托管策略 CLAUDE.md 文件无法被排除。 + + + +

+ `env` +

+ +为每个会话和 Claude Code 从中启动的子进程设置环境变量。[环境变量参考](/docs/zh-CN/env-vars)中的任何变量都可以放在这里，这是如何将其应用于每个会话或向您的团队推出的方式。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 将变量名映射到字符串值的对象 +* **Default**: 未设置 + +此示例关闭自动压缩并通过代理路由 API 请求： + +```json settings.json theme={null} +{ + "env": { + "DISABLE_AUTO_COMPACT": "1", + "ANTHROPIC_BASE_URL": "https://proxy.example.com" + } +} +``` + +

+ `env` 值如何与您的 shell 交互 +

+ +* 此处的值覆盖在您的 shell 中导出的相同变量，当多个设置文件设置一个变量时，[最高优先级](/docs/zh-CN/settings#settings-precedence)的值适用。 +* 要取消 shell 导出，将变量设置为 `""`。Claude Code 将空值视为提供程序选择的未设置，子进程继承空值。 +* `NO_COLOR` 和 `FORCE_COLOR` 在此处设置仅到达子进程。要更改 Claude Code 自己的界面颜色，请在启动 `claude` 之前在您的 shell 中设置它们。 +* 此处的值是设置文件中的纯文本，到达 Claude Code 启动的每个子进程。对于轮换的 OTLP 承载令牌，使用 [`otelHeadersHelper`](#otelheadershelper)；对于 API 凭证，使用 [`apiKeyHelper`](#apikeyhelper)。 + +

+ Claude Code 何时应用 `env` 值 +

+ +* 从用户设置、`--settings` 和托管设置：在启动时，以及在运行会话中当保存的更改改变合并的 `env` 时。 +* 从项目和本地设置：在您信任工作区后，或在 `-p` 模式下启动时（从不显示信任对话），以及当保存的更改改变合并的 `env` 时。 +* Claude Code 分类为安全的变量，例如模型选择、超时和限制、功能切换和遥测设置：在启动时从每个设置文件，除了[项目和本地设置无法设置的变量](#variables-claude-code-ignores-in-env)。 +* 在 v2.1.246 或更高版本上使用 `/cd` [移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory)后：新目录的项目和本地 `env` 值，在前一个目录的基础上。 + +

+ Claude Code 在 `env` 中忽略的变量 +

+ +* 项目和本地设置无法设置已检出的存储库不应控制的变量；改为在您的 shell、用户设置或托管设置中设置这些变量。Claude Code 删除每个变量并记录您可以使用 `claude --debug` 看到的警告。它们包括： + + * 选择 Claude Code 存储或写入其自己文件的位置的变量：`CLAUDE_CONFIG_DIR`、`CLAUDE_CODE_TMPDIR` 和操作系统目录变量，例如 `HOME`、`TMPDIR`、`TMP`、`TEMP` 和 `XDG_*` 系列。 + * 导出会话内容的变量：[`OTEL_LOG_RAW_API_BODIES`](/docs/zh-CN/env-vars#variables) 和详细的 beta 跟踪对 `ENABLE_BETA_TRACING_DETAILED` 和 `BETA_TRACING_ENDPOINT`。 + * 改变 Claude Code 如何启动或同步的变量，例如 `CLAUDE_CODE_PROCESS_WRAPPER`、`CLAUDE_CODE_SYNC_SKILLS`、`CLAUDE_CODE_SYNC_PLUGINS`、`CLAUDE_CODE_PLUGIN_CACHE_DIR` 和 `CLAUDE_CODE_PLUGIN_SEED_DIR`。 + + 在 v2.1.251 之前，项目和本地设置可以设置此列表命名的每个变量，除了 `HOME`、`XDG_CONFIG_HOME` 和改变 Claude Code 如何启动或同步的变量。 +* Claude Code 的托管环境拥有的身份变量，例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`，从每个文件中被忽略。 +* [`CLAUDE_CODE_MESSAGING_SOCKET` 和 `CLAUDE_CODE_MESSAGING_TOKEN`](/docs/zh-CN/env-vars#variables)，Claude Code 自己导出的，从每个文件中被忽略。忽略套接字变量需要 Claude Code v2.1.224 或更高版本，忽略令牌需要 v2.1.228 或更高版本。 +* [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/zh-CN/sessions#name-the-project-directory-yourself)，Claude Code 仅从启动环境读取，从每个文件中被忽略；需要 v2.1.234 或更高版本。 +* [`CLAUDE_CODE_RESTRICTED`](/docs/zh-CN/env-vars#variables)，Claude Code 仅从启动环境读取，从每个文件中被忽略。 + +

+ `fileCheckpointingEnabled` +

+ +让 Claude Code 在每次编辑前快照文件，以便 [`/rewind`](/docs/zh-CN/checkpointing) 可以恢复它们。在 `/config` 中显示为**回退代码（检查点）**，在那里切换它会将此键写入您的用户设置。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`: Claude Code 在每次编辑前快照文件，以便 `/rewind` 可以恢复它们 + * `false`: Claude Code 不快照文件，因此 `/rewind` 无法恢复它们 +* **Default**: `true` +* **Per-session overrides**: [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/docs/zh-CN/env-vars) 为一个会话关闭检查点；两者中任何一个关闭它，另一个就无法将其打开 + +```json settings.json theme={null} +{ + "fileCheckpointingEnabled": false +} +``` + +在 `-p` 运行或 Agent SDK 会话中，Claude Code 忽略此键。SDK 使用其 `enableFileCheckpointing` 选项打开检查点，裸 `-p` 运行需要 `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true`。请参阅 [Agent SDK 中的文件检查点](/docs/zh-CN/agent-sdk/file-checkpointing)。 + +

+ `plansDirectory` +

+ +选择 Claude Code 在[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)中写入的计划文件的存储位置。Claude Code 相对于项目根目录解析路径，当路径解析到项目外时保持默认值。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 字符串，相对于项目根目录的路径 +* **Default**: 未设置，因此 Claude Code 使用 `~/.claude/plans` + +```json settings.json theme={null} +{ + "plansDirectory": "./plans" +} +``` + +

+ `skillListingBudgetFraction` +

+ +每个回合，Claude 看到[您的技能列表](/docs/zh-CN/skills#skill-descriptions-are-cut-short)及其描述，Claude Code 将该列表限制在上下文窗口的一部分。当列表超过上限时，Claude Code 保留每个技能的名称，但删除使用最少的技能的描述，因此 Claude 仍然可以调用这些技能，但不太可能自己选择一个。提高此键以保持更多描述可见，代价是每个回合更多上下文。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 数字，大于 `0` 且最多 `1` 的分数 +* **Default**: `0.01`，保留 1% 的上下文窗口 + +```json settings.json theme={null} +{ + "skillListingBudgetFraction": 0.02 +} +``` + +要查看列表使用多少上下文以及哪些技能贡献最多，请运行 `/doctor`。 + +

+ `skillListingMaxDescChars` +

+ +每个回合，Claude 看到[您的技能列表](/docs/zh-CN/skills#skill-descriptions-are-cut-short)，显示每个技能的 `description` 和 `when_to_use` 文本。此键限制 Claude Code 每个技能显示多少字符的该文本；较长的文本在上限处被切割。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 字符数，正整数 +* **Default**: `1536` + +```json settings.json theme={null} +{ + "skillListingMaxDescChars": 2048 +} +``` + +提高它以保持长描述完整，代价是每个回合更多上下文；降低它以在 [`skillListingBudgetFraction`](#skilllistingbudgetfraction) 下适应更多技能。 + +

+ `taskOutputMaxChars` +

+ +设置[后台任务](/docs/zh-CN/tools-reference#background-commands)的输出字符数，当 Claude 使用 `TaskOutput` 工具读取任务时 Claude 内联接收。当完成的任务的输出更长时，Claude 接收最近的字符。当您的后台任务经常产生比默认值更多的输出时，提高限制。需要 Claude Code v2.1.261 或更高版本。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 字符数，正整数。Claude Code 将值限制在 `4000` 到 `128000` 范围内 +* **Default**: 未设置，因此 Claude 内联接收最多 32,000 个字符 + +```json settings.json theme={null} +{ + "taskOutputMaxChars": 100000 +} +``` + +设置此键时，Claude Code 忽略 [`TASK_MAX_OUTPUT_LENGTH`](/docs/zh-CN/env-vars) 环境变量。 + +

+ 界面和终端 +

+ +改变 Claude Code 在终端中的外观和行为：主题、编辑器模式、状态行、加载动画、会话内通知和无障碍功能。请参阅[终端配置](/docs/zh-CN/terminal-config)。 + +

+ `askUserQuestionTimeout` +

+ +让未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框在空闲一段时间后自动继续，提交您已选择的任何选项。当您离开时设置此项，让 Claude 在没有您的情况下继续。使用默认设置时，问题会等待您回答。需要 Claude Code v2.1.200 或更高版本。 + +* **Scope**: [`User or managed`](#scopes) +* **Type**: string，值为 `"60s"`、`"5m"`、`"10m"` 或 `"never"` 之一 +* **Default**: `"never"` +* **Per-session overrides**: [`CLAUDE_AFK_TIMEOUT_MS`](/docs/zh-CN/env-vars) 在单个会话中优先于此键 + +```json settings.json theme={null} +{ + "askUserQuestionTimeout": "5m" +} +``` + +在 `/config` 中显示为**问题自动继续超时**，它将此键写入用户设置；当托管设置或 `--settings` 标志设置此键时，Claude Code 会隐藏该行。需要 Claude Code v2.1.200 或更高版本。 + +

+ `autoContinueAtUsageLimit` +

+ +在 claude.ai 使用限制停止您的会话后，在打开的会话中等待，并在重置后自动继续任务。请参阅[关闭自动继续](/docs/zh-CN/interactive-mode#turn-automatic-continue-off)。需要 Claude Code v2.1.234 或更高版本。 + +* **Scope**: [`User or managed`](#scopes)。仅从用户设置、`--settings` 和托管设置中读取。当这些都没有设置此键时，设置此键的项目或本地设置文件会关闭该功能，而不是被忽略。 +* **Type**: Boolean + * `true`：在 claude.ai 使用限制停止您的会话后，Claude Code 在打开的会话中等待，并在重置后自动继续任务 + * `false`：Claude Code 不会自动启动等待。您仍然可以从使用限制选项菜单[自己启动等待](/docs/zh-CN/interactive-mode#start-a-wait-yourself) +* **Default**: `true` + +```json settings.json theme={null} +{ + "autoContinueAtUsageLimit": false +} +``` + +在 `/config` 中显示为**在使用限制时自动继续**，它将此键写入用户设置；当托管设置或 `--settings` 标志设置此键时，Claude Code 会隐藏该行。 + +

+ `autoScrollEnabled` +

+ +在[全屏渲染](/docs/zh-CN/fullscreen)中跟随新输出到对话底部。关闭它以在 Claude 继续工作时保持您滚动的位置；权限提示仍会滚动到视图中。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`：对话跟随新输出到底部 + * `false`：当 Claude 继续工作时，您保持在滚动的位置；权限提示仍会显示在记录下方 +* **Default**: `true` + +```json settings.json theme={null} +{ + "autoScrollEnabled": false +} +``` + +在全屏渲染打开时，在 `/config` 中显示为**自动滚动**，它将此键写入用户设置。 + +

+ `axScreenReader` +

+ +渲染屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。屏幕阅读器模式使用经典渲染器，因此在它处于活动状态时 `tui` 设置无效；附加的[后台会话](/docs/zh-CN/agent-view)仍会全屏渲染。需要 Claude Code v2.1.181 或更高版本。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`：Claude Code 使用经典渲染器渲染没有装饰性边框或动画的平面文本 + * `false`：Claude Code 正常渲染 +* **Default**: unset，所以屏幕阅读器模式关闭 +* **Per-session overrides**: [`--ax-screen-reader`](/docs/zh-CN/cli-reference#cli-flags) 优先于 [`CLAUDE_AX_SCREEN_READER`](/docs/zh-CN/env-vars)，两者都优先于单个会话的此键 + +```json settings.json theme={null} +{ + "axScreenReader": true +} +``` + +需要 Claude Code v2.1.181 或更高版本。 + +

+ `companyAnnouncements` +

+ +在启动时向用户显示您组织的公告。当您列出多个公告时，Claude Code 为每个会话随机选择一个；在某人的首次启动时，它显示第一个条目。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: array of strings +* **Default**: unset，所以不显示公告 + +```json settings.json theme={null} +{ + "companyAnnouncements": [ + "欢迎来到 Acme Corp！请在 docs.example.com 查看我们的代码指南" + ] +} +``` + +

+ `defaultShell` +

+ +选择 Bash 或 PowerShell 是否运行您在输入框中使用 [`!` 前缀](/docs/zh-CN/interactive-mode#shell-mode-with-prefix)键入的 shell 命令，以及 Claude Code 直接运行并添加到会话的命令。 + +`"powershell"` 仅在 [PowerShell tool](/docs/zh-CN/tools-reference#powershell-tool) 打开时有效。该工具在没有 Git Bash 的 Windows 上默认打开，在带有 Git Bash 的 Windows 上对于 claude.ai 和 Console 账户默认打开。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 会话中，以及在 macOS、Linux 和 WSL 上，设置 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` 以打开该工具。将该变量设置为 `0` 以关闭该工具。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，值为以下之一： + * `"bash"`：Claude Code 在 Bash 中运行您的 `!` 命令 + * `"powershell"`：Claude Code 在 PowerShell 中运行您的 `!` 命令 +* **Default**: `"bash"`，或在 Bash 不可用时在 Windows 上为 `"powershell"` + +```json settings.json theme={null} +{ + "defaultShell": "powershell" +} +``` + +如果您指定的 shell 不可用，Claude Code 会使用另一个：当 PowerShell 工具关闭时 `"powershell"` 回退到 Bash，当 Bash 未安装时 `"bash"` 回退到 PowerShell。 + +

+ `dialogExpiry` +

+ +为 Claude Code [转发给远程客户端](/docs/zh-CN/remote-control#limitations)的对话框（例如远程控制或 SDK 主机）以及[保留的跨会话消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)的批准对话框设置截止时间。在 Claude Code v2.1.236 或更高版本上，相同的截止时间限制了会话中可能没有人在终端的中期 [Fable 使用额度同意提示](/docs/zh-CN/model-config#fable-and-usage-credits)。当在截止时间前没有答案到达时，Claude Code 取消对话框并继续使用其无操作默认值。需要 Claude Code v2.1.224 或更高版本。 + +* **Scope**: [`User or managed`](#scopes) +* **Type**: string，值为 `"60s"`、`"5m"`、`"10m"` 或 `"never"` 之一，后者禁用截止时间 +* **Default**: `"5m"` +* **Per-session overrides**: [`CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS`](/docs/zh-CN/env-vars) 在单个会话中优先于此键 + +```json settings.json theme={null} +{ + "dialogExpiry": "10m" +} +``` + +权限提示和 [`AskUserQuestion`](/docs/zh-CN/tools-reference#askuserquestion-tool-behavior) 问题使用它们自己的流程，不受此截止时间管制。在 `/config` 中显示为**对话框过期**，它将此键写入用户设置；该行需要 Claude Code v2.1.232 或更高版本，当托管设置或 `--settings` 标志设置此键时，Claude Code 会隐藏它。 + +

+ `editorMode` +

+ +为输入提示选择快捷键绑定模式。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，值为以下之一： + * `"normal"`：提示输入中的标准快捷键 + * `"vim"`：vim 风格编辑，具有 NORMAL、INSERT 和 VISUAL 模式 +* **Default**: `"normal"` + +```json settings.json theme={null} +{ + "editorMode": "vim" +} +``` + +在 `/config` 中显示为**编辑器模式**，它将此键写入用户设置。 + +

+ `emojiCompletionEnabled` +

+ +当您在提示输入中键入 `:` 加上速记代码时显示表情符号建议，并将完成的速记代码（如 `:heart:`）替换为其表情符号。将其设置为 `false` 以关闭两者。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`：Claude Code 在 `:` 后显示表情符号建议，并将完成的速记代码替换为其表情符号 + * `false`：Claude Code 既不建议表情符号也不替换速记代码 +* **Default**: `true` + +```json settings.json theme={null} +{ + "emojiCompletionEnabled": false +} +``` + +请参阅[表情符号速记代码](/docs/zh-CN/interactive-mode#emoji-shortcodes)。需要 Claude Code v2.1.217 或更高版本。 + + + +

+ `fileSuggestion` +

+ +运行您自己的命令来提供 `@` 文件路径自动完成，而不是使用内置文件建议。内置建议使用快速文件系统遍历；大型单体仓库可能会通过项目特定的索引（如预构建的文件索引）做得更好。 + +* **Scope**: [`Any file`](#scopes)。在[状态行和文件建议门](#status-line-and-file-suggestion-gates)下，Claude Code 关闭命令或仅运行托管值，并跳过您的而不发出警告。 +* **Type**: 对象，包含 `type`（始终为 `"command"`）和 `command`（要运行的 shell 命令） +* **Default**: unset，所以 Claude Code 使用内置文件建议 + +```json settings.json theme={null} +{ + "fileSuggestion": { + "type": "command", + "command": "~/.claude/file-suggestion.sh" + } +} +``` + +保存后，在提示中键入 `@` 后跟部分路径：建议来自您命令的输出。 + +

+ 命令输入和输出 +

+ +Claude Code 使用与 [hooks](/docs/zh-CN/hooks) 相同的环境变量运行命令，包括 `CLAUDE_PROJECT_DIR`，并在五秒后停止等待。该命令在 stdin 上接收 JSON，其中 `query` 字段包含您到目前为止键入的内容： + +```json theme={null} +{"query": "src/comp"} +``` + +将换行符分隔的文件路径打印到 stdout。Claude Code 最多显示 15 个： + +```text theme={null} +src/components/Button.tsx +src/components/Modal.tsx +src/components/Form.tsx +``` + +以下脚本读取查询并将其传递给存储库文件索引： + +```bash theme={null} +#!/bin/bash +query=$(cat | jq -r '.query') +# 用您自己的文件搜索命令替换 your-repo-file-index +your-repo-file-index --query "$query" | head -20 +``` + + + +

+ `footerLinksRegexes` +

+ +当正则表达式匹配转向输出时在输入框下方的页脚中渲染额外的可点击徽章：工具结果，包括文件内容和获取的页面，以及 Claude 自己的响应。使用它将项目 CLI 打印的 ID（如审查工具和问题跟踪器）转换为会话链接。需要 Claude Code v2.1.176 或更高版本。 + +* **Scope**: [`User or managed`](#scopes) +* **Type**: 对象数组，每个对象的 `type` 设置为 `"regex"`、`pattern` 正则表达式、`url` 模板和可选的 `label`；`url` 和 `label` 中的 `{name}` 占位符从 `pattern` 中的命名捕获组填充 +* **Default**: unset，所以不渲染徽章 + +此示例匹配问题键（如 `PROJ-1234`）并从捕获的键构建每个链接： + +```json settings.json theme={null} +{ + "footerLinksRegexes": [ + { + "type": "regex", + "pattern": "\\b(?PROJ-\\d+)\\b", + "url": "https://issues.example.com/browse/{key}", + "label": "{key}" + } + ] +} +``` + +配置此项后，当 `PROJ-1234` 出现在工具结果或 Claude 的回复中时，页脚中会出现一个 `PROJ-1234` 徽章，链接到 `https://issues.example.com/browse/PROJ-1234`。需要 Claude Code v2.1.176 或更高版本。 + +

+ 徽章约束 +

+ +每个条目的 URL、标签和徽章计数受以下限制： + +| 约束 | 行为 | +| :----- | :--------------------------------------------------------------------------------------------------------------------------------------------- | +| URL 源 | 捕获的值是 URL 编码的，构造的 URL 必须共享模板的字面源。捕获可以填充路径段或查询值，但不能改变链接指向的位置 | +| URL 长度 | 长于 2048 个字符的构造 URL 被丢弃 | +| URL 方案 | 必须是 `https`、`http` 或公认的编辑器或工作区深层链接方案：`vscode`、`vscode-insiders`、`cursor`、`windsurf`、`zed`、`jetbrains`、`idea`、`slack`、`linear`、`notion`、`figma` | +| 标签 | 默认为匹配的文本，截断为 28 个显示列 | +| 徽章计数 | 最多渲染 5 个徽章。最旧的被较新的匹配替换，`/clear` 删除它们 | + +当转向完成时，Claude Code 在主线程上将每个条目的 `pattern` 正则表达式与转向输出匹配，因此缓慢的正则表达式会阻止 UI 直到完成。嵌套量词（如 `(a+)+$`）对某些输入可能需要指数级长的时间并冻结会话，因此保持每个 `pattern` 线性并避免嵌套 `+` 或 `*`。 + +页脚徽章与[自定义状态行](/docs/zh-CN/statusline)一起渲染（当配置了一个时）；两者都不替换另一个。使用状态行来获得从会话数据计算自己内容的脚本驱动行，使用页脚徽章将对话中的 ID 转换为链接而无需脚本。 + +

+ `keybindingFlavor` +

+ + + 自 v2.1.261 起已弃用，无效。提示的单词编辑键始终[遵循 readline 约定](/docs/zh-CN/interactive-mode#make-ctrl-w-delete-back-to-whitespace)，如在 Bash 中一样。Claude Code 仍然接受 `keybindingFlavor`，因此设置它的设置文件保持有效。 + + +在 v2.1.238 到 v2.1.260 中，将其设置为 `"readline"` 使 `Ctrl+W` 删除回到前一个空格而不仅仅是前一个单词。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，`"classic"` 或 `"readline"` +* **Default**: unset + +

+ `prefersReducedMotion` +

+ +减少或关闭界面动画，如加载动画、闪烁和闪光效果。在 `/config` 中显示为**减少动画**。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`：Claude Code 减少或关闭界面动画，如加载动画、闪烁和闪光效果 + * `false`：与 unset 相同；Claude Code 显示其动画 +* **Default**: `false` + +```json settings.json theme={null} +{ + "prefersReducedMotion": true +} +``` + +

+ `promptSuggestionEnabled` +

+ +显示或隐藏[提示建议](/docs/zh-CN/interactive-mode#prompt-suggestions)，即在您的提示输入中出现的灰显预测。将其设置为 `false`，或在 `/config` 中关闭**提示建议**，以隐藏它们。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`：您在提示输入中看到提示建议 + * `false`：Claude Code 隐藏提示建议 +* **Default**: `true` +* **Per-session overrides**: [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](/docs/zh-CN/env-vars) 在单个会话中优先于此键 + +```json settings.json theme={null} +{ + "promptSuggestionEnabled": false +} +``` + +提示建议需要启用了遥测的 claude.ai 或 Console 账户。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，或关闭遥测时（如通过 [`DISABLE_TELEMETRY`](/docs/zh-CN/env-vars)），此键无效，仅 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=1` 打开它们。 + +

+ `respectGitignore` +

+ +控制 `@` 文件选择器是否排除与 `.gitignore` 模式匹配的文件。在 `/config` 中显示为**在文件选择器中尊重 .gitignore**。 + +* **Scope**: [`Any file`](#scopes)。当没有设置文件设置它时，Claude Code 回退到 `~/.claude.json` 中的 `respectGitignore`，这是 `/config` 切换写入的。 +* **Type**: Boolean + * `true`：`@` 文件选择器排除与 `.gitignore` 模式匹配的文件 + * `false`：`@` 文件选择器包括与 `.gitignore` 模式匹配的文件 +* **Default**: `true` + +```json settings.json theme={null} +{ + "respectGitignore": false +} +``` + +

+ `respondToBashCommands` +

+ +选择在您使用输入框中的 [`!` 前缀](/docs/zh-CN/interactive-mode#shell-mode-with-prefix)运行 shell 命令后 Claude 是否响应。默认情况下，Claude Code 将命令的输出添加到对话中，Claude 对其进行回复。将此键设置为 `false` 以将输出添加到上下文而不进行回复，以便您可以运行多个命令并一起询问它们。需要 Claude Code v2.1.186 或更高版本。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`：Claude Code 将命令的输出添加到对话中，Claude 对其进行回复 + * `false`：Claude Code 将输出添加到上下文而不进行回复 +* **Default**: `true` + +```json settings.json theme={null} +{ + "respondToBashCommands": false +} +``` + +请参阅[使用 `!` 前缀的 Shell 模式](/docs/zh-CN/interactive-mode#shell-mode-with-prefix)。需要 Claude Code v2.1.186 或更高版本。 + +

+ `showClearContextOnPlanAccept` +

+ +当 Claude 在[计划模式](/docs/zh-CN/permission-modes#review-and-approve-a-plan)中完成计划时，它显示一个批准菜单。规划可能会使用大量上下文，因此此键向该菜单添加第一个选项**是的，清除上下文并…**，它批准计划、清除对话上下文并仅从计划开始实施。标签的其余部分命名会话继续的权限模式，并显示规划使用了多少上下文。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`：计划批准菜单获得第一个选项**是的，清除上下文并…**，它批准计划并清除对话上下文 + * `false`：计划批准菜单不显示清除上下文选项 +* **Default**: `false` + +```json settings.json theme={null} +{ + "showClearContextOnPlanAccept": true +} +``` + +

+ `showTurnDuration` +

+ +显示或隐藏每个响应后的转向持续时间消息，如"Cooked for 1m 6s · done 6:05 PM"。"done"后的时钟显示转向何时完成；[`timeFormat`](#timeformat) 和 [`timeZone`](#timezone) 控制其格式和区域。在 `/config` 中显示为**显示转向持续时间**。 + +* **Scope**: [`Any file`](#scopes)。当没有设置文件设置它时，来自较旧版本的 `~/.claude.json` 中的值适用。 +* **Type**: Boolean + * `true`：您在每个响应后看到转向持续时间消息 + * `false`：Claude Code 隐藏转向持续时间消息 +* **Default**: `true` + +```json settings.json theme={null} +{ + "showTurnDuration": false +} +``` + +

+ `spellcheck` +

+ +在您键入时在提示输入中为拼写错误的单词加下划线，使用您安装的拼写检查器。Claude Code 仅检查输入框中的文本。[在您键入时检查拼写](/docs/zh-CN/interactive-mode#check-spelling-as-you-type)涵盖安装 aspell、hunspell 或 ispell 以及检查器涵盖的内容。需要 Claude Code v2.1.235 或更高版本。 + +* **Scope**: [`User or managed`](#scopes)。设置它的最高层的块整体应用。 +* **Type**: 对象，包含 `enabled`（Boolean）、`checker`（`"aspell"`、`"hunspell"`、`"ispell"` 或 `"auto"`）、`language`（字符串，传递给检查器作为其字典名称）和 `color`（字符串，终端颜色名称、`#rrggbb`、`rgb(r,g,b)`、`ansi256(n)` 或 `ansi:`） +* **Default**: unset，所以拼写检查关闭；`checker` 默认为 `"auto"`，`PATH` 上找到的前三个之一；`language` 默认为检查器自己的字典；`color` 默认为主题的错误颜色 + +```json settings.json theme={null} +{ + "spellcheck": { "enabled": true, "language": "en_GB" } +} +``` + +

+ `spinnerTipsEnabled` +

+ +当 Claude 工作时，加载动画行轮换显示关于 Claude Code 功能的短提示，如"使用计划模式为复杂请求做准备，然后再进行更改。按 Shift+Tab 两次以启用。"将此键设置为 `false` 以隐藏它们。在 `/config` 中显示为**显示提示**。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`：当 Claude 工作时，您在加载动画中看到提示 + * `false`：Claude Code 隐藏加载动画提示 +* **Default**: `true` + +```json settings.json theme={null} +{ + "spinnerTipsEnabled": false +} +``` + +

+ `spinnerTipsOverride` +

+ +将您自己的提示添加到 Claude Code 在 Claude 工作时显示的[加载动画提示](#spinnertipsenabled)，或用您的提示替换内置提示。Claude Code 将您的提示放在与内置提示相同的轮换中：它选择未显示时间最长的提示，跳过仍在冷却期中的提示，并通过优先级打破平局。 + +如果您将 [`spinnerTipsEnabled`](#spinnertipsenabled) 设置为 `false`，Claude Code 会隐藏所有提示，包括您的。 + +* **Scope**: [`Any file`](#scopes)。Claude Code 从用户设置、`--settings` 标志和托管设置中尊重提示对象、`tipsFile`、`label` 和 `excludeDefault`；从项目和本地设置中，它仅读取纯字符串提示。 +* **Type**: 对象，包含 `tips`、`tipsFile`、`label` 和 `excludeDefault` 字段，每个都是可选的 +* **Default**: unset，所以 Claude Code 仅显示内置提示 + +提示对象、`tipsFile`、`label` 和 Scope 行的规则（项目和本地设置仅贡献纯字符串）需要 Claude Code v2.1.247 或更高版本。在较早的版本上，项目或本地文件的 `excludeDefault` 也适用。 + +每个 `tips` 条目是纯字符串或具有这些字段的对象： + +| 字段 | 必需 | 描述 | +| :----------------- | :- | :--------------------------------------------------------------------------------------------------------- | +| `id` | 是 | 最多 64 个字母、数字、`.`、`_` 或 `-`。Claude Code 在其上键入提示的显示历史，因此提示的冷却期在重新排序列表后仍然存在。在两个具有相同 id 的条目中，Claude Code 使用第一个 | +| `text` | 是 | 提示，最多 500 个字符的一行。Claude Code 剥离 ANSI 转义和控制字符，并折叠空格 | +| `cooldownSessions` | 否 | Claude Code 在再次显示提示之前等待的会话数，`0` 到 `1000`，默认 `0` | +| `priority` | 否 | 在未显示时间相同的提示中的顺序，较高的优先，`-10` 到 `10`，默认 `0` | + +Claude Code 将纯字符串读取为具有这些默认值和基于位置的 id 的提示，因此当您重新排序列表时其显示历史重置。给提示一个 `id` 以在编辑中保持其历史。 + +Claude Code 在 `tips` 和 `tipsFile` 中最多读取 200 个提示，并用调试警告丢弃无效条目，而不是拒绝设置文件。 + +使用其余字段来命名提示文件、设置前缀和隐藏内置提示： + +* `tipsFile`：指向本地 JSON 文件的绝对或 `~/` 路径，该文件包含相同条目的数组，或包含 `tips` 数组的对象，最多 256 KB。Claude Code 每个进程读取一次文件，因此在下次启动时加载您的编辑。您不能通过[服务器管理的设置](/docs/zh-CN/server-managed-settings)设置它；在那里部署内联 `tips`，或在磁盘上的 `managed-settings.json` 中部署路径。 +* `label`：Claude Code 在来自用户、`--settings` 和托管设置的提示之前显示的前缀，最多 40 个字符。默认值是 `Tip`，与内置提示相同的前缀，来自项目和本地设置的提示始终使用它。 +* `excludeDefault`：将其设置为 `true` 以隐藏内置提示并仅显示您的。当 Claude Code 无法加载您的任何提示时，例如因为 `tipsFile` 不存在或每个条目都无效，它保持内置轮换而不是空加载动画。 + +当多个设置文件设置此键时，Claude Code 显示来自所有这些文件的提示，并从托管设置、`--settings` 标志和用户设置中最高优先级的设置每个的 `tipsFile`、`label` 和 `excludeDefault`。 + +此示例在您的用户设置中添加纯字符串提示和对象提示到 `Acme tip` 前缀下的轮换： + +```json settings.json theme={null} +{ + "spinnerTipsOverride": { + "label": "Acme tip", + "tips": [ + "在打开 PR 之前运行 /review", + { + "id": "gateway-errors", + "text": "看到 5xx 错误？首先检查网关状态页面", + "cooldownSessions": 5, + "priority": 2 + } + ] + } +} +``` + +示例中的每个字段改变 Claude Code 显示提示的一个方面： + +* `label`：Claude Code 将两个提示显示为 `Acme tip: ...` 而不是 `Tip: ...`。 +* 纯字符串：Claude Code 给它默认值，所以它可以在下一个会话中再次出现。 +* `id`：Claude Code 在 `gateway-errors` 上键入第二个提示的显示历史，因此其冷却期在添加或重新排序提示后仍然适用。 +* `cooldownSessions`：在 Claude Code 显示 `gateway-errors` 提示后，它在五个会话后才再次显示该提示。 +* `priority`：当 `gateway-errors` 提示和另一个提示未显示相同数量的会话时，例如当两者都尚未显示时，Claude Code 首先显示 `gateway-errors`。纯字符串具有默认优先级 `0`。 + +当 Claude 工作时，Claude Code 在加载动画中显示您的提示，带有您的前缀，如 `Acme tip: 在打开 PR 之前运行 /review`。 + +

+ `spinnerVerbs` +

+ +当转向进行中时，加载动画显示轮换的动词，如"Accomplishing"、"Architecting"或"Baking"。使用此键将您自己的动词添加到该轮换或用您的替换内置列表。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 对象，包含 `verbs` 字符串数组和 `mode`，值为以下之一： + * `"append"`：Claude Code 将您的动词添加到内置集合 + * `"replace"`：Claude Code 仅显示您的动词 +* **Default**: unset，所以 Claude Code 使用内置动词 + +此示例将两个动词添加到内置集合： + +```json settings.json theme={null} +{ + "spinnerVerbs": { + "mode": "append", + "verbs": ["Pondering", "Crafting"] + } +} +``` + +在 `"replace"` 模式下使用空 `verbs` 数组，Claude Code 保持内置动词。 + +

+ `statusLine` +

+ +运行您自己的命令来渲染提示下方的[状态行](/docs/zh-CN/statusline)，包含模型、成本或 git 分支等上下文。可选字段调整间距、添加定期重新运行，并在您的脚本自己渲染 `vim.mode` 时隐藏内置 vim 模式指示器。 + +* **Scope**: [`Any file`](#scopes)。当 [`allowManagedHooksOnly`](#allowmanagedhooksonly) 打开时，或 [`disableAllHooks`](#disableallhooks) 在托管设置外设置时，仅托管设置值运行。 +* **Type**: 对象，`type` 设置为 `"command"` 和 `command` 字符串，加上可选的 `padding` 作为字符数、`refreshInterval` 作为秒数（最少 `1`）和 `hideVimModeIndicator` 作为 Boolean +* **Default**: unset，所以没有状态行 + +此示例打印模型名称和上下文使用情况，并添加两个字符的水平间距： + +```json settings.json theme={null} +{ + "statusLine": { + "type": "command", + "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'", + "padding": 2 + } +} +``` + +示例需要安装 [`jq`](https://jqlang.org/) 并在 shell 中运行。对于 PowerShell 和 Git Bash 等效项，请参阅[Windows 配置](/docs/zh-CN/statusline#windows-configuration)；对于完整设置，请参阅[手动配置状态行](/docs/zh-CN/statusline#manually-configure-a-status-line)。 + +

+ `subagentStatusLine` +

+ +当 Claude 运行[子代理](/docs/zh-CN/sub-agents)时，Claude Code 在提示下方的任务显示中列出它们，每个子代理一行显示 `name · description · token count`。此键让您运行自己的命令来重写这些行，例如显示每个子代理的上下文使用情况百分比。在每次刷新时，Claude Code 将可见行作为一个 JSON 对象发送到 stdin，其中 `tasks` 数组包含每个子代理的 `id`、`name`、`status`、`model`、`tokenCount` 等，并将您写回的每个 `id` 的行替换为 `{"id", "content"}` 行。您不写回的行保持默认渲染。 + +* **Scope**: [`Any file`](#scopes)。当 [`allowManagedHooksOnly`](#allowmanagedhooksonly) 打开时，或 [`disableAllHooks`](#disableallhooks) 在托管设置外设置时，仅托管设置值运行。 +* **Type**: 对象，`type` 设置为 `"command"` 和 `command` 字符串 +* **Default**: unset，所以 Claude Code 渲染默认行 + +```json settings.json theme={null} +{ + "subagentStatusLine": { + "type": "command", + "command": "jq -c '.tasks[] | {id, content: \"\\(.name): \\(.tokenCount) tokens\"}'" + } +} +``` + +请参阅[子代理状态行](/docs/zh-CN/statusline#subagent-status-lines)。 + +

+ `syntaxHighlightingDisabled` +

+ +Claude Code 使用其内置高亮器按语言为它在终端中显示的差异、代码块和文件预览着色；不涉及插件或语言服务器。将此键设置为 `true` 以改为将它们显示为纯文本，例如如果颜色与您的终端主题冲突或减慢屏幕阅读器。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`：Claude Code 在差异、代码块和文件预览中关闭语法高亮 + * `false`：Claude Code 高亮语法 +* **Default**: `false` + +```json settings.json theme={null} +{ + "syntaxHighlightingDisabled": true +} +``` + +

+ `terminalProgressBarEnabled` +

+ +某些终端可以在选项卡或任务栏中为在其中运行的程序显示进度指示器。当 Claude 工作时，Claude Code 向终端报告进行中状态，因此您可以从另一个选项卡或窗口看到会话是否仍然繁忙。指示器在转向结束后保持可见，同时[后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)或[动态工作流](/docs/zh-CN/workflows)仍在运行，并在会话空闲后清除。 + +Claude Code 仅在支持指示器的终端中报告它：ConEmu、Ghostty 1.2.0 或更高版本以及 iTerm2 3.6.6 或更高版本。将此键设置为 `false` 以停止 Claude Code 报告它。在 `/config` 中显示为**终端进度条**。 + +* **Scope**: [`Any file`](#scopes)。当没有设置文件设置它时，来自较旧版本的 `~/.claude.json` 中的值适用。 +* **Type**: Boolean + * `true`：您在支持它的终端中看到终端进度条 + * `false`：Claude Code 隐藏终端进度条 +* **Default**: `true` + +```json settings.json theme={null} +{ + "terminalProgressBarEnabled": false +} +``` + +

+ `terminalTitleFromRename` +

+ +Claude Code 设置您的终端选项卡的标题。默认情况下，它使用从对话生成的标题，一旦您使用 `/rename` 或 `--name` 给会话[命名](/docs/zh-CN/sessions#name-your-sessions)，选项卡会改为显示该名称。将此键设置为 `false` 以在您命名会话后保持生成的标题在选项卡上。名称本身仍然适用，因此 `/resume ` 和会话选择器找到它。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`：终端选项卡标题显示您设置的会话名称 + * `false`：选项卡保持 Claude Code 从您的对话生成的标题 +* **Default**: `true` + +```json settings.json theme={null} +{ + "terminalTitleFromRename": false +} +``` + +要停止 Claude Code 完全更新终端标题，请改为将 [`CLAUDE_CODE_DISABLE_TERMINAL_TITLE`](/docs/zh-CN/env-vars) 设置为 `1`。 + +

+ `theme` +

+ +为界面选择颜色主题。在 `/config` 中显示为**主题**。 + +* **Scope**: [`Any file`](#scopes)。当没有设置文件设置它时，来自较旧版本的 `~/.claude.json` 中的值适用。 +* **Type**: string，值为以下之一： + * `"auto"`：匹配您的终端的浅色或深色背景 + * `"dark"`：深色主题 + * `"light"`：浅色主题 + * `"dark-daltonized"`：具有色盲友好颜色的深色主题 + * `"light-daltonized"`：具有色盲友好颜色的浅色主题 + * `"dark-ansi"`：仅使用您的终端 ANSI 调色板的深色主题 + * `"light-ansi"`：仅使用您的终端 ANSI 调色板的浅色主题 + * `"custom:"` 或 `"custom::"`：来自 `~/.claude/themes/` 或插件的自定义主题 +* **Default**: `"dark"` + +```json settings.json theme={null} +{ + "theme": "light-daltonized" +} +``` + +请参阅[创建自定义主题](/docs/zh-CN/terminal-config#create-a-custom-theme)。 + +

+ `timeFormat` +

+ +选择 Claude Code 如何写入它在界面中显示的时间，如每个转向持续时间消息末尾的 `done 6:05 PM` 和[记录查看器](/docs/zh-CN/interactive-mode#transcript-viewer)中的时间戳。要选择预设，运行 `/config` 并设置**时间格式**。需要 Claude Code v2.1.257 或更高版本。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，值为以下之一： + * `"auto"`：与 unset 相同；每个时间保持其内置格式，在转向持续时间消息上遵循您的区域设置 + * `"12-hour"`：12 小时制 + * `"24-hour"`：24 小时制 + * `"24-hour-utc"`：UTC 中的 24 小时制，分钟后带 `Z`，如 `18:05Z`；Claude Code 对此预设忽略 [`timeZone`](#timezone) + * strftime 模式，如 `"%H:%M"`：Claude Code 使用模式写入每个时间。任何包含 `%` 的值都是模式，任何在预设外的其他值计为 `"auto"` +* **Default**: `"auto"` + +```json settings.json theme={null} +{ + "timeFormat": "24-hour" +} +``` + +`/config` 仅提供预设，因此要使用 strftime 模式，请将键添加到设置文件。此示例将每个时间显示为两位数 24 小时制： + +```json settings.json theme={null} +{ + "timeFormat": "%H:%M" +} +``` + +转向持续时间消息和记录查看器然后显示时间，如 `18:05`。在记录查看器中，模式是整个时间戳，因此在需要日期时添加日期指令。此示例将日期放在时钟前面： + +```json settings.json theme={null} +{ + "timeFormat": "%Y-%m-%d %H:%M" +} +``` + +相同的表面然后显示时间，如 `2026-09-01 18:05`。 + +

+ `timeZone` +

+ +在不同于您系统的时区中显示界面中的时间。将其设置为 [IANA 时区名称](https://www.iana.org/time-zones)，如 `"UTC"` 或 `"Europe/Dublin"`。[`timeFormat`](#timeformat) 控制的时间然后在此区域中显示。如果 `timeFormat` 是 `"24-hour-utc"`，时间保持在 UTC 中，Claude Code 忽略此键。`/config` 对此键没有行，因此在设置文件中设置它。需要 Claude Code v2.1.257 或更高版本。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，IANA 时区名称。当 Claude Code 不识别名称时，它使用您的系统时区 +* **Default**: unset，所以时间显示在您的系统时区 + +```json settings.json theme={null} +{ + "timeZone": "Europe/Dublin" +} +``` + +

+ `tui` +

+ +选择终端 UI 渲染器。使用 `"fullscreen"` 获得无闪烁的[替代屏幕渲染器](/docs/zh-CN/fullscreen)，具有虚拟化滚动条，或使用 `"default"` 获得经典主屏幕渲染器。运行 `/tui fullscreen` 或 `/tui default` 为您写入此键。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，值为以下之一： + * `"default"`：经典主屏幕渲染器 + * `"fullscreen"`：无闪烁的替代屏幕渲染器，具有虚拟化滚动条 +* **Default**: unset，所以 Claude Code [为您选择渲染器](/docs/zh-CN/fullscreen#fullscreen-by-default) +* **Per-session overrides**: [`CLAUDE_CODE_NO_FLICKER`](/docs/zh-CN/env-vars) 和 [`CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN`](/docs/zh-CN/env-vars) 在单个会话中优先于此键：`CLAUDE_CODE_NO_FLICKER=1` 打开全屏，`CLAUDE_CODE_NO_FLICKER=0` 或 `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1` 关闭它；当两者都设置时，Claude Code 关闭它 + +```json settings.json theme={null} +{ + "tui": "fullscreen" +} +``` + +在 tmux `-CC` 下或通过 SSH 到 Windows，Claude Code 保持经典渲染器，除非您设置 `CLAUDE_CODE_NO_FLICKER=1`。从[代理视图](/docs/zh-CN/agent-view)打开的后台会话始终使用全屏渲染器，无论此设置如何。 + +

+ `verbose` +

+ +默认情况下，记录将每个工具调用折叠为简短摘要，如 Claude 运行的命令和其输出的行数，您按 `Ctrl+O` 在需要详细信息时将整个记录切换到展开视图。将此键设置为 `true` 以在发生时内联显示每个工具调用的完整输入和输出，这在您调试 hook、MCP 服务器或长 shell 命令时很有用。在 `/config` 中显示为**详细输出**。 + +* **Scope**: [`Any file`](#scopes)。当没有设置文件设置它时，来自较旧版本的 `~/.claude.json` 中的值适用。 +* **Type**: Boolean + * `true`：您看到完整工具输出 + * `false`：您看到工具输出的截断摘要 +* **Default**: `false` +* **Per-session overrides**: [`--verbose`](/docs/zh-CN/cli-reference#cli-flags) 在单个会话中优先于此键 + +```json settings.json theme={null} +{ + "verbose": true +} +``` + +[`viewMode`](#viewmode) 值或粘性 `/focus` 选择在每个会话中覆盖此键。 + +

+ `viewMode` +

+ +设置 Claude Code 启动的记录视图：`"default"`、`"verbose"` 或 `"focus"`。设置时，它覆盖粘性 `/focus` 选择和 [`verbose`](#verbose) 设置。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，值为以下之一： + * `"default"`：具有截断工具输出的正常记录 + * `"verbose"`：具有完整工具输出的记录 + * `"focus"`：仅您的最后提示、工具调用的单行摘要，带编辑差异统计，和最终响应。焦点视图需要[全屏渲染器](#tui) +* **Default**: unset，所以 `verbose` 设置和您最后的 `/focus` 选择适用 +* **Per-session overrides**: [`--verbose`](/docs/zh-CN/cli-reference#cli-flags) 在单个会话中优先于此键 + +```json settings.json theme={null} +{ + "viewMode": "focus" +} +``` + +

+ `vimInsertModeRemaps` +

+ +在 [vim 编辑器模式](/docs/zh-CN/interactive-mode#vim-editor-mode)中将两键 INSERT 模式序列映射到 Escape。每个键恰好是按顺序键入的两个可打印字符，`""` 是唯一支持的目标；Claude Code 忽略其他条目。需要 Claude Code v2.1.208 或更高版本。 + +* **Scope**: [`User or managed`](#scopes)。存储库不能重新映射您的按键。 +* **Type**: 对象，将两字符序列映射到 `""` +* **Default**: unset + +```json settings.json theme={null} +{ + "vimInsertModeRemaps": { + "jj": "" + } +} +``` + +除非 `editorMode` 是 `"vim"`，否则无效。请参阅[重新映射 INSERT 模式快捷键序列](/docs/zh-CN/interactive-mode#remap-insert-mode-key-sequences)。需要 Claude Code v2.1.208 或更高版本。 + +

+ `voice` +

+ +打开[语音听写](/docs/zh-CN/voice-dictation)并选择听写键的行为方式。当您运行 `/voice` 时，Claude Code 为您写入此对象。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 对象，`enabled` 作为 Boolean，`autoSubmit` 作为仅在保持模式中适用的 Boolean，和 `mode`，值为以下之一： + * `"hold"`：您在说话时按住听写键，释放它以停止 + * `"tap"`：您点击键一次以开始录制，再次以发送 +* **Default**: unset，所以听写关闭；当 `enabled` 是 `true` 且 `mode` 未设置时，Claude Code 使用 `"hold"` + +此示例打开听写并使键点击一次以开始录制，再次以发送： + +```json settings.json theme={null} +{ + "voice": { + "enabled": true, + "mode": "tap" + } +} +``` + +`autoSubmit` 在保持模式中释放键时发送提示。语音听写需要 claude.ai 账户。 + +

+ `voiceEnabled` +

+ + + 自 v2.1.92 起已弃用，当 [`voice`](#voice) 对象替换它时。Claude Code 仍然读取它，因此较旧的设置文件保持工作，但新配置应设置 `voice.enabled`。 + + +使用在 `voice` 对象之前的单个 Boolean 形式打开语音听写。当两者都设置时，`voice.enabled` 适用。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`：当您使用 claude.ai 账户登录且您的组织政策允许语音时，语音听写打开，除非 `voice.enabled` 设置 + * `false`：语音听写关闭，除非 `voice.enabled` 设置 +* **Default**: unset + +```json settings.json theme={null} +{ + "voiceEnabled": true +} +``` + +

+ `wheelScrollAccelerationEnabled` +

+ +在[全屏渲染](/docs/zh-CN/fullscreen#mouse-wheel-scrolling)中快速滚动期间加速鼠标滚轮滚动速度。将其设置为 `false` 以获得每个滚轮凹口的恒定滚动速率。需要 Claude Code v2.1.174 或更高版本。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`：Claude Code 在快速滚动期间加速鼠标滚轮滚动速度 + * `false`：Claude Code 以每个滚轮凹口的恒定速率滚动 +* **Default**: `true` + +```json settings.json theme={null} +{ + "wheelScrollAccelerationEnabled": false +} +``` + +需要 Claude Code v2.1.174 或更高版本。 + +

+ Git 和归属 +

+ +控制 Claude Code 添加到提交和拉取请求的归属，以及它如何与 git 配合使用。 + + + +

+ `attribution` +

+ +自定义 Claude Code 添加到 git 提交和拉取请求的归属。提交默认获得 [git trailer](https://git-scm.com/docs/git-interpret-trailers)，例如 `Co-Authored-By`；拉取请求描述获得纯文本。使用下面的子键分别设置每个部分。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 包含 `commit` 和 `pr` 字符串以及 `sessionUrl` 布尔值的对象 +* **Default**: 未设置，因此 Claude Code 使用每个子键下显示的标准归属 + +此示例替换提交归属，删除拉取请求归属，并删除会话链接： + +```json settings.json theme={null} +{ + "attribution": { + "commit": "Generated with AI\n\nCo-Authored-By: AI ", + "pr": "", + "sessionUrl": false + } +} +``` + +要隐藏所有归属，请将 [`commit`](#attribution-commit) 和 [`pr`](#attribution-pr) 设置为空字符串，并将 [`sessionUrl`](#attribution-sessionurl) 设置为 `false`。一旦设置 `commit` 或 `pr`，Claude Code 将忽略已弃用的 `includeCoAuthoredBy` 设置，并对未设置的两个中的任何一个使用其默认文本。 + +

+ `includeCoAuthoredBy` +

+ + + 自 v2.0.62 起已弃用，当 [`attribution`](#attribution) 替换它时。Claude Code 仍然读取它，但新配置应设置 `attribution`。 + + +改用 [`attribution`](#attribution)，它替换此键，让您可以分别更改或隐藏提交 trailer、拉取请求文本和会话链接。Claude Code 仍然遵守来自早于 `attribution` 的设置文件中的 `includeCoAuthoredBy: false`，但一旦设置 `attribution.commit` 或 `attribution.pr`，就会忽略它。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 布尔值 + * `true`: 与未设置相同；Claude Code 添加提交 trailer 和拉取请求归属文本 + * `false`: Claude Code 省略提交 trailer 和拉取请求归属文本，除非 `attribution` 设置 `commit` 或 `pr`，在这种情况下 [`attribution`](#attribution) 规则适用 +* **Default**: `true` + +```json settings.json theme={null} +{ + "includeCoAuthoredBy": false +} +``` + +要立即隐藏所有归属，请将 [`attribution.commit`](#attribution-commit) 和 [`attribution.pr`](#attribution-pr) 设置为空字符串，并将 [`attribution.sessionUrl`](#attribution-sessionurl) 设置为 `false`。 + +

+ `includeGitInstructions` +

+ +在会话开始时，Claude Code 向 Claude 的提示添加两个与 git 相关的部分：其内置的关于如何编写提交和拉取请求的说明（在 Bash 工具的描述中），以及您的存储库的 git 状态快照（在系统提示中），意味着当前分支、主分支、`git status` 输出和最近的提交。将此键设置为 `false` 以将两者都排除，例如当您使用自己的 git 工作流技能时。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 布尔值 + * `true`: Claude Code 包含其内置的提交和拉取请求工作流说明以及 git 状态快照。云会话永远不包括快照 + * `false`: Claude Code 将两者都排除 +* **Default**: `true` +* **Per-session overrides**: [`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS`](/docs/zh-CN/env-vars) 对此键优先一个会话 + +```json settings.json theme={null} +{ + "includeGitInstructions": false +} +``` + +

+ `prUrlTemplate` +

+ +将 Claude Code 呈现的 PR 链接（在页脚徽章和工具结果摘要中）指向内部代码审查工具而不是 `github.com`。Claude Code 从 PR URL 替换 `{host}`、`{owner}`、`{repo}`、`{number}` 和 `{url}`。[GitLab 合并请求](/docs/zh-CN/interactive-mode#gitlab-merge-requests)两个表面上的链接保持其 GitLab URL。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 字符串，使用五个占位符中任何一个的 URL 模板 +* **Default**: 未设置 + +```json settings.json theme={null} +{ + "prUrlTemplate": "https://reviews.example.com/{owner}/{repo}/pull/{number}" +} +``` + +Claude Code 仅将模板应用于它自己呈现的链接；Claude 在消息中编写的 PR 号（例如 `#123`）保持 Claude 编写的样子。没有 `/pull/` 形状的 URL 保持不变。 + +

+ `attribution.commit` +

+ +设置 Claude Code 添加到 git 提交的归属文本，包括任何 trailer。将其设置为空字符串以隐藏提交归属。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 字符串 +* **Default**: 未设置，因此 Claude Code 添加 `Co-Authored-By: `。名称是会话的活跃模型，例如 `Claude Sonnet 5`。 + * 当 Claude Code 识别模型为 Claude 模型但无法确认其确切版本时，它单独写入 `Claude`。 + * 当它无法将模型 ID 匹配到任何 Claude 模型（例如通过自定义 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 提供的第三方模型）时，它写入 `Claude Code`。 + +此示例用自定义行和自定义 `Co-Authored-By` trailer 替换默认 trailer： + +```json settings.json theme={null} +{ + "attribution": { + "commit": "Generated with AI\n\nCo-Authored-By: AI " + } +} +``` + +

+ `attribution.pr` +

+ +设置 Claude Code 添加到拉取请求描述的归属文本。将其设置为空字符串以隐藏拉取请求归属。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 字符串 +* **Default**: 未设置，因此 Claude Code 添加 `🤖 Generated with [Claude Code](https://claude.com/claude-code)` + +```json settings.json theme={null} +{ + "attribution": { + "pr": "" + } +} +``` + +

+ `attribution.sessionUrl` +

+ +选择 Claude Code 在从 [cloud](/docs/zh-CN/claude-code-on-the-web) 或 [Remote Control](/docs/zh-CN/remote-control) 会话提交或打开拉取请求时是否附加 claude.ai 会话链接。Claude Code 在提交上添加链接作为 `Claude-Session` trailer，在拉取请求描述中添加链接。将其设置为 `false` 以省略链接。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 布尔值 + * `true`: Claude Code 在从云或 Remote Control 会话提交或打开拉取请求时附加 claude.ai 会话链接 + * `false`: Claude Code 省略链接 +* **Default**: `true` + +```json settings.json theme={null} +{ + "attribution": { + "sessionUrl": false + } +} +``` + + + + + +

+ Hooks 和自动化 +

+ +注册 hooks，限制哪些 hooks 运行，以及控制工作流。有关 hook 事件和有效负载，请参阅 [hooks 参考](/docs/zh-CN/hooks)。 + +

+ `allowedHttpHookUrls` +

+ +限制 [HTTP hooks](/docs/zh-CN/hooks#http-hook-fields) 可以针对的 URL。定义此键时，Claude Code 仅在 HTTP hook 的 URL 与某个模式匹配时才运行该 hook，并阻止其余的而不运行它们；空数组会阻止每个 HTTP hook。 + +* **作用域**: [`任何文件`](#scopes)。数组在设置文件中合并。 +* **类型**: URL 模式数组，`*` 作为通配符 +* **默认值**: 未设置，因此允许任何 URL + +此示例允许 `https://hooks.example.com/` 下的任何 URL 和任何 `http://localhost` URL： + +```json settings.json theme={null} +{ + "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"] +} +``` + +主机名匹配不区分大小写，并将 `hooks.example.com.`（带有标记完全限定域名的尾部点）视为与 `hooks.example.com` 相同，这是 DNS 的处理方式。允许列表适用于来自每个源的 hooks，包括托管设置。 + +

+ `allowManagedHooksOnly` +

+ +限制 hook 执行仅限于您的组织部署的 hooks。 + +* **作用域**: [`托管`](#scopes) +* **类型**: 布尔值 + * `true`: 仅运行托管 hooks，加上 Agent SDK hooks 和您的托管设置强制启用的插件中的 hooks。请参阅 [在 `allowManagedHooksOnly` 下运行什么](#what-runs-under-allowmanagedhooksonly) + * `false`: 来自每个设置作用域和插件的 hooks 都运行 +* **默认值**: 未设置，因此来自每个设置作用域和插件的 hooks 都运行 + +```json managed-settings.json theme={null} +{ + "allowManagedHooksOnly": true +} +``` + +

+ 在 `allowManagedHooksOnly` 下运行什么 +

+ +将其设置为 `true` 时，Claude Code 会更改加载的 hooks 和类似 hook 的命令： + +* **托管和 SDK hooks 运行**: 来自托管设置的 hooks 和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 在进程中注册的 hooks +* **强制启用的插件 hooks 运行**: 来自您的托管设置通过 [`enabledPlugins`](#enabledplugins) 强制启用的插件的 hooks。Claude Code 与完整的 `plugin@marketplace` ID 匹配，因此来自不同市场的同名插件保持被阻止。这使您可以通过组织市场分发经过审查的 hooks，同时阻止其他所有内容 +* **其他所有内容都被阻止**: 用户、项目和本地 hooks，来自其他插件的 hooks，以及在代理 frontmatter 中声明的 hooks +* **禁用命令源插件**: Claude Code 还禁用具有 [`command` 源](/docs/zh-CN/plugin-marketplaces#command-sources) 的插件，包括在托管 `enabledPlugins` 中强制启用的插件，除非您明确将 [`disableCommandPluginSources`](#disablecommandpluginsources) 设置为 `false` +* **市场 `headersHelper` 命令被阻止**: Claude Code 还会阻止市场 [`headersHelper` 命令](/docs/zh-CN/plugin-marketplaces#authenticate-archive-downloads)，除非 [`disableCommandPluginSources`](#disablecommandpluginsources) 明确设置为 `false`，托管设置本身声明的市场除外。需要 Claude Code v2.1.238 或更高版本 +* **状态行和文件建议缩小到托管设置**: Claude Code 仅从托管设置读取 [`statusLine`](/docs/zh-CN/statusline)、[`fileSuggestion`](#filesuggestion) 和 [`subagentStatusLine`](/docs/zh-CN/statusline#subagent-status-lines)，遵循 [状态行和文件建议门](#status-line-and-file-suggestion-gates) + +设置此键时，[`/goal`](/docs/zh-CN/goal) 命令无法运行，因为它依赖于 hooks。 + +

+ `disableAllHooks` +

+ +关闭 [hooks](/docs/zh-CN/hooks#disable-or-remove-hooks)、任何自定义 [状态行](/docs/zh-CN/statusline) 和任何自定义 [文件建议](#filesuggestion) 命令。使用它可以临时关闭所有这些，而无需从设置中删除它们。 + +* **作用域**: [`任何文件`](#scopes)。仅托管设置可以禁用托管 hooks。 +* **类型**: 布尔值 + * `true`: Claude Code 关闭 hooks、任何自定义状态行和任何自定义文件建议命令 + * `false`: hooks、状态行和文件建议命令运行 +* **默认值**: 未设置，因此 hooks 运行 + +```json settings.json theme={null} +{ + "disableAllHooks": true +} +``` + +范围取决于哪个文件包含该键： + +* **在托管设置中**: Claude Code 禁用每个配置的 hook，包括托管的，并继续运行 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 在进程中注册的 hooks +* **在任何其他设置文件中**: Claude Code 禁用用户、项目、本地和插件 hooks；托管 hooks、Agent SDK hooks 和来自在托管 [`enabledPlugins`](#enabledplugins) 中强制启用的插件的 hooks 继续运行 + +当托管设置设置此键时保持 Agent SDK hooks 运行需要 Claude Code v2.1.242 或更高版本。 + +当 hooks 被禁用时，[`/goal`](/docs/zh-CN/goal) 命令无法运行，`/hooks` 菜单显示通知而不是您的 hooks。 + +

+ 状态行和文件建议门 +

+ +Claude Code 为 `statusLine`、`fileSuggestion` 和 `subagentStatusLine` 按此顺序做出两个决定： + +* **完全关闭**: 当托管设置设置 `disableAllHooks` 时，或当文件夹在与 [设置文件中的 hooks 相同的工作区信任规则](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 下不受信任时 +* **缩小到托管设置**: 当设置 [`allowManagedHooksOnly`](#allowmanagedhooksonly) 时，当在应用 [设置优先级](/docs/zh-CN/hooks#disable-or-remove-hooks) 后 `disableAllHooks` 在托管设置外为 `true` 时，或当您使用 `--safe-mode` 启动 Claude Code 时 + +在缩小范围下，如果部署了托管值，Claude Code 会运行它。否则它会跳过您的值而不发出警告：状态行被禁用，`@` 自动完成回退到内置文件建议。 + +

+ `disableWorkflows` +

+ +关闭 [动态工作流](/docs/zh-CN/workflows#turn-workflows-off) 和您的设置所涉及的每个人的捆绑工作流命令，例如通过托管设置的组织。要仅为自己打开或关闭工作流，请改用 [`enableWorkflows`](#enableworkflows)，这是 `/config` 中的 **动态工作流** 切换写入您的用户设置的内容。 + +* **作用域**: [`任何文件`](#scopes) +* **类型**: 布尔值 + * `true`: Claude Code 关闭动态工作流和您的设置所涉及的每个人的捆绑工作流命令 + * `false`: 与未设置相同；工作流是否打开然后遵循 [`enableWorkflows`](#enableworkflows) 和您的计划默认值 +* **默认值**: `false` +* **每会话覆盖**: [`CLAUDE_CODE_DISABLE_WORKFLOWS`](/docs/zh-CN/env-vars) 关闭一个会话的工作流；无论两者中哪一个关闭它们，另一个都无法将其打开 + +```json settings.json theme={null} +{ + "disableWorkflows": true +} +``` + +

+ `enableWorkflows` +

+ +当您的计划默认值不是您想要的时，为自己打开或关闭 [动态工作流](/docs/zh-CN/workflows)。在 `/config` 中显示为 **动态工作流**，它将此键写入您的用户设置，并在您切换回计划默认值时再次删除它。要从托管设置为每个人关闭工作流，请改用 [`disableWorkflows`](#disableworkflows)。 + +* **作用域**: [`任何文件`](#scopes) +* **类型**: 布尔值 + * `true`: Claude Code 为您打开动态工作流 + * `false`: Claude Code 为您关闭动态工作流 +* **默认值**: 未设置，因此工作流打开，除非您在 Pro 计划上，其中工作流关闭 +* **每会话覆盖**: [`CLAUDE_CODE_DISABLE_WORKFLOWS`](/docs/zh-CN/env-vars) 关闭一个会话的工作流，而 `true` 在此处无法在设置时将其打开 + +```json settings.json theme={null} +{ + "enableWorkflows": true +} +``` + +[`disableWorkflows`](#disableworkflows) 和您的组织的工作流策略也优先：`enableWorkflows: true` 在任何源关闭工作流时无法将其打开。当除您的用户设置之外的源设置 `enableWorkflows` 或将 `disableWorkflows` 设置为 `true` 时，Claude Code 隐藏 `/config` 行。 + +

+ `hooks` +

+ +在 Claude Code 的生命周期中的某些点（例如在工具调用之前或会话启动时）运行您自己的命令、提示、代理、HTTP 请求或 MCP 工具作为 [hooks](/docs/zh-CN/hooks)；[hooks 参考](/docs/zh-CN/hooks#hook-events) 列出每个事件、其有效负载和其退出代码。每个事件映射到匹配器组列表，每个组列出在匹配器应用时运行的处理程序。 + +* **作用域**: [`任何文件`](#scopes)。Hooks 在文件中合并而不是相互替换，来自托管设置的 hooks 无法从其他文件中删除。 +* **类型**: 由 [hook 事件](/docs/zh-CN/hooks#hook-events) 键入的对象；每个值是 `{ "matcher", "hooks" }` 组的数组，其 `hooks` 条目的 `type` 为 `"command"`、`"prompt"`、`"agent"`、`"http"` 或 `"mcp_tool"` +* **默认值**: 未设置，因此没有 hooks 运行 + +此示例在每个 Bash 工具调用之前运行脚本： + +```json settings.json theme={null} +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { "type": "command", "command": "~/.claude/hooks/check-bash.sh" } + ] + } + ] + } +} +``` + +对于每个事件、匹配器模式和处理程序字段，请参阅 [hooks 参考](/docs/zh-CN/hooks#configuration)。要关闭 hooks，请参阅 [`disableAllHooks`](#disableallhooks)；要将 hooks 限制为您的组织部署的 hooks，请参阅 [`allowManagedHooksOnly`](#allowmanagedhooksonly)。 + +

+ `httpHookAllowedEnvVars` +

+ +[HTTP hook](/docs/zh-CN/hooks#http-hook-fields) 可以将环境变量的值放入请求标头中，例如 `Authorization: Bearer $HOOK_TOKEN` 标头，但仅限于 hook 在其自己的 `allowedEnvVars` 中列出的变量。此键为每个 HTTP hook 的该列表设置外部限制：hook 只能使用变量（如果其自己的 `allowedEnvVars` 和此键都命名它）。使用它可以防止 hook 读取它不应该读取的秘密，即使 hook 的定义要求它。 + +* **作用域**: [`任何文件`](#scopes)。数组在设置文件中合并。 +* **类型**: 环境变量名称数组 +* **默认值**: 未设置，因此应用每个 hook 自己的 `allowedEnvVars` 列表 + +此示例将标头插值限制为 `MY_TOKEN` 和 `HOOK_SECRET`： + +```json settings.json theme={null} +{ + "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"] +} +``` + +允许列表适用于来自每个源的 hooks，包括托管设置。 + +

+ `workflowKeywordTriggerEnabled` +

+ +选择在提示中键入关键字 `ultracode` 是否触发 [动态工作流](/docs/zh-CN/workflows#ask-for-a-workflow-in-your-prompt)。将其设置为 `false` 以在不触发工作流的情况下键入该词。 + +* **作用域**: [`任何文件`](#scopes)。在 `/config` 中显示为 **Ultracode 关键字触发**。 +* **类型**: 布尔值 + * `true`: 在提示中键入 `ultracode` 触发动态工作流 + * `false`: 您可以在不触发工作流的情况下键入该词 +* **默认值**: `true` + +```json settings.json theme={null} +{ + "workflowKeywordTriggerEnabled": false +} +``` + +`ultracode` 工作量设置、`/workflows` 和保存的工作流命令不受影响。 + +

+ `workflowSizeGuideline` +

+ +设置 [Claude 在其编写的动态工作流中针对的代理计数](/docs/zh-CN/workflows#set-a-size-guideline)。Claude Code 将值作为建议而不是强制上限发送给 Claude：`"small"` 要求少于 5 个代理，`"medium"` 少于 15 个，`"large"` 少于 50 个。当您想限制工作流花费的内容时，选择 `"small"`。需要 Claude Code v2.1.219 或更高版本。 + +* **作用域**: [`任何文件`](#scopes)。那里的值优先于 `/config` 中的 **动态工作流大小** 选择，Claude Code 将其存储在 `~/.claude.json` 中，当设置文件设置键时，Claude Code 隐藏该行。 +* **类型**: 字符串，以下之一： + * `"unrestricted"`: 无指导，因此 Claude 根据任务调整工作流大小 + * `"small"`: Claude 针对少于 5 个代理 + * `"medium"`: Claude 针对少于 15 个代理 + * `"large"`: Claude 针对少于 50 个代理 +* **默认值**: `"medium"` + +```json settings.json theme={null} +{ + "workflowSizeGuideline": "small" +} +``` + +需要 Claude Code v2.1.219 或更高版本；在 v2.1.202 到 v2.1.218 上，改为在 `/config` 中设置指导。 + + + + + + + +

+ 插件和技能 +

+ +启用插件、注册市场、限制组织允许的插件来源，以及控制加载哪些技能。有关安装和构建插件，请参阅 [Plugins](/docs/zh-CN/plugins)。 + +

+ `disableBundledSkills` +

+ +关闭 Claude Code 附带的 [skills](/docs/zh-CN/skills) 和工作流。Claude Code 完全删除捆绑的技能和工作流，而内置命令（如 `/init`）仍可输入但对模型隐藏。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`: Claude Code 删除捆绑的技能和工作流，并对模型隐藏内置命令（如 `/init`） + * `false`: 捆绑的技能加载 +* **Default**: 未设置，因此捆绑的技能加载 +* **Per-session overrides**: [`CLAUDE_CODE_DISABLE_BUNDLED_SKILLS`](/docs/zh-CN/env-vars) 设置为 `1` 会关闭一个会话的捆绑技能；两者中任何一个关闭它们，另一个就无法将其打开 + +```json settings.json theme={null} +{ + "disableBundledSkills": true +} +``` + +来自插件、`.claude/skills/` 和 `.claude/commands/` 的技能不受影响。`/doctor` 与内置命令一样可输入；要隐藏它，请改为设置 [`DISABLE_DOCTOR_COMMAND`](/docs/zh-CN/env-vars)。 + +

+ `disableSkillShellExecution` +

+ +关闭 [skills](/docs/zh-CN/skills) 和来自用户、项目、插件或附加目录来源的自定义命令中 `` !`...` `` 和 ` ```! ` 块的内联 shell 执行。Claude Code 用 `[shell command execution disabled by policy]` 替换每个命令，而不是运行它。 + +* **Scope**: [`Any file`](#scopes)。托管设置中的 `true` 无法被其他地方的 `false` 覆盖。 +* **Type**: Boolean + * `true`: Claude Code 用 `[shell command execution disabled by policy]` 替换每个内联 shell 命令，而不是运行它 + * `false`: 内联 shell 运行 +* **Default**: 未设置，因此内联 shell 运行 + +```json settings.json theme={null} +{ + "disableSkillShellExecution": true +} +``` + +捆绑的技能和通过托管设置部署的技能不受影响。 + +

+ `skillOverrides` +

+ +隐藏或折叠 [skill](/docs/zh-CN/skills#override-skill-visibility-from-settings)，无需编辑其 `SKILL.md`。Claude Code 将每个技能名称下的值应用于 Claude 看到的技能列表和您的 `/` 自动完成。 + +* **Scope**: [`Any file`](#scopes)。`/skills` 菜单写入 `.claude/settings.local.json`。 +* **Type**: 对象，将技能名称映射到以下之一： + * `"on"`: Claude 看到该技能，您可以输入 `/name` + * `"name-only"`: Claude 按名称看到该技能，但不显示其描述 + * `"user-invocable-only"`: Claude 看不到该技能，但您仍可以输入 `/name` + * `"off"`: Claude 看不到该技能，`/name` 从自动完成中隐藏 +* **Default**: 未设置，因此每个技能都是 `"on"` + +此示例仅按名称向 Claude 列出 `legacy-context`，并从 Claude 和 `/` 自动完成中隐藏 `deploy`： + +```json settings.json theme={null} +{ + "skillOverrides": { + "legacy-context": "name-only", + "deploy": "off" + } +} +``` + +覆盖不适用于插件技能，您可以通过 `/plugin` 管理这些技能。 + +在托管设置和使用 `--settings` 传递的文件中，捆绑技能别名上的键（如 `/doctor` 的 `checkup`）也适用于该技能；请参阅 [别名键如何与技能自身名称上的键结合](/docs/zh-CN/skills#override-skill-visibility-from-settings)。 + +

+ `syncClaudeAiSkills` +

+ +关闭 [您在 claude.ai 上启用的技能](/docs/zh-CN/skills#how-synced-skills-behave) 的下载。当您使用 `-p` 标志在 [非交互模式](/docs/zh-CN/headless) 中运行它并设置 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/zh-CN/env-vars#variables) 时，Claude Code 将它们下载到 `~/.claude/skills/synced/`。设置为 `false` 以停止该下载并隐藏已同步的技能。Claude Code 仅接受 `false`：`true` 与未设置相同，不会打开同步。 + +* **Scope**: [`User, local, or managed`](#scopes)。存储库无法为您关闭它。 +* **Type**: Boolean + * `false`: Claude Code 停止下载同步的技能并隐藏 `~/.claude/skills/synced/` 中已有的技能。在用户或托管设置中，它还将它们移动到 `~/.claude/skills/.trash/` + * `true`: 与未设置相同 +* **Default**: 未设置，因此使用 `CLAUDE_CODE_SYNC_SKILLS` 设置的非交互运行会下载技能 + +此示例防止机器下载帐户的技能，无论会话在其环境中设置什么： + +```json settings.json theme={null} +{ + "syncClaudeAiSkills": false +} +``` + +

+ `allowedChannelPlugins` +

+ +选择哪些 [channel](/docs/zh-CN/channels) 插件可以将消息推送到您组织中的会话。设置后，Claude Code 使用您的列表代替默认的 Anthropic 允许列表；每个条目命名一个插件及其来自的市场。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: 对象数组，每个对象都有 `marketplace` 和 `plugin` 字符串。条目也可以是 `"plugin@marketplace"` 字符串，如 `"telegram@claude-plugins-official"`，Claude Code 将其视为等效对象。字符串形式需要 Claude Code v2.1.267 或更高版本；较早版本在包含一个时拒绝整个 `allowedChannelPlugins` 值 +* **Default**: 未设置，因此 Claude Code 使用默认的 Anthropic 允许列表 + +此示例打开频道并仅允许来自官方 Anthropic 市场的 Telegram 插件： + +```json managed-settings.json theme={null} +{ + "channelsEnabled": true, + "allowedChannelPlugins": [ + { "marketplace": "claude-plugins-official", "plugin": "telegram" } + ] +} +``` + +空数组阻止每个频道插件。 + +此键在频道通过帐户的 [`channelsEnabled`](#channelsenabled) 门控后生效：在 Team 和 Enterprise 计划上，以及在具有托管设置的 Console 帐户上，这意味着 `channelsEnabled: true`。请参阅 [限制哪些频道插件可以运行](/docs/zh-CN/channels#restrict-which-channel-plugins-can-run)。 + +

+ `blockedMarketplaces` +

+ +为您的组织阻止插件市场来源。Claude Code 在市场添加以及插件安装、更新、刷新和自动更新时检查阻止列表，因此在您设置策略之前添加的市场无法用于获取插件。在下载前检查被阻止的来源，因此它们永远不会接触文件系统。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: 市场来源对象数组，形式与 [`strictKnownMarketplaces`](#allowed-source-types) 相同 +* **Default**: 未设置，因此没有市场被阻止 + +此示例阻止一个 GitHub 存储库作为市场来源： + +```json managed-settings.json theme={null} +{ + "blockedMarketplaces": [ + { "source": "github", "repo": "untrusted/plugins" } + ] +} +``` + +一个 `github` 条目可能使用 [owner-wildcard 形式](#owner-wildcards) `"owner/*"` 来阻止该 GitHub 所有者下的每个存储库，这需要 Claude Code v2.1.223 或更高版本。添加 `{ "source": "skills-dir" }` 以停止 Claude Code 从 `~/.claude/skills/` 加载 [`@skills-dir` 插件](/docs/zh-CN/plugins-reference#skills-directory-plugins)，而不限制任何市场。请参阅 [托管市场限制](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions)。 + +

+ `channelsEnabled` +

+ +为您的组织允许 [channels](/docs/zh-CN/channels)。在 claude.ai Team 和 Enterprise 计划上，Claude Code 阻止频道，直到您将其设置为 `true`。对于使用 API 密钥进行身份验证的 [Anthropic Console](/docs/zh-CN/authentication#claude-console-authentication) 帐户，默认允许频道。如果您的组织部署托管设置，Claude Code 也会在这些帐户上阻止频道，直到您将此键设置为 `true`。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: Boolean + * `true`: Claude Code 为您的组织允许频道 + * `false`: 与未设置相同；频道是否被阻止取决于您的计划，如默认值所述 +* **Default**: 未设置；频道在 Team 和 Enterprise 计划以及具有托管设置的 Console 帐户上被阻止，在 Pro 和 Max 计划以及没有托管设置的 Console 帐户上被允许 + +```json managed-settings.json theme={null} +{ + "channelsEnabled": true +} +``` + +要限制启用后哪些插件可以注册为频道，请设置 [`allowedChannelPlugins`](#allowedchannelplugins)。请参阅 [Enterprise controls](/docs/zh-CN/channels#enterprise-controls)。 + +

+ `disableCommandPluginSources` +

+ +阻止 [`command` 插件来源](/docs/zh-CN/plugin-marketplaces#command-sources)，它通过在用户机器上运行市场声明的命令来安装插件。当您将其设置为 `true` 时，Claude Code 永远不会运行该命令，不会安装或更新命令来源的插件，并停止加载已安装的插件。设置为 `false` 以明确允许它们。每当它阻止命令来源时，无论您将其设置为 `true` 还是在 [`allowManagedHooksOnly`](#allowmanagedhooksonly) 下保持未设置，它也会阻止市场 [`headersHelper` 命令](/docs/zh-CN/plugin-marketplaces#authenticate-archive-downloads)，除了托管设置本身声明的市场。需要 Claude Code v2.1.229 或更高版本，`headersHelper` 阻止需要 v2.1.238 或更高版本。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: Boolean + * `true`: Claude Code 永远不会运行市场声明的命令，不会安装或更新命令来源的插件，并停止加载已安装的插件 + * `false`: Claude Code 明确允许命令来源的插件 +* **Default**: 未设置，因此 Claude Code 遵循 [`allowManagedHooksOnly`](#allowmanagedhooksonly)：限制 hook 执行到托管设置的组织也会禁用命令来源 + +```json managed-settings.json theme={null} +{ + "disableCommandPluginSources": true +} +``` + +需要 Claude Code v2.1.229 或更高版本。 + +

+ `pluginSuggestionMarketplaces` +

+ +命名其插件可以显示为上下文安装建议的市场，在微调提示和固定在 `/plugin` **Discover** 选项卡顶部。内置的第一方前端设计提示不受影响。建议来自每个插件在其市场条目中的 `relevance` 声明。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: 市场名称数组 +* **Default**: 未设置，因此没有市场声明的建议出现 + +```json managed-settings.json theme={null} +{ + "pluginSuggestionMarketplaces": ["acme-corp-plugins"] +} +``` + +名称仅在市场在机器上注册且其注册来源也在同一托管设置中声明时生效，要么作为该名称的 [`extraKnownMarketplaces`](#extraknownmarketplaces) 条目，要么作为 [`strictKnownMarketplaces`](#strictknownmarketplaces) 的条目。Claude Code 忽略从不同来源注册的市场，即使在允许列表名称下也是如此。官方市场不受来源要求的限制：仅允许列表其名称就足够了，因为该名称只能从官方 Anthropic 来源注册。请参阅 [按上下文建议插件](/docs/zh-CN/plugin-relevance)。 + +

+ `pluginTrustMessage` +

+ +将您组织自己的文本添加到 Claude Code 在安装前显示的插件信任警告中，例如确认来自您内部市场的插件已被审查。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: 字符串 +* **Default**: 未设置，因此 Claude Code 仅显示标准警告 + +```json managed-settings.json theme={null} +{ + "pluginTrustMessage": "All plugins from our marketplace are approved by IT" +} +``` + +

+ `strictKnownMarketplaces` +

+ +限制您组织中的人员可以添加和安装插件的插件市场来源。Claude Code 在市场添加以及插件安装、更新、刷新和自动更新时强制执行允许列表，在任何网络或文件系统操作之前，因此在您设置策略之前添加的市场一旦其来源不再匹配就无法用于获取插件。被阻止的用户会看到一个错误，命名托管策略。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: 市场来源对象数组；请参阅 [允许的来源类型](#allowed-source-types) +* **Default**: 未设置，因此用户可以添加任何市场。空数组是完全锁定，阻止每个市场来源，包括官方 Anthropic 市场 + +此示例允许两个 GitHub 存储库，一个固定到 `v2.0` ref，一个托管的 `marketplace.json` URL： + +```json managed-settings.json theme={null} +{ + "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" } + ] +} +``` + +您也可以将此键写为 `allowedMarketplaces`；[市场键别名](#marketplace-key-aliases) 描述 Claude Code 如何处理别名以及哪个版本接受它。此键是策略门控：它控制用户可能添加什么但不注册任何内容。要在一个文件中限制和预注册，请参阅 [与 `extraKnownMarketplaces` 结合](#combine-with-extraknownmarketplaces)。对于用户面向的视图，请参阅 [托管市场限制](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions)。 + +

+ 允许的来源类型 +

+ +下面每个条目显示每个来源类型的一个允许列表条目及其接受的字段。大多数类型完全匹配；`hostPattern` 和 `pathPattern` 按正则表达式匹配，`github` 条目可以使用 [owner 通配符](#owner-wildcards)。 + +| Source | Example entry | Fields | +| :------------ | :------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------- | +| `github` | `{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }` | `repo` 必需；`ref` 是分支或标签；`path` 是子目录 | +| `git` | `{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git", "ref": "production" }` | `url` 必需；`ref` 和 `path` 与 `github` 相同 | +| `url` | `{ "source": "url", "url": "https://plugins.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }` | `url` 必需；`headers` 为经过身份验证的访问添加 HTTP 标头 | +| `npm` | `{ "source": "npm", "package": "@acme-corp/claude-plugins" }` | `package` 必需，包含 `marketplace.json` 的 npm 包 | +| `file` | `{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }` | `path` 必需，`marketplace.json` 文件的绝对路径 | +| `directory` | `{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }` | `path` 必需，包含 `.claude-plugin/marketplace.json` 的目录的绝对路径 | +| `hostPattern` | `{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }` | `hostPattern` 必需，针对市场主机匹配的正则表达式 | +| `pathPattern` | `{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }` | `pathPattern` 必需，针对 `file` 和 `directory` 来源的 `path` 匹配的正则表达式 | +| `skills-dir` | `{ "source": "skills-dir" }` | 无字段。选择加入 `~/.claude/skills/` 插件扫描 | + +三个来源类型有超出表格的规则： + +* **`url`**: URL 市场仅下载 `marketplace.json` 文件，Claude Code 不会从该服务器按相对路径获取插件文件，因此其插件必须使用 [插件来源](/docs/zh-CN/plugin-marketplaces#plugin-sources)，而不是相对路径，如存档 URL，可以在同一主机上。对于具有相对路径的插件，请改用基于 Git 的市场。请参阅 [URL 基市场中的相对路径插件失败](/docs/zh-CN/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)。 +* **`hostPattern`**: 使用它来允许内部 GitHub Enterprise 或 GitLab 服务器上的每个市场，而无需列出每个存储库。Claude Code 针对 `github.com` 匹配 `github` 来源，从 `url` 来源获取主机名，并根据 [git URL](https://git-scm.com/docs/git-clone#_git_urls) 的形式从 `git` 来源获取： + + * 具有方案的 URL，如 `https://` 或 `ssh://`：URL 中的主机名。 + * 没有方案的 SSH 地址，采用 git 的 `user@host:path` 形式，如 `git@git.example.com:tools/plugins.git`：`@` 和 `:` 之间的主机，这是 git 连接到的主机。 + * 任何其他没有方案的形式：没有主机，因此没有 `strictKnownMarketplaces` `hostPattern` 条目匹配它。对于 `blockedMarketplaces` `hostPattern`，Claude Code 从更广泛的形式集中获取主机，因此阻止列表条目仍可以匹配这样的形式。在 v2.1.234 之前，`strictKnownMarketplaces` `hostPattern` 也匹配 git 不视为 SSH 地址的某些形式。 + + `file` 和 `directory` 来源没有主机，永远不会匹配 `hostPattern` 条目。 +* **`pathPattern`**: 使用它来允许文件系统市场以及网络来源的 `hostPattern` 条目。`".*"` 允许每个本地路径；更窄的模式如 `"^/opt/approved/"` 限制到目录。 + +任何允许列表，即使是空的，也会停止 Claude Code 从 `~/.claude/skills/` 加载 [`@skills-dir` 插件](/docs/zh-CN/plugins-reference#skills-directory-plugins)。添加 `{ "source": "skills-dir" }` 条目以继续加载它们；该条目在此键和 `blockedMarketplaces` 之外没有意义。 + +

+ Owner 通配符 +

+ +一个 `github` 条目，其 `repo` 值为 `"/*"`，匹配该 GitHub 所有者下的每个存储库。Owner 通配符需要 Claude Code v2.1.223 或更高版本，仅在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中工作。在 `github` 来源出现的其他地方，如 `extraKnownMarketplaces` 或 `/plugin marketplace add`，`repo` 值必须命名单个存储库。在 v2.1.223 之前，Claude Code 按字面比较条目，因此允许列表条目不匹配任何存储库，阻止列表条目不阻止任何内容；单存储库条目在每个版本上强制执行。 + +此条目允许 `acme-corp` 组织中的任何市场存储库： + +```json managed-settings.json theme={null} +{ + "strictKnownMarketplaces": [ + { "source": "github", "repo": "acme-corp/*" } + ] +} +``` + +只有整个存储库名称位置可以是通配符。Claude Code 按字面比较条目如 `*`、`*/plugins` 或 `acme-corp/tools-*`，因此它们不匹配任何存储库。 + +两个设置之间的匹配规则不同： + +| Rule | `strictKnownMarketplaces` | `blockedMarketplaces` | +| --------- | ----------------------------------------------------------- | ------------------------------------ | +| 匹配来源拼写 | 仅 `owner/repo` 形式。克隆同一存储库的 git URL 不匹配 | 任何拼写，包括解析为同一 github.com 存储库的 git URL | +| Owner 大小写 | 区分大小写，如精确条目匹配 | 不区分大小写 | +| `ref` | 遵循精确条目规则：带有 `ref` 的条目仅匹配具有该精确 ref 的来源，没有条目的条目仅匹配不指定 ref 的来源 | 没有 `ref` 的条目阻止它匹配的存储库的所有 ref | +| `path` | 比精确条目规则更宽松：带有 `path` 的条目需要该精确值，而没有条目的条目匹配存储库内的任何路径 | 没有 `path` 的条目阻止它匹配的存储库的所有路径 | + +

+ 精确匹配 +

+ +对于除 owner-wildcard `github` 条目和正则表达式匹配的 `hostPattern` 和 `pathPattern` 条目之外的每个来源类型，Claude Code 仅在市场来源与条目完全匹配时允许用户添加。对于基于 git 的来源 `github` 和 `git`，精确匹配包括可选字段： + +* `repo` 或 `url` 必须完全匹配 +* `ref` 字段必须完全匹配，或两者都未定义 +* `path` 字段必须完全匹配，或两者都未定义 + +例如，Claude Code 将下面的每一对视为两个不同的来源： + +* `{ "source": "github", "repo": "acme-corp/plugins" }` 和 `{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }` +* `{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }` 和 `{ "source": "github", "repo": "acme-corp/plugins" }` + +

+ 仅允许官方市场 +

+ +要仅允许官方 Anthropic 市场，列出其存储库： + +```json managed-settings.json theme={null} +{ + "strictKnownMarketplaces": [ + { "source": "github", "repo": "anthropics/claude-plugins-official" } + ] +} +``` + +使用此条目，Claude Code 保持已注册的官方市场可用，在新机器上，在您首次以交互方式启动 Claude Code 时自动注册市场。自动注册最常遗漏： + +* 在机器首次交互启动之前运行的非交互环境。 +* Claude Code 已在阻止市场的策略下以交互方式运行的机器，如空数组锁定。Claude Code 记录被阻止的尝试，不会在策略更改后重试。 + +在这些机器上，将市场添加到同一 `managed-settings.json` 中的 [`extraKnownMarketplaces`](#extraknownmarketplaces)，以便 Claude Code 自动注册它，或运行 `claude plugin marketplace add anthropics/claude-plugins-official`。 + +

+ 与 `extraKnownMarketplaces` 结合 +

+ +两个键做不同的工作。此表比较它们： + +| Aspect | `strictKnownMarketplaces` | `extraKnownMarketplaces` | +| ------ | ------------------------- | ---------------------------- | +| 目的 | 组织策略执行 | 团队便利 | +| 设置文件 | 仅托管设置 | 任何设置文件 | +| 行为 | 阻止非允许列表添加 | 注册缺失的市场 | +| 何时强制执行 | 在网络和文件系统操作之前 | 立即从用户或托管设置；在接受存储库文件的工作区信任对话后 | +| 可以被覆盖 | 否，最高优先级 | 是，由更高优先级设置 | +| 来源格式 | 直接来源对象 | 具有嵌套 `source` 对象的命名市场 | + +要为所有用户限制和预注册市场，请在 `managed-settings.json` 中设置两者： + +```json managed-settings.json theme={null} +{ + "strictKnownMarketplaces": [ + { "source": "github", "repo": "acme-corp/plugins" } + ], + "extraKnownMarketplaces": { + "acme-tools": { + "source": { "source": "github", "repo": "acme-corp/plugins" } + } + } +} +``` + +仅设置 `strictKnownMarketplaces` 时，用户仍可以使用 `/plugin marketplace add` 自己添加允许的市场。官方 Anthropic 市场是 Claude Code 自动注册的唯一市场，仅当允许列表允许时。[仅允许官方市场](#allow-only-the-official-marketplace) 列出它遗漏的机器。 + +

+ `strictPluginOnlyCustomization` +

+ +阻止来自用户和项目来源的技能、代理、hooks 和 MCP 服务器，因此它们只能来自插件或托管设置。将其与 [`strictKnownMarketplaces`](#strictknownmarketplaces) 结合以控制完整的自定义供应链：市场允许列表控制用户可以安装哪些插件。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: `true` 以锁定所有四种自定义，或命名要锁定的种类的数组，来自 `"skills"`、`"agents"`、`"hooks"` 和 `"mcp"` +* **Default**: 未设置，因此没有锁定 + +此示例锁定技能和 hooks，并保持代理和 MCP 服务器解锁： + +```json managed-settings.json theme={null} +{ + "strictPluginOnlyCustomization": ["skills", "hooks"] +} +``` + +下面的四个子键条目列出每个表面阻止什么以及什么仍然加载。Claude Code 忽略它不识别的表面名称，而不是使设置文件失败，因此您可以在每个客户端更新之前添加新的表面名称。 + +

+ `strictPluginOnlyCustomization.skills` +

+ +锁定 `skills` 表面。Claude Code 停止从 `~/.claude/skills/` 和 `.claude/skills/`、`~/.claude/commands/` 和 `.claude/commands/` 中的自定义命令、`--add-dir` 目录下的技能以及从您的 claude.ai 帐户同步的技能加载技能，并继续加载插件技能、捆绑技能和托管策略目录中的技能。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 数组中的字符串 `"skills"` +* **Default**: 未锁定 + +```json managed-settings.json theme={null} +{ + "strictPluginOnlyCustomization": ["skills"] +} +``` + +

+ `strictPluginOnlyCustomization.agents` +

+ +锁定 `agents` 表面。Claude Code 停止从 `~/.claude/agents/` 和 `.claude/agents/` 加载代理，并继续加载插件代理、内置代理和托管策略目录中的代理。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 数组中的字符串 `"agents"` +* **Default**: 未锁定 + +```json managed-settings.json theme={null} +{ + "strictPluginOnlyCustomization": ["agents"] +} +``` + +

+ `strictPluginOnlyCustomization.hooks` +

+ +锁定 `hooks` 表面。Claude Code 停止运行来自用户、项目和本地 `settings.json` 的 hooks，并继续运行插件 hooks 和托管设置中的 hooks。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 数组中的字符串 `"hooks"` +* **Default**: 未锁定 + +```json managed-settings.json theme={null} +{ + "strictPluginOnlyCustomization": ["hooks"] +} +``` + +

+ `strictPluginOnlyCustomization.mcp` +

+ +锁定 `mcp` 表面。Claude Code 停止从 `~/.claude.json` 和 `.mcp.json` 加载 MCP 服务器，并继续加载插件 MCP 服务器、[`managed-mcp.json`](/docs/zh-CN/managed-mcp) 服务器和来自 [`managedMcpServers`](#managedmcpservers) 的服务器。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 数组中的字符串 `"mcp"` +* **Default**: 未锁定 + +```json managed-settings.json theme={null} +{ + "strictPluginOnlyCustomization": ["mcp"] +} +``` + +

+ `enabledPlugins` +

+ +打开或关闭单个 [plugins](/docs/zh-CN/plugins)，由 `plugin-name@marketplace-name` 键控。在任何范围内没有条目的插件回退到其 [`defaultEnabled`](/docs/zh-CN/plugins-reference#default-enablement) 值。当您使用 `/plugin` 或 `claude plugin enable` 启用或禁用插件时，Claude Code 为您写入此键。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: 对象，将 `plugin-name@marketplace-name` 映射到 Boolean +* **Default**: 未设置，因此每个插件遵循其 `defaultEnabled` 值 + +此示例启用来自 `team-tools` 市场的两个插件并禁用来自 `personal` 的一个： + +```json settings.json theme={null} +{ + "enabledPlugins": { + "code-formatter@team-tools": true, + "deployment-tools@team-tools": true, + "experimental-features@personal": false + } +} +``` + +每个范围服务于不同的目的： + +* **用户设置**: 您的个人插件偏好 +* **项目设置**: 与存储库中的每个人共享的插件 +* **本地设置**: 每台机器的覆盖，当 Claude Code 在那里保存设置时被 gitignored +* **托管设置**: 组织范围的策略。设置为 `false` 的插件在每个范围内被阻止安装并从市场隐藏 + +项目设置优先于用户设置，因此在 `~/.claude/settings.json` 中将插件设置为 `false` 不会禁用项目的 `.claude/settings.json` 启用的插件。要在您的机器上选择退出项目启用的插件，请改为在 `.claude/settings.local.json` 中将其设置为 `false`。由托管设置强制启用的插件无法以这种方式禁用，因为托管设置覆盖本地设置。 + +在项目的 `.claude/settings.json` 中启用来自外部来源（如 GitHub 存储库或 npm 包）的插件不会为其他人安装它。在加载插件的每条路径上，Claude Code 报告插件未安装，直到每个用户 [自己安装它](/docs/zh-CN/discover-plugins#configure-team-marketplaces)。 + +

+ `extraKnownMarketplaces` +

+ +按名称注册其他插件市场，以便打开存储库的人或托管设置到达的每个人都获得市场，而无需自己添加。Claude Code 注册它还不知道的每个市场。[`enabledPlugins`](#enabledplugins) 从中命名的插件是否安装取决于插件的来源和哪个文件启用它；该条目有规则。 + +* **Scope**: [`Any file`](#scopes)。Claude Code 仅在您接受该文件夹的工作区信任对话后才接受存储库的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的条目；在您未信任的文件夹中，包括 `-p` 运行，它会忽略它们而不显示消息。 +* **Type**: 对象，将市场名称映射到具有 `source` 对象和可选 `autoUpdate` Boolean 的对象 +* **Default**: 未设置 + +此示例注册 GitHub 市场和来自自托管 git URL 的市场： + +```json settings.json theme={null} +{ + "extraKnownMarketplaces": { + "acme-tools": { + "source": { + "source": "github", + "repo": "acme-corp/claude-plugins" + } + }, + "security-plugins": { + "source": { + "source": "git", + "url": "https://git.example.com/security/plugins.git" + } + } + } +} +``` + +[在您信任文件夹之前运行什么](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 将信任门与存储库可以提供的其他内容进行比较。您也可以将此键写为 `additionalMarketplaces`；请参阅 [市场键别名](#marketplace-key-aliases)。 + +在 `source` 旁边设置 `"autoUpdate": true` 以使 Claude Code 在启动后在后台刷新该市场并更新其已安装的插件。省略时，`claude-plugins-official` 和大多数其他官方 Anthropic 市场默认为 `true`，第三方市场默认为 `false`。请参阅 [配置自动更新](/docs/zh-CN/discover-plugins#configure-auto-updates)。 + +当多个设置文件在同一名称下定义市场条目时，Claude Code 使用来自 [最高优先级文件](/docs/zh-CN/settings#settings-precedence) 的条目。该条目替换较低优先级条目，不继承其任何字段，因此重新定义无法将一个文件的 `source.headers` 凭证与另一个文件控制的 URL 结合。在 v2.1.228 之前，Claude Code 逐字段合并同名条目，因此较高优先级文件中的条目可以继承它未设置的字段，包括另一个文件的 `headers`。 + +

+ 市场来源类型 +

+ +`source` 对象采用以下形式之一： + +* **`github`**: GitHub 存储库，带有 `repo` +* **`git`**: 任何 git URL，带有 `url` +* **`url`**: 直接 URL 到 `marketplace.json` 文件，带有 `url` 和可选 `headers` 和 `headersHelper` 用于经过身份验证的访问。`headersHelper` 命名一个打印标头的命令，其值太短暂而无法在 `headers` 中列出，需要 Claude Code v2.1.238 或更高版本 +* **`file`**: 到 `marketplace.json` 文件的本地路径，带有 `path` +* **`directory`**: 本地文件系统路径，带有 `path`，仅用于开发 +* **`settings`**: 直接在设置文件中声明的内联市场，无需托管存储库，带有 `name` 和 `plugins` + +`git` 来源类型适用于任何 git 托管服务，包括自托管 GitLab 和 Bitbucket。Claude Code 使用该机器上 `git clone` 会使用的相同身份验证克隆存储库：配置的凭证助手或 SSH 密钥。提供者令牌如 `GITHUB_TOKEN` 仅通过读取它的凭证助手生效。请参阅 [私有存储库](/docs/zh-CN/plugin-marketplaces#private-repositories) 了解设置详情。 + +对于 `github` 和 `git` 来源，在 `source` 对象内部设置 `"skipLfs": true`，与 `repo` 或 `url` 一起，以在 Claude Code 克隆或更新市场存储库时跳过 Git LFS 下载。LFS 指针文件保持为指针而不是下载其内容。当存储库包含与插件内容无关的大型 LFS 对象时使用此功能。 + +对于 `url` 来源，当 `headers` 中的凭证过期且命令必须生成新凭证时，在 `source` 对象内部设置 `headersHelper`。需要 Claude Code v2.1.238 或更高版本。有关命令必须打印什么以及 Claude Code 在哪里运行它，请参阅 [编写 headersHelper 命令](/docs/zh-CN/plugin-marketplaces#write-the-headershelper-command)，以及 Claude Code 不运行它的情况，请参阅 [何时 Claude Code 跳过 headersHelper 命令或丢弃其输出](/docs/zh-CN/plugin-marketplaces#when-claude-code-skips-a-headershelper-command-or-drops-its-output)。在 `https://` 市场 URL 上设置 `headersHelper` 后，Claude Code 在两个点运行命令，重用一次运行的输出长达 60 秒： + +* 在该市场 `marketplace.json` 的每次获取之前，包括稍后刷新。Claude Code 使用该获取发送打印的标头。 +* 在市场 URL 来源上的每个插件存档下载之前，意味着相同的方案、主机和端口。Claude Code 使用该下载发送输出，没有其他下载获得标头。 + +Claude Code 忽略在您使用 [`--add-dir`](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 添加的目录的 `.claude/settings.json` 或 `.claude/settings.local.json` 中设置的任何 `headersHelper`，在 `url` 来源和内联插件条目上，仅发送在该文件中设置的固定 `headers`。[用户如何接受 headersHelper 命令](/docs/zh-CN/plugin-marketplaces#how-users-accept-a-headershelper-command) 涵盖其他设置文件。 + +`settings` 来源中列出的插件必须引用外部来源如 GitHub 或 npm，`name` 必须匹配市场键。您仍然在 `enabledPlugins` 中单独启用每个插件。此示例声明一个内联插件： + +```json settings.json theme={null} +{ + "extraKnownMarketplaces": { + "team-tools": { + "source": { + "source": "settings", + "name": "team-tools", + "plugins": [ + { + "name": "code-formatter", + "source": { + "source": "github", + "repo": "acme-corp/code-formatter" + } + } + ] + } + } + } +} +``` + +在 `source: 'settings'` 下的插件条目，其自身 `source` 是 [`archive`](/docs/zh-CN/plugin-marketplaces#zip-archives)，可以为存档下载设置 `headers`。如果您要放在 `headers` 中的值是短暂的，如您的注册表按请求铸造的令牌，请改为设置 `headersHelper` 命令。条目可以设置两者。两个字段都需要 Claude Code v2.1.238 或更高版本。 + +Claude Code 发送条目的 `headers` 和命令打印的任何内容，与该插件的存档下载一起，没有其他下载。Claude Code 仅在用户 [自己安装或更新该一个插件](/docs/zh-CN/plugin-marketplaces#how-users-accept-a-headershelper-command) 时运行命令。三个进一步的规则取决于哪个文件持有条目： + +* **`strict`**: 与市场 `marketplace.json` 中的条目不同，设置文件中的条目不需要 `"strict": false`，因为设置文件不携带要内联的清单字段。请参阅 [严格模式](/docs/zh-CN/plugin-marketplaces#strict-mode)。 +* **文件夹信任**: 对于项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的条目，Claude Code 仅在用户也 [信任该文件夹](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 后运行命令。 +* **标头过滤**: Claude Code 从项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的条目删除 [请求路由和客户端身份标头名称](/docs/zh-CN/plugin-marketplaces#when-claude-code-skips-a-headershelper-command-or-drops-its-output)，因为存储库可以提供这些文件。Claude Code 对目录条目和 `--add-dir` 目录的设置中的条目应用相同的过滤，对您的用户设置、`--settings` 文件或托管设置中的条目不应用过滤。 + +

+ 市场键别名 +

+ +在 Claude Code v2.1.232 或更高版本上，您可以将 `extraKnownMarketplaces` 写为 `additionalMarketplaces`，将 `strictKnownMarketplaces` 写为 `allowedMarketplaces`。Claude Code 按如下方式处理每个别名： + +* 较早的版本忽略别名，因此在较旧版本也读取的文件中保持规范拼写，如具有混合 Claude Code 版本的队伍的托管设置文件。 +* 在接受规范键的任何设置文件中，Claude Code 完全按照读取规范键的方式读取别名。 +* Claude Code 在更新文件时可能会将 `additionalMarketplaces` 重写为 `extraKnownMarketplaces`。 +* 如果您在一个文件中设置两个拼写，Claude Code 使用规范值并忽略别名。 + +

+ `pluginConfigs` +

+ +存储您给插件的 [`userConfig`](/docs/zh-CN/plugins-reference#user-configuration) 配置对话的非敏感答案，由插件 ID 键控。当您填写对话时，Claude Code 将此键写入您的用户设置，因此您无需手动编辑它。Claude Code 将敏感选项存储在 macOS Keychain 中，当 Keychain 拒绝写入时回退到 `~/.claude/.credentials.json`；在没有支持的 keychain 的平台上，它将它们存储在 `~/.claude/.credentials.json`。 + +* **Scope**: [`User or managed`](#scopes) +* **Type**: 对象，将插件 ID 映射到具有 `options` 字段的对象，将每个选项名称映射到字符串、数字、Boolean 或字符串数组，以及可选的 `mcpServers` 字段，以相同形状保存每个服务器的用户配置值 +* **Default**: 未设置 + +此示例存储来自 `acme-tools` 的 `deployer` 插件的 `api_endpoint` 选项： + +```json settings.json theme={null} +{ + "pluginConfigs": { + "deployer@acme-tools": { + "options": { + "api_endpoint": "https://api.example.com" + } + } + } +} +``` + +Claude Code 忽略项目和本地条目，因为它将这些值替换到插件 hook、MCP 和 LSP 配置中，克隆的存储库不得能够提供它们。在 v2.1.207 之前，项目和本地设置也被读取。 + +

+ MCP +

+ +控制 Claude Code 连接到哪些 MCP 服务器以及组织允许哪些服务器。请参阅[使用 MCP 连接到外部工具](/docs/zh-CN/mcp)和[托管 MCP 配置](/docs/zh-CN/managed-mcp)。 + +

+ `allowAllClaudeAiMcps` +

+ +加载 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)，Claude Code 会在部署的 `managed-mcp.json` 旁边自行获取这些连接器。如果没有此密钥，`managed-mcp.json` 将对 MCP 服务器拥有独占控制权并禁止这些连接器。 + +* **作用域**: [`Managed`](#scopes)。用户无法重新启用独占控制禁止的连接器。 +* **类型**: 布尔值 + * `true`: Claude Code 在部署的 `managed-mcp.json` 旁边加载 claude.ai 连接器 + * `false`: 部署的 `managed-mcp.json` 对 MCP 服务器拥有独占控制权并禁止 claude.ai 连接器 [Claude Code 自行获取](/docs/zh-CN/mcp#how-connectors-reach-claude-code) +* **默认值**: `false`，因此部署的 `managed-mcp.json` 会禁止 Claude Code 自行获取的 claude.ai 连接器 + +```json managed-settings.json theme={null} +{ + "allowAllClaudeAiMcps": true +} +``` + +[`allowedMcpServers`](#allowedmcpservers) 和 [`deniedMcpServers`](#deniedmcpservers) 仍然适用于此密钥加载的连接器。传递到[云会话](/docs/zh-CN/claude-code-on-the-web)的连接器，其主机携带 `managed-mcp.json`（例如自托管运行器），仍然会被禁止。请参阅[在托管集合旁边允许 claude.ai 连接器](/docs/zh-CN/managed-mcp#allow-claude-ai-connectors-alongside-the-managed-set)。 + +

+ `allowedMcpServers` +

+ +允许列表化人们可以添加的 MCP 服务器。Claude Code 会阻止任何不匹配条目的服务器，无论在何处定义，包括插件服务器、使用 `--mcp-config` 传递的服务器以及来自 claude.ai 的服务器。 + +内置服务器（例如 Chrome 中的 Claude、Claude Code 在运行的 [VS Code](/docs/zh-CN/vs-code#the-built-in-ide-mcp-server) 或 [JetBrains](/docs/zh-CN/jetbrains#the-built-in-ide-mcp-server) IDE 中连接的 `ide` 服务器，以及 CLI 本身配置的服务器）不受允许列表的限制，拒绝列表仍然适用于它们。进程内 `type: "sdk"` 服务器不受两个列表的限制；[启动会话的应用](/docs/zh-CN/mcp#how-connectors-reach-claude-code)会注册它们。 + +您的组织提供的服务器也不受允许列表的限制，拒绝列表仍然适用于它们。豁免涵盖每个 [`managedMcpServers`](#managedmcpservers) 条目，以及任何 [`managed-mcp.json`](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json) 条目，其值不使用 `${VAR}` 扩展。有关完整的检查顺序，请参阅[如何评估服务器](/docs/zh-CN/managed-mcp#how-a-server-is-evaluated)。在 v2.1.259 之前，来自 `managed-mcp.json` 的服务器也必须匹配。 + +* **作用域**: [`Any file`](#scopes)。来自每个文件的条目合并为一个允许列表，除非设置了 [`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly)。在托管设置中部署它以强制执行。 +* **类型**: 对象数组，每个对象恰好有一个密钥：`serverName`，一个限制为字母、数字、连字符和下划线的字符串；`serverCommand`，一个与命令及其参数完全匹配的数组；或 `serverUrl`，一个带有 `*` 通配符的 URL 模式 +* **默认值**: 未设置，因此允许每个服务器；空数组会阻止用户添加的每个服务器 + +此示例仅允许列出的 `npx` 命令启动的 stdio 服务器： + +```json settings.json theme={null} +{ + "allowedMcpServers": [ + { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] } + ] +} +``` + +[`deniedMcpServers`](#deniedmcpservers) 条目优先，因此同时在两个列表中的服务器会被阻止。一旦列表包含任何 `serverCommand` 条目，stdio 服务器必须匹配 `serverCommand` 条目，一旦它包含任何 `serverUrl` 条目，远程服务器必须匹配 `serverUrl` 条目：`serverName` 匹配不再允许该类型的服务器。请参阅[使用允许列表和拒绝列表进行基于策略的控制](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists)。 + +

+ `allowManagedMcpServersOnly` +

+ +使托管允许列表成为唯一适用的列表。Claude Code 随后仅从托管设置中读取 [`allowedMcpServers`](#allowedmcpservers)，并忽略用户、项目和本地设置中的允许列表；[`deniedMcpServers`](#deniedmcpservers) 仍然从每个设置作用域合并，因此用户仍然可以为自己阻止服务器。管理员设置它，以便用户自己的设置无法扩展托管允许列表允许的内容。 + +* **作用域**: [`Managed`](#scopes) +* **类型**: 布尔值 + * `true`: Claude Code 仅从托管设置中读取 `allowedMcpServers`，并忽略用户、项目和本地设置中的允许列表 + * `false`: 来自每个设置作用域的允许列表合并 +* **默认值**: `false`，因此来自每个设置作用域的允许列表合并 + +此示例将允许列表锁定到托管设置，并仅允许名为 `github` 的服务器： + +```json managed-settings.json theme={null} +{ + "allowManagedMcpServersOnly": true, + "allowedMcpServers": [ + { "serverName": "github" } + ] +} +``` + +用户仍然可以添加自己的 MCP 服务器；只有与托管允许列表匹配的服务器才会加载。请参阅[将允许列表限制为仅托管设置](/docs/zh-CN/managed-mcp#restrict-the-allowlist-to-managed-settings-only)。 + +

+ `deniedMcpServers` +

+ +阻止特定的 MCP 服务器。Claude Code 拒绝加载匹配的服务器，无论在何处定义，包括插件服务器、使用 `--mcp-config` 传递的服务器、来自 `managed-mcp.json` 的服务器、来自 [`managedMcpServers`](#managedmcpservers) 的服务器，以及 [它自行获取](/docs/zh-CN/mcp#how-connectors-reach-claude-code)的 claude.ai 连接器。进程内 `type: "sdk"` 服务器不受限制；启动会话的应用会注册它们。 + +* **作用域**: [`Any file`](#scopes)。来自每个文件的条目合并为一个拒绝列表，[`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly) 不会改变这一点。在托管设置中部署它以强制执行。 +* **类型**: 对象数组，每个对象恰好有一个密钥：`serverName`，任何非空字符串，因此 claude.ai 连接器的显示名称（例如 `"claude.ai Slack"`）有效；`serverCommand`，一个与命令及其参数完全匹配的数组；或 `serverUrl`，一个带有 `*` 通配符的 URL 模式 +* **默认值**: 未设置，因此不阻止任何服务器；空数组也不阻止任何内容 + +```json settings.json theme={null} +{ + "deniedMcpServers": [ + { "serverName": "filesystem" } + ] +} +``` + +拒绝列表优先于 [`allowedMcpServers`](#allowedmcpservers)，因此同时在两个列表中的服务器会被阻止。请参阅[使用允许列表和拒绝列表进行基于策略的控制](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists)。 + +

+ `disableClaudeAiConnectors` +

+ +关闭 [claude.ai MCP 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) [Claude Code 自行获取](/docs/zh-CN/mcp#how-connectors-reach-claude-code)，因此它既不获取也不连接它们。任何设置文件中的 `true` 都适用：签入的项目 `.claude/settings.json` 可以选择退出存储库中的这些连接器，但项目级别的 `false` 无法覆盖用户级别或托管级别的 `true`。需要 Claude Code v2.1.182 或更高版本。 + +* **作用域**: [`Any file`](#scopes) +* **类型**: 布尔值 + * `true`: Claude Code 既不获取也不连接这些连接器 + * `false`: 与未设置相同；Claude Code 获取您的连接器，除非另一个设置文件或 `ENABLE_CLAUDEAI_MCP_SERVERS` 关闭它们 +* **默认值**: `false`，因此 Claude Code 获取您的连接器 +* **每会话覆盖**: [`ENABLE_CLAUDEAI_MCP_SERVERS`](/docs/zh-CN/env-vars) 设置为 `false` 会为一个会话关闭连接器；无论两者中哪一个关闭它们，另一个都无法将其打开 + +```json settings.json theme={null} +{ + "disableClaudeAiConnectors": true +} +``` + +您使用 `--mcp-config` 显式传递的服务器不受影响。要阻止单个连接器而不是全部，请使用 [`deniedMcpServers`](#deniedmcpservers)。请参阅[禁用 claude.ai 连接器](/docs/zh-CN/mcp#disable-claude-ai-connectors)。需要 Claude Code v2.1.182 或更高版本。 + +

+ `disabledMcpjsonServers` +

+ +拒绝项目 `.mcp.json` 文件中定义的特定服务器，以便 Claude Code 永远不会连接它们或要求您批准它们。任何设置文件中的拒绝都适用，包括签入存储库的项目 `.claude/settings.json`。 + +* **作用域**: [`Any file`](#scopes) +* **类型**: 字符串数组，服务器名称如 `.mcp.json` 中所示 +* **默认值**: 未设置 + +```json settings.json theme={null} +{ + "disabledMcpjsonServers": ["filesystem"] +} +``` + +当您在批准对话框中拒绝服务器时，Claude Code 会将此密钥写入 `.claude/settings.local.json`。`claude mcp get ` 将被拒绝的服务器显示为 `✘ Rejected (see disabledMcpjsonServers in settings)`。拒绝优先于 [`enabledMcpjsonServers`](#enabledmcpjsonservers) 和 [`enableAllProjectMcpServers`](#enableallprojectmcpservers)。 + +

+ `enableAllProjectMcpServers` +

+ +批准项目 `.mcp.json` 文件中定义的每个 MCP 服务器，无需提示。当您在批准对话框中选择批准所有服务器时，Claude Code 会将此密钥写入 `.claude/settings.local.json`。 + +* **作用域**: [`Any file`](#scopes)。在您尚未接受信任对话框的文件夹中，Claude Code 从用户设置、托管设置和 `--settings` 中遵守它，并在共享项目文件中忽略它，包括在会话中以及 `claude mcp list` 和 `claude mcp get`；[项目服务器批准和工作区信任](/docs/zh-CN/mcp#project-server-approvals-and-workspace-trust)说明何时未跟踪的 `.claude/settings.local.json` 也计数。 +* **类型**: 布尔值 + * `true`: Claude Code 批准项目 `.mcp.json` 文件中定义的每个 MCP 服务器，无需提示 + * `false`: Claude Code 要求您批准每个服务器。在受信任的文件夹中，较高优先级文件中的 `false` 会覆盖较低优先级文件中的 `true`；在您尚未信任的文件夹中，任何受尊重文件中的 `true` 就足够了 +* **默认值**: 未设置，因此 Claude Code 要求您批准每个服务器 + +```json settings.json theme={null} +{ + "enableAllProjectMcpServers": true +} +``` + +[`disabledMcpjsonServers`](#disabledmcpjsonservers) 条目仍然会拒绝服务器。 + +

+ `enabledMcpjsonServers` +

+ +批准项目 `.mcp.json` 文件中定义的特定服务器，以便 Claude Code 连接它们而无需询问。当您在批准对话框中批准服务器时，Claude Code 会将此密钥写入 `.claude/settings.local.json`。 + +* **作用域**: [`Any file`](#scopes)。在您尚未接受信任对话框的文件夹中，Claude Code 从用户设置、托管设置和 `--settings` 中遵守它，并在共享项目文件中忽略它，包括在会话中以及 `claude mcp list` 和 `claude mcp get`；[项目服务器批准和工作区信任](/docs/zh-CN/mcp#project-server-approvals-and-workspace-trust)说明何时未跟踪的 `.claude/settings.local.json` 也计数。 +* **类型**: 字符串数组，服务器名称如 `.mcp.json` 中所示 +* **默认值**: 未设置 + +此示例批准项目 `.mcp.json` 中的 `memory` 和 `github` 服务器： + +```json settings.json theme={null} +{ + "enabledMcpjsonServers": ["memory", "github"] +} +``` + +[`disabledMcpjsonServers`](#disabledmcpjsonservers) 条目仍然会拒绝服务器。 + +

+ `managedMcpServers` +

+ +从托管设置向每个用户提供远程 MCP 服务器。用户保留他们自己添加的服务器，无法编辑或删除您提供的服务器。需要 Claude Code v2.1.259 或更高版本。 + +* **作用域**: [`Managed`](#scopes)。Claude Code 在用户、项目和本地设置中使用警告删除该密钥，并且不在 Claude Desktop 应用的代码选项卡中读取它（在第三方部署上）或在应用的 Cowork 会话中读取它，其中 Claude Desktop 提供并锁定这些会话的 MCP 服务器。 +* **类型**: 按服务器名称键入的对象。每个条目都具有 `http` 或 `sse` 服务器的 `.mcp.json` 形状：必需的 `https://` `url`，以及可选的 `headers`、`oauth` 和其他 HTTP 和 SSE 选项。Claude Code 删除验证失败的条目，[条目可以包含的内容](/docs/zh-CN/managed-mcp#what-an-entry-can-contain)列出了条件 +* **默认值**: 未设置，因此托管设置不提供任何服务器 + +此示例提供一个名为 `search` 的 HTTP 服务器： + +```json managed-settings.json theme={null} +{ + "managedMcpServers": { + "search": { + "type": "http", + "url": "https://search.example.com/mcp" + } + } +} +``` + +有关优先级、提供的服务器如何与 `managed-mcp.json` 以及允许和拒绝列表结合、用户看到的内容，请参阅[通过托管设置提供服务器](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings)。 + +

+ 代理、会话和工作树 +

+ +设置默认代理、控制团队成员和跨会话消息传递，以及配置工作树。请参阅 [Subagents](/docs/zh-CN/sub-agents) 和 [Worktrees](/docs/zh-CN/worktrees)。 + +

+ `agent` +

+ +将主线程作为命名的 [subagent](/docs/zh-CN/sub-agents#invoke-subagents-explicitly) 运行，以便 Claude Code 将该 subagent 的系统提示、工具限制和模型应用于您的会话。同一密钥为从 `claude agents` 分派的会话设置默认代理。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，内置或自定义代理的名称 +* **Default**: 未设置，因此主线程作为 Claude Code 的默认代理运行 +* **Per-session overrides**: `--agent` 对一个会话的优先级高于此密钥 + +```json settings.json theme={null} +{ + "agent": "code-reviewer" +} +``` + +插件自己的 `settings.json` 也可以提供此密钥；请参阅 [Ship default settings with your plugin](/docs/zh-CN/plugins#ship-default-settings-with-your-plugin)。 + +

+ `crossSessionInbound` +

+ +选择此会话如何处理 [来自您其他 Claude Code 会话的消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)。当没有值适用时，Claude Code 根据两个会话的权限模式类从每条消息中决定。需要 Claude Code v2.1.224 或更高版本。 + +* **Scope**: [`Any file`](#scopes)。项目或本地值仅在严格于托管设置、`--settings` 标志或用户设置提供的值时才适用。 +* **Type**: string，以下之一： + * `"accept"`: Claude Code 将消息传递给 Claude + * `"hold"`: Claude Code 显示消息通知而不传递它 + * `"refuse"`: Claude Code 丢弃消息 +* **Default**: 未设置，因此 Claude Code 从每条消息中决定 + +```json settings.json theme={null} +{ + "crossSessionInbound": "hold" +} +``` + +Claude Code 首先读取托管设置，然后是 `--settings` 标志，然后是用户设置，并应用找到的第一个值。`refuse` 比 `hold` 更严格，`hold` 比 `accept` 更严格。当没有受信任的源设置值时，项目或本地 `hold` 或 `refuse` 仍然适用，替换每条消息的默认值。在具有跨会话消息传递的会话中，此密钥在 `/config` 中显示为 **Messages from your other sessions**，它将其写入用户设置；该行需要 Claude Code v2.1.232 或更高版本，当 `--settings` 标志或托管设置设置密钥时，Claude Code 会隐藏它。 + +Claude Code [warns](/docs/zh-CN/errors#crosssessioninbound-must-be-one-of-accept-hold-refuse) 当您设置它无法识别的值时。当该值存在于用户、项目、本地或 `--settings` 文件中时，Claude Code 会保留入站消息，即使优先级更高的源设置 `accept`。另一个源设置的 `refuse` 仍然适用。修复或删除该值以清除保留。 + +当无法识别的值在 [managed settings](/docs/zh-CN/managed-settings) 中时，Claude Code 改为将其视为 `refuse`，直到管理员修复它。在 v2.1.248 之前，Claude Code 忽略无法识别的值而不发出警告。 + +

+ `disableAgentView` +

+ +关闭 [background agents and agent view](/docs/zh-CN/agent-view)：`claude agents`、`--bg`、`/background` 和按需主管。在 [managed settings](/docs/zh-CN/managed-settings) 中设置它以为组织强制执行。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: Boolean + * `true`: Claude Code 关闭 `claude agents`、`--bg`、`/background` 和按需主管 + * `false`: agent view 可用 +* **Default**: 未设置，因此 agent view 可用 +* **Per-session overrides**: [`CLAUDE_CODE_DISABLE_AGENT_VIEW`](/docs/zh-CN/env-vars) 为一个会话关闭 agent view；无论两者中哪一个关闭它，另一个都无法将其打开 + +```json settings.json theme={null} +{ + "disableAgentView": true +} +``` + +

+ `isolatePeerMachines` +

+ +在 Claude 的 `SendMessage` 到达此机器之外的您的会话之前，需要您的明确批准；请参阅 [Require approval for cross-machine messages](/docs/zh-CN/cross-session-messaging#require-approval-for-cross-machine-messages)。即使在 [`bypassPermissions` mode](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode) 中，批准提示也会出现。 + +* **Scope**: [`Any file`](#scopes)。来自任何范围的 `true` 都适用，因此签入的项目文件可以打开要求但不能关闭。 +* **Type**: Boolean + * `true`: Claude Code 在 Claude 的 `SendMessage` 到达此机器之外的您的会话之前要求您的批准 + * `false`: 跨机器消息不提示 +* **Default**: 未设置，因此跨机器消息不提示 + +```json settings.json theme={null} +{ + "isolatePeerMachines": true +} +``` + +跨机器 `SendMessage` 批准需要 Claude Code v2.1.224 或更高版本。 + +

+ `processWrapper` +

+ +在 macOS 和 Linux 上，在 [Claude Code 启动的后台进程](/docs/zh-CN/corporate-launcher#what-the-launcher-covers) 前面放置公司启动器命令。Claude Code 使用其自己的命令行附加运行启动器，因此启动器必须执行到 Claude Code；请参阅 [Run Claude Code behind a corporate launcher](/docs/zh-CN/corporate-launcher) 了解启动器合约。需要 Claude Code v2.1.210 或更高版本。 + +* **Scope**: [`User or managed`](#scopes) +* **Type**: string，启动器命令作为 argv 前缀，例如带有可选参数的绝对路径 +* **Default**: 未设置，因此后台进程启动时不包装 +* **Per-session overrides**: [`CLAUDE_CODE_PROCESS_WRAPPER`](/docs/zh-CN/env-vars) 对此密钥的一个会话优先级更高 + +```json settings.json theme={null} +{ + "processWrapper": "/opt/corp/launcher --profile claude" +} +``` + +Claude Code 在 Windows 上忽略启动器并启动每个进程不包装。需要 Claude Code v2.1.210 或更高版本。 + +

+ `teammateMode` +

+ +选择 Claude Code 显示 [agent team](/docs/zh-CN/agent-teams) 队友的位置：在您的主终端窗格内，或在您的终端支持时在分割窗格中。请参阅 [Choose a display mode](/docs/zh-CN/agent-teams#choose-a-display-mode)。 + +* **Scope**: [`Any file`](#scopes)。Claude Code 也读取由较旧版本留在 `~/.claude.json` 中的值。 +* **Type**: string，以下之一： + * `"in-process"`: 队友在您的主终端窗格内运行 + * `"auto"`: 当您在 tmux 内运行时分割窗格，或在 iTerm2 内运行且 `it2` 在您的 `PATH` 上或安装了 tmux；否则为进程内 + * `"tmux"`: 使用 tmux 或 iTerm2 分割窗格，从您的终端检测 + * `"iterm2"`: iTerm2 本机分割窗格通过 `it2` CLI，在 Claude Code v2.1.186 或更高版本中 +* **Default**: `"in-process"` +* **Per-session overrides**: `--teammate-mode` 对此密钥的一个会话优先级更高 + +```json settings.json theme={null} +{ + "teammateMode": "auto" +} +``` + +在 v2.1.179 之前，默认值为 `auto`。`iterm2` 值需要 Claude Code v2.1.186 或更高版本。 + + + +

+ `worktree` +

+ +配置 Claude Code 如何为 `--worktree`、`EnterWorktree` 工具以及隔离的 subagents 和后台会话创建和管理 [git worktrees](/docs/zh-CN/worktrees)。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: object with `baseRef`, `symlinkDirectories`, `sparsePaths`, and `bgIsolation` +* **Default**: 未设置 + +此示例从您当前的 `HEAD` 分支新工作树，并将 `node_modules` 符号链接到每个工作树中： + +```json settings.json theme={null} +{ + "worktree": { + "baseRef": "head", + "symlinkDirectories": ["node_modules"] + } +} +``` + +要将 gitignored 文件（如 `.env`）复制到新工作树中，请改为在项目根目录中添加 [`.worktreeinclude` file](/docs/zh-CN/worktrees#copy-gitignored-files-into-worktrees)，而不是设置。 + +

+ `worktree.baseRef` +

+ +选择新工作树从哪个 ref 分支。`"fresh"` 从 `origin/` 分支以获得与远程匹配的干净树；`"head"` 从您当前的本地 `HEAD` 分支，因此未推送的提交和功能分支状态存在于工作树中。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，以下之一： + * `"fresh"`: 新工作树从 `origin/` 分支 + * `"head"`: 新工作树从您当前的本地 `HEAD` 分支，包括未推送的提交 +* **Default**: `"fresh"` + +```json settings.json theme={null} +{ + "worktree": { + "baseRef": "head" + } +} +``` + +在链接的工作树内，`"head"` 解析为该工作树的 `HEAD`，而不是主检出的。 + +

+ `worktree.symlinkDirectories` +

+ +将目录从主存储库符号链接到每个工作树中，以便您不会在磁盘上复制大型目录。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: array of strings，相对于存储库根目录的目录路径 +* **Default**: 未设置，因此 Claude Code 不符号链接任何目录 + +此示例将 `node_modules` 和 `.cache` 从主存储库符号链接到每个新工作树中： + +```json settings.json theme={null} +{ + "worktree": { + "symlinkDirectories": ["node_modules", ".cache"] + } +} +``` + +

+ `worktree.sparsePaths` +

+ +通过 git sparse-checkout 在每个工作树中仅检出列出的目录。Claude Code 仅将这些目录加上根级文件写入磁盘，这在大型 monorepos 中更快；请参阅 [Check out only the directories you need](/docs/zh-CN/large-codebases#check-out-only-the-directories-you-need)。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: array of strings，相对于存储库根目录的目录路径 +* **Default**: 未设置，因此每个工作树检出整个树 + +此示例在每个工作树中仅检出 `packages/my-app` 和 `shared/utils`，加上根级文件： + +```json settings.json theme={null} +{ + "worktree": { + "sparsePaths": ["packages/my-app", "shared/utils"] + } +} +``` + +当稀疏工作树存在时，git 在存储库的共享 `.git/config` 中启用 `extensions.worktreeConfig`。 + +

+ `worktree.bgIsolation` +

+ +选择 [background sessions](/docs/zh-CN/agent-view#how-file-edits-are-isolated) 如何隔离其文件编辑。使用 `"worktree"`，Claude Code 在会话调用 `EnterWorktree` 之前阻止主检出中的 `Edit` 和 `Write`；使用 `"none"`，后台作业直接编辑工作副本。对于 git worktrees 不切实际的存储库，设置 `"none"`。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，以下之一： + * `"worktree"`: Claude Code 在会话调用 `EnterWorktree` 之前阻止主检出中的 `Edit` 和 `Write` + * `"none"`: 后台作业直接编辑工作副本 +* **Default**: `"worktree"` + +```json settings.json theme={null} +{ + "worktree": { + "bgIsolation": "none" + } +} +``` + +在 git 存储库之外，失败的 [`WorktreeCreate` hook](/docs/zh-CN/worktrees#non-git-version-control) 释放块，以便会话可以就地编辑工作目录；该释放需要 Claude Code v2.1.203 或更高版本。 + +

+ 远程、桌面和通知 +

+ +配置远程控制、云环境、桌面应用和 Claude Code 在需要你时发送的通知。请参阅[远程控制](/docs/zh-CN/remote-control)。 + +

+ `agentPushNotifEnabled` +

+ +允许 Claude 在认为值得发送时向你的手机发送推送通知，例如当长任务完成时。Claude Code 将此选择同步到你的账户，推送在[远程控制](/docs/zh-CN/remote-control)连接时到达。在 `/config` 中显示为**Claude 决定时推送**。 + +* **作用域**: [`任何文件`](#scopes)。Claude Code 也会读取由旧版本留在 `~/.claude.json` 中的值。 +* **类型**: 布尔值 + * `true`: Claude 可以在认为值得时向你的手机发送推送通知 + * `false`: Claude 不发送这些通知 +* **默认值**: `false` + +```json settings.json theme={null} +{ + "agentPushNotifEnabled": true +} +``` + +请参阅[移动推送通知](/docs/zh-CN/remote-control#mobile-push-notifications)。 + +

+ `awaySummaryEnabled` +

+ +当你离开终端几分钟后返回时，显示一行会话摘要。将其设置为 `false`，或在 `/config` 中关闭**会话摘要**，以停止摘要。 + +* **作用域**: [`任何文件`](#scopes) +* **类型**: 布尔值 + * `true`: 你离开几分钟后返回时会看到一行会话摘要 + * `false`: Claude Code 不显示摘要 +* **默认值**: 未设置，因此摘要处于开启状态 +* **每个会话的覆盖**: [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/docs/zh-CN/env-vars) 在任一方向上优先于此键一个会话 + +```json settings.json theme={null} +{ + "awaySummaryEnabled": false +} +``` + +Claude Code 在非交互模式下永远不会显示摘要。 + +

+ `disableArtifact` +

+ + + 已弃用，已被 [`enableArtifact`](#enableartifact) 替代。Claude Code 仍然将 `disableArtifact: true` 视为等同于 `enableArtifact: false`，并忽略 `disableArtifact: false`。 + + +改用 [`enableArtifact`](#enableartifact) 来关闭 [Artifact](/docs/zh-CN/artifacts) 工具，该工具将会话输出发布为 claude.ai 上的私有网页。当你在 `/config` 中关闭**Artifacts** 行时，Claude Code 会将 `enableArtifact` 写入你的用户设置并清除此键。 + +* **作用域**: [`任何文件`](#scopes) +* **类型**: 布尔值 + * `true`: Claude Code 为该文件适用的每个会话关闭 Artifact 工具，且没有其他文件将其打开。在 v2.1.242 之前，优先级较高的文件可能会覆盖较低文件的 `true`，而不是该键充当锁定 + * `false`: 被忽略；要保持工具打开，请删除该键 +* **默认值**: 未设置，因此工具遵循你账户的[可用性](/docs/zh-CN/artifacts#availability) +* **每个会话的覆盖**: [`CLAUDE_CODE_DISABLE_ARTIFACT`](/docs/zh-CN/env-vars) 设置为 `1` 会为一个会话关闭工具 + +```json settings.json theme={null} +{ + "disableArtifact": true +} +``` + +[禁用 artifacts](/docs/zh-CN/artifacts#disable-artifacts) 列出了关闭工具的每种方式。 + +

+ `disableDeepLinkRegistration` +

+ +阻止 Claude Code 向操作系统注册 `claude-cli://` 协议处理程序，否则在你发送交互式会话的第一个提示后会进行注册。[深链接](/docs/zh-CN/deep-links)允许外部工具使用预填充的提示打开 Claude Code 会话。在协议处理程序注册受限或单独管理的环境中设置此项。 + +* **作用域**: [`任何文件`](#scopes) +* **类型**: 字符串 `"disable"` +* **默认值**: 未设置，因此 Claude Code 注册处理程序 + +```json settings.json theme={null} +{ + "disableDeepLinkRegistration": "disable" +} +``` + +

+ `disableDesktopLocalSessions` +

+ +在[桌面应用](/docs/zh-CN/desktop#local-sessions-on-managed-devices)中关闭在设备上运行的 Code 会话，用于开发人员应该通过 SSH 在远程机器上工作的部署。在 Code 选项卡中，**本地**环境保留在环境下拉列表中，但呈灰显状态且无法选择，工具提示显示你的组织已关闭它；在 Windows 上，WSL 条目以相同方式呈灰显，尽管 WSL 会话是否在托管设备上运行[由单独管理](/docs/zh-CN/admin-setup#wsl-sessions-in-claude-code-desktop)。新会话默认为第一个[SSH 连接](/docs/zh-CN/desktop#ssh-sessions)（如果已配置），应用拒绝在设备上启动或恢复会话，包括返回同一机器的 SSH 连接。到其他主机的 SSH 会话和云会话不受影响。桌面应用读取此键；终端 CLI 忽略它。需要 Claude Desktop v1.37937.0 或更高版本。 + +* **作用域**: [`托管`](#scopes) +* **类型**: 布尔值；仅 JSON 布尔值 `true` 生效 + * `true`: 桌面应用不提供设备上的 Code 会话；现有本地会话保留在列表中但无法继续 + * `false`: 本地会话保持可用 +* **默认值**: 未设置，因此本地会话可用 + +```json managed-settings.json theme={null} +{ + "disableDesktopLocalSessions": true +} +``` + +桌面应用忽略任何其他值，非布尔值（如字符串 `"true"` 或 `1`）也会记录警告。将其与 [`sshConfigs`](#sshconfigs) 配对，以便用户登陆到工作连接，并与 [`sshHostAllowlist`](#sshhostallowlist) 配对以限制他们可以访问的主机。请参阅[托管设备上的本地会话](/docs/zh-CN/desktop#local-sessions-on-managed-devices)。 + +Claude Desktop 为 Code 会话提供从你的桌面配置派生的策略，例如出口允许列表、文件系统沙箱和第三方部署中的 MCP 限制。每当存在[管理员源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)时，Claude Code 忽略这些父设置：服务器管理的设置、MDM 或操作系统级别的策略或托管设置文件。通过其中一个在之前没有的设备上部署此键（如在第三方部署中），因此会停止桌面派生的策略应用。[让嵌入主机添加策略](/docs/zh-CN/managed-settings#let-an-embedding-host-add-policy)涵盖了父设置何时仍可合并；这适用于你以这种方式部署的任何键，不仅仅是这个。 + +

+ `disableRemoteControl` +

+ +关闭[远程控制](/docs/zh-CN/remote-control)：Claude Code 随后拒绝 `claude remote-control`、`--remote-control` 标志、自动启动和会话内切换，并报告你的组织的策略已禁用它。将其放在[托管设置](/docs/zh-CN/managed-settings)中以进行每个设备的 MDM 强制执行。 + +* **作用域**: [`任何文件`](#scopes) +* **类型**: 布尔值 + * `true`: Claude Code 拒绝 `claude remote-control`、`--remote-control` 标志、自动启动和会话内切换 + * `false`: 远程控制保持可用 +* **默认值**: `false` + +```json settings.json theme={null} +{ + "disableRemoteControl": true +} +``` + +

+ `enableArtifact` +

+ +关闭 [Artifact](/docs/zh-CN/artifacts) 工具，该工具将会话输出发布为 claude.ai 上的私有网页。当你在 `/config` 中关闭**Artifacts** 行时，Claude Code 会将此键写入你的用户设置，因此你通常不需要手动编辑它。需要 Claude Code v2.1.196 或更高版本。 + +* **作用域**: [`任何文件`](#scopes)。每个文件都可以关闭工具，但没有文件可以将其打开。 +* **类型**: 布尔值 + * `false`: Claude Code 为该文件适用的每个会话关闭 Artifact 工具 + * `true`: 与保留键未设置相同，因为它永远不会覆盖来自另一个文件、[`CLAUDE_CODE_DISABLE_ARTIFACT`](/docs/zh-CN/env-vars) 或你的组织[管理员设置](/docs/zh-CN/artifacts#manage-artifacts-for-your-organization)的 `false` +* **默认值**: 未设置，因此工具遵循你账户的[可用性](/docs/zh-CN/artifacts#availability) + +```json settings.json theme={null} +{ + "enableArtifact": false +} +``` + +当除你自己的用户设置之外的源保持工具关闭时，Claude Code 在 `/config` 中隐藏**Artifacts** 行，因为在那里打开它不会改变任何东西。[禁用 artifacts](/docs/zh-CN/artifacts#disable-artifacts) 列出了关闭工具的每种方式。在 v2.1.242 之前，Claude Code 在项目和本地设置中忽略此键，[优先级堆栈](/docs/zh-CN/settings#settings-precedence)中较高的文件可能会在较低文件的关闭上打开工具。 + +

+ `inputNeededNotifEnabled` +

+ +当权限提示或问题等待你的输入时，在你的手机上获得推送通知。Claude Code 仅在[远程控制](/docs/zh-CN/remote-control)连接时发送这些通知。在 `/config` 中显示为**需要操作时推送**。 + +* **作用域**: [`任何文件`](#scopes)。Claude Code 也会读取由旧版本留在 `~/.claude.json` 中的值。 +* **类型**: 布尔值 + * `true`: 当权限提示或问题等待时，你会在手机上获得推送通知，同时远程控制已连接 + * `false`: Claude Code 不发送此类通知 +* **默认值**: `false` + +```json settings.json theme={null} +{ + "inputNeededNotifEnabled": true +} +``` + +请参阅[移动推送通知](/docs/zh-CN/remote-control#mobile-push-notifications)。 + +

+ `preferredNotifChannel` +

+ +选择 Claude Code 在任务完成或权限提示等待时如何通知你。在 `/config` 中显示为**本地通知**。 + +* **作用域**: [`任何文件`](#scopes)。Claude Code 也会读取由旧版本留在 `~/.claude.json` 中的值。 +* **类型**: 字符串，以下之一： + * `"auto"`: Claude Code 在 iTerm2、Ghostty 和 Kitty 中发送桌面通知，在 Terminal.app 中仅当其可听铃声关闭时才响铃，在其他地方不执行任何操作 + * `"terminal_bell"`: Claude Code 在任何终端中响铃字符 + * `"iterm2"`: Claude Code 发送 iTerm2 桌面通知 + * `"iterm2_with_bell"`: Claude Code 发送 iTerm2 桌面通知并响铃 + * `"kitty"`: Claude Code 发送 Kitty 桌面通知 + * `"ghostty"`: Claude Code 发送 Ghostty 桌面通知 + * `"notifications_disabled"`: Claude Code 不发送通知 +* **默认值**: `"auto"` + +```json settings.json theme={null} +{ + "preferredNotifChannel": "terminal_bell" +} +``` + +使用 `"auto"` 时，Claude Code 在 iTerm2、Ghostty 和 Kitty 中发送桌面通知。在 Terminal.app 中，仅当你关闭了 Terminal 的可听铃声时才响铃字符，在其他终端中不执行任何操作。设置 `"terminal_bell"` 以在任何终端中响铃字符。请参阅[获取终端铃声或通知](/docs/zh-CN/terminal-config#get-a-terminal-bell-or-notification)。 + +

+ `remote.defaultEnvironmentId` +

+ +为你从 CLI 创建的云会话（例如使用 `claude --cloud`）选择默认[云环境](/docs/zh-CN/cloud-environments)。当你使用 [`/remote-env`](/docs/zh-CN/cloud-environments#select-an-environment-from-the-cli) 选择环境时，Claude Code 会将此键写入你的用户设置。 + +* **作用域**: [`任何文件`](#scopes)。对于自托管环境 ID，仅用户或托管设置或 `--settings` 标志。 +* **类型**: 字符串，环境 ID，如 `env_...` 或 `ccpool_...` +* **默认值**: 未设置，因此当你的列表有 Anthropic 托管环境时 Claude Code 使用它，否则使用列表中不是[远程控制桥接环境](/docs/zh-CN/cloud-environments#the-default-environment)的第一个环境，或当每个都是桥接环境时使用第一个环境 +* **每个会话的覆盖**: `--environment` 优先于此键用于它创建的一个云会话 + +```json settings.json theme={null} +{ + "remote": { + "defaultEnvironmentId": "env_0123abcd" + } +} +``` + +Anthropic 托管的环境 ID（以 `env_` 开头）遵循标准设置优先级，因此存储库的项目设置中的值会覆盖你的用户级别选择。[自托管环境](/docs/zh-CN/self-hosted-environments) ID（以 `ccpool_` 开头）仅从用户设置、托管设置和 `--settings` 标志中获得尊重；Claude Code 忽略存储库的项目或本地设置中的一个，`/remote-env` 显示它忽略了哪个值，因此签入的文件无法将会话引导到你未选择的自托管环境。 + +

+ `remoteControlAtStartup` +

+ +当每个交互式会话启动时自动连接[远程控制](/docs/zh-CN/remote-control)，而不是等待 `/remote-control`。将其设置为 `true` 以打开自动连接，`false` 以关闭。在 `/config` 中显示为**为所有会话启用远程控制**。 + +* **作用域**: [`任何文件`](#scopes)。Claude Code 也会读取由旧版本留在 `~/.claude.json` 中的值。 +* **类型**: 布尔值 + * `true`: Claude Code 在每个交互式会话启动时自动连接远程控制 + * `false`: Claude Code 等待 `/remote-control` +* **默认值**: 未设置，因此自动连接遵循你的组织的管理员默认值（如果已设置），否则遵循 Claude Code 的当前默认值 +* **每个会话的覆盖**: `--remote-control` 即使此键为 `false` 也会为一个会话打开远程控制，没有标志会为一个会话关闭它 + +```json settings.json theme={null} +{ + "remoteControlAtStartup": true +} +``` + +Claude Code 忽略项目或本地设置中的 `true`，因此存储库可以为其检出关闭自动连接，但无法打开。有关完整的每个作用域行为，请参阅[为所有会话启用远程控制](/docs/zh-CN/remote-control#enable-remote-control-for-all-sessions)和[应用更严格值的安全键](/docs/zh-CN/settings#security-keys-where-the-stricter-value-applies)。 + +

+ `sshConfigs` +

+ +将 SSH 连接添加到[桌面](/docs/zh-CN/desktop#pre-configure-ssh-connections-for-your-team)环境下拉列表。管理员使用它向团队分发共享连接。你在托管设置中定义的连接显示为托管，因此用户可以选择它们，但无法在应用中编辑或删除它们。 + +* **作用域**: [`用户或托管`](#scopes)。桌面应用读取此键。 +* **类型**: 对象数组，每个都有必需的 `id`、`name` 和 `sshHost` 以及可选的 `sshPort` 和 `sshIdentityFile` +* **默认值**: 未设置 + +此示例添加一个名为 `Dev VM` 的连接，连接到 `user@dev.example.com`： + +```json settings.json theme={null} +{ + "sshConfigs": [ + { + "id": "dev-vm", + "name": "Dev VM", + "sshHost": "user@dev.example.com" + } + ] +} +``` + +

+ `sshHostAllowlist` +

+ +限制[桌面 SSH 会话](/docs/zh-CN/desktop#restrict-which-ssh-hosts-users-can-connect-to)可以连接到的主机。仅桌面应用读取此键；CLI 不读取。模式不区分大小写：`*` 匹配任何主机，`*.example.com` 匹配 `example.com` 和每个子域，其他任何内容都是针对 `~/.ssh/config` 解析后的主机名的精确匹配。空数组关闭 SSH 会话。 + +* **作用域**: [`托管`](#scopes) +* **类型**: 主机名模式数组 +* **默认值**: 未设置，因此允许任何主机 + +此示例允许 `devboxes.example.com` 及其子域，加上精确主机 `bastion.example.com`： + +```json managed-settings.json theme={null} +{ + "sshHostAllowlist": ["*.devboxes.example.com", "bastion.example.com"] +} +``` + + + +

+ 身份验证和提供商 +

+ +通过辅助脚本提供凭证，对于组织，强制使用登录方法或组织。请参阅[身份验证](/docs/zh-CN/authentication)。 + +

+ `apiKeyHelper` +

+ +运行您自己的命令来生成 Claude Code 随模型请求发送的凭证。Claude Code 通过系统 shell 运行该命令，在 macOS 和 Linux 上为 `/bin/sh`，在 Windows 上为 `cmd`，并将其输出作为 `X-Api-Key` 和 `Authorization: Bearer` 标头发送。将其用于动态或轮换凭证，例如从保管库获取的短期令牌。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，shell 命令行 +* **Default**: 未设置，因此 Claude Code 不运行辅助程序 + +```json settings.json theme={null} +{ + "apiKeyHelper": "/bin/generate_temp_api_key.sh" +} +``` + +Claude Code 缓存该值并在以下情况下重新运行该命令： + +* 在缓存生命周期后，默认为五分钟或您使用 [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/docs/zh-CN/env-vars) 设置的间隔。 +* 当对 Anthropic API 的请求（直接或通过 [LLM gateway](/docs/zh-CN/llm-gateway)）失败并返回 `401` 或 `403` 时。 +* 在向 Anthropic API 发送请求之前（直接或通过 LLM gateway），当缓存的输出是在辅助程序生成后过期的 JWT 时。需要 Claude Code v2.1.246 或更高版本。 + +最后两种情况仅在辅助程序的输出是 Claude Code 发送的凭证且未设置 `ANTHROPIC_AUTH_TOKEN` 时适用。 + +在交互式会话中，当命令来自项目或本地设置时，Claude Code 在您接受工作区信任提示之前不会运行它。请参阅[凭证管理](/docs/zh-CN/authentication#credential-management)。 + +

+ `awsAuthRefresh` +

+ +运行您自己的命令（例如 `aws sso login`），以在 Claude Code 用于 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 的凭证停止工作时刷新 `.aws` 目录中的凭证。Claude Code 首先根据 STS 检查当前凭证，仅在该检查失败时运行该命令，然后读取刷新的 `.aws` 目录。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，shell 命令行 +* **Default**: 未设置，因此 Claude Code 不为您刷新 AWS 凭证 + +```json settings.json theme={null} +{ + "awsAuthRefresh": "aws sso login --profile myprofile" +} +``` + +当您的刷新流写入 `.aws` 时使用此密钥；当它打印凭证时使用 [`awsCredentialExport`](#awscredentialexport)。请参阅[高级凭证配置](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration)。 + +

+ `awsCredentialExport` +

+ +运行您自己的命令，该命令将 AWS 凭证打印为 JSON，以便 Claude Code 可以使用不存在于 `.aws` 目录中的凭证调用 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)。Claude Code 接受 `aws sts` 输出形状和平面 `aws configure export-credentials` 形状，并将凭证范围限定为其自己的 Bedrock 客户端，因此 Claude Code 运行的 shell 命令仍然看到您的环境凭证。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，shell 命令行 +* **Default**: 未设置，因此 Claude Code 使用环境 AWS 凭证链 + +```json settings.json theme={null} +{ + "awsCredentialExport": "/bin/generate_aws_grant.sh" +} +``` + +与 [`awsAuthRefresh`](#awsauthrefresh) 不同，Claude Code 在设置此命令时始终运行它，而不首先检查环境凭证。请参阅[高级凭证配置](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration)。 + +

+ `forceLoginMethod` +

+ +限制人们可以使用哪种帐户登录。设置 `"claudeai"` 以仅允许 claude.ai 帐户，设置 `"console"` 以仅允许 Claude Console 帐户，或设置 `"gateway"` 以将人们发送到 [cloud gateway](/docs/zh-CN/claude-apps-gateway) 而不是第一方登录。管理员在托管设置中设置它，并将其与 [`forceLoginOrgUUID`](#forceloginorguuid) 配对，以将开发人员的 claude.ai 登录保持在一个组织内。如果您在任何设置文件中将其设置为 `"claudeai"` 或 `"console"`，Claude Code 也会停止在该文件适用的会话中提供[无密钥 Console 登录](/docs/zh-CN/authentication#sign-in-without-an-api-key)。 + +* **Scope**: [`Any file`](#scopes)。Claude Code 仅从机器上的托管源（`managed-settings.json`、macOS plist 或 Windows HKLM 注册表或策略辅助程序）接受 `"gateway"`。它在用户、项目、本地、HKCU 和服务器托管设置中将 `"gateway"` 视为未设置，与 [`forceLoginGatewayUrl`](#forcelogingatewayurl) 的规则相同。 +* **Type**: string，以下之一： + * `"claudeai"`：仅 claude.ai 帐户可以登录 + * `"console"`：仅 Claude Console 帐户可以登录 + * `"gateway"`：Claude Code 将人们发送到 cloud gateway 而不是第一方登录 +* **Default**: 未设置，因此人们选择登录方法 + +```json settings.json theme={null} +{ + "forceLoginMethod": "claudeai" +} +``` + +每个第一方登录路径都应用该限制，包括 [VS Code 扩展](/docs/zh-CN/vs-code)、Agent SDK、`claude setup-token` 和 `/install-github-app`，除了终端的交互式登录屏幕（通过 `/login` 或首次运行入门到达），它预选择该方法而不强制执行。在 v2.1.212 之前，仅终端登录应用了它。请参阅[限制登录到您的组织](/docs/zh-CN/authentication#restrict-login-to-your-organization)，了解如何处理每个登录路径、环境凭证和第三方提供商。 + +当机器上的托管源设置 `"gateway"` 时，Claude Code 不使用剩余登录、API 密钥或 `apiKeyHelper` 凭证。请参阅[管理员策略需要 Cloud gateway 登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)，了解每个凭证生成的消息。如果您通过 `CLAUDE_CODE_USE_BEDROCK` 或类似的环境变量选择云提供商，该会话不需要网关登录。在 v2.1.261 之前，Claude Code 在这些机器上使用了剩余登录。 + +

+ `forceLoginGatewayUrl` +

+ +设置 `/login` Cloud gateway 屏幕连接到的网关 URL，以便人们可以到达您的 [cloud gateway](/docs/zh-CN/claude-apps-gateway) 而无需输入其地址。该屏幕没有 URL 字段：设置此密钥后，它显示您的网关 URL 并在人们按 Enter 时连接；不设置时，它告诉他们联系其 IT 管理员。 + +此密钥或 `forceLoginMethod: "gateway"` 使机器仅限网关，因此 `/login` 在 Cloud gateway 屏幕上打开，没有登录方法选择器。请参阅[管理员策略需要 Cloud gateway 登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)，了解剩余第一方登录或 API 密钥会发生什么。设置两个密钥，以便屏幕连接而不是显示错误。 + +* **Scope**: [`Managed`](#scopes)。仅从机器上的源读取：`managed-settings.json`、macOS plist 或 Windows HKLM 注册表或策略辅助程序。Claude Code 在 HKCU 和服务器托管设置中忽略它。 +* **Type**: string，包括方案的完整 URL +* **Default**: 未设置，因此 Cloud gateway 屏幕显示错误，告诉人们联系其 IT 管理员 + +```json managed-settings.json theme={null} +{ + "forceLoginGatewayUrl": "https://claude-gateway.example.com" +} +``` + +如果该值不是有效的 URL，登录屏幕会报告它，托管设置文件的其余部分仍然适用。请参阅[设置网关 URL](/docs/zh-CN/claude-apps-gateway#set-the-gateway-url)。 + +

+ `forceLoginOrgUUID` +

+ +从托管源，要求 claude.ai 帐户登录属于一个 Anthropic 组织（给定为单个 UUID）或属于多个组织（给定为数组）。从任何设置文件，Claude Code 也使用单个 UUID 在 claude.ai 或 Claude Console 登录期间预选择该组织，对于数组预选择任何内容。如果您在任何设置文件中设置该密钥，Claude Code 也会停止在该文件适用的会话中提供[无密钥 Console 登录](/docs/zh-CN/authentication#sign-in-without-an-api-key)，并改为创建 API 密钥。 + +* **Scope**: [`Any file`](#scopes)。仅托管源强制执行限制；任何其他设置文件中的单个 UUID 在登录期间预选择组织而不限制它。 +* **Type**: string，一个 UUID，或字符串数组，多个 UUID +* **Default**: 未设置，因此任何组织都可以登录 + +此示例接受来自两个组织之一的登录，而不预选择一个： + +```json managed-settings.json theme={null} +{ + "forceLoginOrgUUID": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"] +} +``` + +如果托管源设置空数组或 Claude Code 无法解析的值，Claude Code 会使用错误配置消息阻止每个登录。 + +请参阅[限制登录到您的组织](/docs/zh-CN/authentication#restrict-login-to-your-organization)，了解 Claude Code 如何处理 Claude Console 登录、其他登录路径和环境凭证。 + +

+ `gcpAuthRefresh` +

+ +运行您自己的命令以在 Claude Code 发现 Google Cloud Application Default Credentials 已过期或无法加载时刷新它们，以便 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 请求继续工作，而无需您手动重新身份验证。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，shell 命令行 +* **Default**: 未设置，因此 Claude Code 的凭证错误告诉您自己运行 `gcloud auth application-default login` + +```json settings.json theme={null} +{ + "gcpAuthRefresh": "gcloud auth application-default login" +} +``` + +请参阅[高级凭证配置](/docs/zh-CN/google-vertex-ai#advanced-credential-configuration)。 + +

+ `otelHeadersHelper` +

+ +运行您自己的命令以生成 Claude Code 随 OpenTelemetry 导出发送的标头，用于令牌轮换的后端。Claude Code 在启动时运行它，之后定期运行，并期望在 stdout 上获得字符串标头值的 JSON 对象。 + +* **Scope**: [`Any file`](#scopes) +* **Type**: string，可执行路径或 shell 命令行 +* **Default**: 未设置，因此 Claude Code 不添加辅助程序生成的标头 + +```json settings.json theme={null} +{ + "otelHeadersHelper": "/bin/generate_otel_headers.sh" +} +``` + +使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/docs/zh-CN/env-vars) 设置刷新间隔。请参阅[动态标头](/docs/zh-CN/monitoring-usage#dynamic-headers)，了解脚本要求以及 Claude Code 报告失败辅助程序的位置。 + +

+ 更新和版本控制 +

+ +选择更新渠道，对于组织，可以固定人们可以运行的版本。请参阅[更新 Claude Code](/docs/zh-CN/setup#update-claude-code)。 + +

+ `autoUpdatesChannel` +

+ +选择[发布渠道](/docs/zh-CN/setup#configure-release-channel)，背景自动更新和 `claude update` 遵循该渠道。设置 `"stable"` 以获得通常约一周前的版本，并跳过有重大回归的发布，或设置 `"latest"` 以获得最新发布。 + +* **Scope**: [`Any file`](#scopes)。在托管设置中设置以在整个组织中强制执行一个渠道。 +* **Type**: string，以下之一： + * `"latest"`：更新遵循最新发布 + * `"stable"`：更新遵循通常约一周前的版本，并跳过有重大回归的发布 +* **Default**: 未设置，所以 Claude Code 遵循 `"latest"` + +```json settings.json theme={null} +{ + "autoUpdatesChannel": "stable" +} +``` + +当您在 `/config` 中的**自动更新渠道**下选择它时，Claude Code 会将 `"stable"` 写入您的用户设置，当您在那里切换回最新版本时会删除该键。`claude install stable` 和 `claude install latest` 也会保存您命名的渠道。在 `/config` 中从 `"latest"` 切换到 `"stable"` 会询问是否允许降级或保持当前版本；保持设置 [`minimumVersion`](#minimumversion)。Homebrew 安装会忽略此键：`claude-code` cask 跟踪稳定版，`claude-code@latest` 跟踪最新版，`claude update` 遵循 `brew upgrade`。要完全关闭自动更新，请在 `env` 中设置 [`DISABLE_AUTOUPDATER`](/docs/zh-CN/setup#disable-auto-updates)。 + +

+ `minimumVersion` +

+ +防止背景自动更新和 `claude update` 安装低于此版本的任何版本，因此移动到 `"stable"` 渠道不会从较新的 `"latest"` 构建中降级您。当您在 `/config` 中选择在切换渠道时保持当前版本时，Claude Code 会为您写入此键，当您切换回 `"latest"` 时会清除它。 + +* **Scope**: [`Any file`](#scopes)。在托管设置中设置以固定组织范围的最小值，用户和项目设置无法降低。 +* **Type**: string，版本号，例如 `"2.1.100"` +* **Default**: 未设置，所以更新可以安装渠道提供的任何版本 + +此示例遵循稳定渠道，并拒绝安装低于 2.1.100 的任何版本： + +```json settings.json theme={null} +{ + "autoUpdatesChannel": "stable", + "minimumVersion": "2.1.100" +} +``` + +此键仅约束更新。要使 Claude Code 拒绝在版本以下启动，请改用 [`requiredMinimumVersion`](#requiredminimumversion)。请参阅[固定最小版本](/docs/zh-CN/setup#pin-a-minimum-version)。 + +

+ `requiredMaximumVersion` +

+ +设置您的组织允许启动的最新 Claude Code 版本。当运行版本较新时，Claude Code 在启动时退出，并告诉用户通过您组织的批准方法安装批准的版本；`claude install ` 也可能有效。需要 Claude Code v2.1.163 或更高版本。 + +* **Scope**: [`Managed`](#scopes)。Claude Code 在其他地方忽略该键时不会发出警告。 +* **Type**: string，版本号，例如 `"2.1.150"`；不是有效版本的值会被忽略 +* **Default**: 未设置，所以不适用上限 + +```json managed-settings.json theme={null} +{ + "requiredMaximumVersion": "2.1.150" +} +``` + +背景自动更新和 `claude update` 跳过上限以上的版本，因此范围内的安装保持在范围内。`claude update`、`claude install` 和 `claude doctor` 在上限以上继续工作，以便用户可以恢复。将其与 [`requiredMinimumVersion`](#requiredminimumversion) 配对以强制执行范围。 + +

+ `requiredMinimumVersion` +

+ +设置您的组织允许启动的最旧 Claude Code 版本。当运行版本较旧时，Claude Code 在启动时退出，并告诉用户通过您组织的批准方法进行更新。检查仅在启动时运行，因此已在运行的会话会继续。需要 Claude Code v2.1.163 或更高版本。 + +* **Scope**: [`Managed`](#scopes)。Claude Code 在其他地方忽略该键时不会发出警告。 +* **Type**: string，版本号，例如 `"2.1.150"`；不是有效版本的值会被忽略 +* **Default**: 未设置，所以不适用下限 + +```json managed-settings.json theme={null} +{ + "requiredMinimumVersion": "2.1.150" +} +``` + +`claude update`、`claude install` 和 `claude doctor` 在下限以下继续工作，以便用户可以恢复。与仅防止降级的 [`minimumVersion`](#minimumversion) 不同，此键会阻止启动。将其与 [`requiredMaximumVersion`](#requiredmaximumversion) 配对以强制执行范围。 + +

+ Tools +

+ +在 [Claude Code 桌面应用](/docs/zh-CN/desktop) 中关闭特定工具。终端 CLI 会忽略这些密钥。有关工具本身，请参阅 [Claude 可用的工具](/docs/zh-CN/tools-reference)。 + +

+ `browserExternalPageTools` +

+ +阻止 Claude 在桌面应用的 [浏览器窗格](/docs/zh-CN/desktop#browse-external-sites) 中使用其工具读取或作用于外部页面。您组织中的人员仍然可以自己打开外部网站，本地开发服务器预览继续与 Claude 的工具一起工作。桌面应用读取此密钥；终端 CLI 会忽略它。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: string，`"disabled"`；桌面应用也接受 `"disable"`，在任何一种情况下 +* **Default**: 未设置，因此 Claude 的工具可在外部页面上工作 + +```json managed-settings.json theme={null} +{ + "browserExternalPageTools": "disabled" +} +``` + +任何其他值都会使 Claude 的工具保持打开状态，非空字符串如果不是两个接受的值之一，则会记录警告。要同时阻止人员和 Claude 访问外部网站，请改为设置 [`disableBrowserExternalNavigation`](#disablebrowserexternalnavigation)。请参阅 [为您的组织限制外部浏览](/docs/zh-CN/desktop#restrict-external-browsing-for-your-organization)。 + +

+ `disableBrowserExternalNavigation` +

+ +在桌面应用的 [浏览器窗格](/docs/zh-CN/desktop#browse-external-sites) 中为人员和 Claude 关闭外部浏览。Localhost 开发服务器预览继续工作。桌面应用读取此密钥；终端 CLI 会忽略它。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: Boolean；仅 JSON Boolean `true` 生效 + * `true`：桌面应用在浏览器窗格中为人员和 Claude 关闭外部浏览；localhost 预览继续工作 + * `false`：外部浏览保持打开 +* **Default**: 未设置，因此外部浏览是打开的 + +```json managed-settings.json theme={null} +{ + "disableBrowserExternalNavigation": true +} +``` + +桌面应用会忽略任何其他值，非 Boolean 的值（例如字符串 `"true"` 或 `1`）也会记录警告。要保持外部浏览打开但在外部页面上关闭 Claude 的工具，请改为设置 [`browserExternalPageTools`](#browserexternalpagetools)。请参阅 [为您的组织限制外部浏览](/docs/zh-CN/desktop#restrict-external-browsing-for-your-organization)。 + +

+ `disableMobileSimulatorTools` +

+ +阻止 Claude 的工具用于桌面应用的 [iOS 模拟器窗格](/docs/zh-CN/desktop-ios-simulator#turn-off-simulator-access)。人员保持对窗格的手动使用；仅移除 Claude 的访问权限，任何人都无法从应用内部将其重新打开。桌面应用读取此密钥；终端 CLI 会忽略它。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: Boolean；仅 JSON Boolean `true` 生效 + * `true`：桌面应用阻止 Claude 的工具用于 iOS 模拟器窗格 + * `false`：Claude 的模拟器工具遵循桌面应用中每个人的设置切换 +* **Default**: 未设置，因此 Claude 的模拟器工具遵循桌面应用中每个人的设置切换 + +```json managed-settings.json theme={null} +{ + "disableMobileSimulatorTools": true +} +``` + +桌面应用会忽略任何其他值，非 Boolean 的值（例如字符串 `"true"` 或 `1`）也会记录警告。 + + + +

+ 隐私和遥测 +

+ +控制 Claude Code 保留会话数据的时间以及它发送的内容。关闭使用指标和错误报告的开关是环境变量，而不是设置键：在 [`env`](#env) 键中或在 shell 中设置 `DISABLE_TELEMETRY`、`DISABLE_ERROR_REPORTING` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`。[遥测服务](/docs/zh-CN/data-usage#telemetry-services)说明了每个变量的作用。两个例外可以从设置文件中关闭：下面的 [`feedbackDrafts`](#feedbackdrafts) 用于 Claude 起草的反馈，下面的 [`feedbackSurveyRate`](#feedbacksurveyrate) 用于会话调查。 + +

+ `cleanupPeriodDays` +

+ +设置 Claude Code 在删除之前保留[会话记录和其他应用程序数据](/docs/zh-CN/claude-directory#cleaned-up-automatically)的天数。Claude Code 在会话开始后作为后台扫描运行删除，只要它能够安全地确定保留期。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 天数，整数，最小值 `1` +* **默认值**: `30` + +```json settings.json theme={null} +{ + "cleanupPeriodDays": 20 +} +``` + +设置 `0` 会导致验证失败，因此请选择一个较大的值，例如 `3650` 以实现长期保留。要停止 Claude Code 完全写入记录，请参阅[纯文本存储](/docs/zh-CN/claude-directory#plaintext-storage)。 + +

+ `desktopSessionCleanupPeriodDays` +

+ +为您在 Claude Desktop 或 Cowork 中启动或最近继续的会话的记录设置天数年龄限制。没有此键，Claude Code [会无限期地保留这些记录](/docs/zh-CN/claude-directory#cleaned-up-automatically)。Claude Code 在每个记录的年龄超过此限制和 [`cleanupPeriodDays`](#cleanupperioddays) 时删除它，因此当 `cleanupPeriodDays` 处于其默认值 30 时，值 `7` 仍会保留它们 30 天。当托管设置设置 `cleanupPeriodDays` 时，该期间改为适用，此键被忽略。需要 Claude Code v2.1.248 或更高版本。 + +* **范围**: [`用户或托管`](#scopes)。Claude Code 也从您使用 `--settings` 传递的文件中读取该键，并在项目和本地设置中忽略它。 +* **类型**: 天数，整数，最小值 `0` +* **默认值**: `0`，不设置年龄限制 + +```json settings.json theme={null} +{ + "desktopSessionCleanupPeriodDays": 90 +} +``` + +

+ `feedbackDrafts` +

+ +控制 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)：Claude 是否可以为您排队反馈草稿以供审查，以及 Claude Code 在 Claude 排队时是否显示卡片。 + +* **范围**: [`用户或托管`](#scopes) +* **类型**: 字符串，`"notify"`、`"quiet"` 或 `"off"` 之一 + * `"notify"`：当 Claude 排队草稿时，Claude Code 在提示上方显示卡片，默认情况下[一个会话中最多三张卡片](/docs/zh-CN/tools-reference#what-you-see-when-claude-drafts) + * `"quiet"`：Claude 在没有卡片的情况下起草。您在提示页脚中看到排队草稿的计数，并在 `/feedback` 中审查它们 + * `"off"`：Claude Code 删除 SendFeedback 工具，因此 Claude 无法排队草稿 +* **默认值**: `"notify"` +* **每个会话的覆盖**: [`CLAUDE_CODE_SEND_FEEDBACK`](/docs/zh-CN/env-vars) 设置为 `0` 会关闭一个会话的此功能 + +```json settings.json theme={null} +{ + "feedbackDrafts": "quiet" +} +``` + +在 `/config` 中显示为**Claude 起草的反馈**，它将此键写入您的用户设置。您只在 Claude 可以起草反馈的[会话中](/docs/zh-CN/tools-reference#sessions-without-claude-drafted-feedback)看到 `/config` 行；设置 `"off"` 不会隐藏它，因此您可以从同一行重新打开此功能。托管设置中的值优先于您的用户设置，因此当管理员设置此键时，该行显示托管值，更改它无效。Claude Code 在项目和本地设置中忽略此键。 + +

+ `feedbackSurveyRate` +

+ +设置[会话质量调查](/docs/zh-CN/data-usage#session-quality-surveys)在会话符合条件时出现的概率。设置 `0` 以防止调查出现。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: `0` 到 `1` 之间的数字 +* **默认值**: 未设置，因此 Claude Code 使用 Anthropic 远程设置的速率，或在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的内置速率 `0.005`，这些不接收远程配置 +* **每个会话的覆盖**: [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/docs/zh-CN/env-vars) 设置为 `1` 会关闭一个会话的调查，无论此键设置的速率如何 + +```json settings.json theme={null} +{ + "feedbackSurveyRate": 0.05 +} +``` + +相同的速率适用于 VS Code 扩展中的调查。 + +

+ `skipWebFetchPreflight` +

+ +跳过 [WebFetch 域安全检查](/docs/zh-CN/data-usage#webfetch-domain-safety-check)，该检查在获取之前将每个请求的主机名发送到 `api.anthropic.com`。在阻止到 Anthropic 的流量的环境中设置 `true`，例如 Amazon Bedrock、Google Cloud 的 Agent Platform 或具有限制性出站的 Microsoft Foundry 部署。 + +* **范围**: [`任何文件`](#scopes) +* **类型**: 布尔值 + * `true`：Claude Code 跳过 WebFetch 域安全检查 + * `false`：检查在会话中首次获取每个主机名之前运行，以及对于其早期检查被阻止或失败的主机名再次运行 +* **默认值**: 未设置，因此检查在会话中首次获取每个主机名之前运行 + +```json settings.json theme={null} +{ + "skipWebFetchPreflight": true +} +``` + +跳过检查后，WebFetch 尝试任何 URL 而不查询阻止列表，因此如果您需要限制 Claude 可以访问的域，请将其与 [`WebFetch` 权限规则](/docs/zh-CN/permissions#webfetch)配对。 + + + +

+ 企业和托管设置 +

+ +组织用来计算、刷新和合并托管设置的密钥。请参阅[设置托管设置](/docs/zh-CN/admin-setup)。 + +

+ `disableSideloadFlags` +

+ +在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` CLI 标志，用户可能会通过这些标志来绕过 [`strictKnownMarketplaces`](#strictknownmarketplaces) 进行单次运行。Claude Code 会以错误退出并命名被拒绝的标志，并对在内部使用这些标志启动 CLI 的表面应用相同的检查，目前在桌面应用中的 [Cowork](/docs/zh-CN/desktop) 本地会话。在[云会话](/docs/zh-CN/claude-code-on-the-web)中，Claude Code 会删除服务器通过 `--mcp-config` 传递的 MCP 服务器，除了进程内 `type: "sdk"` 条目，并启动会话。需要 Claude Code v2.1.193 或更高版本。 + +* **Scope**: [`Managed`](#scopes) +* **Type**: Boolean + * `true`: Claude Code 在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config`，并以错误退出并命名它们，除了在云会话中它会删除服务器通过 `--mcp-config` 传递的 MCP 服务器，除了进程内 `type: "sdk"` 条目，并启动会话 + * `false`: Claude Code 接受这些标志 +* **Default**: `false` + +```json managed-settings.json theme={null} +{ + "disableSideloadFlags": true +} +``` + +Claude Code 仍然接受其服务器都是进程内 `type: "sdk"` 条目的 `--mcp-config`，因此 Agent SDK 和 VS Code 扩展继续工作。用户仍然可以使用 `claude mcp add` 或 `.mcp.json` 文件添加服务器；为了进行每个服务器的控制，也可以设置 [`allowedMcpServers`](/docs/zh-CN/managed-mcp)。需要 Claude Code v2.1.193 或更高版本。 + +在云会话中，Claude Code 也会忽略服务器传递的中途 MCP 更新，这是云会话配置和远程工作者上 SDK `setMcpServers()` 背后的路径。进程内 `type: "sdk"` 条目在那里仍然豁免。在 v2.1.239 之前，服务器传递的 `--mcp-config` 会阻止云会话启动。 + +

+ `forceRemoteSettingsRefresh` +

+ +阻止 CLI 启动，直到 Claude Code 已经新鲜获取[服务器管理的设置](/docs/zh-CN/server-managed-settings)。如果获取失败，Claude Code 会退出而不是继续使用缓存或无设置。当您的环境无法接受即使是短暂的窗口（在该窗口中会话在没有其托管策略的情况下运行）时，请设置它。 + +当密钥未设置时，Claude Code 不会在获取时阻止启动，尽管当开发者在启动时登录时，它会等待最多五秒钟以进行获取。Cloud 网关会话总是等待，如果无法到达网关则退出。 + +* **Scope**: [`Managed`](#scopes)。Claude Code 从任何管理员控制的托管源（即使不是最高优先级源）中接受 `true`。 +* **Type**: Boolean + * `true`: Claude Code 阻止启动，直到它已经新鲜获取服务器管理的设置，如果获取失败则退出 + * `false`: Claude Code 不会在获取时阻止启动，尽管在登录启动时它会等待最多五秒钟以进行获取 +* **Default**: `false` + +```json managed-settings.json theme={null} +{ + "forceRemoteSettingsRefresh": true +} +``` + +在 MDM 配置文件或托管设置文件中设置它以在第一个服务器有效负载到达之前强制执行故障关闭启动。Claude Code 仅在获取服务器管理的设置的会话中应用检查，因此[不获取它们](/docs/zh-CN/server-managed-settings#platform-availability)的会话启动时不会等待。`claude auth` 子命令豁免，因此用户可以在过期凭证是获取失败原因时重新身份验证。请参阅[强制执行故障关闭启动](/docs/zh-CN/server-managed-settings#enforce-fail-closed-startup)。 + +

+ `managedSourcesBehavior` +

+ +选择 Claude Code 是仅应用您的组织提供的最高优先级[托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)，还是合并它提供的每个管理员源。默认情况下，Claude Code 采用携带[策略密钥](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)的最高优先级源并忽略其余的。策略密钥是除了这个密钥和 `wslInheritsWindowsSettings` 之外的任何设置密钥。因此，一旦服务器管理的设置或 MDM 策略提供策略密钥，`managed-settings.json` 文件仅贡献 [Claude Code 从每个管理员源读取的密钥](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)。使用 `"merge"`，您提供的每个管理员源都会将其密钥贡献给一个合并的策略。需要 Claude Code v2.1.242 或更高版本。 + +仅在您[排名](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)在最高优先级源下方的每个源都在管理员的控制下时设置 `"merge"`，因为 Claude Code 然后从较低源（例如 `permissions.allow` 规则）添加条目到策略。 + +* **Scope**: [`Managed`](#scopes)。Claude Code 从携带此密钥或策略密钥的最高优先级源读取此密钥，并忽略排名较低的每个源中的此密钥，因此较低源无法选择自己合并到上面的源。Windows HKCU 注册表和[来自嵌入主机的父设置](/docs/zh-CN/managed-settings#let-an-embedding-host-add-policy)都不参与合并。 +* **Type**: string，其中之一： + * `"first-wins"`: 携带策略密钥的最高优先级源提供策略，较低源仅贡献 [Claude Code 从每个管理员源读取的密钥](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source) + * `"merge"`: 您提供的每个管理员源都贡献其密钥，按以下规则合并 +* **Default**: `"first-wins"` + +在您部署的最高优先级源中提供密钥。从不接收服务器管理的设置的机器也需要在其 MDM 配置文件中使用该密钥，因为 Claude Code 从携带它或策略密钥的最高优先级源读取该密钥。`managed-settings.json` 文件是最低排名的管理员源，因此在那里设置的 `"merge"` 没有下面的源可以合并。在服务器管理的设置中，密钥看起来像这样： + +```json theme={null} +{ + "managedSourcesBehavior": "merge" +} +``` + +在 `"merge"` 下，Claude Code 按其类型合并每个密钥。此表给出每种类型的规则。限制允许列表、整体取值和仅最高源行命名它们覆盖的每个密钥，其他行给出示例： + +| 密钥类型 | Claude Code 如何合并它 | 密钥 | +| :----------------------------------------- | :----------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Lists | 合并来自每个源的条目 | [`permissions.allow`](#permissions-allow)、[`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 和其他列表密钥 | +| Locks | 应用任何源设置的最严格值。当没有源设置严格值时，仅从最高源应用较宽松的值 | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly)、[`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 和其他布尔值或枚举锁 | +| Restriction allowlists | 从设置它的最高源整体取值，不从较低源添加条目。当最高源未设置时，从下一个源整体取值 | [`availableModels`](#availablemodels)、[`allowedMcpServers`](#allowedmcpservers)、[`strictKnownMarketplaces`](#strictknownmarketplaces)、[`allowedChannelPlugins`](#allowedchannelplugins) 和 [`fallbackModel`](#fallbackmodel) 链 | +| Values taken whole | 从设置它的最高源整体取值，不合并来自较低源的条目或字段。当最高源未设置时，从下一个源整体取值 | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs)、[`sandbox.ripgrep`](#sandbox-ripgrep) | +| Provided MCP servers | 合并来自每个源的服务器名称。当两个源设置相同名称时，应用较高源的整个条目 | [`managedMcpServers`](#managedmcpservers) | +| Read from the highest-priority source only | 仅从携带策略密钥的最高优先级源读取密钥，因此即使最高源未设置，较低源的值也会被忽略 | [`apiKeyHelper`](#apikeyhelper)、[`awsAuthRefresh`](#awsauthrefresh)、[`awsCredentialExport`](#awscredentialexport)、[`gcpAuthRefresh`](#gcpauthrefresh)、[`otelHeadersHelper`](#otelheadershelper)、`proxyAuthHelper`、[`forceLoginOrgUUID`](#forceloginorguuid)、[`forceLoginMethod`](#forceloginmethod)、[`forceLoginGatewayUrl`](#forcelogingatewayurl)、[`parentSettingsBehavior`](#parentsettingsbehavior)、[`modelPicker`](#modelpicker)、[`policyHelper`](#policyhelper)、[`permissions.defaultMode`](#permissions-defaultmode) | +| `env` | [在管理员源之间按变量合并](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)，在 `"first-wins"` 和 `"merge"` 下都是如此 | [`env`](#env) | +| Every other key | 从设置它的最高源取值 | [`cleanupPeriodDays`](#cleanupperioddays)、[`model`](#model) | + +整体取值 `sandbox.credentials.awsPairs` 和 `sandbox.ripgrep` 需要 Claude Code v2.1.257 或更高版本。 + +这些密钥中的三个添加了自己的条件： + +* **[`policyHelper`](#policyhelper)**: Claude Code 仅在携带策略密钥的最高源是 MDM 策略或托管设置文件时才接受它，因此在服务器管理的设置下它不适用。 +* **[`modelOverrides`](#modeloverrides)**: 与 `availableModels` 配对。Claude Code 从设置它的最高源取值 `modelOverrides`，除非较高源设置 `availableModels` 而不设置 `modelOverrides`。在这种情况下，它忽略来自每个源的 `modelOverrides`。 +* **[`forceLoginGatewayUrl`](#forcelogingatewayurl) 和 [`forceLoginMethod`](#forceloginmethod) 的 `"gateway"` 值**: Claude Code 仅从机器本身上的托管源读取它们，并忽略服务器管理的设置中的它们。机器的值即使在服务器管理的设置也存在时也适用。 + +要确认机器上合并了哪些源，请运行 `/status` 并[读取 `Setting sources` 行](/docs/zh-CN/managed-settings#read-the-source-in-/status)。 + +

+ `parentSettingsBehavior` +

+ +选择 Claude Code 是否应用由嵌入主机进程（例如 Agent SDK 或 IDE 扩展）提供的托管设置，当管理员部署的托管层也存在时。使用 `"first-wins"`，Claude Code 会删除主机提供的设置；使用 `"merge"`，它通过限制性过滤器在管理员层下应用它们。当主机需要将其自己的限制传递给它启动的会话时，设置 `"merge"`，例如 Claude Desktop 传递网关的出口允许列表。 + +* **Scope**: [`Managed`](#scopes)。Claude Code 从最高优先级管理员控制的托管源读取它。 +* **Type**: string，其中之一： + * `"first-wins"`: 当管理员部署的托管层存在时，Claude Code 会删除主机提供的设置 + * `"merge"`: Claude Code 通过限制性过滤器在管理员层下应用主机提供的设置 +* **Default**: `"first-wins"` + +```json managed-settings.json theme={null} +{ + "parentSettingsBehavior": "merge" +} +``` + +当不存在管理员部署的托管层时，此密钥无效：主机的设置然后应用为唯一的托管层，仍然过滤为限制性值。有关过滤器的限制以及托管源如何交互，请参阅[来自嵌入主机的父设置](/docs/zh-CN/managed-settings#parent-settings-from-embedding-hosts)和[限制父设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings)。 + + + +

+ `policyHelper` +

+ +运行您部署的可执行文件，在启动时计算托管设置，因此您可以从设备状态、身份或远程服务而不是静态文件派生策略。Claude Code 在接受第一个提示之前运行帮助程序，并将其发出的设置视为会话的托管设置。 + +* **Scope**: [`Managed`](#scopes)。从 macOS plist、Windows HKLM 注册表或托管设置文件读取。Claude Code 从携带[策略密钥](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)的最高优先级托管源读取密钥，并仅当该源是这三个之一时才运行帮助程序；它忽略服务器管理的设置、HKCU 注册表和主机提供的父设置中的密钥。 +* **Type**: 具有 `path`、`timeoutMs` 和 `refreshIntervalMs` 的对象 +* **Default**: 未设置，因此不运行帮助程序 + +当服务器管理的设置在启动时提供策略时，它们优先于帮助程序的源，帮助程序不运行。 + +如果稍后的设置获取报告服务器管理的设置已删除，Claude Code 此时运行帮助程序，而不是等待下一次启动。其输出管理会话的其余部分，失败的运行以与[失败的启动运行](#helper-failures)相同的消息结束会话。 + +此示例使用 5 秒超时运行帮助程序，并每五分钟重新运行一次： + +```json managed-settings.json theme={null} +{ + "policyHelper": { + "path": "/usr/local/bin/claude-policy", + "timeoutMs": 5000, + "refreshIntervalMs": 300000 + } +} +``` + +

+ 写入帮助程序输出 +

+ +Claude Code 不带参数运行帮助程序，在其环境中设置 `CLAUDE_CODE_VERSION`，并从 stdout 读取 JSON 信封，上限为 1 MiB。 + +将设置放在 `managedSettings` 密钥下。没有 `managedSettings` 密钥的裸设置对象使用 `managedSettings` 未定义进行解析并不应用任何内容，Claude Code 报告无错误： + +```json theme={null} +{ + "managedSettings": { + "permissions": { "deny": ["Read(//etc/secrets/**)"] } + } +} +``` + +当帮助程序发出 `managedSettings` 时，该对象成为运行的唯一托管设置源：Claude Code 忽略 MDM、文件和 HKCU 源，仅从帮助程序的输出读取[跨源密钥](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)，并且从不合并[父设置](/docs/zh-CN/managed-settings#parent-settings-from-embedding-hosts)。 + +启动 `forceRemoteSettingsRefresh` 检查在帮助程序之前运行并读取任何管理员源。以 0 退出且信封省略 `managedSettings` 的帮助程序不贡献托管设置，其他源照常应用。 + +

+ 帮助程序失败 +

+ +帮助程序运行在以下情况下失败： + +* `path` 违反 [`policyHelper.path`](#policyhelper-path) 中的规则。 +* `path` 处没有常规文件。Claude Code 在启动帮助程序之前检查文件，在相同的 `timeoutMs` 预算内，因此无响应的网络挂载可能导致运行失败。 +* 帮助程序以非零退出、在 `timeoutMs` 经过时仍在运行，或根本不启动，例如因为它不可执行。 +* 帮助程序向 stdout 或 stderr 写入超过 1 MiB。 +* stdout 不是单个 JSON 对象，或其 `managedSettings` 有 [Claude Code 无法修复的架构违规](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)。 + +当启动运行失败时，Claude Code 打印原因并拒绝启动。非零退出后，原因包括帮助程序的 stderr，或当 stderr 为空时的 stdout。超时后，原因命名 `timeoutMs` 限制，不包括帮助程序的任何输出。拒绝涵盖交互式会话、`claude -p`、Agent SDK 会话、[后台会话](/docs/zh-CN/agent-view) 和大多数子命令。 + +拒绝是故意的，因此需要中断恢复能力的帮助程序应该从自己的缓存提供并以 0 退出。 + +当后台刷新失败时，Claude Code 保持最后成功的策略有效，`/status` 显示失败的刷新及其原因，直到刷新成功。每次刷新在与启动运行相同的 `timeoutMs` 和失败规则下运行。 + +使用 `--debug`，Claude Code 将每次运行的帮助程序的 stderr 写入[调试日志](/docs/zh-CN/debug-your-config)。 + +Claude Code 将无效的 `policyHelper` 值报告为[删除的条目](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)，并在剩余的托管设置上启动会话而不运行帮助程序。无效值包括裸路径字符串和低于[其最小值](#policyhelper-timeoutms)的 `timeoutMs`。 + +要关闭帮助程序，请从设置它的源中删除密钥。 + +

+ `policyHelper.path` +

+ +命名 Claude Code 运行的帮助程序可执行文件。有关路径违反以下规则时发生的情况，请参阅[帮助程序失败](#helper-failures)。 + +* **Scope**: [`Managed`](#scopes)。从 macOS plist、Windows HKLM 注册表或托管设置文件读取，无论 [`policyHelper`](#policyhelper) 在哪里读取。 +* **Type**: string，规范化形式的绝对路径，没有 `.` 或 `..` 段；在 Windows 上，以 `.exe` 结尾的驱动器字母或 UNC 路径 +* **Default**: 无；当设置 `policyHelper` 时需要 + +```json managed-settings.json theme={null} +{ + "policyHelper": { + "path": "/usr/local/bin/claude-policy" + } +} +``` + +

+ `policyHelper.timeoutMs` +

+ +设置 Claude Code 在将运行视为失败之前等待帮助程序的时间。超时的运行失败方式与非零退出相同，因此在启动时 Claude Code 拒绝启动。 + +* **Scope**: [`Managed`](#scopes)。从 macOS plist、Windows HKLM 注册表或托管设置文件读取，无论 [`policyHelper`](#policyhelper) 在哪里读取。 +* **Type**: integer，毫秒，最小 `1000` +* **Default**: `10000` + +```json managed-settings.json theme={null} +{ + "policyHelper": { + "path": "/usr/local/bin/claude-policy", + "timeoutMs": 5000 + } +} +``` + +

+ `policyHelper.refreshIntervalMs` +

+ +让 Claude Code 在后台按间隔重新运行帮助程序，以便策略更改到达运行中的会话。当刷新成功时，其输出替换之前的托管设置而不重启；当刷新失败时，Claude Code 保持它已有的策略。 + +* **Scope**: [`Managed`](#scopes)。从 macOS plist、Windows HKLM 注册表或托管设置文件读取，无论 [`policyHelper`](#policyhelper) 在哪里读取。 +* **Type**: integer，毫秒：`0` 禁用刷新，否则至少 `60000` +* **Default**: 未设置，因此 Claude Code 仅在启动时运行帮助程序一次 + +此示例每五分钟重新运行帮助程序： + +```json managed-settings.json theme={null} +{ + "policyHelper": { + "path": "/usr/local/bin/claude-policy", + "refreshIntervalMs": 300000 + } +} +``` + +

+ `wslInheritsWindowsSettings` +

+ +让 WSL 上的 Claude Code 从 Windows 策略链读取托管设置，HKLM 和 Windows 托管设置文件优先于 `/etc/claude-code` 和下面的 HKCU。当链打开时，Claude Code 仅在 `C:\Program Files\ClaudeCode\` 下没有托管设置文件或删除项提供[策略密钥](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)时才读取 `/etc/claude-code`。设置它以将您已在 Windows 上部署的策略扩展到同一机器上的 WSL 会话，以便它们遵循与主机会话相同的规则。Claude Code 仅在 HKLM 注册表密钥或 `C:\Program Files\ClaudeCode\` 下的托管设置文件或删除项中设置时才接受它，两者都需要 Windows 管理员写入。 + +* **Scope**: [`Managed`](#scopes)。在管理员控制的 Windows 源中。 +* **Type**: Boolean + * `true`: WSL 上的 Claude Code 从 Windows 策略链读取托管设置，并仅在 `C:\Program Files\ClaudeCode\` 下没有托管设置文件或删除项提供[策略密钥](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)时才读取 `/etc/claude-code` + * `false`: WSL 仅读取 `/etc/claude-code` +* **Default**: `false`，因此 WSL 仅读取 `/etc/claude-code` + +```json managed-settings.json theme={null} +{ + "wslInheritsWindowsSettings": true +} +``` + +一旦管理员源打开链，HKCU 策略仅在 HKCU 也将密钥设置为 `true` 时才加入 WSL 上的链。该副本不会自行打开链。仅包含此密钥的 Windows 源不计为策略源，因此较低优先级源仍然提供策略。此密钥对本机 Windows 无效。 + +

+ 全局配置设置 +

+ +将这些键保存在 `~/.claude.json` 中，而不是在设置文件中。Claude Code 在其他任何地方都会忽略它们。Claude Code 和 `/config` 会为你写入大部分设置，你也可以手动编辑它们。 + +

+ `autoConnectIde` +

+ +当你从外部终端启动 Claude Code 时，自动连接到正在运行的 IDE。当你在 VS Code 或 JetBrains 终端外运行 Claude Code 时，在 `/config` 中显示为**自动连接到 IDE（外部终端）**。 + +* **作用域**: [`全局配置`](#scopes) +* **类型**: 布尔值 + * `true`: 当你从外部终端启动 Claude Code 时，它会自动连接到正在运行的 IDE + * `false`: Claude Code 不会从外部终端自动连接；在 VS Code 或 JetBrains 终端内，或使用 `--ide`，它仍然会连接 +* **默认值**: `false` +* **每个会话的覆盖**: [`CLAUDE_CODE_AUTO_CONNECT_IDE`](/docs/zh-CN/env-vars) 在任一方向上优先于此键，持续一个会话 + +```json ~/.claude.json theme={null} +{ + "autoConnectIde": true +} +``` + +Claude Code 在 `settings.json` 中忽略此键。 + +

+ `autoInstallIdeExtension` +

+ +当你从 VS Code 终端运行 Claude Code 时，自动安装 Claude Code IDE 扩展。当你在 VS Code 或 JetBrains 终端内运行 Claude Code 时，在 `/config` 中显示为**自动安装 IDE 扩展**。 + +* **作用域**: [`全局配置`](#scopes) +* **类型**: 布尔值 + * `true`: 当你从 VS Code 终端运行 Claude Code 时，它会自动安装 IDE 扩展 + * `false`: Claude Code 不会自动安装扩展 +* **默认值**: `true` +* **每个会话的覆盖**: [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/docs/zh-CN/env-vars) 设置为 `1` 会跳过安装一个会话，即使此键为 `true` + +```json ~/.claude.json theme={null} +{ + "autoInstallIdeExtension": false +} +``` + +Claude Code 在 `settings.json` 中忽略此键。 + +

+ `copyOnSelect` +

+ +当你在[全屏渲染](/docs/zh-CN/fullscreen#use-the-mouse)或[代理视图](/docs/zh-CN/agent-view)中用鼠标完成文本选择时，自动将文本复制到剪贴板。在全屏渲染打开时，在 `/config` 中显示为**选择时复制**。 + +* **作用域**: [`全局配置`](#scopes) +* **类型**: 布尔值 + * `true`: 当你完成文本选择时，Claude Code 会将文本复制到剪贴板 + * `false`: 选择文本不会改变你的剪贴板，你[用键盘快捷键复制选择](/docs/zh-CN/fullscreen#use-the-mouse) +* **默认值**: `true` + +```json ~/.claude.json theme={null} +{ + "copyOnSelect": false +} +``` + +Claude Code 在 `settings.json` 中忽略此键。 + +

+ `diffTool` +

+ +选择 Claude Code 在连接[VS Code](/docs/zh-CN/vs-code)或[JetBrains](/docs/zh-CN/jetbrains#features) IDE 时显示其提议的 `Edit` 或 `Write` 更改的 diff 的位置：`"auto"` 在 IDE 的 diff 查看器中打开它，`"terminal"` 将其保留在终端中。仅当 Claude Code 连接到 VS Code 或 JetBrains IDE 时，在 `/config` 中显示为**Diff 工具**。 + +* **作用域**: [`全局配置`](#scopes) +* **类型**: 字符串，以下之一： + * `"auto"`: 当连接到 VS Code 或 JetBrains IDE 时，Claude Code 在 IDE 的 diff 查看器中打开 diff + * `"terminal"`: Claude Code 将 diff 保留在终端中 +* **默认值**: `"auto"` + +```json ~/.claude.json theme={null} +{ + "diffTool": "terminal" +} +``` + +Claude Code 在 `settings.json` 中忽略此键。 + +

+ `externalEditorContext` +

+ +当你按 `Ctrl+G` 时，Claude Code 在你的[外部编辑器](/docs/zh-CN/interactive-mode#general-controls)中打开你正在输入的提示。启用此键后，编辑器缓冲区以 Claude 的上一个响应作为 `#` 注释行开始，因此你可以在写入时读取它，Claude Code 在你保存时删除这些行。在 `/config` 中显示为**在外部编辑器中显示最后响应**。 + +* **作用域**: [`全局配置`](#scopes) +* **类型**: 布尔值 + * `true`: 编辑器缓冲区以 Claude 的上一个响应作为 `#` 注释行开始，Claude Code 在保存时删除这些行 + * `false`: 编辑器缓冲区仅以你的提示打开 +* **默认值**: `false` + +```json ~/.claude.json theme={null} +{ + "externalEditorContext": true +} +``` + +启用后，Claude Code 打开的缓冲区如下所示，只有标记行下方的文本才会作为你的提示发送： + +```text theme={null} +# ─── Claude's last response (for reference; removed on save) ─── +# I added the retry loop to fetchUser in src/api.ts and a test +# for the timeout case. Want me to wire the same retry into +# fetchOrders? +# ─── Write your reply below this line ────────────────────────── + +Yes, and cap it at three attempts. +``` + +Claude Code 保留响应的最后 50 行，并用 `# … (earlier output truncated)` 标记截断。 + +Claude Code 在 `settings.json` 中忽略此键。 + +

+ `permissionExplainerEnabled` +

+ + + 在 v2.1.257 中删除，以及 Bash 和 PowerShell 权限提示上的 `Ctrl+E` 命令说明。在当前版本中设置它没有效果。 + + +在 v2.1.256 及更早版本中，你可以在 Bash 或 PowerShell 权限提示上按 `Ctrl+E` 查看模型生成的命令说明，并将此键设置为 `false` 以关闭该快捷键。 + +* **作用域**: [`全局配置`](#scopes)。在 v2.1.256 及更早版本上。 +* **类型**: 布尔值 +* **默认值**: `true` + +

+ `teammateDefaultModel` +

+ + + 在 v2.1.234 中删除，以及其 `/config` 行**默认队友模型**。在当前版本中设置它没有效果。 + + +在 v2.1.233 及更早版本中，你将此键设置为[代理团队](/docs/zh-CN/agent-teams#specify-teammates-and-models)队友的模型，你的提示没有为其命名模型：一个别名如 `"sonnet"`，或 `null` 以遵循主导的模型。有关 Claude Code 现在为此类队友选择的模型，请参阅[指定队友和模型](/docs/zh-CN/agent-teams#specify-teammates-and-models)。 + +* **作用域**: [`全局配置`](#scopes)。在 v2.1.233 及更早版本上。 +* **类型**: 字符串，模型别名或完整模型 ID，或 `null` +* **默认值**: 未设置 + +

+ 另请参阅 +

+ +* [配置权限](/docs/zh-CN/permissions)：规则语法、权限模式和工作区信任 +* [环境变量](/docs/zh-CN/env-vars)：Claude Code 读取的每个 `CLAUDE_*`、`ANTHROPIC_*` 和提供商变量 +* [Claude 可用的工具](/docs/zh-CN/tools-reference)：内置工具以及哪些需要批准 +* [示例设置文件](/docs/zh-CN/settings-example)：个人文件、团队文件和组织的托管文件 +* [设置托管设置](/docs/zh-CN/admin-setup)：组织如何决定要强制执行的内容 +* [部署托管设置](/docs/zh-CN/managed-settings)：交付机制、托管层内的优先级和托管设置中的无效条目 +* [调试您的配置](/docs/zh-CN/debug-your-config)：`claude doctor` 和设置错误对话框