Anthropic
OpenAI
xAI
Gemini
S
settings-reference.md
2026-09-27 23:59 UTC to 2026-09-28 22:01 UTC
This page contains 13 additions and 13 deletions.
Page
Diff
2026
2026
Jan
Feb
Mar
Apr
May
Jun
Jul
Aug
Sep
Oct
Nov
Dec
所有设置
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
<a className={'bti-btn' + (show ? ' bti-show' : '')} href={href} aria-hidden={!show} tabIndex={show ? 0 : -1}>
{label}
;
};
export const ReferenceFilter = ({placeholder, noun, facets, facetOrder, columnHelp, children}) => {
const useLive = init => {
const [v, setV] = useState(init);
const ref = useRef(init);
return [v, ref, x => {
ref.current = x;
setV(x);
}];
};
const cap = s => s.charAt(0).toUpperCase() + s.slice(1);
const plural = s => s.endsWith('y') ? s.slice(0, -1) + 'ies' : s + 's';
const facetNames = facets || ['category', 'topic', 'scope', 'where'];
const orderOf = {};
Object.keys(facetOrder || ({})).forEach(k => {
orderOf[k] = facetOrder[k].map(x => String(x).toLowerCase());
});
const rankIn = (col, v) => {
const list = orderOf[col];
if (!list) return -1;
const i = list.indexOf(String(v).toLowerCase());
return i < 0 ? list.length : i;
};
const cmpValues = col => (a, b) => {
const ra = rankIn(col, a);
const rb = rankIn(col, b);
if (ra !== rb) return ra - rb;
return a < b ? -1 : a > b ? 1 : 0;
};
const help = columnHelp || ({});
const FIRST_COL_HELP = 'Click an entry to open it.';
const optionLabel = (f, c) => c === 'All' ? 'All ' + plural(f.label.toLowerCase()) : c;
const nounText = noun || 'entries';
const placeholderText = placeholder || 'Filter this reference';
const rootRef = useRef(null);
const tablesRef = useRef(null);
const searchRef = useRef(null);
const menuRef = useRef({});
const [q, qRef, setQ] = useLive('');
const [sel, selRef, setSel] = useLive({});
const [sortBy, sortRef, setSortBy] = useLive(null);
const [menuOpen, menuOpenRef, setMenu] = useLive(null);
const [facetList, setFacetList] = useState([]);
const [firstHead, setFirstHead] = useState('');
const [counts, setCounts] = useState({
shown: 0,
total: 0
});
const [disabled, setDisabled] = useState(false);
const menuBtn = name => menuRef.current[name] ? menuRef.current[name].querySelector(':scope > button') : null;
const menuList = name => menuRef.current[name] ? menuRef.current[name].querySelector('[role="listbox"]') : null;
const closeMenu = name => {
setMenu(null);
const btn = menuBtn(name);
if (btn) btn.focus();
};
const focusSelected = name => {
const list = menuList(name);
if (!list) return;
const btn = list.querySelector('button[aria-selected="true"]') || list.querySelector('button');
if (btn) btn.focus();
};
const setFacet = (name, value) => {
setSel(Object.assign({}, selRef.current, {
[name]: value
}));
apply(qRef.current);
closeMenu(name);
};
const sortTables = by => {
(tablesRef.current || []).forEach(tab => {
const t = tab.el;
const idx = tab.heads.indexOf(by);
const body = t.querySelector('tbody');
if (idx < 0 || !body) return;
const rows = [...body.querySelectorAll('tr')];
const keyOf = r => r.children[idx] ? r.children[idx].textContent.trim().toLowerCase() : '';
const cmp = cmpValues(by);
rows.map((r, i) => ({
r,
i: Number(r.dataset.sfIndex !== undefined ? r.dataset.sfIndex : i),
k: keyOf(r)
})).sort((a, b) => cmp(a.k, b.k) || a.i - b.i).forEach(x => body.appendChild(x.r));
[...t.querySelectorAll('thead th')].forEach((h, i) => {
const sortable = tab.heads[i] === tab.heads[0] || facetNames.indexOf(tab.heads[i]) > -1;
if (sortable) h.setAttribute('aria-sort', i === idx ? 'ascending' : 'none'); else h.removeAttribute('aria-sort');
});
});
};
const scan = () => {
const tables = [];
let el = rootRef.current ? rootRef.current.nextElementSibling : null;
while (el) {
if (el.tagName === 'H2' || el.querySelector(':scope > h2')) break;
const found = el.tagName === 'TABLE' ? [el] : [...el.querySelectorAll('table')];
found.forEach(t => {
const headCells = [...t.querySelectorAll('thead th, thead td')];
const heads = headCells.map(h => h.textContent.trim().toLowerCase());
if (heads.length === 0) return;
const facetIdx = {};
heads.forEach((h, i) => {
if (facetNames.indexOf(h) > -1) facetIdx[h] = i;
});
if (!t.dataset.sfDecorated) {
t.dataset.sfDecorated = '1';
headCells.forEach((h, i) => {
const text = i === 0 ? help[heads[0]] || FIRST_COL_HELP : help[heads[i]];
if (text) h.title = text;
});
}
const rows = [...t.querySelectorAll('tbody tr')].map((r, i) => {
if (r.dataset.sfIndex === undefined) r.dataset.sfIndex = String(i);
const cells = r.querySelectorAll('td');
const fv = {};
Object.keys(facetIdx).forEach(h => {
fv[h] = cells[facetIdx[h]] ? cells[facetIdx[h]].textContent.trim() : '';
});
return {
el: r,
text: [...cells].map(c => c.textContent).join(' ').toLowerCase(),
facets: fv,
anchors: [...r.querySelectorAll('a[href^="#"]')].map(a => a.getAttribute('href').slice(1)),
ids: [...r.querySelectorAll('[id]')].map(n => n.id)
};
});
tables.push({
el: t,
box: t.closest('[data-table-wrapper]') || t,
rows,
heads
});
});
el = el.nextElementSibling;
}
tablesRef.current = tables;
if (sortRef.current) sortTables(sortRef.current);
return tables;
};
const apply = query => {
let tables = tablesRef.current || scan();
if (tables.some(t => !t.el.isConnected)) tables = scan();
const needle = query.trim().toLowerCase();
const sel = selRef.current;
const activeFacets = Object.keys(sel).filter(h => sel[h] && sel[h] !== 'All');
const show = (el, on) => {
const want = on ? '' : 'none';
if (el.style.display !== want) el.style.display = want;
};
let total = 0;
let shown = 0;
const visibleTargets = new Set();
tables.forEach(t => {
let tableVisible = 0;
t.rows.forEach(row => {
total += 1;
const catOk = activeFacets.every(h => {
const v = row.facets[h];
return v === sel[h] || v === '' || v === undefined;
});
const match = catOk && (needle === '' || row.text.includes(needle));
show(row.el, match);
if (match) {
tableVisible += 1;
row.anchors.forEach(a => visibleTargets.add(a));
}
});
show(t.box, !(t.rows.length > 0 && tableVisible === 0));
shown += tableVisible;
});
if (shown < total && visibleTargets.size > 0) {
tables.forEach(t => {
t.rows.forEach(row => {
if (row.el.style.display === 'none' && row.ids.some(id => visibleTargets.has(id))) {
show(row.el, true);
show(t.box, true);
shown += 1;
}
});
});
}
setCounts({
shown,
total
});
return total;
};
const deriveFacets = tables => {
const seen = {};
tables.forEach(t => t.rows.forEach(r => {
Object.keys(r.facets).forEach(h => {
if (!seen[h]) seen[h] = [];
if (r.facets[h] && seen[h].indexOf(r.facets[h]) === -1) seen[h].push(r.facets[h]);
});
}));
const list = facetNames.filter(h => seen[h] && seen[h].length > 0).map(h => ({
name: h,
label: cap(h),
values: seen[h].sort(cmpValues(h))
}));
setFacetList(list);
const first = tables[0] ? tables[0].heads[0] : '';
setFirstHead(first);
if (!sortRef.current && first) {
setSortBy(first);
sortTables(first);
}
const init = {};
list.forEach(f => {
init[f.name] = selRef.current[f.name] || 'All';
});
setSel(init);
};
const onChange = value => {
setQ(value);
apply(value);
};
const clearAll = () => {
const next = {};
Object.keys(selRef.current).forEach(k => {
next[k] = 'All';
});
setSel(next);
setQ('');
apply('');
if (searchRef.current) searchRef.current.focus();
};
useEffect(() => {
const tables = scan();
deriveFacets(tables);
const total = apply('');
let retryTimer;
if (total === 0) {
retryTimer = setTimeout(() => {
tablesRef.current = null;
if (apply(qRef.current) > 0) deriveFacets(tablesRef.current); else setDisabled(true);
}, 500);
}
const onKey = e => {
if (e.key === 'Escape' && menuOpenRef.current !== null) closeMenu(menuOpenRef.current);
if (!searchRef.current) return;
if (e.metaKey || e.ctrlKey || e.altKey) return;
const active = document.activeElement;
const tag = active && active.tagName;
const editable = active && active.isContentEditable;
const interactive = tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || tag === 'BUTTON' || tag === 'A' || editable || active && active.getAttribute && active.getAttribute('role');
if (e.key === '/' && !interactive) {
const r = rootRef.current ? rootRef.current.getBoundingClientRect() : null;
if (r && r.bottom > 0 && r.top < (window.innerHeight || 0)) {
e.preventDefault();
setMenu(null);
searchRef.current.focus();
}
}
if (e.key === 'Escape' && menuOpenRef.current === null && active === searchRef.current) {
onChange('');
searchRef.current.blur();
}
};
const onDocClick = e => {
const open = menuOpenRef.current;
if (open !== null && menuRef.current[open] && !menuRef.current[open].contains(e.target)) setMenu(null);
};
window.addEventListener('keydown', onKey);
document.addEventListener('mousedown', onDocClick);
return () => {
if (retryTimer) clearTimeout(retryTimer);
window.removeEventListener('keydown', onKey);
document.removeEventListener('mousedown', onDocClick);
(tablesRef.current || []).forEach(t => {
t.box.style.display = '';
t.rows.forEach(row => {
row.el.style.display = '';
});
});
};
}, []);
useEffect(() => {
if (menuOpen !== null) focusSelected(menuOpen);
}, [menuOpen]);
if (disabled) return null;
const facetActive = Object.keys(sel).some(h => sel[h] && sel[h] !== 'All');
const sortOptions = [firstHead].concat(facetList.map(f => f.name)).filter((h, i, a) => h && a.indexOf(h) === i);
return <>
<div ref={rootRef} className="sf-root" style={{
margin: '16px 0 8px'
}}>
<div style={{
display: 'flex',
gap: '8px',
flexWrap: 'wrap',
alignItems: 'center'
}}>
<div style={{
position: 'relative',
flex: '1 1 260px',
maxWidth: '480px'
}}>
<input ref={searchRef} value={q} onChange={e => onChange(e.target.value)} placeholder={placeholderText} aria-label={placeholderText} style={{
width: '100%',
padding: '8px 56px 8px 12px',
borderRadius: '8px',
border: '1px solid var(--sf-border)',
background: 'var(--sf-bg)',
color: 'var(--sf-text)',
fontSize: '14px',
outline: 'none',
boxSizing: 'border-box'
}} />
{q ? <button type="button" onClick={() => {
onChange('');
if (searchRef.current) searchRef.current.focus();
}} aria-label="Clear text" className="sf-end sf-x">
×
: <span className="sf-end" style={{
fontFamily: 'var(--font-mono, ui-monospace, monospace)',
fontSize: '11px',
color: 'var(--sf-text-4)',
border: '1px solid var(--sf-border)',
borderRadius: '3px',
padding: '0 5px',
pointerEvents: 'none'
}}>
/
}
{facetList.map(f => {
const cur = sel[f.name] || 'All';
const isOpen = menuOpen === f.name;
return <div key={f.name} ref={el => {
menuRef.current[f.name] = el;
}} style={{
position: 'relative'
}}>
<button type="button" onClick={() => setMenu(isOpen ? null : f.name)} onKeyDown={e => {
if (e.key === 'ArrowDown') {
e.preventDefault();
if (!isOpen) setMenu(f.name); else focusSelected(f.name);
}
}} aria-haspopup="listbox" aria-expanded={isOpen} style={{
display: 'flex',
alignItems: 'center',
gap: '8px',
padding: cur !== 'All' ? '8px 30px 8px 12px' : '8px 12px',
borderRadius: '8px',
border: '1px solid ' + (cur !== 'All' ? 'var(--sf-accent)' : 'var(--sf-border)'),
background: 'var(--sf-bg)',
color: cur === 'All' ? 'var(--sf-text-3)' : 'var(--sf-text)',
fontSize: '13.5px',
cursor: 'pointer',
whiteSpace: 'nowrap',
maxWidth: '260px'
}}>
<span style={{
overflow: 'hidden',
textOverflow: 'ellipsis'
}}>
{f.label + ': ' + optionLabel(f, cur)}
<span aria-hidden="true" style={{
fontSize: '9px',
color: 'var(--sf-text-4)',
transform: isOpen ? 'rotate(180deg)' : 'none',
transition: 'transform 120ms'
}}>
▼
{cur !== 'All' && <button type="button" onClick={() => setFacet(f.name, 'All')} aria-label={'Clear ' + f.label + ' filter'} title={'Clear ' + f.label + ' filter'} className="sf-end sf-x">
×
}
{isOpen && <div role="listbox" aria-label={f.label} onKeyDown={e => {
const items = [...e.currentTarget.querySelectorAll('button')];
const idx = items.indexOf(document.activeElement);
if (e.key === 'ArrowDown') {
e.preventDefault();
(items[idx + 1] || items[0]).focus();
} else if (e.key === 'ArrowUp') {
e.preventDefault();
(items[idx - 1] || items[items.length - 1]).focus();
} else if (e.key === 'Home') {
e.preventDefault();
if (items[0]) items[0].focus();
} else if (e.key === 'End') {
e.preventDefault();
if (items[items.length - 1]) items[items.length - 1].focus();
} else if (e.key === 'Tab') {
closeMenu(f.name);
}
}} style={{
position: 'absolute',
top: 'calc(100% + 6px)',
left: 0,
zIndex: 1000,
minWidth: '260px',
maxHeight: '340px',
overflowY: 'auto',
background: 'var(--sf-bg)',
border: '1px solid var(--sf-border)',
borderRadius: '10px',
boxShadow: '0 8px 24px rgba(0,0,0,0.12)',
padding: '5px'
}}>
{['All'].concat(f.values).map(c => {
const selected = cur === c;
return <button key={c} role="option" aria-selected={selected} tabIndex={-1} onClick={() => setFacet(f.name, c)} style={{
display: 'flex',
alignItems: 'center',
gap: '8px',
width: '100%',
textAlign: 'left',
padding: '7px 10px',
borderRadius: '6px',
border: 'none',
background: 'transparent',
color: selected ? 'var(--sf-accent)' : 'var(--sf-text)',
fontWeight: selected ? 600 : 400,
fontSize: '13.5px',
cursor: 'pointer'
}}>
<span aria-hidden="true" style={{
width: '14px',
color: 'var(--sf-accent)',
flexShrink: 0
}}>
{selected ? '✓' : ''}
{optionLabel(f, c)}
;
})}
}
;
})}
{sortOptions.length > 1 && <div role="group" aria-label="Sort by" style={{
display: 'flex',
alignItems: 'center',
gap: '4px',
fontSize: '13px',
color: 'var(--sf-text-3)',
whiteSpace: 'nowrap'
}}>
<span style={{
marginRight: '4px'
}}>Sort by
{sortOptions.map(o => {
const on = sortBy === o;
return <button key={o} type="button" aria-pressed={on} onClick={() => {
setSortBy(o);
sortTables(o);
}} style={{
padding: '6px 10px',
borderRadius: '8px',
border: '1px solid ' + (on ? 'var(--sf-accent)' : 'var(--sf-border)'),
background: 'var(--sf-bg)',
color: on ? 'var(--sf-text)' : 'var(--sf-text-3)',
fontSize: '13px',
cursor: 'pointer'
}}>
{o.charAt(0).toUpperCase() + o.slice(1)}
;
})}
}
<div aria-live="polite" style={{
margin: '8px 0 0',
fontSize: '13px',
color: 'var(--sf-text-3)',
minHeight: '1px'
}}>
{q.trim() === '' && !facetActive ? <>{counts.total} {nounText}</> : counts.shown === 0 ? <>
{q.trim() === '' ? 'No ' + nounText + ' match the selected filters.' : facetActive ? 'No ' + nounText + ' match \u201c' + q + '\u201d with the selected filters.' : 'No ' + nounText + ' match \u201c' + q + '\u201d.'}{' '}
<button type="button" onClick={clearAll} style={{
background: 'none',
border: 'none',
padding: 0,
color: 'var(--sf-accent)',
cursor: 'pointer',
font: 'inherit',
textDecoration: 'underline'
}}>
Clear filters
{children ? <> {children}</> : null}
</> : <>
Showing {counts.shown} of {counts.total} {nounText}
</>}
</>;
};
本参考页面列出了 Claude Code 从设置文件读取的每个键,以及它保存在 ~/.claude.json 中的短键组 。要选择文件或检查优先级,请从设置文件和优先级 开始。
设置索引
下面的每个键都链接到其条目。范围列出了文件 ,其中可以使用该键:User 是 ~/.claude/settings.json,Project 是 .claude/settings.json,Local 是 .claude/settings.local.json,Managed 是您的组织部署的内容 。Any file 表示所有四个文件,Global config 表示 ~/.claude.json 。
<ReferenceFilter
noun="settings"
placeholder="按键或用途筛选设置"
facetOrder={{ scope: ["Any file", "User, local, or managed", "User or managed", "Managed", "Global config"] }}
columnHelp={{
topic: "本页面中包含该条目的部分。使用排序方式按主题对表格进行分组。",
scope: "哪些设置文件可以设置该键:用户 (~/.claude/settings.json)、项目 (.claude/settings.json)、本地 (.claude/settings.local.json) 或托管(由您的组织部署)。全局配置键位于 ~/.claude.json 中。",
}}
/>
模型和响应
选择 Claude Code 使用的模型以及它如何响应。关于这些设置如何与 /model 命令和环境变量交互,请参阅模型配置 。
`advisorModel`
选择当 Claude 调用服务器端顾问工具 时哪个模型来回答。取消设置它以关闭顾问。顾问的能力必须至少与您的主模型一样强。请参阅选择顾问模型 了解接受的配对以及选择未被接受的配对时会发生什么。
您通常不会手动编辑此键。运行 /advisor 打开一个选择器,显示当前选择、可以提供建议的模型和无顾问 。Claude Code 将您的选择保存到 ~/.claude/settings.json 中的此键。如果您从远程控制 客户端或附加到远程工作者的会话中选择,该选择仅适用于该会话,不会更改此键。
如果您的账户需要使用额度同意 ,请先通过运行 /model fable 来接受。在您这样做之前,在 /advisor 中选择 Fable 不会保存任何内容,Claude Code 会告诉您先运行 /model fable。
Scope : Any file
Type : string,别名之一 "fable"、"opus" 或 "sonnet",它们解析为 Claude Code 当前该模型系列的默认版本,或完整模型 ID,如 "claude-opus-5-5"
Default : 未设置,因此顾问已关闭
Per-session overrides : --advisor 对此键优先一个会话。CLAUDE_CODE_DISABLE_ADVISOR_TOOL 关闭顾问,此键无法将其重新打开
{
"advisorModel" : "opus"
}
该键对顾问不可用 的提供商没有影响,例如 Amazon Bedrock 和 AWS 上的 Claude Platform。"fable" 需要Fable 访问权限 。
`alwaysThinkingEnabled`
通过将其设置为 false 来为每个会话关闭扩展思考 。默认情况下思考是打开的,所以 true 不会改变任何内容。大多数人通过 /config 而不是编辑文件来设置这个。
在始终思考的模型上,例如 Opus 5.5 和 Fable 模型,false 没有效果。在第三方提供商 上,Claude Code 省略 thinking 参数而不是关闭思考,因此自适应推理模型可能仍然会思考。在 Anthropic API 上关闭思考时,Claude Code 向它知道不接受该组合 的模型(例如 Opus 5)发送努力 high 而不是更高级别。
Scope : Any file
Type : Boolean
true: 无效果;思考已经打开
false: Claude Code 为每个会话关闭扩展思考
Default : 未设置,因此对支持它的模型思考是打开的
Per-session overrides : MAX_THINKING_TOKENS 对此键优先一个会话:0 关闭思考,在与 false 相同的模型和提供商限制下,正值打开思考,即使此键是 false。在自适应推理模型上,数字本身被忽略
{
"alwaysThinkingEnabled" : false
}
`availableModels`
限制人们可以为主会话、子代理 、skills 和顾问 选择的模型。托管列表限制 /model、--model 和开发人员自己文件中的 model 键;列表外的模型无法选择。单独来说,这不会触及默认选项;将其与enforceAvailableModels 配对以实现该目的。
Scope : Any file 。在托管设置中部署它以为组织强制执行。
Type : 模型别名或 ID 的数组
Default : 未设置,因此每个模型都可用
此示例仅允许人们选择 Sonnet 和 Haiku 模型:
{
"availableModels" : [ "sonnet" , "haiku" ]
}
请参阅限制模型选择 。
`effortLevel`
为您尚未保存级别的模型设置默认努力级别 。较低的级别在直接任务上更快且更便宜,较高的级别在复杂问题上推理更深入。
当您在您的机器上的交互式会话中运行 /effort low、medium、high 或 xhigh 时,Claude Code 将该级别保存到modelSettings 下的活动模型,而不是写入此键。在 v2.1.251 之前,/effort 写入此键。
在同一设置文件中,Claude Code 使用模型的保存级别而不是此键。modelSettings 说明跨文件优先级。
在附加到远程工作者的会话中、在 -p 运行中以及在 Agent SDK 中,/effort 仅适用于该会话。调整努力级别 列出也仅适用于该会话的交互式选择。/effort 打印的消息说明发生了什么。
Scope : Any file
Type : string,其中之一:
"low": 最少推理,用于短的、范围内的、延迟敏感的、不是智能敏感的任务
"medium": 减少成本敏感工作的令牌使用,可以权衡一些智能
"high": 平衡令牌使用和智能
"xhigh": 更深入的推理,更高的令牌支出
Default : 未设置
Per-session overrides : --effort 对此键优先一个会话,CLAUDE_CODE_EFFORT_LEVEL 对两者都优先
{
"effortLevel" : "xhigh"
}
在您的用户设置文件 ~/.claude/settings.json 中,此键是 /effort 在按模型保存级别之前写入的较旧形式,它继续在之前应用的地方应用,在 Opus 5、Fable 5.1 和更早的模型上。Opus 5.5 和之后发布的模型忽略它,并从它们自己的默认值开始,直到您为它们保存一个级别,/effort 在modelSettings 下写入。在项目、本地和托管设置中,以及使用 --settings 时,此键适用于每个模型。
`enforceAvailableModels`
/model 选择器有一个默认 选项,当应用时解析为您的组织默认模型 ,否则解析为您的账户类型的默认值。availableModels 允许列表限制您可以命名的模型,但单独来说它不会改变默认 ,因此默认 仍然可以解析为列表外的模型。此键关闭了该间隙。需要 Claude Code v2.1.175 或更高版本。
当您的组织部署任何托管设置时,Claude Code 仅从托管源读取此键,并在您的其他文件中忽略它。
Scope : Any file
Type : Boolean
true: 当默认 将解析为 availableModels 外的模型时,Claude Code 将其解析为列表中第一个可用的模型
false: 默认 照常解析,即使是列表外的模型
Default : false
此示例将命名选择限制为 Sonnet 和 Haiku 模型,并使默认 解析为其中第一个可用的:
{
"availableModels" : [ "sonnet" , "haiku" ] ,
"enforceAvailableModels" : true
}
当 availableModels 未设置或为空时,此键无效。请参阅为默认模型强制执行允许列表 。需要 Claude Code v2.1.175 或更高版本。
`fallbackModel`
命名备份模型供 Claude Code 在您的主模型过载或不可用时按顺序尝试。Claude Code 在链中的下一个可用模型上切换以完成该轮,并显示通知。没有链的情况下,Claude Code 重试同一模型,然后显示服务器的错误,您重试或自己切换模型。
切换意味着在备用模型上进行一轮冷提示缓存 ;您的下一条消息首先再次尝试主模型。
Scope : Any file
Type : 模型别名或 ID 的数组;"default" 扩展为默认模型
Default : 未设置,因此失败的请求不会在另一个模型上重试
Per-session overrides : --fallback-model 对此键优先一个会话
此示例在您的主模型失败时首先尝试 Sonnet 5,然后尝试 Haiku 4.5:
{
"fallbackModel" : [ "claude-sonnet-5" , "claude-haiku-4-5" ]
}
与大多数数组设置不同,此键不会跨设置文件合并:最高优先级的定义它的文件提供整个链。如果您的项目文件设置 ["claude-sonnet-5"] 而您的用户文件设置 ["claude-haiku-4-5"],链是 ["claude-sonnet-5"] 仅。Claude Code 从列表中最多保留三个不同的允许模型,忽略其余的。请参阅备用模型链 。
`fastMode`
为可用的会话打开快速模式 ,用于交互式工作,如快速迭代或实时调试,您希望以更高的每令牌成本获得速度。您通常不会手动编辑此键:运行 /fast 将 fastMode: true 写入 ~/.claude/settings.json,再次运行它以关闭快速模式会删除该键。快速模式仅在 Opus 5.5、Opus 5 和 Opus 4.8 上运行:从另一个模型打开它会将您切换到 Opus,切换到不支持的模型会关闭它。请参阅在快速模式打开时切换模型 。
{
"fastMode" : true
}
`fastModePerSessionOptIn`
通常,运行 /fast 将fastMode 保存到一个人的用户设置,因此快速模式在之后每个会话的开始时打开。将此键设置为 true 以停止这种情况:保存的 fastMode: true 不再在会话开始时打开快速模式,每个人必须在他们想要它的每个会话中运行 /fast。Claude Code 在他们的文件中保留 fastMode 键,因此关闭此键会恢复旧行为。
Team 或 Enterprise 计划的所有者可以通过服务器托管设置 在组织范围内部署它。当托管设置设置该键时,/fast on 在交互式终端会话外被拒绝,并报告您的组织已禁用快速模式。这涵盖非交互式模式 、VS Code 扩展 和云会话 。
Scope : Any file
Type : Boolean
true: 保存的 fastMode: true 不再在会话开始时打开快速模式,因此每个人在他们想要它的每个会话中运行 /fast;使用 --settings 传递的 fastMode: true 仍然对该会话计数,除非托管设置设置此键
false: 保存的 fastMode: true 在之后每个会话的开始时打开快速模式
Default : false
{
"fastModePerSessionOptIn" : true
}
请参阅需要按会话选择加入 。
`language`
默认情况下让 Claude 用英语以外的语言响应。响应没有固定列表:Claude Code 将值逐字传递给 Claude 作为始终用该语言响应的指令,因此任何 Claude 可以读取的语言名称都有效。Claude Code 不检查该值,因此拼写错误的名称按原样到达 Claude,而不是产生错误。相同的值为语音听写 设置语言,它有一个固定的支持的听写语言 列表,以及自动生成的会话标题。
Scope : Any file
Type : string,任何语言名称,例如 "japanese"、"spanish" 或 "french";Claude Code 不验证它
Default : 未设置;会话标题然后匹配您的对话语言
{
"language" : "japanese"
}
`maxEffortLevel`
限制会话可以使用的努力级别 ,保留较低的级别可用。任何更高的级别都在上限处运行,包括来自 /effort、/model 选择器、--effort、CLAUDE_CODE_EFFORT_LEVEL 、skill 或 subagent 的 effort frontmatter 或模型自己的默认值。Claude Code 在每个请求之前应用上限本身,因此它在每个提供商上都有效,包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry。需要 Claude Code v2.1.267 或更高版本。
Scope : Any file 。在托管设置中部署它以为组织强制执行。当多个范围设置上限时,最低的适用,因此在一个范围中设置的上限无法从另一个范围提高
Type : string,其中之一 "low"、"medium"、"high"、"xhigh" 或 "max"。"max" 值不设置上限
Default : 未设置,因此不适用上限
Effect on ultracode : 低于 xhigh 的上限使ultracode 在上限适用的模型上不可用
Per-model caps : 将 maxEffortLevel 添加到模型的modelSettings 条目。该条目仅在设置源中替换此键,该源同时设置两者,例如您的用户设置或一个托管源 。在那里设置 "max" 以豁免该模型不受该源的上限;Claude Code 仍然应用来自其他源的上限
此示例将每个模型限制在 medium,并豁免 Sonnet 4.6:
{
"maxEffortLevel" : "medium" ,
"modelSettings" : {
"claude-sonnet-4-6" : {
"maxEffortLevel" : "max"
}
}
}
当您的组织也为模型设置努力限制 时,两个上限中较低的适用。
`model`
设置每个新会话使用的模型,因此您不必每次都使用 /model 选择一个。在此处设置它不会阻止您在会话中期切换。如果您的管理员设置了组织默认模型 以覆盖用户选择,即使您在用户、项目或本地设置中设置此键,您也会获得该模型。
{
"model" : "claude-sonnet-5"
}
此处的值优先于ANTHROPIC_DEFAULT_MODEL ,Claude Code 仅在没有其他内容选择模型时使用。
`modelOverrides`
将 Anthropic 模型 ID 映射到提供商特定的模型 ID,例如 Amazon Bedrock 推理配置文件 ARN。然后每个模型选择器条目在调用提供商 API 时使用其映射值。管理员在Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上使用这个来将每个模型版本路由到特定的推理配置文件、版本名称或部署,以实现治理、成本分配或区域路由。
Scope : Any file
Type : 将模型 ID 映射到提供商模型 ID 的对象
Default : 未设置
此示例将 Opus 4.6 的每个调用路由到命名的 Bedrock 推理配置文件:
{
"modelOverrides" : {
"claude-opus-4-6" : "arn:aws:bedrock:us-east-1:123456789012:inference-profile/example"
}
}
请参阅按版本覆盖模型 ID 。
`modelPicker`
列出 /model 选择器提供的模型,按您写入它们的顺序和您选择的标签下,因此选择器列出您的组织运行的模型,在内置阵容之后或代替它。每行的 model 按字面意思取用,因此它接受 --model 接受的任何内容:别名如 opus、Anthropic 模型 ID 或 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 网关的提供商格式 ID。需要 Claude Code v2.1.242 或更高版本。
Scope : User or managed 。Claude Code 从托管设置、--settings 和用户设置读取该键,并在项目和本地设置中忽略它,因此您克隆的存储库无法重新标记选择器。这三个中最高的设置该键的提供整个阵容,Claude Code 从不合并来自两个源的阵容。
Type : 具有 options 数组和可选 replaceBuiltInOptions Boolean 的对象
Default : 未设置,因此选择器显示内置阵容
此示例在内置阵容之后添加两个 Bedrock 部署,在您的团队识别的名称下:
{
"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` 的字段
该键采用两个字段,一个用于行本身,一个用于它们是替换内置阵容还是添加到它。
Field
Type
What it does
options
行的数组,每个都有必需的 model 和可选的 label 和 description
选择器显示的行,按此顺序,除了灰显的行移到底部。没有 label,Claude Code 用它知道的模型的内置名称标记行,或模型 ID 否则,没有 description 它写一个通用的第二行
replaceBuiltInOptions
Boolean,默认 false
将其设置为 true 以仅显示这些行、默认 和会话已在使用的模型的行。保留未设置以在内置阵容之后添加这些行
启用 replaceBuiltInOptions 时,Claude Code 隐藏每个其他行:内置阵容、它为availableModels 条目添加的行、网关发现 找到的模型和ANTHROPIC_CUSTOM_MODEL_OPTION 。关闭时,Claude Code 跳过内置阵容已覆盖的列出的模型。标签改变选择器显示的内容,而不是 Claude Code 运行的模型。
availableModels 允许列表仍然适用于这些行。在将列出的模型添加到允许列表之前,请阅读合并行为 :特定模型 ID 缩小其系列的通配符条目。Claude Code 还在显示选择器之前检查每行与会话:
Dropped : Claude Code 无法提供的行,例如已停用的模型或您的组织无权访问的模型
Grayed out : 您还无法选择的行,显示原因
No row survives : Claude Code 保留内置阵容,按允许列表过滤如常
Claude Code 删除它无法解析的行并保留其余的。请参阅修复损坏的设置文件 。
`modelPricing`
以您的组织支付的费率而不是列表价格报告支出。当您的组织有合同费率时设置它,因此开发人员看到的美元数字与您的账单相匹配。Claude Code 在 /usage、状态行 、Agent SDK 的 total_cost_usd、--max-budget-usd 限制和OpenTelemetry 成本指标和事件中应用费率。您提供费率:Claude Code 不从您的合同或 Claude Console 读取它们。需要 Claude Code v2.1.242 或更高版本。
Scope : Managed 。通过服务器托管设置、MDM 策略、managed-settings.json 文件或策略助手 部署该键。Claude Code 在用户、项目和本地设置中、在 --settings 中以及在 Windows 中的用户可写HKCU 注册表 中忽略它。使用服务器托管设置,每个会话以列表价格报告成本,直到该会话的设置获取 已确认该设置。嵌入 Claude Code 的主机应用程序,设置CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST 可以通过 SDK managedSettings 选项提供自己的表,Claude Code 仅在没有托管源设置该键时使用,仅在 Claude Code v2.1.246 或更高版本中。
Type : 具有可选 multiplier 和可选 overrides 映射的对象
Default : 未设置,因此 Claude Code 报告列表价格,除非主机应用程序提供表
单独设置 multiplier 以获得固定折扣或加价,单独设置 overrides 以获得按模型费率,或两者都设置。
此示例为 Sonnet 4.6 设置合同费率,然后将每个数字(包括 Sonnet 行)减少 15%:
{
"modelPricing" : {
"multiplier" : 0.85,
"overrides" : {
"claude-sonnet-4-6" : {
"input" : 2.4,
"output" : 12,
"cacheRead" : 0.24,
"cacheWrite" : 3
}
}
}
}
将 multiplier 设置为 1 以上,最多 10,以标记每个数字。加价需要 Claude Code v2.1.271 或更高版本。较早的版本忽略 multiplier 大于 1 的警告并保留设置的其余部分。
有关步骤,包括如何确认费率有效,请参阅以您的合同费率报告支出 。
`modelPricing` 的字段
Field
Type
What it does
multiplier
大于 0 且最多 10 的数字
缩放 Claude Code 计算的每个成本,无论 overrides 行是否覆盖它。低于 1 是折扣,高于 1 是加价
overrides
模型 ID 到具有 input、output、cacheRead 和 cacheWrite 的费率对象的映射,每个 0 到 10000
该模型的美元每百万令牌费率,全部四个必需。cacheWrite 涵盖五分钟和一小时缓存写入。请参阅modelPricing 行适用于哪些模型
Claude Code 完全按照您写入的方式使用行的费率,不添加快速模式附加费或仅限美国推理费率 。如果您也设置 multiplier,Claude Code 在行的费率之上应用它。Claude Code 删除具有它无法解析的费率或 multiplier 的行,并保留其余的;请参阅修复损坏的设置文件 。
`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 映射或bedrock:GetInferenceProfile 查找 将配置文件解析为它路由到的模型,Claude Code 将该模型的行应用于配置文件。
`modelSettings`
为您使用的每个模型保存努力级别 。需要 Claude Code v2.1.251 或更高版本。
在您的机器上的交互式会话中,当您使用 /effort 或 /model 选择器的努力滑块将 low、medium、high 或 xhigh 保存为您的默认值时,Claude Code 在您使用的模型下在此处写入该级别,因此您很少自己编辑此键。当您在VS Code 扩展的模型选择器 中选择这些级别之一时,Claude Code 以相同的方式在此处保存它。effortLevel 条目列出 /effort 仅适用于该会话的会话。
手动编辑该键以更改或删除您保存的级别。
此处模型的 effortLevel 优先于同一设置文件中的顶级effortLevel 。跨文件,Claude Code 分别解析每个模型:最高优先级设置文件 ,为该模型设置 effortLevel 或适用于该模型 的顶级 effortLevel 决定,因此托管设置中的 effortLevel 优先于您在用户设置中保存的级别。调整努力级别 列出还可以覆盖保存级别的内容,例如启动时的 --effort。
要限制一个模型的努力而不是设置其级别,请将maxEffortLevel 字段添加到该模型的条目。该字段需要 Claude Code v2.1.267 或更高版本。
Scope : Any file
Type : 将模型名称映射到具有 effortLevel 字段的对象的对象,其中之一 "low"、"medium"、"high" 或 "xhigh"、maxEffortLevel 字段或两者
Default : 未设置
Claude Code 在模型的规范名称下写入每个条目,例如 claude-opus-5-5,并将该模型的别名、日期后缀、[1m] 和识别的提供商特定 ID 匹配到同一条目。
此示例将 Opus 5.5 保持在 high,而其他模型使用它们自己的保存或默认级别:
{
"modelSettings" : {
"claude-opus-5-5" : {
"effortLevel" : "high"
}
}
}
运行 /effort auto 以清除您为正在使用的模型保存的级别。Claude Code 保留其他条目和任何顶级 effortLevel。
`outputStyle`
按名称选择输出样式 。输出样式是一组保存的指令,改变 Claude 的角色、语气和输出格式,例如内置的 Explanatory 和 Learning 样式或您自己写的。
如果您在会话期间更改此键,Claude 从您的下一条消息开始使用新样式。有关该消息在提示缓存中的成本,请参阅更改输出样式 。在 v2.1.251 之前,编辑仅在您运行 /clear 或启动新会话后应用。
Scope : Any file
Type : string,内置 或自定义 输出样式的名称
Default : 未设置,因此 Claude Code 使用默认样式
此示例选择内置的 Explanatory 样式,它在任务之间添加教育见解:
{
"outputStyle" : "Explanatory"
}
`promptCacheTtl`
选择提示缓存 保持主对话的时间长度。此键适用于您的交互式、-p 和 Agent SDK 轮,以及 Claude Code 与它们内联运行的助手。一小时的生命周期在较长的中断中保持缓存温暖,API 以比五分钟生命周期更高的费率为每个缓存写入计费 。需要 Claude Code v2.1.242 或更高版本。
此示例将主对话保持在一小时生命周期,并将 subagent 保留在五分钟:
{
"promptCacheTtl" : "1h" ,
"subagentPromptCacheTtl" : "5m"
}
有关每个生命周期的成本,请参阅缓存生命周期 。
`showThinkingSummaries`
在交互式会话中查看 Claude 的扩展思考 摘要。如果您想在使用 Ctrl+O 展开思考时看到完整摘要,请设置它。未设置或 false 时,Anthropic API 编辑思考块,Claude Code 显示折叠的存根;第三方提供商不编辑。
Scope : Any file
Type : Boolean
true: 当您使用 Ctrl+O 展开思考时,您看到完整的思考摘要
false: Anthropic API 编辑思考块,Claude Code 显示折叠的存根
Default : false
{
"showThinkingSummaries" : true
}
编辑仅改变您看到的内容,而不是模型生成的内容。要减少思考支出,降低预算或禁用思考 。
`subagentPromptCacheTtl`
选择提示缓存 保持 Claude Code 在主对话外进行的请求的时间长度。此键适用于subagent 、工作流 和 Claude Code 自己的后台和助手请求,例如压缩和会话标题。一小时的生命周期在较长的中断中保持缓存温暖,API 以比五分钟生命周期更高的费率为每个缓存写入计费 。需要 Claude Code v2.1.242 或更高版本。
此示例为 subagent 和主对话外的其他请求提供一小时生命周期:
{
"subagentPromptCacheTtl" : "1h"
}
此键涵盖promptCacheTtl 不涵盖的请求,因此设置两者以为 Claude Code 进行的每个请求选择生命周期。有关 subagent 的缓存与主对话的缓存的不同之处,请参阅Subagent 和缓存 。
`switchModelsOnFlag`
选择当安全分类器标记请求 时会发生什么:切换到备用模型并继续,或暂停以便您可以在切换和编辑提示之间选择。
Scope : Any file 。在 /config 中显示为消息被标记时切换模型 。
Type : Boolean
true: Claude Code 切换到备用模型并继续
false: 在交互式会话中,Claude Code 暂停以便您可以在切换和编辑提示之间选择;在无法显示对话的地方,例如 -p 运行,标记的请求以错误结束
Default : true,自动切换
{
"switchModelsOnFlag" : false
}
请参阅切换前询问 。
`ultracode`
使用ultracode 启动会话。启用它后,Claude 为每个实质性任务规划工作流,而不是等待您要求。Claude 仅在为您启用动态工作流 、您的模型支持 xhigh 努力且没有努力上限 低于 xhigh 时规划工作流。无论如何,ultracode: true 在 xhigh 努力或当努力上限较低时在上限处运行会话。Claude Code 读取此键但从不写入它:/effort ultracode 仅为当前会话打开 ultracode。
Scope : Any file
Type : Boolean
true: 会话以 xhigh 努力启动,当为您启用动态工作流、您的模型支持 xhigh 且没有努力上限低于 xhigh 时,ultracode 打开
false: 会话以 ultracode 关闭启动
Default : 未设置,因此 ultracode 已关闭
Per-session overrides : /effort ultracode 在没有此键的情况下为一个会话打开 ultracode。--effort ultracode 标志也为一个会话打开它,需要 Claude Code v2.1.203 或更高版本
{
"ultracode" : true
}
Ultracode 在 xhigh 努力处运行会话,优先于 effortLevel 和modelSettings 条目。如果努力上限 低于 xhigh 适用于模型,例如maxEffortLevel 设置,会话改为在上限处运行,ultracode 保持关闭。Claude 然后不会自己规划工作流,/effort 不提供 ultracode。Agent SDK apply_flag_settings 控制请求也接受该键。
权限设置
决定 Claude 在不询问的情况下可以做什么、会话以哪种权限模式启动,以及自动模式的分类器允许什么。有关规则语法和权限模型,请参阅配置权限 。
`allowManagedPermissionRulesOnly`
使托管设置成为权限规则的唯一设置源。Claude Code 随后会忽略用户、项目、本地和 --settings 文件中的 allow、ask 和 deny 规则,忽略 --allowedTools,隐藏权限提示中的始终允许选项,并停止保存新规则。
当来自嵌入主机的父设置 适用时,Claude Code 将其视为托管层的一部分。它删除其 allow 规则和 additionalDirectories,并保留其 deny 和 ask 规则,除了 Read 和 Edit 规则,其模式以 ! 开头。主机无法使用 ! 规则从托管规则中切割出路径,无论您是否设置此键。
--disallowedTools 规则和当前会话的 deny 和 ask 规则仍然适用,包括在 Claude Code 在会话中途重新加载设置后。它们仅限制,因此无法扩展托管规则授予的权限。在 v2.1.257 之前,Claude Code 在第一次设置重新加载时删除了这些命令行和会话规则。
有关 ! 模式在 --disallowedTools 或会话规则中可以切割出什么,请参阅Read 和 Edit 规则 。
作用域 : Managed
类型 : 布尔值
true:托管设置成为权限规则的唯一设置源
false:Claude Code 除了应用托管规则外,还应用来自用户、项目、本地和 --settings 文件的权限规则
默认值 : 未设置,因此 Claude Code 应用来自用户、项目和本地设置以及 --settings 的权限规则,以及托管规则
{
"allowManagedPermissionRulesOnly" : true
}
此键不会锁定 MCP 服务器允许列表;为此,请设置 allowManagedMcpServersOnly 。请参阅仅托管设置 。
`autoMode`
向自动模式 分类器阻止和允许的内容添加您自己的规则。使用它告诉分类器您的组织信任哪些存储库、存储桶和域,以便它停止阻止常规内部操作。分类器附带内置允许和拒绝规则 。在数组中包含字面字符串 "$defaults" 以在该位置保留这些内置规则并在其周围添加您的规则;省略它以用您的规则替换它们。
此示例通过 "$defaults" 保留内置的 soft_deny 规则,并添加一个阻止 terraform apply 的规则:
{
"autoMode" : {
"soft_deny" : [ "$defaults" , "Never run terraform apply" ]
}
}
当这些文件中的多个文件设置相同的数组时,Claude Code 会连接这些条目。有关规则格式以及如何应用每个数组,请参阅配置自动模式 。
`autoMode.classifyAllShell`
在自动模式处于活动状态时,通过自动模式分类器发送每个 Bash 和 PowerShell 命令。默认情况下,自动模式仅暂停可能运行任意代码的允许规则:工具范围和通配符规则(如 Bash(*))以及解释器或 shell 包装器前缀(如 Bash(python *))。任何其他允许规则匹配的命令(如 Bash(npm test))会跳过分类器,除非它携带每命令允许的域 ,规则的前缀未预期的破坏性参数可能会被看不见地通过。设置此键会为会话暂停每个 shell 允许规则,以便分类器看到每个命令。需要 Claude Code v2.1.193 或更高版本。
作用域 : User or managed 。在读取 autoMode 的任何地方读取。
类型 : 布尔值
true:在自动模式处于活动状态时,Claude Code 通过分类器发送每个 Bash 和 PowerShell 命令,并暂停您的 shell 允许规则;在自动模式之外,规则仍然适用
false:自动模式仅暂停可能运行任意代码的允许规则,如 Bash(*) 和 Bash(python *);任何其他允许规则匹配的命令会跳过分类器,除非它携带每命令允许的域 ,每个其他 shell 命令都会通过它
默认值 : false
{
"autoMode" : {
"classifyAllShell" : true
}
}
请参阅通过分类器路由所有 shell 命令 。需要 Claude Code v2.1.193 或更高版本。
`disableAutoMode`
从 Shift+Tab 循环中删除自动模式 。任何本应以自动模式启动 的会话,无论是来自 --permission-mode auto、设置文件还是内置默认值,都会改为以 default 启动。管理员在托管设置中设置它以防止其组织中的开发人员使用自动模式。
作用域 : Any file 。在托管设置 中最有用,用户无法覆盖它。也接受在 permissions 下作为 permissions.disableAutoMode。
类型 : 字符串 "disable"
默认值 : 未设置
{
"disableAutoMode" : "disable"
}
`permissions`
控制 Claude 可以在不询问的情况下使用哪些工具、哪些工具始终提示,以及哪些工具被阻止,并设置会话启动的权限模式 。下面的每个 permissions.* 键都嵌套在此对象下。
作用域 : Any file
类型 : 包含 allow、ask、deny、additionalDirectories、blockReadsOutsideWorkingDirectories、defaultMode、disableBypassPermissionsMode 和 disableAutoMode 的对象
默认值 : 未设置
此示例在不询问的情况下批准 npm run 命令,在 git push 之前提示,阻止读取 .env,并在 acceptEdits 中启动会话:
{
"permissions" : {
"allow" : [ "Bash(npm run *)" ] ,
"ask" : [ "Bash(git push *)" ] ,
"deny" : [ "Read(./.env)" ] ,
"defaultMode" : "acceptEdits"
}
}
这三个规则数组共享一个语法;请参阅 permissions.allow 下的权限规则语法 。有关来自不同文件的权限规则如何组合,请参阅权限规则如何跨作用域合并 ;有关设置键如何组合,请参阅设置指南上的设置优先级 。
`useAutoModeDuringPlan`
选择 Claude Code 是否使用自动模式分类器在计划模式下审查 shell 命令。使用默认值 true,分类器在规划期间审查每个命令,当自动模式可用且您看不到提示时。设置 false 以获得内置只读集之外的每个命令的权限提示。在 /config 中显示为在计划期间使用自动模式 。
作用域 : User, local, or managed 。存储库无法为您关闭它。
类型 : 布尔值
true:与未设置相同;当自动模式可用时,分类器在规划期间审查每个 shell 命令,而不是提示您。任何这些文件中的 false 仍然会关闭它
false:您会获得内置只读集之外的每个命令的权限提示
默认值 : true
{
"useAutoModeDuringPlan" : false
}
`permissions.allow`
列出 Claude Code 在不询问您的情况下批准的工具使用。在 MCP 规则中,* 只能出现在 mcp__<server>__ 前缀之后的工具名称中,如 mcp__github__get_*;它不能出现在服务器名称中。
作用域 : Any file
类型 : 权限规则字符串数组
默认值 : 未设置
每会话覆盖 : --allowedTools 为一个会话添加允许规则,来自任何设置文件的拒绝规则仍然会阻止它命名的工具
此示例批准 git diff 并让 Claude Code 读取您的 .zshrc 而不询问:
{
"permissions" : {
"allow" : [ "Bash(git diff *)" , "Read(~/.zshrc)" ]
}
}
Claude Code 仅在您接受该文件夹的工作区信任对话框 后,才应用项目的 .claude/settings.json 中的 allow 规则。
权限规则语法
权限规则遵循格式 Tool 或 Tool(specifier)。Claude Code 首先评估 deny 规则,然后是 ask,然后是 allow,第一个匹配决定,无论每个规则有多具体;请参阅权限规则评估顺序 。
每行显示一个规则形状及其匹配的内容。
规则
它匹配的内容
Bash
每个 Bash 命令
Bash(npm run *)
以 npm run 开头的命令
Read(./.env)
读取 .env 文件
WebFetch(domain:example.com)
对 example.com 的获取请求
有关完整的规则语法,包括通配符行为、Read、Edit、WebFetch、MCP 和 Agent 规则的工具特定模式,以及 Bash 模式的安全限制,请参阅权限规则语法 。
`permissions.ask`
列出即使在会否则批准它们的权限模式(如 acceptEdits 或 bypassPermissions)中也会提示您确认的工具使用。在 dontAsk 模式中,Claude Code 拒绝匹配的工具使用,而不是提示。
{
"permissions" : {
"ask" : [ "Bash(git push *)" ]
}
}
`permissions.deny`
列出 Claude Code 阻止的工具使用。将其用于保存 API 密钥、机密或环境值的文件:Claude Code 从文件发现和搜索结果中排除匹配的文件,拒绝读取它们,并在匹配的路径上阻止编辑和写入工具 。读取和编辑拒绝规则适用于 Claude 的内置文件工具、Claude Code 在 Bash 中识别的文件命令(如 cat、head、tail、sed 和 tee)以及 Bash重定向 的目标(如 > file 和 < file);它们不适用于读取文件而不命名它们的命令(如 grep -r pattern .)或任意子进程,因此对于操作系统级别的强制执行,请启用沙箱 。
作用域 : Any file
类型 : 权限规则字符串数组
默认值 : 未设置
每会话覆盖 : --disallowedTools 为一个会话添加拒绝规则,与此键一起
此示例拒绝读取 .env 文件、secrets 目录和凭据文件,并阻止 curl 命令:
{
"permissions" : {
"deny" : [
"Read(./.env)" ,
"Read(./.env.*)" ,
"Read(./secrets/**)" ,
"Read(./config/credentials.json)" ,
"Bash(curl *)"
]
}
}
工具名称接受 glob 模式,因此 "*" 拒绝每个工具,"mcp__*" 拒绝每个 MCP 工具。只要任何其他工具仍然可用于 Claude,Claude Code 就会忽略 EndConversation 工具的拒绝规则。Bash 拒绝规则匹配 Claude 编写的命令,因此 Bash(curl *) 不会停止 /usr/bin/curl 或 sh -c 'curl …';请参阅Bash 规则不匹配的内容 。此键替换已弃用的 ignorePatterns 配置。
`permissions.additionalDirectories`
给予 Claude 对您启动的目录之外的目录的文件访问权限,作为额外的工作目录 。大多数 .claude/ 配置未从这些目录发现 。
作用域 : Any file
类型 : 目录路径数组
默认值 : 未设置
每会话覆盖 : --add-dir 和 /add-dir 为一个会话添加目录,与此键一起
{
"permissions" : {
"additionalDirectories" : [ "../docs/" ]
}
}
与 allow 规则一样,项目的 .claude/settings.json 中的条目仅在您接受该文件夹的工作区信任对话框 后才生效。
`permissions.blockReadsOutsideWorkingDirectories`
阻止 Claude 在每个权限模式(包括 bypassPermissions)中使用 Read、Grep、Glob 和 LSP 工具读取会话工作目录 之外的路径。通过 Claude Code 识别的文件命令(如 cat)读取匹配路径的 Bash 命令会在自动模式和 bypassPermissions 模式中提示您。需要 Claude Code v2.1.257 或更高版本。
shell 解析器无法追踪的 Bash 命令(如多次更改目录或运行子 shell 的命令)会在自动模式和 bypassPermissions 模式中提示您。即使命令未命名工作目录之外的任何路径,提示也会出现。当命令在沙箱 中运行且沙箱强制执行该块时,此提示不适用。
Claude Code 也会在此处写入 true,当您选择在自动模式的提示中阻止此类读取(在第一次读取工作目录之外之前) 时。
作用域 : Any file 。如果任何设置源设置 true,则应用该块,因此存储库的签入文件可以为项目打开该块,但无法解除您设置的块。
类型 : 布尔值
true:阻止工作目录之外的文件读取
false:与未设置相同;任何其他设置文件中的 true 仍然会阻止
默认值 : 未设置,因此工作目录之外的读取遵循您的权限模式和规则
{
"permissions" : {
"blockReadsOutsideWorkingDirectories" : true
}
}
如果仅存储库的签入设置文件添加目录,该块仍然适用于那里的读取。当 autoMemoryDirectory 来自项目的 .claude/settings.json,或来自被视为存储库提供的 .claude/settings.local.json 时,Claude Code 不会从该目录加载任何自动内存 ,也不会保存任何到其中。Claude Code 本身需要的文件保持可读,如您的技能、插件、规则、代理、命令以及 ~/.claude/ 下的 CLAUDE.md 内存文件。
当沙箱 打开时,该块也会拒绝沙箱命令对工作目录之外的主目录和挂载卷根的读取访问。需要批准以在沙箱外运行 的重试会在 bypassPermissions 模式中提示您。工具从您的主目录读取的文件(如 ~/.gitconfig)与其余文件一起被拒绝;当工具需要它时,使用 sandbox.filesystem.allowRead 重新打开特定路径。
当会话的工作目录是链接的 git worktree (包括 Claude Code 在会话中途进入的)时,存储库的公共 .git 目录对沙箱命令保持可读和可写,因此 git 在那里继续工作。
`permissions.defaultMode`
设置新会话启动的权限模式 。当您将其留空时,会话会以您的计划和表面的内置默认值 启动。
作用域 : Any file 。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 对一个会话优先于此键
{
"permissions" : {
"defaultMode" : "acceptEdits"
}
}
权限规则分层在每个模式之上:deny 规则在每个模式中阻止,包括 bypassPermissions。请参阅权限模式 。manual 命名 CLI 和 VS Code 扩展中标记为"手动"的权限模式;别名需要 Claude Code v2.1.200 或更高版本。在云会话中,Claude Code 仅从此键中遵守 acceptEdits、plan、default 和 auto。对于 VS Code 扩展启动的对话,请参阅扩展为启动权限模式读取的设置 。
`permissions.disableBypassPermissionsMode`
防止任何人进入 bypassPermissions 模式。Claude Code 随后会拒绝 --dangerously-skip-permissions 标志,并忽略代理定义的 permissionMode: bypassPermissions,因此子代理使用父会话的权限模式运行。
作用域 : Any file 。通常在托管设置 中设置以强制执行组织政策。
类型 : 字符串 "disable"
默认值 : 未设置
每会话覆盖 : 此键优先于 --dangerously-skip-permissions,在设置此键时 Claude Code 会拒绝它
{
"permissions" : {
"disableBypassPermissionsMode" : "disable"
}
}
在 v2.1.223 之前,即使禁用绕过,Claude Code 也应用了 frontmatter 权限模式。
`skipAutoPermissionPrompt`
跳过 Claude Code 在您自己首次进入自动模式时显示的一次性通知,描述自动模式 ,例如通过您自己的设置或模式选择器,而不是当内置默认值在其中启动会话时。Claude Code 显示该通知一次,然后记录它已显示,因此此键仅在通知尚未出现的地方重要。
作用域 : User or managed 。存储库无法为您设置它。
类型 : 布尔值
true:Claude Code 跳过通知
false:与未设置相同;除非这些文件中的另一个设置 true,否则通知出现一次
默认值 : 未设置,因此通知出现一次
{
"skipAutoPermissionPrompt" : true
}
`skipDangerousModePermissionPrompt`
跳过 Claude Code 在会话进入 bypassPermissions 模式之前显示的确认对话框,无论是来自 --dangerously-skip-permissions 还是来自 defaultMode: "bypassPermissions"。当您接受该对话框一次时,Claude Code 在您的用户设置中写入 true。
作用域 : User, local, or managed 。不受信任的存储库无法为您跳过对话框。
类型 : 布尔值
true:Claude Code 跳过会话进入 bypassPermissions 模式之前的确认对话框
false:与未设置相同;除非这些文件中的另一个设置 true,否则对话框出现
默认值 : 未设置,因此对话框出现
{
"skipDangerousModePermissionPrompt" : true
}
Sandbox 设置
将 Claude 运行的命令与您的文件系统、网络和凭证隔离。有关沙箱工作原理和平台要求,请参阅 Sandboxing 。
`sandbox`
使用 sandboxing 将 Claude 运行的 Bash 命令与您的文件系统和网络隔离。使用 enabled 打开沙箱,然后使用 filesystem、network 和 credentials 子对象缩小或扩大沙箱命令可以接触的内容。沙箱在 macOS、Linux 和 WSL2 上运行。
Scope : Any file
Type : 对象,包含 enabled、failIfUnavailable、autoAllowBashIfSandboxed、excludedCommands、allowUnsandboxedCommands、enableWeakerNestedSandbox、enableWeakerNetworkIsolation、allowAppleEvents、bwrapPath、socatPath、ignoreViolations 和 ripgrep,以及 filesystem、network 和 credentials 对象
Default : 未设置,因此 Claude Code 运行命令时不使用沙箱
这会打开沙箱,跳过沙箱命令的权限提示,在沙箱外运行 docker,打开两个额外的写入路径,隐藏您的 AWS 凭证文件,并预先允许 GitHub 和 npm:
{
"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 了解仅限托管的锁。要为组织强制执行沙箱,请参阅 Enforce sandboxing with managed settings 。
`sandbox.enabled`
为 Bash 命令打开 sandboxing 。当您在 /sandbox 面板中选择一个模式时,Claude Code 会将此键写入当前项目的 .claude/settings.local.json;在 ~/.claude/settings.json 中设置它以对每个项目进行沙箱处理。
Scope : Any file
Type : 布尔值
true: Claude Code 对 Bash 命令进行沙箱处理
false: Bash 命令在没有沙箱的情况下运行
Default : false
{
"sandbox" : {
"enabled" : true
}
}
在 Linux 和 WSL2 上,沙箱需要 bubblewrap 和 socat;请参阅 Set up Linux and WSL2 。当沙箱无法启动时,Claude Code 会显示警告并在没有设置 failIfUnavailable 的情况下运行未沙箱化的命令。
`sandbox.failIfUnavailable`
当 sandbox.enabled 为 true 但沙箱无法启动时(因为缺少依赖项或不支持该平台),使 Claude Code 在启动时以错误退出。没有它,Claude Code 会显示警告并运行未沙箱化的命令。在托管设置中使用它,当您的组织要求沙箱作为硬门时。
Scope : Any file
Type : 布尔值
true: 当 sandbox.enabled 为 true 但沙箱无法启动时,Claude Code 在启动时以错误退出
false: Claude Code 显示警告并运行未沙箱化的命令
Default : false
这使每台托管机器对命令进行沙箱处理或拒绝启动:
{
"sandbox" : {
"enabled" : true,
"failIfUnavailable" : true
}
}
请参阅 Enforce sandboxing with managed settings 。
`sandbox.autoAllowBashIfSandboxed`
让 Claude Code 运行沙箱化的 Bash 命令而无需权限提示。无法在沙箱中运行的命令仍会通过常规权限流程,deny 规则和内容范围的 ask 规则(如 Bash(git push *) )仍然适用;对于沙箱化命令,裸 Bash ask 规则被跳过。将其设置为 false 以也通过常规权限流程发送沙箱化命令,/sandbox Mode 选项卡称之为常规权限模式。
Scope : Any file
Type : 布尔值
true: Claude Code 运行沙箱化的 Bash 命令而无需权限提示,受 deny 规则和内容范围的 ask 规则约束;CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 关闭自动允许
false: 沙箱化命令通过常规权限流程,因此您的允许规则和权限模式决定。/sandbox Mode 选项卡称之为常规权限模式
Default : true
这保持沙箱打开并通过常规权限流程发送沙箱化命令:
{
"sandbox" : {
"enabled" : true,
"autoAllowBashIfSandboxed" : false
}
}
请参阅 Sandbox modes 了解自动允许模式仍会提示什么以及它在计划模式中的行为。
`sandbox.excludedCommands`
命名 Claude Code 在沙箱外运行的命令,例如在沙箱下不工作的工具。每个条目使用与 Bash(...) permission rule 内容相同的语法:精确命令、前缀(如 docker * )或通配符模式。
您的条目仅当它们覆盖复合命令中的每个命令时才将 Bash 调用从沙箱中取出,某些调用形式即使这样也保持沙箱化。单独的 docker * 条目不会将 npm ci && docker build . 从沙箱中取出。
Scope : Any file
Type : 命令模式数组
Default : 未设置,因此没有命令被排除
{
"sandbox" : {
"excludedCommands" : [ "docker *" ]
}
}
Claude Code 在具有以下形式之一时保持 Bash 调用沙箱化,以及其他形式:
以 sudo、eval 或 xargs 开头的命令
cd、pushd 或 popd,无论它在调用中的任何位置出现
命令替换、子 shell 或控制流块,例如 if 或 for
重定向,例如 docker build . > build.log,除了仅复制文件描述符的重定向,如 2>&1 所做的
来自变量的命令名称
例如,cd build && docker compose up 在 docker * 条目下保持沙箱化,添加 cd 条目不会改变这一点。
排除的命令仍会通过常规权限流程。排除是一种便利,而不是安全边界:当工具只需要在特定位置写入时,优先使用 filesystem.allowWrite 。Claude Code 在会话加载的每个设置范围中合并条目,此列表没有仅限托管的锁,因此保持托管列表狭窄。
`sandbox.allowUnsandboxedCommands`
让 Claude 在沙箱阻止后使用 dangerouslyDisableSandbox 参数在沙箱外重试命令。将其设置为 false 以使 Claude Code 完全忽略该参数,并且 Claude 运行的每个命令都必须进行沙箱处理或出现在 excludedCommands 中。/sandbox Overrides 选项卡将该状态显示为 Strict sandbox mode 。在托管设置中使用 false 以获得需要严格沙箱处理的策略。
Scope : Any file
Type : 布尔值
true: Claude 可以在沙箱阻止后使用 dangerouslyDisableSandbox 参数在沙箱外重试命令
false: Claude Code 忽略该参数,因此 Claude 运行的每个命令都进行沙箱处理或出现在 excludedCommands 中
Default : true
这为托管设置覆盖的每个人强制执行严格沙箱模式:
{
"sandbox" : {
"enabled" : true,
"allowUnsandboxedCommands" : false
}
}
未沙箱化的重试通过常规权限流程,在手动模式下带有提示。请参阅 The unsandboxed retry escape hatch 。
要查看您在 ! shell-mode prompt 处自己输入的命令何时运行沙箱化,请参阅 strict sandbox mode 。
`sandbox.filesystem`
控制沙箱化命令可以读取和写入的路径。默认情况下,它们可以写入工作目录、会话临时目录以及使用 --add-dir、/add-dir 或 permissions.additionalDirectories 添加的目录,并可以读取文件系统的其余部分,包括凭证文件。使用四个路径列表扩大或缩小范围,或使用 disabled 关闭文件系统层。请参阅 Filesystem isolation 了解默认边界。
Scope : Any file
Type : 对象,包含 allowWrite、denyWrite、denyRead 和 allowRead 数组,以及 allowManagedReadPathsOnly 和 disabled 布尔值
Default : 未设置,因此应用默认读写边界
这让沙箱化命令写入构建目录和您的 kubeconfig,并隐藏您的 AWS 凭证文件:
{
"sandbox" : {
"filesystem" : {
"allowWrite" : [ "/tmp/build" , "~/.kube" ] ,
"denyRead" : [ "~/.aws/credentials" ]
}
}
}
Claude Code 在操作系统沙箱边界强制执行这些列表,因此它们适用于沙箱化命令启动的每个子进程,例如 kubectl、terraform 或 npm。Claude Code 将您的 permission rules 添加到相同的列表:Edit 允许和拒绝规则到 allowWrite 和 denyWrite,Read 拒绝规则到 denyRead,以及 WebFetch(domain:...) 允许和拒绝规则到 network 域列表。
除非设置了仅限托管的锁,否则 Claude Code 在会话加载的设置文件中合并每个列表。allowManagedReadPathsOnly 将 allowRead 限制为托管设置中的条目,allowManagedDomainsOnly 对允许的域执行相同操作。
Configure sandboxing 涵盖您使用 --setting-sources 排除的源。当您在会话期间编辑列表时,Claude Code applies the change to the running session 。
Sandbox 路径前缀
allowWrite、denyWrite、denyRead、allowRead 和 credentials.files 中的路径按其前缀解析:
前缀
含义
示例
/
从文件系统根目录的绝对路径
/tmp/build 保持 /tmp/build
~/
相对于主目录
~/.kube 变为 $HOME/.kube
./ 或无前缀
相对于项目根目录(用于项目设置)或 ~/.claude(用于用户设置)
.claude/settings.json 中的 ./output 解析为 <project-root>/output
绝对路径的 //path 前缀也有效。如果您使用单斜杠 /path 期望项目相对解析,请切换到 ./path。此语法与 Read and Edit permission rules 不同,后者使用 //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 或构建工具)需要在项目外写入时使用它。
这让构建在 /tmp/build 下写入并让 kubectl 更新您的 kubeconfig:
{
"sandbox" : {
"filesystem" : {
"allowWrite" : [ "/tmp/build" , "~/.kube" ]
}
}
}
Claude Code 在会话加载的每个设置范围中合并条目:用户、项目、本地和托管路径组合而不是替换彼此,Claude Code 添加您的 Edit(...) 允许权限规则中的路径。allowWrite 条目不能提升 protected path 。
`sandbox.filesystem.denyWrite`
阻止沙箱化命令写入特定路径,包括在其他可写目录内的路径。
这防止沙箱化命令更改系统配置或安装二进制文件:
{
"sandbox" : {
"filesystem" : {
"denyWrite" : [ "/etc" , "/usr/local/bin" ]
}
}
}
Claude Code 在会话加载的每个设置范围中合并条目,并添加您的 Edit(...) 拒绝权限规则中的路径。
`sandbox.filesystem.denyRead`
阻止沙箱化命令读取特定路径,例如默认读取策略会公开的凭证文件。要保护凭证文件并使其可通过沙箱代理使用,请改为参阅 sandbox.credentials 。
{
"sandbox" : {
"filesystem" : {
"denyRead" : [ "~/.aws/credentials" ]
}
}
}
Claude Code 在会话加载的每个设置范围中合并条目,并添加您的 Read(...) 拒绝权限规则中的路径。当 filesystem.disabled 为 true 时,Claude Code 不强制执行这些条目。
`sandbox.filesystem.allowRead`
重新打开 denyRead 阻止的区域内特定路径的读取,以构建仅工作区读取访问。精确或通配符 denyRead 条目在更广泛的 allowRead 内保持阻止,如 overlap table 所示。当通配符 denyRead 条目(如 ~/**/.env )匹配目录时,Claude Code 也会阻止其内容的读取。在 v2.1.236 之前的 macOS 上,Claude Code 在更广泛的 allowRead 条目覆盖它们的任何地方重新打开通配符 denyRead 条目匹配的路径,并保持匹配目录的内容可读。
这阻止读取您的主目录,除了项目本身:
{
"sandbox" : {
"filesystem" : {
"denyRead" : [ "~/" ] ,
"allowRead" : [ "." ]
}
}
}
Claude Code 在项目设置中将 . 条目解析为项目根目录,在用户设置中解析为 ~/.claude。Claude Code 在会话加载的每个设置文件中合并条目,除非设置了 allowManagedReadPathsOnly 。
`sandbox.filesystem.allowManagedReadPathsOnly`
仅遵守来自托管设置的 allowRead 条目,以便开发人员无法重新打开对您的组织阻止的路径的读取访问。Claude Code 仍然从会话加载的每个设置范围合并 denyRead 条目。
Scope : Managed
Type : 布尔值
true: Claude Code 仅遵守来自托管设置的 allowRead 条目
false: allowRead 条目从会话加载的每个设置范围合并
Default : false
这阻止读取主目录,重新打开 ~/work,并阻止开发人员重新打开任何其他内容:
{
"sandbox" : {
"filesystem" : {
"denyRead" : [ "~/" ] ,
"allowRead" : [ "~/work" ] ,
"allowManagedReadPathsOnly" : true
}
}
}
请参阅 Keep developers from widening the policy 。
`sandbox.filesystem.disabled`
跳过文件系统隔离,同时保持网络隔离。沙箱化命令获得对主机文件系统的无限制读写访问,其网络出口仍限制在 network.allowedDomains 。当您沙箱化以控制命令连接的位置而不是它们写入的内容时使用它。需要 Claude Code v2.1.216 或更高版本。
Scope : User or managed 。当托管设置配置 sandbox.filesystem 时,或列出带有 "mode": "deny" 的 sandbox.credentials.files 条目时,只有托管设置可以设置它。
Type : 布尔值
true: Claude Code 跳过文件系统隔离并保持网络隔离
false: 文件系统隔离保持打开
Default : false,因此文件系统隔离保持打开
这使文件系统打开并将网络出口限制在 GitHub 和 npm:
{
"sandbox" : {
"enabled" : true,
"filesystem" : {
"disabled" : true
} ,
"network" : {
"allowedDomains" : [ "github.com" , "*.npmjs.org" ]
}
}
}
关闭该层后,Claude Code 不强制执行 denyRead 或 credentials.files deny 条目,而 credentials.envVars 条目和应用的 mask 条目保持工作。autoAllowBashIfSandboxed 仍默认为 true,因此将其设置为 false 以保持提示。请参阅 Disable filesystem isolation 了解可以设置它的完整源列表以及隔离关闭时的变化。需要 Claude Code v2.1.216 或更高版本。
`sandbox.ignoreViolations`
沉默沙箱违规报告,针对您期望命令探测并被拒绝的路径,例如在启动时检查 /etc/hosts 的工具,因此这些拒绝不会显示为违规或在 Claude 看到的内容中。沙箱仍然阻止访问;只有报告被抑制。键是与命令匹配的子字符串,* 匹配每个命令,值是该命令要忽略的违规子字符串,例如文件系统路径。
Scope : Any file
Type : 对象,将命令子字符串映射到违规子字符串数组,通常是路径
Default : 未设置,因此报告每个违规
{
"sandbox" : {
"ignoreViolations" : {
"*" : [ "/etc/hosts" ]
}
}
}
`sandbox.enableWeakerNestedSandbox`
在无特权 Docker 容器内运行 Linux 沙箱,其中 bubblewrap 无法挂载新的 /proc。相反,内部沙箱绑定挂载容器的现有 /proc,这暴露了新挂载会隐藏的进程信息。这降低了安全性;仅当外部容器已提供您需要的隔离时才使用它。
Scope : Any file
Type : 布尔值
true: 内部沙箱绑定挂载容器的现有 /proc 而不是挂载新的
false: 沙箱挂载新的 /proc,在无特权 Docker 容器中不工作
Default : false
{
"sandbox" : {
"enabled" : true,
"enableWeakerNestedSandbox" : true
}
}
仅限 Linux 和 WSL2。请参阅 Bubblewrap fails to start inside a container 。
`sandbox.enableWeakerNetworkIsolation`
让 macOS 上的沙箱化命令到达系统 TLS 信任服务 com.apple.trustd.agent。基于 Go 的工具(如 gh、gcloud 和 terraform )在您使用 network.httpProxyPort 与 MITM 代理和自定义 CA 时需要它来验证 TLS 证书。这通过打开通过信任服务的潜在数据泄露路径来降低安全性。
Scope : Any file
Type : 布尔值
true: macOS 上的沙箱化命令可以到达 com.apple.trustd.agent
false: macOS 上的沙箱化命令无法到达系统 TLS 信任服务
Default : false
{
"sandbox" : {
"enabled" : true,
"enableWeakerNetworkIsolation" : true
}
}
如果您不使用 MITM 代理,请改为在 excludedCommands 中列出失败的工具;请参阅 Go-based CLIs fail TLS verification on macOS 。
`sandbox.allowAppleEvents`
让 macOS 上的沙箱化命令发送 Apple Events,open、osascript 和在浏览器中打开 URL 的工具需要它;没有它们会失败,错误为 -600。这删除了代码执行隔离:沙箱化命令可以在没有用户提示的情况下启动其他应用程序,并可以向运行的应用程序(如 Terminal)发送 AppleScript 命令,受每个应用程序的 macOS 自动化同意提示 (TCC) 约束。
Scope : User or managed
Type : 布尔值
true: macOS 上的沙箱化命令可以发送 Apple Events
false: macOS 上的沙箱化命令无法发送 Apple Events,因此 open 和 osascript 失败,错误为 -600
Default : false
{
"sandbox" : {
"enabled" : true,
"allowAppleEvents" : true
}
}
要保持隔离并仍然运行一个这样的工具,请改为将其添加到 excludedCommands 。请参阅 Apple Events on macOS 。
`sandbox.ripgrep`
将沙箱指向您自己的 ripgrep 二进制文件,而不是 Claude Code 使用的,例如当您的平台需要不同构建的 rg 时。
Scope : User or managed
Type : 对象,包含 command(ripgrep 二进制文件的路径)和可选的 args(要前置的参数数组)
Default : 未设置,因此沙箱使用与 Claude Code 相同的 ripgrep 二进制文件。这是捆绑的二进制文件,除非您将 USE_BUILTIN_RIPGREP 设置为 0
{
"sandbox" : {
"ripgrep" : {
"command" : "/usr/local/bin/rg"
}
}
}
`sandbox.bwrapPath`
将沙箱指向安装在 PATH 外的 bubblewrap 二进制文件,例如在气隙主机上的供应商副本。Claude Code 在启动依赖项检查和包装每个沙箱化命令时都使用该路径。
Scope : Managed 。Claude Code 仅从托管设置读取它,以便用户、项目或本地文件无法将沙箱指向不同的二进制文件。
Type : 字符串,绝对路径;Claude Code 删除相对路径并回退到 PATH 查找
Default : 未设置,因此 Claude Code 在 PATH 上找到 bwrap
{
"sandbox" : {
"enabled" : true,
"bwrapPath" : "/opt/admin/bwrap"
}
}
仅限 Linux 和 WSL2。
`sandbox.socatPath`
将沙箱网络代理指向安装在 PATH 外的 socat 二进制文件。
Scope : Managed
Type : 字符串,绝对路径;Claude Code 删除相对路径并回退到 PATH 查找
Default : 未设置,因此 Claude Code 在 PATH 上找到 socat
{
"sandbox" : {
"enabled" : true,
"socatPath" : "/opt/admin/socat"
}
}
仅限 Linux 和 WSL2。
`sandbox.credentials`
声明凭证文件和环境变量以 protect from sandboxed commands 。每个条目命名文件 path 或变量 name 和 mode:deny 在沙箱内隐藏凭证,mask 向沙箱化命令显示占位符,同时 sandbox proxy 在出站请求上替换真实值。Claude Code 仅保护您列出的条目;没有内置凭证拒绝列表。需要 Claude Code v2.1.187 或更高版本。
Scope : Any file 。Claude Code 仅从用户设置、托管设置和 --settings 标志遵守 mask 条目、allowPlaintextInject、awsPairs 和 sigv4。
Type : 对象,包含 files、envVars、allowPlaintextInject、awsPairs 和 sigv4
Default : 未设置,因此没有凭证被保护
这隐藏您的 AWS 凭证文件并从沙箱化命令中删除 GITHUB_TOKEN:
{
"sandbox" : {
"credentials" : {
"files" : [ { "path" : "~/.aws/credentials" , "mode" : "deny" } ] ,
"envVars" : [ { "name" : "GITHUB_TOKEN" , "mode" : "deny" } ]
}
}
}
deny 文件保护是文件系统层的一部分,因此当您 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 ,警告注意如果托管设置关闭文件系统隔离,其读取块不被强制执行。
具有未知 mode 或无效 path 或 name 的条目被删除。
每种情况都会警告;无论条目是降级还是删除,其余有效条目仍然被强制执行,完全无效的 credentials 值被删除,同时 sandbox 的其余部分仍然适用。
适用于 v2.1.191 及更高版本;在 v2.1.221 之前,每个无效条目都被删除。对于其他具有每字段处理的托管键,请参阅 Invalid entries in managed settings 。
`sandbox.credentials.files`
保护凭证文件或目录免受沙箱化命令。使用 "mode": "deny",Claude Code 阻止在沙箱内读取路径,与 sandbox.filesystem.denyRead 相同的读取块。使用 "mode": "mask",Linux 和 WSL2 上的沙箱化命令读取文件的哨兵副本,沙箱代理在对该条目的 injectHosts 的出站请求上替换真实值;在 macOS 上,文件在沙箱内不可读。需要 Claude Code v2.1.187 或更高版本,"mode": "mask" 需要 v2.1.221 或更高版本。
Scope : Any file 。Claude Code 从项目 .claude/settings.json 和本地 .claude/settings.local.json 删除 mask 条目。
Type : 对象数组,每个包含 path 和 "deny" 或 "mask" 的 mode,加上可选的 mask fields for files
Default : 未设置,因此没有凭证文件被保护
这隐藏您的 AWS 凭证文件并掩盖 gh 主机文件,仅在对 api.github.com 的请求上替换真实值:
{
"sandbox" : {
"credentials" : {
"files" : [
{ "path" : "~/.aws/credentials" , "mode" : "deny" } ,
{ "path" : "~/.config/gh/hosts.yml" , "mode" : "mask" , "injectHosts" : [ "api.github.com" ] }
]
}
}
}
路径使用与 sandbox.filesystem.* 设置相同的 prefixes ,Claude Code 在会话加载的每个设置范围中合并数组。Protect credentials 涵盖您使用 --setting-sources 排除的源仍然适用的内容。需要 Claude Code v2.1.187 或更高版本;mask 条目需要 v2.1.221 或更高版本。
mask 替换仅通过沙箱代理运行,因此设置 sandbox.network.tlsTerminate 或 allowPlaintextInject 用于纯 HTTP 测试网络。mask 适用于单个文件,因此单独列出每个凭证文件。Claude Code 接受但忽略 deny 条目上的 mask 字段。Mask credential files 涵盖遵守哪些设置源以及条目何时回退到 deny。
文件的掩盖字段
mask 条目接受这些可选字段。没有 extract 或 decode,Claude Code 用一个哨兵替换整个文件内容。在启用文件系统隔离的 macOS 上,Claude Code 在 extract 或 decode 运行之前将 mask 条目应用为 deny;请参阅 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 或 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 中每个主机的请求上替换它。需要 v2.1.221 或更高版本
这仅掩盖 gh 主机文件中的 oauth_token 值,替换文件中它的每个其他副本,如果模式匹配不到任何内容则使文件不可读,并仅在对 api.github.com 的请求上替换真实令牌:
{
"sandbox" : {
"credentials" : {
"files" : [
{
"path" : "~/.config/gh/hosts.yml" ,
"mode" : "mask" ,
"extract" : "oauth_token:\\s*(\\S+)" ,
"maskDuplicates" : true,
"onExtractNoMatch" : "deny" ,
"injectHosts" : [ "api.github.com" ]
}
]
}
}
}
`sandbox.credentials.envVars`
保护环境变量免受沙箱化命令。使用 "mode": "deny",Claude Code 从沙箱化命令的环境中删除变量。使用 "mode": "mask",沙箱化命令看到每个会话的哨兵值,沙箱代理在对该条目的 injectHosts 的出站请求上替换真实值,因此 gh 和 npm 等工具保持认证而无需持有真实凭证。需要 Claude Code v2.1.187 或更高版本,"mode": "mask" 需要 v2.1.199 或更高版本。
这从沙箱化命令中删除 NPM_TOKEN 并掩盖 GITHUB_TOKEN,仅在对 api.github.com 的请求上替换真实值:
{
"sandbox" : {
"credentials" : {
"envVars" : [
{ "name" : "NPM_TOKEN" , "mode" : "deny" } ,
{ "name" : "GITHUB_TOKEN" , "mode" : "mask" , "injectHosts" : [ "api.github.com" ] }
]
}
}
}
name 必须以字母或下划线开头,仅包含字母、数字和下划线。Claude Code 在会话加载的每个设置范围中合并数组,当同一变量同时出现两种模式时应用 deny。Protect credentials 涵盖您使用 --setting-sources 排除的源仍然适用的内容。需要 Claude Code v2.1.187 或更高版本;mask 条目需要 v2.1.199 或更高版本。
mask 替换仅通过沙箱代理运行,因此设置 sandbox.network.tlsTerminate 或 allowPlaintextInject 用于纯 HTTP 测试网络;请参阅 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 中每个主机的请求上替换它。将 IPv6 目标写为裸压缩地址,例如 "::1",而不是括号形式;请参阅 IPv6 destinations in injectHosts 。需要 v2.1.199 或更高版本
这仅掩盖 DATABASE_URL 内的密码,如果模式匹配不到任何内容则取消设置变量,并掩盖 SERVICE_JWT 中的 JWT,同时保持除 api_key 外的每个声明可读:
{
"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
Type : 布尔值
true: Claude Code 允许 mask 替换在纯 HTTP 请求以及 TLS 终止的 HTTPS 上
false: Claude Code 仅允许 mask 替换在 TLS 终止的 HTTPS 上
Default : false
{
"sandbox" : {
"credentials" : {
"allowPlaintextInject" : true
}
}
}
需要 Claude Code v2.1.199 或更高版本。
`sandbox.credentials.awsPairs`
分组掩盖的环境变量,形成一个 AWS 凭证用于 SigV4 re-signing ,当您的凭证存在于具有非标准名称的变量中时。Claude Code 在您掩盖其整个值时自动链接常规 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 AWS_SESSION_TOKEN 三元组,因此您仅在其他名称时需要此键。需要 Claude Code v2.1.224 或更高版本。
Scope : User or managed
Type : 对象数组,每个包含 accessKeyIdVar、secretAccessKeyVar 和可选的 sessionTokenVar,命名 sandbox.credentials.envVars 条目
Default : 未设置,因此仅配对常规三元组
这将三个自定义命名的变量链接到一个 AWS 凭证以进行重新签名:
{
"sandbox" : {
"credentials" : {
"awsPairs" : [
{
"accessKeyIdVar" : "MY_KEY_ID" ,
"secretAccessKeyVar" : "MY_SECRET_KEY" ,
"sessionTokenVar" : "MY_SESSION_TOKEN"
}
]
}
}
}
每个命名的变量必须是 sandbox.credentials.envVars 中的整个值 mask 条目,没有 extract 或 decode,并且只能在所有对中填充一个槽。
`sandbox.credentials.sigv4`
选择沙箱代理对 AWS 请求形式的处理,它 can't re-sign :streaming 用于 aws-chunked 流上传,presigned 用于预签名 URL,sigv4a 用于 SigV4A 非对称签名。这仅适用于使用掩盖对的占位符访问密钥 ID 签名的请求。需要 Claude Code v2.1.224 或更高版本。
Scope : User or managed
Type : 对象,包含 streaming、presigned 和 sigv4a,每个为以下之一:
"deny": 代理失败请求
"passthrough": 代理转发使用掩盖占位符签名的请求,因此工具接收 AWS 自己的拒绝
Default : 未设置,因此每种形式都是 "deny"
这转发流上传而不是在代理处失败它们:
{
"sandbox" : {
"credentials" : {
"sigv4" : {
"streaming" : "passthrough"
}
}
}
}
使用 deny,代理失败请求。使用 passthrough,代理转发使用掩盖占位符计算的签名的请求,因此 AWS 拒绝它,调用工具接收 AWS 自己的响应而不是代理错误。
`sandbox.network`
控制沙箱化命令可以到达的主机、端口和套接字。沙箱通过强制执行这些列表的代理路由出站流量;请参阅 Network isolation 了解代理如何决定以及何时提示。
Scope : Any file 。strictAllowlist、allowManagedDomainsOnly 和 tlsTerminate 从较少的源读取,如其条目所述。
Type : 对象,包含以下子键
Default : 未设置,因此没有域被预先允许,沙箱为每个新主机提示
这预先允许 GitHub 和 npm,阻止 uploads.github.com,并让命令绑定到 localhost:
{
"sandbox" : {
"network" : {
"allowedDomains" : [ "github.com" , "*.npmjs.org" ] ,
"deniedDomains" : [ "uploads.github.com" ] ,
"allowLocalBinding" : true
}
}
}
Claude Code 在设置范围中合并数组子键并删除重复项,因此项目可以向您的用户列表添加域。WebFetch(domain:...) 允许和拒绝 permission rules 馈送相同的允许和拒绝列表。
`sandbox.network.allowUnixSockets`
列出 macOS 上沙箱化命令可以连接到的 Unix 套接字路径。Claude Code 在 Linux 和 WSL2 上忽略此列表,其中 seccomp 过滤器无法检查套接字路径;改为在那里使用 allowAllUnixSockets 。
Scope : Any file
Type : 字符串数组,每个是套接字路径
Default : 未设置,因此 macOS 沙箱阻止每个 Unix 套接字
{
"sandbox" : {
"network" : {
"allowUnixSockets" : [ "~/.ssh/agent-socket" ]
}
}
}
套接字路径可以授予广泛的访问权限:例如,允许 /var/run/docker.sock 让沙箱化命令控制 Docker 守护程序。请参阅 Security limitations 。
`sandbox.network.allowAllUnixSockets`
让沙箱化命令连接到每个 Unix 套接字。在 Linux 和 WSL2 上,沙箱的 seccomp filter 阻止 socket(AF_UNIX, ...) 调用,因此这是在那里允许 Unix 套接字的唯一方式。当过滤器缺失时,/sandbox 在其 Dependencies 选项卡上报告,沙箱不阻止 Unix 套接字调用。请参阅 Set up Linux and WSL2 了解过滤器来自何处。
Scope : Any file
Type : 布尔值
true: 沙箱化命令可以连接到每个 Unix 套接字
false: 沙箱阻止 Unix 套接字连接:在 macOS 上除了 allowUnixSockets 中的路径,在 Linux 和 WSL2 上通过 seccomp 过滤器(当存在时)
Default : false
{
"sandbox" : {
"network" : {
"allowAllUnixSockets" : true
}
}
}
在 WSL2 上,true 也重新打开启动 Windows 二进制文件(如 cmd.exe 和 powershell.exe )的互操作套接字。
`sandbox.network.allowLocalBinding`
让 macOS 上的沙箱化命令绑定到 localhost 端口,例如启动开发服务器。
Scope : Any file
Type : 布尔值
true: macOS 上的沙箱化命令可以绑定到 localhost 端口
false: macOS 上的沙箱化命令无法绑定到 localhost 端口
Default : false
{
"sandbox" : {
"network" : {
"allowLocalBinding" : true
}
}
}
`sandbox.network.allowMachLookup`
列出 macOS 沙箱可能查找的其他 XPC 和 Mach 服务名称。通过 XPC 通信的工具,例如 iOS Simulator 或 Playwright,需要在此处列出其服务。
Scope : Any file
Type : 字符串数组,每个是服务名称;单个尾部 * 匹配前缀,"*" 单独匹配每个服务
Default : 未设置
这允许 com.apple.coresimulator. 前缀下的每个服务:
{
"sandbox" : {
"network" : {
"allowMachLookup" : [ "com.apple.coresimulator.*" ]
}
}
}
`sandbox.network.allowedDomains`
预先允许来自沙箱化命令的出站流量的域,因此沙箱不会为它们提示。通配符(如 *.example.com )匹配子域,可选的 :port 后缀将条目限制为一个端口;没有端口的条目匹配每个端口。
这预先允许 GitHub 在每个端口、每个 npm 子域和一个 API 主机仅在端口 443 上:
{
"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 。
`sandbox.network.deniedDomains`
阻止来自沙箱化命令的出站流量的域,使用与 allowedDomains 相同的通配符、端口和 IPv6 语法。被拒绝的域即使 allowedDomains 条目也匹配它也保持阻止。
Scope : Any file
Type : 字符串数组,每个是域、通配符模式或 IP 文字,带有可选的 :port 后缀
Default : 未设置
{
"sandbox" : {
"network" : {
"deniedDomains" : [ "sensitive.cloud.example.com" ]
}
}
}
Claude Code 从会话加载的每个设置源合并此列表,即使设置了 allowManagedDomainsOnly,因此开发人员总是可以收紧拒绝列表。对于 IPv6 文字,请参阅 IPv6 addresses in domain lists 。
使用标记完全限定域名的尾部点编写的条目,例如 example.com.,阻止与 example.com 相同的连接。
`sandbox.network.strictAllowlist`
拒绝沙箱化命令访问允许列表外的主机,而不是提示批准。允许列表是 allowedDomains 加上来自 WebFetch(domain:...) 允许规则的域,或仅当设置 allowManagedDomainsOnly 时的托管设置条目。需要 Claude Code v2.1.219 或更高版本。
Scope : User or managed 。存储库无法打开或关闭它。
Type : 布尔值
true: Claude Code 拒绝沙箱化命令访问允许列表外的主机
false: 除非另一个受信任的设置文件设置 true,Claude Code 根据权限模式而不是直接拒绝来决定允许列表外的主机:它在自动模式下检查主机对命令的 per-command allowed domains ,在 dontAsk 模式下拒绝,在 bypassPermissions 模式下允许,在交互式终端计划模式会话中当绕过可用时允许,否则询问您
Default : false
{
"sandbox" : {
"network" : {
"strictAllowlist" : true
}
}
}
Claude Code 仅对沙箱化命令强制执行此;进程内工具(如 WebFetch )仍然遵循其 permission rules 。当任何遵守的源将其设置为 true 时,它保持打开。请参阅 Network isolation 。需要 Claude Code v2.1.219 或更高版本。
`sandbox.network.allowManagedDomainsOnly`
将网络允许列表锁定到托管设置定义的内容。Claude Code 然后仅遵守来自托管设置的 allowedDomains 和 WebFetch(domain:...) 允许规则,忽略来自用户、项目、本地和 --settings 设置的域,并自动阻止非允许的域而不是提示。
Scope : Managed
Type : 布尔值
true: Claude Code 仅遵守来自托管设置的 allowedDomains 和 WebFetch(domain:...) 允许规则,并自动阻止非允许的域而不是提示
false: 来自用户、项目、本地和 --settings 设置的域合并到允许列表中
Default : false
这将允许列表锁定到 GitHub 和 npm,并忽略开发人员添加的任何域:
{
"sandbox" : {
"network" : {
"allowManagedDomainsOnly" : true,
"allowedDomains" : [ "github.com" , "*.npmjs.org" ]
}
}
}
被拒绝的域仍然从会话加载的每个源合并。请参阅 Keep developers from widening the policy 。
`sandbox.network.httpProxyPort`
将沙箱指向您自己的 HTTP 代理而不是 Claude Code 运行的。组织这样做以检查 HTTPS 流量、应用自己的过滤规则或记录每个请求。未设置时,Claude Code 为 HTTP 流量启动自己的代理。
Scope : Any file
Type : 数字,本地 TCP 端口
Default : 未设置,因此 Claude Code 运行自己的代理
{
"sandbox" : {
"network" : {
"httpProxyPort" : 8080
}
}
}
如果您的代理也应该携带 SOCKS 流量,也设置 socksProxyPort ;仅设置其中一个,Claude Code 仍然为另一个协议运行自己的代理。请参阅 Custom proxy configuration 。
`sandbox.network.socksProxyPort`
将沙箱指向您自己的 SOCKS5 代理而不是 Claude Code 运行的。未设置时,Claude Code 为 SOCKS 流量启动自己的代理。
Scope : Any file
Type : 数字,本地 TCP 端口
Default : 未设置,因此 Claude Code 运行自己的代理
{
"sandbox" : {
"network" : {
"socksProxyPort" : 8081
}
}
}
请参阅 Custom proxy configuration 。
`sandbox.network.tlsTerminate`
使沙箱代理终止 TLS,以便它可以读取 HTTPS 请求的内容。这是实验性的,mask credential substitution 需要它。设置 {} 为会话生成临时证书颁发机构,或设置 caCertPath 和 caKeyPath 以使用您自己的。
Scope : User or managed 。存储库无法打开它或提供证书颁发机构。
Type : 对象,包含可选的 caCertPath 和 caKeyPath 字符串,每个是文件路径
Default : 未设置,因此代理不终止或检查 TLS
{
"sandbox" : {
"network" : {
"tlsTerminate" : { }
}
}
}
当多个遵守的源设置它时,Claude Code 使用来自最高优先级源的值:托管设置,然后是 --settings 标志,然后是用户设置。需要 Claude Code v2.1.199 或更高版本。
内存和上下文
控制 Claude Code 加载到上下文中的内容、如何压缩以及在何处保存内存和计划。请参阅管理上下文 和内存 。
`autoCompactEnabled`
当上下文接近限制时,让 Claude Code 自动压缩对话 。在 /config 中显示为自动压缩 ,在那里切换它会将此键写入您的用户设置。
Scope : Any file
Type : Boolean
true: 当上下文接近限制时,Claude Code 自动压缩对话
false: Claude Code 不自动压缩
Default : true
Per-session overrides : DISABLE_AUTO_COMPACT 为一个会话关闭自动压缩;两者中任何一个关闭它,另一个就无法将其打开
{
"autoCompactEnabled" : false
}
手动 /compact 命令在自动压缩关闭时继续工作。
`autoCompactWindow`
设置在 Claude Code 自动压缩 之前上下文窗口的填充程度。
{
"autoCompactWindow" : 500000
}
使用 /autocompact 命令设置它,该命令将此键写入您的用户设置。设置自动压缩窗口 涵盖了命令、标志、变量和设置如何相互作用。
`autoMemoryDirectory`
将自动内存 存储在您选择的目录中,而不是每个项目的默认值。
Scope : Any file
Type : 字符串,绝对路径或 ~/ 前缀的目录路径
Default : 未设置,因此 Claude Code 使用 ~/.claude/projects/<project>/memory/
{
"autoMemoryDirectory" : "~/my-memory-dir"
}
从项目或本地设置中,Claude Code 在与 hooks 相同的工作区信任规则 下遵守此键,因为克隆的存储库可以提供这些文件。
`autoMemoryEnabled`
打开或关闭自动内存 。当为 false 时,Claude 不会从自动内存目录读取或写入。您也可以在会话期间使用 /memory 切换它,这会将此键写入您的用户设置。
Scope : Any file
Type : Boolean
true: 与未设置相同;自动内存保持打开,除非优先于此键的内容为会话关闭它,例如 --bare、安全模式或 CLAUDE_CODE_DISABLE_AUTO_MEMORY
false: Claude 不会从自动内存目录读取或写入
Default : true
Per-session overrides : CLAUDE_CODE_DISABLE_AUTO_MEMORY 对一个会话优先于此键,无论哪个方向
{
"autoMemoryEnabled" : false
}
`bashOutputMaxChars`
设置成功的 Bash 或 PowerShell 命令的输出 Claude 内联接收 的字符数。当输出超过限制时,Claude Code 将其保存到文件,Claude 接收简短预览加文件路径。当命令输出(例如详细构建或完整测试套件日志)经常超过默认值且您希望 Claude 在不打开文件的情况下读取它时,提高限制。需要 Claude Code v2.1.261 或更高版本。
Scope : Any file
Type : 字符数,正整数。Claude Code 将值限制在 4000 到 128000 范围内
Default : 未设置,因此 Claude 内联接收最多 30,000 个字符
{
"bashOutputMaxChars" : 100000
}
设置此键时,Claude Code 忽略 BASH_MAX_OUTPUT_LENGTH 环境变量。
`claudeMd`
注入 CLAUDE.md 风格的说明作为组织管理的内存,无需部署单独的文件。Claude Code 将文本作为托管内存条目加载,位于用户和项目 CLAUDE.md 文件之前。
Scope : Managed
Type : 字符串,CLAUDE.md 文件的文本;按照您编写文件的方式编写,包括 Markdown,行中断为 \n
Default : 未设置
此示例将两个规则部署为简短的 Markdown 列表:
{
"claudeMd" : "# Engineering rules\n\n- Always run make lint before committing.\n- Never push directly to main."
}
请参阅部署组织范围的 CLAUDE.md 。
`claudeMdExcludes`
当 Claude Code 加载内存 时跳过特定的 CLAUDE.md 文件。在大型单体仓库中,使用它跳过来自与您的工作无关的其他团队的 CLAUDE.md 文件;大型代码库指南中的排除无关的 CLAUDE.md 文件 演示了该情况。模式与绝对文件路径匹配。
Scope : Any file
Type : 字符串数组,每个都是 glob 模式或绝对路径
Default : 未设置,因此 Claude Code 加载它找到的每个 CLAUDE.md
{
"claudeMdExcludes" : [ "**/vendor/**/CLAUDE.md" ]
}
排除仅适用于用户、项目和本地内存文件;托管策略 CLAUDE.md 文件无法被排除。
`env`
为每个会话和 Claude Code 从中启动的子进程设置环境变量。环境变量参考 中的大多数变量都可以放在这里,这是如何将其应用于每个会话或向您的团队推出的方式。项目和本地设置无法设置其中一些 。
Scope : Any file
Type : 将变量名映射到字符串值的对象
Default : 未设置
此示例关闭自动压缩并通过代理路由 API 请求:
{
"env" : {
"DISABLE_AUTO_COMPACT" : "1" ,
"ANTHROPIC_BASE_URL" : "https://proxy.example.com"
}
}
`env` 值如何与您的 shell 交互
此处的值覆盖在您的 shell 中导出的相同变量,当多个设置文件设置一个变量时,最高优先级 的值适用。Claude Code 在 env 中忽略的变量 列出了项目和本地设置的例外。
要取消 shell 导出,将变量设置为 ""。Claude Code 将空值视为提供程序选择的未设置,子进程继承空值。
NO_COLOR 和 FORCE_COLOR 在此处设置仅到达子进程。要更改 Claude Code 自己的界面颜色,请在启动 claude 之前在您的 shell 中设置它们。
此处的值是设置文件中的纯文本,到达 Claude Code 启动的每个子进程。对于轮换的 OTLP 承载令牌,使用 otelHeadersHelper ;对于 API 凭证,使用 apiKeyHelper 。
Claude Code 何时应用 `env` 值
从用户设置、--settings 和托管设置:在启动时,以及在运行会话中当保存的更改改变合并的 env 时。
从项目和本地设置:在您信任工作区后,或在 -p 模式下启动时(从不显示信任对话),以及当保存的更改改变合并的 env 时。
Claude Code 分类为安全的变量,例如模型选择、超时和限制、功能切换:在启动时从每个设置文件,除了项目和本地设置无法设置的变量 。
在 v2.1.246 或更高版本上使用 /cd 移动会话 后:新目录的项目和本地 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 和详细的 beta 跟踪对 ENABLE_BETA_TRACING_DETAILED 和 BETA_TRACING_ENDPOINT。
OpenTelemetry 导出器 变量,打开遥测、选择它的去向或选择它捕获的内容:
CLAUDE_CODE_ENABLE_TELEMETRY,加上增强的遥测 beta 对 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA 和 ENABLE_ENHANCED_TELEMETRY_BETA
导出器选择器 OTEL_LOGS_EXPORTER、OTEL_METRICS_EXPORTER 和 OTEL_TRACES_EXPORTER
内容变量 OTEL_LOG_USER_PROMPTS、OTEL_LOG_ASSISTANT_RESPONSES、OTEL_LOG_TOOL_CONTENT 和 OTEL_LOG_TOOL_DETAILS
OTEL_EXPORTER_OTLP_* 变量,其名称以 _ENDPOINT、_HEADERS、_PROTOCOL、_CERTIFICATE、_CLIENT_KEY 或 _INSECURE 结尾,采用通用和按信号形式,例如 OTEL_EXPORTER_OTLP_ENDPOINT 和 OTEL_EXPORTER_OTLP_METRICS_HEADERS
OTEL_EXPORTER_PROMETHEUS_HOST 和 OTEL_EXPORTER_PROMETHEUS_PORT
只有这些值仍然适用于项目和本地设置,因为它们关闭某些内容:三个导出器选择器的 none,以及 OTEL_LOG_USER_PROMPTS、OTEL_LOG_TOOL_CONTENT 和 OTEL_LOG_TOOL_DETAILS 的关闭值,例如 0。这样的值覆盖您的用户设置中的相同变量,但不覆盖您启动 Claude Code 的环境、--settings 文件或托管设置设置的变量。
当项目或本地设置文件设置此组中的变量时,本地交互式会话在启动时显示通知。运行 /status 或 claude doctor 以查看 Claude Code 忽略了哪些变量以及哪些关闭了遥测;两者都列出名称,从不列出值。非交互式运行(使用 -p 或 Agent SDK 会话)不显示通知,因此在升级后检查您的收集器是否仍然接收数据。如果没有,请在您的用户设置、托管设置、作业的环境或您使用 --settings 传递的文件中设置变量。
在项目和本地设置中忽略此组需要 Claude Code v2.1.282 或更高版本。
改变 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 之前,项目和本地设置也可以设置此列表中选择 Claude Code 写入其文件位置或导出会话内容的变量,除了 HOME 和 XDG_CONFIG_HOME。
Claude Code 的托管环境拥有的身份变量,例如 CLAUDE_CODE_REMOTE 和 CLAUDE_CODE_ACCOUNT_UUID,从每个文件中被忽略。
CLAUDE_CODE_MESSAGING_SOCKET 和 CLAUDE_CODE_MESSAGING_TOKEN ,Claude Code 自己导出的,从每个文件中被忽略。忽略套接字变量需要 Claude Code v2.1.224 或更高版本,忽略令牌需要 v2.1.228 或更高版本。
CLAUDE_CODE_PROJECT_DIR_NAME ,Claude Code 仅从启动环境读取,从每个文件中被忽略;需要 v2.1.234 或更高版本。
CLAUDE_CODE_RESTRICTED ,Claude Code 仅从启动环境读取,从每个文件中被忽略。
`fileCheckpointingEnabled`
让 Claude Code 在每次编辑前快照文件,以便 /rewind 可以恢复它们。在 /config 中显示为回退代码(检查点) ,在那里切换它会将此键写入您的用户设置。
{
"fileCheckpointingEnabled" : false
}
在 -p 运行或 Agent SDK 会话中,Claude Code 忽略此键。SDK 使用其 enableFileCheckpointing 选项打开检查点,裸 -p 运行需要 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true。请参阅 Agent SDK 中的文件检查点 。
`plansDirectory`
选择 Claude Code 在计划模式 中写入的计划文件的存储位置。Claude Code 相对于项目根目录解析路径,当路径解析到项目外时保持默认值。
Scope : Any file
Type : 字符串,相对于项目根目录的路径
Default : 未设置,因此 Claude Code 使用 ~/.claude/plans
{
"plansDirectory" : "./plans"
}
`skillListingBudgetFraction`
每个回合,Claude 看到您的技能列表 及其描述,Claude Code 将该列表限制在上下文窗口的一部分。当列表超过上限时,Claude Code 保留每个技能的名称,但删除使用最少的技能的描述,因此 Claude 仍然可以调用这些技能,但不太可能自己选择一个。提高此键以保持更多描述可见,代价是每个回合更多上下文。
Scope : Any file
Type : 数字,大于 0 且最多 1 的分数
Default : 0.01,保留 1% 的上下文窗口
{
"skillListingBudgetFraction" : 0.02
}
要查看列表使用多少上下文以及哪些技能贡献最多,请运行 /doctor。
`skillListingMaxDescChars`
每个回合,Claude 看到您的技能列表 ,显示每个技能的 description 和 when_to_use 文本。此键限制 Claude Code 每个技能显示多少字符的该文本;较长的文本在上限处被切割。
Scope : Any file
Type : 字符数,正整数
Default : 1536
{
"skillListingMaxDescChars" : 2048
}
提高它以保持长描述完整,代价是每个回合更多上下文;降低它以在 skillListingBudgetFraction 下适应更多技能。
`taskOutputMaxChars`
通过 v2.1.276,您将此键设置为后台任务 的输出字符数,当 Claude 使用 TaskOutput 工具读取任务时 Claude 内联接收。
界面和终端
改变 Claude Code 在终端中的外观和行为:主题、编辑器模式、状态行、加载动画、会话内通知和无障碍功能。请参阅终端配置 。
`askUserQuestionTimeout`
让未回答的 AskUserQuestion 对话框在空闲一段时间后自动继续,提交您已选择的任何选项。当您离开时设置此项,让 Claude 在没有您的情况下继续。使用默认设置时,问题会等待您回答。需要 Claude Code v2.1.200 或更高版本。
{
"askUserQuestionTimeout" : "5m"
}
在 /config 中显示为问题自动继续超时 ,它将此键写入用户设置;当托管设置或 --settings 标志设置此键时,Claude Code 会隐藏该行。需要 Claude Code v2.1.200 或更高版本。
`autoContinueAtUsageLimit`
在 claude.ai 使用限制停止您的会话后,在打开的会话中等待,并在重置后自动继续任务。请参阅关闭自动继续 。需要 Claude Code v2.1.234 或更高版本。
Scope : User or managed 。仅从用户设置、--settings 和托管设置中读取。当这些都没有设置此键时,设置此键的项目或本地设置文件会关闭该功能,而不是被忽略。
Type : Boolean
true:在 claude.ai 使用限制停止您的会话后,Claude Code 在打开的会话中等待,并在重置后自动继续任务
false:Claude Code 不会自动启动等待。您仍然可以从使用限制选项菜单自己启动等待
Default : true
{
"autoContinueAtUsageLimit" : false
}
在 /config 中显示为在使用限制时自动继续 ,它将此键写入用户设置;当托管设置或 --settings 标志设置此键时,Claude Code 会隐藏该行。
在全屏渲染 中跟随新输出到对话底部。关闭它以在 Claude 继续工作时保持您滚动的位置;权限提示仍会滚动到视图中。
Scope : Any file
Type : Boolean
true:对话跟随新输出到底部
false:当 Claude 继续工作时,您保持在滚动的位置;权限提示仍会显示在记录下方
Default : true
{
"autoScrollEnabled" : false
}
在全屏渲染打开时,在 /config 中显示为自动滚动 ,它将此键写入用户设置。
`axScreenReader`
渲染屏幕阅读器友好的输出:没有装饰性边框或动画的平面文本。屏幕阅读器模式使用经典渲染器,因此在它处于活动状态时 tui 设置无效;附加的后台会话 仍会全屏渲染。
{
"axScreenReader" : true
}
`bashEditDiffEnabled`
选择 Claude Code 是否记录 Bash 命令在 Git 存储库中更改的文件。当它记录它们时,您会在命令后在终端中看到它们的差异,您的 PostToolUse Bash hooks 会接收更改的文件列表。
列出的文件并不总是命令更改的文件。命令运行时另一个程序或另一个 Bash 调用所做的更改也可能出现在那里。
将键设置为 true 以在每个权限模式中记录它们。需要 Claude Code v2.1.269 或更高版本。
Scope : User or managed 。true 仅从您的用户设置、使用 --settings 传递的 JSON 或托管设置 计数,因此存储库的 .claude/settings.json 或 .claude/settings.local.json 中的 true 无法打开记录。存储库文件中的 false 仍会关闭它,除非更高优先级 的文件设置 true。
Type : Boolean
Default : unset,所以当 Claude Code 指导 Claude 通过 Bash 编辑文件时,Claude Code 在自动模式和 bypassPermissions 模式中记录更改
Per-session overrides : CLAUDE_CODE_BASH_EDIT_DIFF 在单个会话中优先于此键
{
"bashEditDiffEnabled" : true
}
`companyAnnouncements`
在启动时向用户显示您组织的公告。当您列出多个公告时,Claude Code 为每个会话随机选择一个;在某人的首次启动时,它显示第一个条目。
Scope : Any file
Type : array of strings
Default : unset,所以不显示公告
{
"companyAnnouncements" : [
"欢迎来到 Acme Corp!请在 docs.example.com 查看我们的代码指南"
]
}
`defaultShell`
选择 Bash 或 PowerShell 是否运行您在输入框中使用 ! 前缀 键入的 shell 命令,以及 Claude Code 直接运行并添加到会话的命令。
"powershell" 仅在 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
Type : string,值为以下之一:
"bash":Claude Code 在 Bash 中运行您的 ! 命令
"powershell":Claude Code 在 PowerShell 中运行您的 ! 命令
Default : "bash",或在 Bash 不可用时在 Windows 上为 "powershell"
{
"defaultShell" : "powershell"
}
如果您指定的 shell 不可用,Claude Code 会使用另一个:当 PowerShell 工具关闭时 "powershell" 回退到 Bash,当 Bash 未安装时 "bash" 回退到 PowerShell。
`dialogExpiry`
为 Claude Code 转发给远程客户端 的对话框(例如远程控制或 SDK 主机)以及保留的跨会话消息 的批准对话框设置截止时间。在 Claude Code v2.1.236 或更高版本上,相同的截止时间限制了会话中可能没有人在终端的中期 Fable 使用额度同意提示 。当在截止时间前没有答案到达时,Claude Code 取消对话框并继续使用其无操作默认值。需要 Claude Code v2.1.224 或更高版本。
{
"dialogExpiry" : "10m"
}
权限提示和 AskUserQuestion 问题使用它们自己的流程,不受此截止时间管制。在 /config 中显示为对话框过期 ,它将此键写入用户设置;该行需要 Claude Code v2.1.232 或更高版本,当托管设置或 --settings 标志设置此键时,Claude Code 会隐藏它。
`editorMode`
为输入提示选择快捷键绑定模式。
Scope : Any file
Type : string,值为以下之一:
"normal":提示输入中的标准快捷键
"vim":vim 风格编辑,具有 NORMAL、INSERT 和 VISUAL 模式
Default : "normal"
{
"editorMode" : "vim"
}
在 /config 中显示为编辑器模式 ,它将此键写入用户设置。
`emojiCompletionEnabled`
当您在提示输入中键入 : 加上速记代码时显示表情符号建议,并将完成的速记代码(如 :heart:)替换为其表情符号。将其设置为 false 以关闭两者。
Scope : Any file
Type : Boolean
true:Claude Code 在 : 后显示表情符号建议,并将完成的速记代码替换为其表情符号
false:Claude Code 既不建议表情符号也不替换速记代码
Default : true
{
"emojiCompletionEnabled" : false
}
请参阅表情符号速记代码 。需要 Claude Code v2.1.217 或更高版本。
`fileSuggestion`
运行您自己的命令来提供 @ 文件路径自动完成,而不是使用内置文件建议。内置建议使用快速文件系统遍历;大型单体仓库可能会通过项目特定的索引(如预构建的文件索引)做得更好。
Scope : Any file 。在状态行和文件建议门 下,Claude Code 关闭命令或仅运行托管值,并跳过您的而不发出警告。
Type : 对象,包含 type(始终为 "command")和 command(要运行的 shell 命令)
Default : unset,所以 Claude Code 使用内置文件建议
{
"fileSuggestion" : {
"type" : "command" ,
"command" : "~/.claude/file-suggestion.sh"
}
}
保存后,在提示中键入 @ 后跟部分路径:建议来自您命令的输出。
Claude Code 使用与 hooks 相同的环境变量运行命令,包括 CLAUDE_PROJECT_DIR,并在五秒后停止等待。该命令在 stdin 上接收 JSON,其中 query 字段包含您到目前为止键入的内容:
{ "query" : "src/comp" }
将换行符分隔的文件路径打印到 stdout。Claude Code 最多显示 15 个:
src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx
以下脚本读取查询并将其传递给存储库文件索引:
query=$(cat | jq -r '.query' )
your-repo-file-index --query "$query" | head -20
当正则表达式匹配转向输出时在输入框下方的页脚中渲染额外的可点击徽章:工具结果,包括文件内容和获取的页面,以及 Claude 自己的响应。使用它将项目 CLI 打印的 ID(如审查工具和问题跟踪器)转换为会话链接。
Scope : User or managed
Type : 对象数组,每个对象的 type 设置为 "regex"、pattern 正则表达式、url 模板和可选的 label;url 和 label 中的 {name} 占位符从 pattern 中的命名捕获组填充
Default : unset,所以不渲染徽章
此示例匹配问题键(如 PROJ-1234)并从捕获的键构建每个链接:
{
"footerLinksRegexes" : [
{
"type" : "regex" ,
"pattern" : "\\b(?<key>PROJ-\\d+)\\b" ,
"url" : "https://issues.example.com/browse/{key}" ,
"label" : "{key}"
}
]
}
配置此项后,当 PROJ-1234 出现在工具结果或 Claude 的回复中时,页脚中会出现一个 PROJ-1234 徽章,链接到 https://issues.example.com/browse/PROJ-1234。
徽章约束
每个条目的 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 线性并避免嵌套 + 或 *。
页脚徽章与自定义状态行 一起渲染(当配置了一个时);两者都不替换另一个。使用状态行来获得从会话数据计算自己内容的脚本驱动行,使用页脚徽章将对话中的 ID 转换为链接而无需脚本。
`keybindingFlavor`
在 v2.1.238 到 v2.1.260 中,将其设置为 "readline" 使 Ctrl+W 删除回到前一个空格而不仅仅是前一个单词。
Scope : Any file
Type : string,"classic" 或 "readline"
Default : unset
`prefersReducedMotion`
减少或关闭界面动画,如加载动画、闪烁和闪光效果。在 /config 中显示为减少动画 。
Scope : Any file
Type : Boolean
true:Claude Code 减少或关闭界面动画,如加载动画、闪烁和闪光效果
false:与 unset 相同;Claude Code 显示其动画
Default : false
{
"prefersReducedMotion" : true
}
`promptSuggestionEnabled`
显示或隐藏提示建议 ,即在您的提示输入中出现的灰显预测。将其设置为 false,或在 /config 中关闭提示建议 ,以隐藏它们。
{
"promptSuggestionEnabled" : false
}
提示建议需要启用了遥测的 claude.ai 或 Console 账户。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上,或关闭遥测时(如通过 DISABLE_TELEMETRY ),此键无效,仅 CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=1 打开它们。
`respectGitignore`
控制 @ 文件选择器是否排除与 .gitignore 模式匹配的文件。在 /config 中显示为在文件选择器中尊重 .gitignore 。
Scope : Any file 。当没有设置文件设置它时,Claude Code 回退到 ~/.claude.json 中的 respectGitignore,这是 /config 切换写入的。
Type : Boolean
true:@ 文件选择器排除与 .gitignore 模式匹配的文件
false:@ 文件选择器包括与 .gitignore 模式匹配的文件
Default : true
{
"respectGitignore" : false
}
`respondToBashCommands`
选择在您使用输入框中的 ! 前缀 运行 shell 命令后 Claude 是否响应。默认情况下,Claude Code 将命令的输出添加到对话中,Claude 对其进行回复。将此键设置为 false 以将输出添加到上下文而不进行回复,以便您可以运行多个命令并一起询问它们。需要 Claude Code v2.1.186 或更高版本。
Scope : Any file
Type : Boolean
true:Claude Code 将命令的输出添加到对话中,Claude 对其进行回复
false:Claude Code 将输出添加到上下文而不进行回复
Default : true
{
"respondToBashCommands" : false
}
请参阅使用 ! 前缀的 Shell 模式 。需要 Claude Code v2.1.186 或更高版本。
`showClearContextOnPlanAccept`
当 Claude 在计划模式 中完成计划时,它显示一个批准菜单。规划可能会使用大量上下文,因此此键向该菜单添加第一个选项是的,清除上下文并… ,它批准计划、清除对话上下文并仅从计划开始实施。标签的其余部分命名会话继续的权限模式,并显示规划使用了多少上下文。
Scope : Any file
Type : Boolean
true:计划批准菜单获得第一个选项是的,清除上下文并… ,它批准计划并清除对话上下文
false:计划批准菜单不显示清除上下文选项
Default : false
{
"showClearContextOnPlanAccept" : true
}
`showTurnDuration`
显示或隐藏每个响应后的转向持续时间消息,如"Cooked for 1m 6s · done 6:05 PM"。"done"后的时钟显示转向何时完成;timeFormat 和 timeZone 控制其格式和区域。在 /config 中显示为显示转向持续时间 。
Scope : Any file 。当没有设置文件设置它时,来自较旧版本的 ~/.claude.json 中的值适用。
Type : Boolean
true:您在每个响应后看到转向持续时间消息
false:Claude Code 隐藏转向持续时间消息
Default : true
{
"showTurnDuration" : false
}
`spellcheck`
在您键入时在提示输入中为拼写错误的单词加下划线,使用您安装的拼写检查器。Claude Code 仅检查输入框中的文本。在您键入时检查拼写 涵盖安装 aspell、hunspell 或 ispell 以及检查器涵盖的内容。需要 Claude Code v2.1.235 或更高版本。
Scope : User or managed 。设置它的最高层的块整体应用。
Type : 对象,包含 enabled(Boolean)、checker("aspell"、"hunspell"、"ispell" 或 "auto")、language(字符串,传递给检查器作为其字典名称)和 color(字符串,终端颜色名称、#rrggbb、rgb(r,g,b)、ansi256(n) 或 ansi:<name>)
Default : unset,所以拼写检查关闭;checker 默认为 "auto",PATH 上找到的前三个之一;language 默认为检查器自己的字典;color 默认为主题的错误颜色
{
"spellcheck" : { "enabled" : true, "language" : "en_GB" }
}
`spinnerTipsEnabled`
当 Claude 工作时,加载动画行轮换显示关于 Claude Code 功能的短提示,如"使用计划模式为复杂请求做准备,然后再进行更改。按 Shift+Tab 两次以启用。"将此键设置为 false 以隐藏它们。在 /config 中显示为显示提示 。
Scope : Any file
Type : Boolean
true:当 Claude 工作时,您在加载动画中看到提示
false:Claude Code 隐藏加载动画提示
Default : true
{
"spinnerTipsEnabled" : false
}
`spinnerTipsOverride`
将您自己的提示添加到 Claude Code 在 Claude 工作时显示的加载动画提示 ,或用您的提示替换内置提示。Claude Code 将您的提示放在与内置提示相同的轮换中:它选择未显示时间最长的提示,跳过仍在冷却期中的提示,并通过优先级打破平局。
如果您将 spinnerTipsEnabled 设置为 false,Claude Code 会隐藏所有提示,包括您的。
Scope : Any file 。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 每个进程读取一次文件,因此在下次启动时加载您的编辑。您不能通过服务器管理的设置 设置它;在那里部署内联 tips,或在磁盘上的 managed-settings.json 中部署路径。
label:Claude Code 在来自用户、--settings 和托管设置的提示之前显示的前缀,最多 40 个字符。默认值是 Tip,与内置提示相同的前缀,来自项目和本地设置的提示始终使用它。
excludeDefault:将其设置为 true 以隐藏内置提示并仅显示您的。当 Claude Code 无法加载您的任何提示时,例如因为 tipsFile 不存在或每个条目都无效,它保持内置轮换而不是空加载动画。
当多个设置文件设置此键时,Claude Code 显示来自所有这些文件的提示,并从托管设置、--settings 标志和用户设置中最高优先级的设置每个的 tipsFile、label 和 excludeDefault。
此示例在您的用户设置中添加纯字符串提示和对象提示到 Acme tip 前缀下的轮换:
{
"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
Type : 对象,包含 verbs 字符串数组和 mode,值为以下之一:
"append":Claude Code 将您的动词添加到内置集合
"replace":Claude Code 仅显示您的动词
Default : unset,所以 Claude Code 使用内置动词
此示例将两个动词添加到内置集合:
{
"spinnerVerbs" : {
"mode" : "append" ,
"verbs" : [ "Pondering" , "Crafting" ]
}
}
在 "replace" 模式下使用空 verbs 数组,Claude Code 保持内置动词。
`statusLine`
运行您自己的命令来渲染提示下方的状态行 ,包含模型、成本或 git 分支等上下文。可选字段调整间距、添加定期重新运行,并在您的脚本自己渲染 vim.mode 时隐藏内置 vim 模式指示器。
Scope : Any file 。当 allowManagedHooksOnly 打开时,或 disableAllHooks 在托管设置外设置时,仅托管设置值运行。
Type : 对象,type 设置为 "command" 和 command 字符串,加上可选的 padding 作为字符数、refreshInterval 作为秒数(最少 1)和 hideVimModeIndicator 作为 Boolean
Default : unset,所以没有状态行
此示例打印模型名称和上下文使用情况,并添加两个字符的水平间距:
{
"statusLine" : {
"type" : "command" ,
"command" : "jq -r '\" [ \\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'" ,
"padding" : 2
}
}
示例需要安装 jq 并在 shell 中运行。对于 PowerShell 和 Git Bash 等效项,请参阅Windows 配置 ;对于完整设置,请参阅手动配置状态行 。
`subagentStatusLine`
当 Claude 运行子代理 时,Claude Code 在提示下方的任务显示中列出它们,每个子代理一行显示 name · description · token count。此键让您运行自己的命令来重写这些行,例如显示每个子代理的上下文使用情况百分比。在每次刷新时,Claude Code 将可见行作为一个 JSON 对象发送到 stdin,其中 tasks 数组包含每个子代理的 id、name、status、model、tokenCount 等,并将您写回的每个 id 的行替换为 {"id", "content"} 行。您不写回的行保持默认渲染。
{
"subagentStatusLine" : {
"type" : "command" ,
"command" : "jq -c '.tasks[] | {id, content: \" \\(.name): \\(.tokenCount) tokens\"}'"
}
}
请参阅子代理状态行 。
`syntaxHighlightingDisabled`
Claude Code 使用其内置高亮器按语言为它在终端中显示的差异、代码块和文件预览着色;不涉及插件或语言服务器。将此键设置为 true 以改为将它们显示为纯文本,例如如果颜色与您的终端主题冲突或减慢屏幕阅读器。
Scope : Any file
Type : Boolean
true:Claude Code 在差异、代码块和文件预览中关闭语法高亮
false:Claude Code 高亮语法
Default : false
{
"syntaxHighlightingDisabled" : true
}
`terminalProgressBarEnabled`
某些终端可以在选项卡或任务栏中为在其中运行的程序显示进度指示器。当 Claude 工作时,Claude Code 向终端报告进行中状态,因此您可以从另一个选项卡或窗口看到会话是否仍然繁忙。指示器在转向结束后保持可见,同时后台子代理 或动态工作流 仍在运行,并在会话空闲后清除。
Claude Code 仅在支持指示器的终端中报告它:ConEmu、Ghostty 1.2.0 或更高版本以及 iTerm2 3.6.6 或更高版本。将此键设置为 false 以停止 Claude Code 报告它。在 /config 中显示为终端进度条 。
Scope : Any file 。当没有设置文件设置它时,来自较旧版本的 ~/.claude.json 中的值适用。
Type : Boolean
true:您在支持它的终端中看到终端进度条
false:Claude Code 隐藏终端进度条
Default : true
{
"terminalProgressBarEnabled" : false
}
`terminalTitleFromRename`
Claude Code 设置您的终端选项卡的标题。默认情况下,它使用从对话生成的标题,一旦您使用 /rename 或 --name 给会话命名 ,选项卡会改为显示该名称。将此键设置为 false 以在您命名会话后保持生成的标题在选项卡上。名称本身仍然适用,因此 /resume <name> 和会话选择器找到它。
Scope : Any file
Type : Boolean
true:终端选项卡标题显示您设置的会话名称
false:选项卡保持 Claude Code 从您的对话生成的标题
Default : true
{
"terminalTitleFromRename" : false
}
要停止 Claude Code 完全更新终端标题,请改为将 CLAUDE_CODE_DISABLE_TERMINAL_TITLE 设置为 1。
`theme`
为界面选择颜色主题。在 /config 中显示为主题 。
Scope : Any file 。当没有设置文件设置它时,来自较旧版本的 ~/.claude.json 中的值适用。
Type : string,值为以下之一:
"auto":匹配您的终端的浅色或深色背景
"dark":深色主题
"light":浅色主题
"dark-daltonized":具有色盲友好颜色的深色主题
"light-daltonized":具有色盲友好颜色的浅色主题
"dark-ansi":仅使用您的终端 ANSI 调色板的深色主题
"light-ansi":仅使用您的终端 ANSI 调色板的浅色主题
"custom:<slug>" 或 "custom:<plugin-name>:<slug>":来自 ~/.claude/themes/ 或插件的自定义主题
Default : "dark"
{
"theme" : "light-daltonized"
}
请参阅创建自定义主题 。
选择 Claude Code 如何写入它在界面中显示的时间,如每个转向持续时间消息末尾的 done 6:05 PM 和记录查看器 中的时间戳。要选择预设,运行 /config 并设置时间格式 。需要 Claude Code v2.1.257 或更高版本。
Scope : Any file
Type : string,值为以下之一:
"auto":与 unset 相同;每个时间保持其内置格式,在转向持续时间消息上遵循您的区域设置
"12-hour":12 小时制
"24-hour":24 小时制
"24-hour-utc":UTC 中的 24 小时制,分钟后带 Z,如 18:05Z;Claude Code 对此预设忽略 timeZone
strftime 模式,如 "%H:%M":Claude Code 使用模式写入每个时间。任何包含 % 的值都是模式,任何在预设外的其他值计为 "auto"
Default : "auto"
{
"timeFormat" : "24-hour"
}
/config 仅提供预设,因此要使用 strftime 模式,请将键添加到设置文件。此示例将每个时间显示为两位数 24 小时制:
{
"timeFormat" : "%H:%M"
}
转向持续时间消息和记录查看器然后显示时间,如 18:05。在记录查看器中,模式是整个时间戳,因此在需要日期时添加日期指令。此示例将日期放在时钟前面:
{
"timeFormat" : "%Y-%m-%d %H:%M"
}
相同的表面然后显示时间,如 2026-09-01 18:05。
`timeZone`
在不同于您系统的时区中显示界面中的时间。将其设置为 IANA 时区名称 ,如 "UTC" 或 "Europe/Dublin"。timeFormat 控制的时间然后在此区域中显示。如果 timeFormat 是 "24-hour-utc",时间保持在 UTC 中,Claude Code 忽略此键。/config 对此键没有行,因此在设置文件中设置它。需要 Claude Code v2.1.257 或更高版本。
Scope : Any file
Type : string,IANA 时区名称。当 Claude Code 不识别名称时,它使用您的系统时区
Default : unset,所以时间显示在您的系统时区
{
"timeZone" : "Europe/Dublin"
}
`tui`
选择终端 UI 渲染器。使用 "fullscreen" 获得无闪烁的替代屏幕渲染器 ,具有虚拟化滚动条,或使用 "default" 获得经典主屏幕渲染器。运行 /tui fullscreen 或 /tui default 为您写入此键。
{
"tui" : "fullscreen"
}
在 tmux -CC 下或通过 SSH 到 Windows,Claude Code 保持经典渲染器,除非您设置 CLAUDE_CODE_NO_FLICKER=1。从代理视图 打开的后台会话始终使用全屏渲染器,无论此设置如何。
`verbose`
默认情况下,记录将每个工具调用折叠为简短摘要,如 Claude 运行的命令和其输出的行数,您按 Ctrl+O 在需要详细信息时将整个记录切换到展开视图。将此键设置为 true 以在发生时内联显示每个工具调用的完整输入和输出,这在您调试 hook、MCP 服务器或长 shell 命令时很有用。在 /config 中显示为详细输出 。
Scope : Any file 。当没有设置文件设置它时,来自较旧版本的 ~/.claude.json 中的值适用。
Type : Boolean
true:您看到完整工具输出
false:您看到工具输出的截断摘要
Default : false
Per-session overrides : --verbose 在单个会话中优先于此键
{
"verbose" : true
}
viewMode 值或粘性 /focus 选择在每个会话中覆盖此键。
`viewMode`
设置 Claude Code 启动的记录视图:"default"、"verbose" 或 "focus"。设置时,它覆盖粘性 /focus 选择和 verbose 设置。
Scope : Any file
Type : string,值为以下之一:
"default":具有截断工具输出的正常记录
"verbose":具有完整工具输出的记录
"focus":仅您的最后提示、工具调用的单行摘要,带编辑差异统计,和最终响应。焦点视图需要全屏渲染器
Default : unset,所以 verbose 设置和您最后的 /focus 选择适用
Per-session overrides : --verbose 在单个会话中优先于此键
{
"viewMode" : "focus"
}
`vimInsertModeRemaps`
在 vim 编辑器模式 中将两键 INSERT 模式序列映射到 Escape。每个键恰好是按顺序键入的两个可打印字符,"<Esc>" 是唯一支持的目标;Claude Code 忽略其他条目。需要 Claude Code v2.1.208 或更高版本。
Scope : User or managed 。存储库不能重新映射您的按键。
Type : 对象,将两字符序列映射到 "<Esc>"
Default : unset
{
"vimInsertModeRemaps" : {
"jj" : "<Esc>"
}
}
除非 editorMode 是 "vim",否则无效。请参阅重新映射 INSERT 模式快捷键序列 。需要 Claude Code v2.1.208 或更高版本。
`voice`
打开语音听写 并选择听写键的行为方式。当您运行 /voice 时,Claude Code 为您写入此对象。
Scope : Any file
Type : 对象,enabled 作为 Boolean,autoSubmit 作为仅在保持模式中适用的 Boolean,和 mode,值为以下之一:
"hold":您在说话时按住听写键,释放它以停止
"tap":您点击键一次以开始录制,再次以发送
Default : unset,所以听写关闭;当 enabled 是 true 且 mode 未设置时,Claude Code 使用 "hold"
此示例打开听写并使键点击一次以开始录制,再次以发送:
{
"voice" : {
"enabled" : true,
"mode" : "tap"
}
}
autoSubmit 在保持模式中释放键时发送提示。语音听写需要 claude.ai 账户。
`voiceEnabled`
使用在 voice 对象之前的单个 Boolean 形式打开语音听写。当两者都设置时,voice.enabled 适用。
Scope : Any file
Type : Boolean
true:当您使用 claude.ai 账户登录且您的组织政策允许语音时,语音听写打开,除非 voice.enabled 设置
false:语音听写关闭,除非 voice.enabled 设置
Default : unset
{
"voiceEnabled" : true
}
在全屏渲染 中快速滚动期间加速鼠标滚轮滚动速度。将其设置为 false 以获得每个滚轮凹口的恒定滚动速率。
Scope : Any file
Type : Boolean
true:Claude Code 在快速滚动期间加速鼠标滚轮滚动速度
false:Claude Code 以每个滚轮凹口的恒定速率滚动
Default : true
{
"wheelScrollAccelerationEnabled" : false
}
Git 和归属
控制 Claude Code 添加到提交和拉取请求的归属,以及它如何与 git 配合使用。
`attribution`
自定义 Claude Code 添加到 git 提交和拉取请求的归属。提交默认获得 git trailer ,例如 Co-Authored-By;拉取请求描述获得纯文本。使用下面的子键分别设置每个部分。
Scope : Any file
Type : 包含 commit 和 pr 字符串以及 sessionUrl 布尔值的对象,或 false 以隐藏所有归属。false 值需要 Claude Code v2.1.281 或更高版本;更早的版本会拒绝它并跳过整个用户、项目或本地设置文件
Default : 未设置,因此 Claude Code 使用每个子键下显示的标准归属
要隐藏所有归属,请将 attribution 设置为 false。在早期版本也读取的设置文件中,将 commit 和 pr 设置为空字符串,并将 sessionUrl 设置为 false。
此示例替换提交归属,删除拉取请求归属,并删除会话链接:
{
"attribution" : {
"commit" : "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>" ,
"pr" : "" ,
"sessionUrl" : false
}
}
一旦设置 commit 或 pr,Claude Code 将忽略已弃用的 includeCoAuthoredBy 设置,并对未设置的两个中的任何一个使用其默认文本。
Claude Code 告诉 Claude,您自己关于归属的说明(例如 CLAUDE.md 或 memory 规则)优先于这些提交和 PR 行,除非该行在 managed settings 中设置。
`includeCoAuthoredBy`
改用 attribution ,它替换此键,让您可以分别更改或隐藏提交 trailer、拉取请求文本和会话链接。Claude Code 仍然遵守来自早于 attribution 的设置文件中的 includeCoAuthoredBy: false,但一旦设置 attribution.commit 或 attribution.pr,就会忽略它。
Scope : Any file
Type : 布尔值
true: 与未设置相同;Claude Code 添加提交 trailer 和拉取请求归属文本
false: Claude Code 省略提交 trailer 和拉取请求归属文本,除非 attribution 设置 commit 或 pr,在这种情况下 attribution 规则适用
Default : true
{
"includeCoAuthoredBy" : false
}
要隐藏所有归属,请参阅 attribution 。
`includeGitInstructions`
Claude Code 向 Claude 提供两个与 git 相关的上下文片段:其内置的关于如何编写提交和拉取请求的说明(在 Bash 工具的描述中),以及您的存储库的 git 状态快照。快照包含当前分支、主分支、git status 输出和最近的提交。Claude Code 在会话开始时读取它。
将此键设置为 false 以将两者都排除,例如当您使用自己的 git 工作流技能时。
{
"includeGitInstructions" : false
}
`prUrlTemplate`
将 Claude Code 呈现的 PR 链接(在页脚徽章和工具结果摘要中)指向内部代码审查工具而不是 github.com。Claude Code 从 PR URL 替换 {host}、{owner}、{repo}、{number} 和 {url}。GitLab 合并请求 两个表面上的链接保持其 GitLab URL。
Scope : Any file
Type : 字符串,使用五个占位符中任何一个的 URL 模板
Default : 未设置
{
"prUrlTemplate" : "https://reviews.example.com/{owner}/{repo}/pull/{number}"
}
Claude Code 仅将模板应用于它自己呈现的链接;Claude 在消息中编写的 PR 号(例如 #123)保持 Claude 编写的样子。没有 /pull/<number> 形状的 URL 保持不变。
`attribution.commit`
设置 Claude Code 添加到 git 提交的归属文本,包括任何 trailer。将其设置为空字符串以隐藏提交归属。
Scope : Any file
Type : 字符串
Default : 未设置,因此 Claude Code 添加 Co-Authored-By: <name> <noreply@anthropic.com>。名称是会话的活跃模型,例如 Claude Sonnet 5。
当 Claude Code 识别模型为 Claude 模型但无法确认其确切版本时,它单独写入 Claude。
当它无法将模型 ID 匹配到任何 Claude 模型(例如通过自定义 ANTHROPIC_BASE_URL 提供的第三方模型)时,它写入 Claude Code。
此示例用自定义行和自定义 Co-Authored-By trailer 替换默认 trailer:
{
"attribution" : {
"commit" : "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>"
}
}
`attribution.pr`
设置 Claude Code 添加到拉取请求描述的归属文本。将其设置为空字符串以隐藏拉取请求归属。
Scope : Any file
Type : 字符串
Default : 未设置,因此 Claude Code 添加 🤖 Generated with [Claude Code](https://claude.com/claude-code)
{
"attribution" : {
"pr" : ""
}
}
`attribution.sessionUrl`
选择 Claude Code 在从 cloud 或 Remote Control 会话提交或打开拉取请求时是否附加 claude.ai 会话链接。Claude Code 在提交上添加链接作为 Claude-Session trailer,在拉取请求描述中添加链接。将其设置为 false 以省略链接。
Scope : Any file
Type : 布尔值
true: Claude Code 在从云或 Remote Control 会话提交或打开拉取请求时附加 claude.ai 会话链接
false: Claude Code 省略链接
Default : true
{
"attribution" : {
"sessionUrl" : false
}
}
Hooks 和自动化
注册 hooks,限制哪些 hooks 运行,以及控制工作流。有关 hook 事件和有效负载,请参阅 hooks 参考 。
`allowedHttpHookUrls`
限制 HTTP hooks 可以针对的 URL。定义此键时,Claude Code 仅在 HTTP hook 的 URL 与某个模式匹配时才运行该 hook,并阻止其余的而不运行它们;空数组会阻止每个 HTTP hook。
作用域 : 任何文件 。数组在设置文件中合并。
类型 : URL 模式数组,* 作为通配符
默认值 : 未设置,因此允许任何 URL
此示例允许 https://hooks.example.com/ 下的任何 URL 和任何 http://localhost URL:
{
"allowedHttpHookUrls" : [ "https://hooks.example.com/*" , "http://localhost:*" ]
}
主机名匹配不区分大小写,并将 hooks.example.com.(带有标记完全限定域名的尾部点)视为与 hooks.example.com 相同,这是 DNS 的处理方式。允许列表适用于来自每个源的 hooks,包括托管设置。
`allowManagedHooksOnly`
限制 hook 执行仅限于您的组织部署的 hooks。
作用域 : 托管
类型 : 布尔值
默认值 : 未设置,因此来自每个设置作用域和插件的 hooks 都运行
{
"allowManagedHooksOnly" : true
}
在 `allowManagedHooksOnly` 下运行什么
将其设置为 true 时,Claude Code 会更改加载的 hooks 和类似 hook 的命令:
设置此键时,/goal 命令无法运行,因为它依赖于 hooks。
`disableAllHooks`
关闭 hooks 、任何自定义 状态行 和任何自定义 文件建议 命令。使用它可以临时关闭所有这些,而无需从设置中删除它们。
作用域 : 任何文件 。仅托管设置可以禁用托管 hooks。
类型 : 布尔值
true: Claude Code 关闭 hooks、任何自定义状态行和任何自定义文件建议命令
false: hooks、状态行和文件建议命令运行
默认值 : 未设置,因此 hooks 运行
{
"disableAllHooks" : true
}
范围取决于哪个文件包含该键:
在托管设置中 : Claude Code 禁用每个配置的 hook,包括托管的,并继续运行 Agent SDK 在进程中注册的 hooks
在任何其他设置文件中 : Claude Code 禁用用户、项目、本地和插件 hooks;托管 hooks、Agent SDK hooks 和来自在托管 enabledPlugins 中强制启用的插件的 hooks 继续运行
当托管设置设置此键时保持 Agent SDK hooks 运行需要 Claude Code v2.1.242 或更高版本。
当 hooks 被禁用时,/goal 命令无法运行,/hooks 菜单显示通知而不是您的 hooks。
状态行和文件建议门
Claude Code 为 statusLine、fileSuggestion 和 subagentStatusLine 按此顺序做出两个决定:
在缩小范围下,如果部署了托管值,Claude Code 会运行它。否则它会跳过您的值而不发出警告:状态行被禁用,@ 自动完成回退到内置文件建议。
`disableWorkflows`
关闭 动态工作流 和您的设置所涉及的每个人的捆绑工作流命令,例如通过托管设置的组织。要仅为自己打开或关闭工作流,请改用 enableWorkflows ,这是 /config 中的 动态工作流 切换写入您的用户设置的内容。
{
"disableWorkflows" : true
}
`enableWorkflows`
当您的计划默认值不是您想要的时,为自己打开或关闭 动态工作流 。在 /config 中显示为 动态工作流 ,它将此键写入您的用户设置,并在您切换回计划默认值时再次删除它。要从托管设置为每个人关闭工作流,请改用 disableWorkflows 。
作用域 : 任何文件
类型 : 布尔值
true: Claude Code 为您打开动态工作流
false: Claude Code 为您关闭动态工作流
默认值 : 未设置,因此工作流打开,除非您在 Pro 计划上,其中工作流关闭
每会话覆盖 : CLAUDE_CODE_DISABLE_WORKFLOWS 关闭一个会话的工作流,而 true 在此处无法在设置时将其打开
{
"enableWorkflows" : true
}
disableWorkflows 和您的组织的工作流策略也优先:enableWorkflows: true 在任何源关闭工作流时无法将其打开。当除您的用户设置之外的源设置 enableWorkflows 或将 disableWorkflows 设置为 true 时,Claude Code 隐藏 /config 行。
`hooks`
在 Claude Code 的生命周期中的某些点(例如在工具调用之前或会话启动时)运行您自己的命令、提示、代理、HTTP 请求或 MCP 工具作为 hooks ;hooks 参考 列出每个事件、其有效负载和其退出代码。每个事件映射到匹配器组列表,每个组列出在匹配器应用时运行的处理程序。
作用域 : 任何文件 。Hooks 在文件中合并而不是相互替换,来自托管设置的 hooks 无法从其他文件中删除。
类型 : 由 hook 事件 键入的对象;每个值是 { "matcher", "hooks" } 组的数组,其 hooks 条目的 type 为 "command"、"prompt"、"agent"、"http" 或 "mcp_tool"
默认值 : 未设置,因此没有 hooks 运行
此示例在每个 Bash 工具调用之前运行脚本:
{
"hooks" : {
"PreToolUse" : [
{
"matcher" : "Bash" ,
"hooks" : [
{ "type" : "command" , "command" : "~/.claude/hooks/check-bash.sh" }
]
}
]
}
}
对于每个事件、匹配器模式和处理程序字段,请参阅 hooks 参考 。要关闭 hooks,请参阅 disableAllHooks ;要将 hooks 限制为您的组织部署的 hooks,请参阅 allowManagedHooksOnly 。
`httpHookAllowedEnvVars`
HTTP hook 可以将环境变量的值放入请求标头中,例如 Authorization: Bearer $HOOK_TOKEN 标头,但仅限于 hook 在其自己的 allowedEnvVars 中列出的变量。此键为每个 HTTP hook 的该列表设置外部限制:hook 只能使用变量(如果其自己的 allowedEnvVars 和此键都命名它)。使用它可以防止 hook 读取它不应该读取的秘密,即使 hook 的定义要求它。
作用域 : 任何文件 。数组在设置文件中合并。
类型 : 环境变量名称数组
默认值 : 未设置,因此应用每个 hook 自己的 allowedEnvVars 列表
此示例将标头插值限制为 MY_TOKEN 和 HOOK_SECRET:
{
"httpHookAllowedEnvVars" : [ "MY_TOKEN" , "HOOK_SECRET" ]
}
允许列表适用于来自每个源的 hooks,包括托管设置。
`workflowKeywordTriggerEnabled`
选择在提示中键入关键字 ultracode 是否触发 动态工作流 。将其设置为 false 以在不触发工作流的情况下键入该词。
作用域 : 任何文件 。在 /config 中显示为 Ultracode 关键字触发 。
类型 : 布尔值
true: 在提示中键入 ultracode 触发动态工作流
false: 您可以在不触发工作流的情况下键入该词
默认值 : true
{
"workflowKeywordTriggerEnabled" : false
}
ultracode 工作量设置、/workflows 和保存的工作流命令不受影响。
`workflowSizeGuideline`
设置 Claude 在其编写的动态工作流中针对的代理计数 。Claude Code 将值作为建议而不是强制上限发送给 Claude:"small" 要求少于 5 个代理,"medium" 少于 10 个,"large" 少于 50 个。当您想限制工作流花费的内容时,选择 "small"。需要 Claude Code v2.1.219 或更高版本。
作用域 : 任何文件 。那里的值优先于 /config 中的 动态工作流大小 选择,Claude Code 将其存储在 ~/.claude.json 中,当设置文件设置键时,Claude Code 隐藏该行。
类型 : 字符串,以下之一:
"unrestricted": 无指导,因此 Claude 根据任务调整工作流大小
"small": Claude 针对少于 5 个代理
"medium": Claude 针对少于 10 个代理
"large": Claude 针对少于 50 个代理
默认值 : "medium",或 当您在 Pro 计划上使用 Claude Code v2.1.271 或更高版本登录时为 "small"
{
"workflowSizeGuideline" : "small"
}
需要 Claude Code v2.1.219 或更高版本;在 v2.1.202 到 v2.1.218 上,改为在 /config 中设置指导。
Plugins 和 skills
启用 plugins,注册 marketplaces,限制组织允许的 plugin 源,并控制哪些 skills 加载。有关安装和构建 plugins,请参阅 Plugins 。
`disableBundledSkills`
关闭 Claude Code 附带的 skills 和工作流。Claude Code 完全删除捆绑的 skills 和工作流,而内置命令(如 /init)仍可输入但对模型隐藏。
Scope : Any file
Type : Boolean
true: Claude Code 删除捆绑的 skills 和工作流,并对模型隐藏内置命令(如 /init)
false: 捆绑的 skills 加载
Default : 未设置,因此捆绑的 skills 加载
Per-session overrides : CLAUDE_CODE_DISABLE_BUNDLED_SKILLS 设置为 1 会在一个会话中关闭捆绑的 skills;两者中任何一个关闭它们,另一个就无法将其打开
{
"disableBundledSkills" : true
}
来自 plugins、.claude/skills/ 和 .claude/commands/ 的 skills 不受影响。/doctor 与内置命令一样仍可输入;要隐藏它,请改为设置 DISABLE_DOCTOR_COMMAND 。
`disableSkillShellExecution`
关闭 skills 和来自用户、项目、plugin 或附加目录源的自定义命令中 !`...` 和 ```! 块的内联 shell 执行。Claude Code 用 [shell command execution disabled by policy] 替换每个命令,而不是运行它。
Scope : Any file 。托管设置中的 true 无法被其他地方的 false 覆盖。
Type : Boolean
true: Claude Code 用 [shell command execution disabled by policy] 替换每个内联 shell 命令,而不是运行它
false: 内联 shell 运行
Default : 未设置,因此内联 shell 运行
{
"disableSkillShellExecution" : true
}
捆绑的 skills 和通过托管设置部署的 skills 不受影响。
`skillOverrides`
隐藏或折叠 skill ,无需编辑其 SKILL.md。Claude Code 将每个 skill 名称下的值应用于 Claude 看到的 skill 列表和您的 / 自动完成。
Scope : Any file 。/skills 菜单写入 .claude/settings.local.json。
Type : 对象,将 skill 名称映射到以下之一:
"on": Claude 看到该 skill,您可以输入 /name
"name-only": Claude 按名称看到该 skill,但不显示其描述
"user-invocable-only": Claude 看不到该 skill,但您仍可输入 /name
"off": Claude 看不到该 skill,/name 从自动完成中隐藏
Default : 未设置,因此每个 skill 都是 "on"
此示例仅按名称向 Claude 列出 legacy-context,并从 Claude 和 / 自动完成中隐藏 deploy:
{
"skillOverrides" : {
"legacy-context" : "name-only" ,
"deploy" : "off"
}
}
覆盖不适用于 plugin skills,您可以通过 /plugin 管理这些。
在托管设置和使用 --settings 传递的文件中,捆绑 skill 的别名上的键(如 /doctor 的 checkup)也适用于该 skill;请参阅 别名键如何与 skill 自身名称上的键结合 。
`syncClaudeAiSkills`
关闭 为您的 claude.ai 账户启用的 skills 的下载。Claude Code 在 您使用 claude.ai 账户登录的终端会话 (交互式或非交互式)以及 Cowork 和云会话中将它们下载到 ~/.claude/skills/synced/。设置 false 以停止该下载并停止加载已同步的 skills。Claude Code 仅接受 false:true 与未设置相同,不会在其他情况下关闭的地方打开同步。
Scope : User, local, or managed ,以及使用 --settings 传递的文件。存储库无法为您关闭它。
Type : Boolean
false: Claude Code 停止下载同步的 skills,停止加载 ~/.claude/skills/synced/ 中已有的 skills。在用户或托管设置中,它还将它们移动到 ~/.claude/skills/.trash/
true: 与未设置相同
Default : 未设置,因此使用 claude.ai 账户登录的会话同步您的 skills
此示例防止机器在任何会话中下载账户的 skills:
{
"syncClaudeAiSkills" : false
}
`syncClaudeAiPlugins`
关闭 为您的 claude.ai 账户启用的 plugins 的下载。Claude Code 在您使用 claude.ai 账户登录的终端会话开始时和 Cowork 会话中将它们下载到 ~/.claude/plugins/synced/,并将每个加载为 <name>@synced。设置 false 以停止该下载并停止加载已同步的 plugins。Claude Code 仅接受 false:true 与未设置相同,不会在其他情况下关闭的地方打开同步。需要 Claude Code v2.1.273 或更高版本。
Scope : User, local, or managed ,以及使用 --settings 传递的文件。存储库无法为您关闭它。
Type : Boolean
false: Claude Code 停止下载同步的 plugins,停止加载 ~/.claude/plugins/synced/ 中已有的 plugins。在用户或托管设置中,它还将它们移动到 ~/.claude/plugins/.trash/
true: 与未设置相同
Default : 未设置,因此使用 claude.ai 账户登录的会话同步您的 plugins
要关闭一个同步的 plugin 而不是全部,请在 enabledPlugins 中设置 "<name>@synced": false。
此示例防止机器在任何会话中下载账户的 plugins:
{
"syncClaudeAiPlugins" : false
}
`allowedChannelPlugins`
选择哪些 channel plugins 可以将消息推送到您组织中的会话。设置后,Claude Code 使用您的列表代替默认的 Anthropic 允许列表;每个条目命名一个 plugin 和它来自的 marketplace。
Scope : Managed
Type : 对象数组,每个都有 marketplace 和 plugin 字符串。条目也可以是 "plugin@marketplace" 字符串,如 "telegram@claude-plugins-official",Claude Code 将其视为等效对象。字符串形式需要 Claude Code v2.1.267 或更高版本;更早的版本在 allowedChannelPlugins 包含一个时拒绝整个值
Default : 未设置,因此 Claude Code 使用默认的 Anthropic 允许列表
此示例打开 channels 并仅允许来自官方 Anthropic marketplace 的 Telegram plugin:
{
"channelsEnabled" : true,
"allowedChannelPlugins" : [
{ "marketplace" : "claude-plugins-official" , "plugin" : "telegram" }
]
}
空数组阻止每个 channel plugin。
此键在 channels 通过账户的 channelsEnabled 门控后生效:在 Team 和 Enterprise 计划上,以及在具有托管设置的 Console 账户上,这意味着 channelsEnabled: true。请参阅 限制哪些 channel plugins 可以运行 。
`blockedMarketplaces`
阻止您组织的 plugin marketplace 源。Claude Code 在 marketplace 添加以及 plugin 安装、更新、刷新和自动更新时检查阻止列表,因此在您设置策略之前添加的 marketplace 也无法用于获取 plugins。阻止的源在下载前被检查,因此它们永远不会接触文件系统。
如果您在 claude.ai 管理控制台 中设置此键,claude.ai 也会在您组织中的任何人从 claude.ai 上的 git 存储库添加 marketplace 时应用它,如 限制如何工作 所述。
此示例阻止一个 GitHub 存储库作为 marketplace 源:
{
"blockedMarketplaces" : [
{ "source" : "github" , "repo" : "untrusted/plugins" }
]
}
一个 github 条目可能使用 owner-wildcard 形式 "owner/*" 来阻止该 GitHub owner 下的每个存储库,这需要 Claude Code v2.1.223 或更高版本。添加 { "source": "skills-dir" } 以停止 Claude Code 从 ~/.claude/skills/ 加载 @skills-dir plugins ,而不限制任何 marketplace。请参阅 托管 marketplace 限制 。
`channelsEnabled`
为您的组织允许 channels 。在 claude.ai Team 和 Enterprise 计划上,Claude Code 阻止 channels 直到您将其设置为 true。对于使用 API 密钥进行身份验证的 Anthropic Console 账户,channels 默认被允许。如果您的组织部署托管设置,Claude Code 也会在这些账户上阻止 channels,直到您将此键设置为 true。
Scope : Managed
Type : Boolean
true: Claude Code 为您的组织允许 channels
false: 与未设置相同;channels 是否被阻止取决于您的计划,如默认值所述
Default : 未设置;channels 在 Team 和 Enterprise 计划上以及在具有托管设置的 Console 账户上被阻止,在 Pro 和 Max 计划上以及在没有托管设置的 Console 账户上被允许
{
"channelsEnabled" : true
}
要限制哪些 plugins 可以在启用后注册为 channels,请设置 allowedChannelPlugins 。请参阅 企业控制 。
`disableCommandPluginSources`
阻止 command plugin 源 ,它通过在用户的机器上运行 marketplace 声明的命令来安装 plugin。当您将其设置为 true 时,Claude Code 永远不会运行该命令,不会安装或更新命令源的 plugins,并停止加载已安装的 plugins。设置为 false 以明确允许它们。每当它阻止命令源时,无论您将其设置为 true 还是在 allowManagedHooksOnly 下保持未设置,它也会阻止 marketplace headersHelper 命令 ,除了托管设置本身声明的 marketplace。需要 Claude Code v2.1.229 或更高版本,headersHelper 阻止需要 v2.1.238 或更高版本。
Scope : Managed
Type : Boolean
true: Claude Code 永远不会运行 marketplace 声明的命令,不会安装或更新命令源的 plugins,并停止加载已安装的 plugins
false: Claude Code 明确允许命令源的 plugins
Default : 未设置,因此 Claude Code 遵循 allowManagedHooksOnly :限制 hook 执行到托管设置的组织也会禁用命令源
{
"disableCommandPluginSources" : true
}
需要 Claude Code v2.1.229 或更高版本。
`pluginSuggestionMarketplaces`
命名其 plugins 可以作为上下文安装建议出现的 marketplaces,在 spinner 提示和 /plugin Discover 标签顶部固定。内置的第一方前端设计提示不受影响。建议来自每个 plugin 在其 marketplace 条目中的 relevance 声明。
Scope : Managed
Type : marketplace 名称数组
Default : 未设置,因此没有 marketplace 声明的建议出现
{
"pluginSuggestionMarketplaces" : [ "acme-corp-plugins" ]
}
一个名称仅在 marketplace 在机器上注册且其注册源也在同一托管设置中声明时生效,要么作为该名称的 extraKnownMarketplaces 条目,要么作为 strictKnownMarketplaces 的条目。Claude Code 忽略从不同源注册的 marketplace,即使在允许列表名称下。官方 marketplace 豁免源要求:仅允许列表其名称就足够了,因为该名称只能从官方 Anthropic 源注册。请参阅 按上下文建议 plugins 。
`pluginTrustMessage`
在安装前向 Claude Code 显示的 plugin 信任警告中添加您组织自己的文本,例如确认来自您内部 marketplace 的 plugins 已被审查。
Scope : Managed
Type : 字符串
Default : 未设置,因此 Claude Code 仅显示标准警告
{
"pluginTrustMessage" : "All plugins from our marketplace are approved by IT"
}
`strictKnownMarketplaces`
限制您组织中的人员可以添加和安装 plugins 的 plugin marketplace 源。Claude Code 在 marketplace 添加以及 plugin 安装、更新、刷新和自动更新时强制执行允许列表,在任何网络或文件系统操作之前,因此在您设置策略之前添加的 marketplace 一旦其源不再匹配就无法用于获取 plugins。被阻止的用户会看到一个错误,命名托管策略。
如果您在 claude.ai 管理控制台 中设置此键,claude.ai 也会在您组织中的任何人从 claude.ai 上的 git 存储库添加 marketplace 时应用它,如 限制如何工作 所述。
Scope : Managed
Type : marketplace 源对象数组;请参阅 允许的源类型
Default : 未设置,因此用户可以添加任何 marketplace。空数组是完全锁定,阻止每个 marketplace 源,包括官方 Anthropic marketplace
此示例允许两个 GitHub 存储库,一个固定到 v2.0 ref,一个托管的 marketplace.json URL:
{
"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 键别名 描述 Claude Code 如何处理别名以及哪个版本接受它。此键是一个策略门控:它控制用户可能添加什么,但不注册任何内容。要在一个文件中限制和预注册,请参阅 与 extraKnownMarketplaces 结合 。对于用户面向的视图,请参阅 托管 marketplace 限制 。
允许的源类型
下面每个条目显示每个源类型的一个允许列表条目及其接受的字段。大多数类型精确匹配;hostPattern 和 pathPattern 按正则表达式匹配,github 条目可以使用 owner 通配符 。
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 标头
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 必需,在 marketplace 主机中任何地方匹配的正则表达式;用 ^ 和 $ 锚定它以匹配整个主机
pathPattern
{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
pathPattern 必需,在 file 和 directory 源的 path 中任何地方匹配的正则表达式;用 ^ 开始它以固定前缀
skills-dir
{ "source": "skills-dir" }
无字段。选择 ~/.claude/skills/ plugin 扫描回入
三个源类型有超出表格的规则:
url : URL marketplace 仅下载 marketplace.json 文件,Claude Code 不从该服务器按相对路径获取 plugin 文件,因此其 plugins 必须使用 plugin 源 ,而不是相对路径,如存档 URL,可以在同一主机上。对于具有相对路径的 plugins,请改用基于 Git 的 marketplace。请参阅 URL 基础 marketplaces 中的相对路径 plugins 失败 。
hostPattern : 使用它来允许内部 GitHub Enterprise 或 GitLab 服务器上的每个 marketplace,而无需列出每个存储库。Claude Code 针对 github.com 匹配 github 源,从 url 源获取主机名,从 git 源获取它,取决于 git URL 的形式:
具有方案的 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 : 使用它来允许文件系统 marketplaces 与网络源的 hostPattern 条目一起。".*" 允许每个本地路径;更窄的模式如 "^/opt/approved/" 限制到一个目录。
任何允许列表,即使是空的,也会停止 Claude Code 从 ~/.claude/skills/ 加载 @skills-dir plugins 。添加 { "source": "skills-dir" } 条目以继续加载它们;该条目在此键和 blockedMarketplaces 之外没有意义。
Owner 通配符
一个 github 条目,其 repo 值为 "<owner>/*",匹配该 GitHub owner 下的每个存储库。Owner 通配符需要 Claude Code v2.1.223 或更高版本,仅在 strictKnownMarketplaces 和 blockedMarketplaces 中工作。在 github 源出现的其他地方,如 extraKnownMarketplaces 或 /plugin marketplace add,repo 值必须命名单个存储库。在 v2.1.223 之前,Claude Code 按字面比较条目,因此允许列表条目不匹配任何存储库,阻止列表条目不阻止任何内容;单存储库条目在每个版本上强制执行。
此条目允许 acme-corp 组织下的任何 marketplace 存储库:
{
"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 的条目阻止它匹配的存储库的所有 refs
path
比精确条目规则更宽松:带 path 的条目需要该精确值,而没有的条目匹配存储库内的任何路径
没有 path 的条目阻止它匹配的存储库的所有路径
精确匹配
对于除 owner-wildcard github 条目和正则表达式匹配的 hostPattern 和 pathPattern 条目之外的每个源类型,Claude Code 仅在 marketplace 源与条目精确匹配时允许用户的添加。对于基于 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" }
仅允许官方 marketplace
要仅允许官方 Anthropic marketplace,列出其存储库:
{
"strictKnownMarketplaces" : [
{ "source" : "github" , "repo" : "anthropics/claude-plugins-official" }
]
}
使用此条目,Claude Code 保持已注册的官方 marketplace 可用,在新机器上,在您第一次启动交互式终端会话时自动注册 marketplace。自动注册最常遗漏:
在机器的第一个交互式终端会话之前运行的非交互式环境。
Claude Code 仅通过 VS Code 扩展运行过的机器。
Claude Code 已在阻止 marketplace 的策略下运行过交互式终端会话的机器,如空数组锁定。Claude Code 记录被阻止的尝试,在策略更改后不重试。
在这些机器上,将 marketplace 添加到同一 managed-settings.json 中的 extraKnownMarketplaces ,以便 Claude Code 自动注册它,或运行 claude plugin marketplace add anthropics/claude-plugins-official。
两个键做不同的工作。此表比较它们:
Aspect
strictKnownMarketplaces
extraKnownMarketplaces
Purpose
组织策略执行
团队便利
Settings file
仅托管设置
任何设置文件
Behavior
阻止非允许列表的添加
注册缺失的 marketplaces
When enforced
在网络和文件系统操作之前
立即从用户或托管设置;在存储库文件的工作区信任对话框之后
Can be overridden
否,最高优先级
是,由更高优先级的设置
Source format
直接源对象
具有嵌套 source 对象的命名 marketplace
要为所有用户限制和预注册 marketplace,请在 managed-settings.json 中同时设置两者:
{
"strictKnownMarketplaces" : [
{ "source" : "github" , "repo" : "acme-corp/plugins" }
] ,
"extraKnownMarketplaces" : {
"acme-tools" : {
"source" : { "source" : "github" , "repo" : "acme-corp/plugins" }
}
}
}
仅设置 strictKnownMarketplaces 时,用户仍可以使用 /plugin marketplace add 自己添加允许的 marketplace。官方 Anthropic marketplace 是唯一 Claude Code 自动注册的,仅当允许列表允许时。仅允许官方 marketplace 列出它遗漏的机器。
`strictPluginOnlyCustomization`
阻止 skills、agents、hooks 和 MCP 服务器来自用户和项目源,因此它们只能来自 plugins 或托管设置。将其与 strictKnownMarketplaces 结合以控制完整的自定义供应链:marketplace 允许列表控制用户可以安装哪些 plugins。
Scope : Managed
Type : true 以锁定所有四种自定义,或一个数组命名要锁定的种类,来自 "skills"、"agents"、"hooks" 和 "mcp"
Default : 未设置,因此没有被锁定
此示例锁定 skills 和 hooks,保留 agents 和 MCP 服务器解锁:
{
"strictPluginOnlyCustomization" : [ "skills" , "hooks" ]
}
下面的四个子键条目列出每个表面阻止什么以及什么仍然加载。Claude Code 忽略它不识别的表面名称,而不是使设置文件失败,因此您可以在每个客户端更新之前添加新的表面名称。
`strictPluginOnlyCustomization.skills`
锁定 skills 表面。Claude Code 停止从 ~/.claude/skills/ 和 .claude/skills/ 加载 skills,从 ~/.claude/commands/ 和 .claude/commands/ 加载自定义命令,从 --add-dir 目录加载 skills,从您的 claude.ai 账户同步的 skills,并继续加载 plugin skills、捆绑的 skills 和托管策略目录中的 skills。
{
"strictPluginOnlyCustomization" : [ "skills" ]
}
`strictPluginOnlyCustomization.agents`
锁定 agents 表面。Claude Code 停止从 ~/.claude/agents/ 和 .claude/agents/ 加载 agents,并继续加载 plugin agents、内置 agents 和托管策略目录中的 agents。
{
"strictPluginOnlyCustomization" : [ "agents" ]
}
`strictPluginOnlyCustomization.hooks`
锁定 hooks 表面。Claude Code 停止运行来自用户、项目和本地 settings.json 的 hooks,并继续运行 plugin hooks 和托管设置中的 hooks。
{
"strictPluginOnlyCustomization" : [ "hooks" ]
}
`strictPluginOnlyCustomization.mcp`
锁定 mcp 表面。Claude Code 停止从 ~/.claude.json 和 .mcp.json 加载 MCP 服务器,并继续加载 plugin MCP 服务器、managed-mcp.json 服务器和来自 managedMcpServers 的服务器。
{
"strictPluginOnlyCustomization" : [ "mcp" ]
}
`enabledPlugins`
打开或关闭单个 plugins ,由 plugin-name@marketplace-name 键控。在任何范围内没有条目的 plugin 回退到其 defaultEnabled 值。当您使用 /plugin 或 claude plugin enable 启用或禁用 plugin 时,Claude Code 为您写入此键。
Scope : Any file
Type : 对象,将 plugin-name@marketplace-name 映射到 Boolean
Default : 未设置,因此每个 plugin 遵循其 defaultEnabled 值
此示例启用来自 team-tools marketplace 的两个 plugins,禁用来自 personal 的一个:
{
"enabledPlugins" : {
"code-formatter@team-tools" : true,
"deployment-tools@team-tools" : true,
"experimental-features@personal" : false
}
}
每个范围服务不同的目的:
User settings : 您的个人 plugin 偏好
Project settings : 与存储库中的每个人共享的 plugins
Local settings : 每台机器的覆盖,当 Claude Code 在那里保存设置时被 gitignored
Managed settings : 组织范围的策略。设置为 false 的 plugin 在每个范围都被阻止安装,并从 marketplace 隐藏
项目设置优先于用户设置,因此在 ~/.claude/settings.json 中将 plugin 设置为 false 不会禁用项目的 .claude/settings.json 启用的 plugin。要在您的机器上选择退出项目启用的 plugin,请改为在 .claude/settings.local.json 中将其设置为 false。由托管设置强制启用的 Plugins 无法以这种方式禁用,因为托管设置覆盖本地设置。
在项目的 .claude/settings.json 中启用来自外部源(如 GitHub 存储库或 npm 包)的 plugin 不会为其他人安装它。在加载 plugins 的每条路径上,Claude Code 报告 plugin 未安装,直到每个用户 自己安装它 。
按名称注册其他 plugin marketplaces,以便打开存储库的人或您的托管设置到达的每个人都获得 marketplace,而无需自己添加它。Claude Code 注册它还不知道的每个 marketplace。enabledPlugins 从它命名的 plugin 是否安装取决于 plugin 的源和哪个文件启用它;该条目有规则。
Scope : Any file 。Claude Code 仅在您接受该文件夹的工作区信任对话框后才接受存储库的 .claude/settings.json 或 .claude/settings.local.json 中的条目;在您未信任的文件夹中,包括 -p 运行,它在没有消息的情况下忽略它们。
Type : 对象,将 marketplace 名称映射到具有 source 对象和可选 autoUpdate Boolean 的对象
Default : 未设置
此示例注册一个 GitHub marketplace 和来自自托管 git URL 的 marketplace:
{
"extraKnownMarketplaces" : {
"acme-tools" : {
"source" : {
"source" : "github" ,
"repo" : "acme-corp/claude-plugins"
}
} ,
"security-plugins" : {
"source" : {
"source" : "git" ,
"url" : "https://git.example.com/security/plugins.git"
}
}
}
}
在您信任文件夹之前运行什么 将信任门与存储库可以提供的其他内容进行比较。您也可以将此键写为 additionalMarketplaces;请参阅 Marketplace 键别名 。
设置 "autoUpdate": true 与 source 一起,使 Claude Code 在启动后在后台刷新该 marketplace 并更新其已安装的 plugins。省略时,claude-plugins-official 和大多数其他官方 Anthropic marketplaces 默认为 true,第三方 marketplaces 默认为 false。请参阅 配置自动更新 。
当多个设置文件在同一名称下定义 marketplace 条目时,Claude Code 使用来自 最高优先级文件 的条目。该条目替换较低优先级的条目,不继承其任何字段,因此重新定义无法将一个文件的 source.headers 凭证与另一个文件控制的 URL 结合。在 v2.1.228 之前,Claude Code 逐字段合并同名条目,因此较高优先级文件中的条目可以继承它未设置的字段,包括另一个文件的 headers。
Marketplace 源类型
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 : 直接在设置文件中声明的内联 marketplace,不带托管存储库,带 name 和 plugins
git 源类型适用于任何 git 托管服务,包括自托管 GitLab 和 Bitbucket。Claude Code 使用 git clone 在该机器上使用的相同身份验证克隆存储库:配置的凭证助手或 SSH 密钥。提供者令牌如 GITHUB_TOKEN 通过读取它的凭证助手生效。请参阅 私有存储库 了解设置详情。
对于 github 和 git 源,Claude Code 在克隆 marketplace 存储库以添加或更新它时永远不会下载 Git LFS 内容。LFS 跟踪的文件被检出为指针文件,添加或更新输出报告有多少。
source 对象内的 skipLfs 字段被接受且没有效果。在 v2.1.274 之前,Claude Code 下载 LFS 内容,除非您设置 "skipLfs": true。
对于 url 源,当 headers 中的凭证过期且命令必须生成新凭证时,在 source 对象内设置 headersHelper。需要 Claude Code v2.1.238 或更高版本。对于命令必须打印的内容以及 Claude Code 运行它的位置,请参阅 编写 headersHelper 命令 ,对于 Claude Code 不运行它的情况,请参阅 当 Claude Code 跳过 headersHelper 命令或丢弃其输出时 。一旦您在 https:// marketplace URL 上设置 headersHelper,Claude Code 在两个点运行命令,重用一次运行的输出长达 60 秒:
在该 marketplace 的 marketplace.json 的每次获取之前,包括稍后的刷新。Claude Code 使用该获取发送打印的标头。
在 marketplace URL 的源上的每个 plugin 存档下载之前,意味着相同的方案、主机和端口。Claude Code 使用该下载发送输出,没有其他下载获得标头。
Claude Code 忽略在您使用 --add-dir 添加的目录的 .claude/settings.json 或 .claude/settings.local.json 中设置的任何 headersHelper,在 url 源和内联 plugin 条目上,仅发送在该文件中设置的固定 headers。用户如何接受 headersHelper 命令 涵盖其他设置文件。
在 settings 源中列出的 Plugins 必须引用外部源如 GitHub 或 npm,name 必须与 marketplace 键匹配。您仍然在 enabledPlugins 中单独启用每个 plugin。此示例声明一个 plugin 内联:
{
"extraKnownMarketplaces" : {
"team-tools" : {
"source" : {
"source" : "settings" ,
"name" : "team-tools" ,
"plugins" : [
{
"name" : "code-formatter" ,
"source" : {
"source" : "github" ,
"repo" : "acme-corp/code-formatter"
}
}
]
}
}
}
}
在 source: 'settings' 下的 plugin 条目,其自身 source 是 archive 的,可以为存档下载设置 headers。如果您想放在 headers 中的值是短暂的,如您的注册表按请求铸造的令牌,请改为设置 headersHelper 命令。条目可以同时设置两者。两个字段都需要 Claude Code v2.1.238 或更高版本。
Claude Code 发送条目的 headers 和命令打印的任何内容,与该 plugin 的存档下载一起,没有其他下载。Claude Code 仅在用户 自己安装或更新该一个 plugin 时运行命令。三个进一步的规则取决于哪个文件持有条目:
strict : 与 marketplace 的 marketplace.json 中的条目不同,设置文件中的条目不需要 "strict": false,因为设置文件不携带要内联的清单字段。请参阅 严格模式 。
Folder trust : 对于项目的 .claude/settings.json 或 .claude/settings.local.json 中的条目,Claude Code 仅在用户也 信任该文件夹 后运行命令。
Header filter : Claude Code 从项目的 .claude/settings.json 或 .claude/settings.local.json 中的条目删除 请求路由和客户端身份标头名称 ,因为存储库可以提供这些文件。Claude Code 对目录条目和 --add-dir 目录的设置中的条目应用相同的过滤器,对您的用户设置、--settings 文件或托管设置中的条目不应用过滤器。
Marketplace 键别名
在 Claude Code v2.1.232 或更高版本上,您可以将 extraKnownMarketplaces 写为 additionalMarketplaces,将 strictKnownMarketplaces 写为 allowedMarketplaces。Claude Code 按如下方式处理每个别名:
更早的版本忽略别名,因此在较旧版本也读取的文件中保持规范拼写,如具有混合 Claude Code 版本的队伍的托管设置文件。
在接受规范键的任何设置文件中,Claude Code 完全按照读取规范键的方式读取别名。
Claude Code 可能在更新文件时将 additionalMarketplaces 重写为 extraKnownMarketplaces。
如果您在一个文件中同时设置两个拼写,Claude Code 使用规范值并忽略别名。
`pluginConfigs`
存储您给 plugin 的 userConfig 配置对话框的非敏感答案,由 plugin ID 键控。当您填写对话框时,Claude Code 将此键写入您的用户设置,因此您无需手动编辑它。Claude Code 将敏感选项存储在 macOS Keychain 中,当 Keychain 拒绝写入时回退到 ~/.claude/.credentials.json;在没有支持的 keychain 的平台上,它将它们存储在 ~/.claude/.credentials.json 中。
Scope : User or managed
Type : 对象,将 plugin ID 映射到具有 options 字段的对象,将每个选项名称映射到字符串、数字、Boolean 或字符串数组,以及可选的 mcpServers 字段,以相同形状保存每个服务器的用户配置值
Default : 未设置
此示例为来自 acme-tools 的 deployer plugin 存储 api_endpoint 选项:
{
"pluginConfigs" : {
"deployer@acme-tools" : {
"options" : {
"api_endpoint" : "https://api.example.com"
}
}
}
}
内置 plugins 在同一键下存储其选项,带 @builtin 后缀。例如,控制 Claude Code 是否读取 AGENTS.md 文件的 Project instructions 设置是 pluginConfigs["agents-md@builtin"].options.instructionFiles。
Claude Code 忽略项目和本地条目,因为它将这些值替换到 plugin hook、MCP 和 LSP 配置中,克隆的存储库不得能够提供它们。在 v2.1.207 之前,项目和本地设置也被读取。
MCP
控制 Claude Code 连接到哪些 MCP 服务器以及组织允许哪些服务器。请参阅使用 MCP 连接到外部工具 和托管 MCP 配置 。
`allowAllClaudeAiMcps`
加载 claude.ai 连接器 ,Claude Code 会在部署的 managed-mcp.json 旁边自行获取这些连接器。如果没有此密钥,managed-mcp.json 将对 MCP 服务器拥有独占控制权并禁止这些连接器。
作用域 : Managed 。用户无法重新启用独占控制禁止的连接器。
类型 : 布尔值
true: Claude Code 在部署的 managed-mcp.json 旁边加载 claude.ai 连接器
false: 部署的 managed-mcp.json 对 MCP 服务器拥有独占控制权并禁止 claude.ai 连接器 Claude Code 自行获取
默认值 : false,因此部署的 managed-mcp.json 会禁止 Claude Code 自行获取的 claude.ai 连接器
{
"allowAllClaudeAiMcps" : true
}
allowedMcpServers 和 deniedMcpServers 仍然适用于此密钥加载的连接器。传递到云会话 的连接器,其主机携带 managed-mcp.json(例如自托管运行器),仍然会被禁止。请参阅在托管集合旁边允许 claude.ai 连接器 。
`allowedMcpServers`
允许列表化人们可以添加的 MCP 服务器。Claude Code 会阻止任何不匹配条目的服务器,无论在何处定义,包括插件服务器、使用 --mcp-config 传递的服务器以及来自 claude.ai 的服务器。
内置服务器(例如 Chrome 中的 Claude、Claude Code 在运行的 VS Code 或 JetBrains IDE 中连接的 ide 服务器,以及 CLI 本身配置的服务器)不受允许列表的限制,拒绝列表仍然适用于它们。进程内 type: "sdk" 服务器不受两个列表的限制;启动会话的应用 会注册它们。
您的组织提供的服务器也不受允许列表的限制,拒绝列表仍然适用于它们。豁免涵盖每个 managedMcpServers 条目,以及任何 managed-mcp.json 条目,其值不使用 ${VAR} 扩展。有关完整的检查顺序,请参阅如何评估服务器 。在 v2.1.259 之前,来自 managed-mcp.json 的服务器也必须匹配。
作用域 : Any file 。来自每个文件的条目合并为一个允许列表,除非设置了 allowManagedMcpServersOnly 。在托管设置中部署它以强制执行。
类型 : 对象数组,每个对象恰好有一个密钥:serverName,一个限制为字母、数字、连字符和下划线的字符串;serverCommand,一个与命令及其参数完全匹配的数组;或 serverUrl,一个带有 * 通配符的 URL 模式
默认值 : 未设置,因此允许每个服务器;空数组会阻止用户添加的每个服务器
此示例仅允许列出的 npx 命令启动的 stdio 服务器:
{
"allowedMcpServers" : [
{ "serverCommand" : [ "npx" , "-y" , "@modelcontextprotocol/server-filesystem" ] }
]
}
deniedMcpServers 条目优先,因此同时在两个列表中的服务器会被阻止。一旦列表包含任何 serverCommand 条目,stdio 服务器必须匹配 serverCommand 条目,一旦它包含任何 serverUrl 条目,远程服务器必须匹配 serverUrl 条目:serverName 匹配不再允许该类型的服务器。请参阅使用允许列表和拒绝列表进行基于策略的控制 。
`allowManagedMcpServersOnly`
使托管允许列表成为唯一适用的列表。Claude Code 随后仅从托管设置中读取 allowedMcpServers ,并忽略用户、项目和本地设置中的允许列表;deniedMcpServers 仍然从每个设置作用域合并,因此用户仍然可以为自己阻止服务器。管理员设置它,以便用户自己的设置无法扩展托管允许列表允许的内容。
作用域 : Managed
类型 : 布尔值
true: Claude Code 仅从托管设置中读取 allowedMcpServers,并忽略用户、项目和本地设置中的允许列表
false: 来自每个设置作用域的允许列表合并
默认值 : false,因此来自每个设置作用域的允许列表合并
此示例将允许列表锁定到托管设置,并仅允许名为 github 的服务器:
{
"allowManagedMcpServersOnly" : true,
"allowedMcpServers" : [
{ "serverName" : "github" }
]
}
用户仍然可以添加自己的 MCP 服务器;只有与托管允许列表匹配的服务器才会加载。请参阅将允许列表限制为仅托管设置 。
`deniedMcpServers`
阻止特定的 MCP 服务器。Claude Code 拒绝加载匹配的服务器,无论在何处定义,包括插件服务器、使用 --mcp-config 传递的服务器、来自 managed-mcp.json 的服务器、来自 managedMcpServers 的服务器,以及 它自行获取 的 claude.ai 连接器。进程内 type: "sdk" 服务器不受限制;启动会话的应用会注册它们。
作用域 : Any file 。来自每个文件的条目合并为一个拒绝列表,allowManagedMcpServersOnly 不会改变这一点。在托管设置中部署它以强制执行。
类型 : 对象数组,每个对象恰好有一个密钥:serverName,一个字符串,因此 claude.ai 连接器的显示名称(例如 "claude.ai Slack")有效;serverCommand,一个与命令及其参数完全匹配的数组;或 serverUrl,一个带有 * 通配符的 URL 模式
默认值 : 未设置,因此不阻止任何服务器;空数组也不阻止任何内容
{
"deniedMcpServers" : [
{ "serverName" : "filesystem" }
]
}
拒绝列表优先于 allowedMcpServers ,因此同时在两个列表中的服务器会被阻止。请参阅使用允许列表和拒绝列表进行基于策略的控制 。
`disableClaudeAiConnectors`
关闭 claude.ai MCP 连接器 Claude Code 自行获取 ,因此它既不获取也不连接它们。任何设置文件中的 true 都适用:签入的项目 .claude/settings.json 可以选择退出存储库中的这些连接器,但项目级别的 false 无法覆盖用户级别或托管级别的 true。
作用域 : Any file
类型 : 布尔值
true: Claude Code 既不获取也不连接这些连接器
false: 与未设置相同;Claude Code 获取您的连接器,除非另一个设置文件或 ENABLE_CLAUDEAI_MCP_SERVERS 关闭它们
默认值 : false,因此 Claude Code 获取您的连接器
每会话覆盖 : ENABLE_CLAUDEAI_MCP_SERVERS 设置为 false 会为一个会话关闭连接器;无论两者中哪一个关闭它们,另一个都无法将其打开
{
"disableClaudeAiConnectors" : true
}
您使用 --mcp-config 显式传递的服务器不受影响。要阻止单个连接器而不是全部,请使用 deniedMcpServers 。请参阅禁用 claude.ai 连接器 。
`disabledMcpjsonServers`
拒绝项目 .mcp.json 文件中定义的特定服务器,以便 Claude Code 永远不会连接它们或要求您批准它们。任何设置文件中的拒绝都适用,包括签入存储库的项目 .claude/settings.json。
作用域 : Any file
类型 : 字符串数组,服务器名称如 .mcp.json 中所示
默认值 : 未设置
{
"disabledMcpjsonServers" : [ "filesystem" ]
}
当您在批准对话框中拒绝服务器时,Claude Code 会将此密钥写入 .claude/settings.local.json。claude mcp get <name> 将被拒绝的服务器显示为 ✘ Rejected (see disabledMcpjsonServers in settings)。拒绝优先于 enabledMcpjsonServers 和 enableAllProjectMcpServers 。
`enableAllProjectMcpServers`
批准项目 .mcp.json 文件中定义的每个 MCP 服务器,无需提示。当您在批准对话框中选择批准所有服务器时,Claude Code 会将此密钥写入 .claude/settings.local.json。
作用域 : Any file 。在您尚未接受信任对话框的文件夹中,Claude Code 从用户设置、托管设置和 --settings 中遵守它,并在共享项目文件中忽略它,包括在会话中以及 claude mcp list 和 claude mcp get;项目服务器批准和工作区信任 说明何时未跟踪的 .claude/settings.local.json 也计数。
类型 : 布尔值
true: Claude Code 批准项目 .mcp.json 文件中定义的每个 MCP 服务器,无需提示
false: Claude Code 要求您批准每个服务器。在受信任的文件夹中,较高优先级文件中的 false 会覆盖较低优先级文件中的 true;在您尚未信任的文件夹中,任何受尊重文件中的 true 就足够了
默认值 : 未设置,因此 Claude Code 要求您批准每个服务器
{
"enableAllProjectMcpServers" : true
}
disabledMcpjsonServers 条目仍然会拒绝服务器。
`enabledMcpjsonServers`
批准项目 .mcp.json 文件中定义的特定服务器,以便 Claude Code 连接它们而无需询问。当您在批准对话框中批准服务器时,Claude Code 会将此密钥写入 .claude/settings.local.json。
作用域 : Any file 。在您尚未接受信任对话框的文件夹中,Claude Code 从用户设置、托管设置和 --settings 中遵守它,并在共享项目文件中忽略它,包括在会话中以及 claude mcp list 和 claude mcp get;项目服务器批准和工作区信任 说明何时未跟踪的 .claude/settings.local.json 也计数。
类型 : 字符串数组,服务器名称如 .mcp.json 中所示
默认值 : 未设置
此示例批准项目 .mcp.json 中的 memory 和 github 服务器:
{
"enabledMcpjsonServers" : [ "memory" , "github" ]
}
disabledMcpjsonServers 条目仍然会拒绝服务器。
`managedMcpServers`
从托管设置向每个用户提供远程 MCP 服务器。用户保留他们自己添加的服务器,无法编辑或删除您提供的服务器。需要 Claude Code v2.1.259 或更高版本。
作用域 : Managed 。Claude Code 在用户、项目和本地设置中使用警告删除该密钥,并且不在 Claude Desktop 应用的代码选项卡中读取它(在第三方部署上)或在应用的 Cowork 会话中读取它,其中 Claude Desktop 提供并锁定这些会话的 MCP 服务器。
类型 : 按服务器名称键入的对象。每个条目都具有 http 或 sse 服务器的 .mcp.json 形状:必需的 https:// url,以及可选的 headers、oauth 和其他 HTTP 和 SSE 选项。Claude Code 删除验证失败的条目,条目可以包含的内容 列出了条件
默认值 : 未设置,因此托管设置不提供任何服务器
此示例提供一个名为 search 的 HTTP 服务器:
{
"managedMcpServers" : {
"search" : {
"type" : "http" ,
"url" : "https://search.example.com/mcp"
}
}
}
有关优先级、提供的服务器如何与 managed-mcp.json 以及允许和拒绝列表结合、用户看到的内容,请参阅通过托管设置提供服务器 。
代理、会话和工作树
设置默认代理、控制团队成员和跨会话消息传递,以及配置工作树。请参阅 Subagents 和 Worktrees 。
`agent`
将主线程作为命名的 subagent 运行,以便 Claude Code 将该 subagent 的系统提示、工具限制和模型应用于您的会话。同一密钥为从 claude agents 分派的会话设置默认代理。
Scope : Any file
Type : string,内置或自定义代理的名称
Default : 未设置,因此主线程作为 Claude Code 的默认代理运行
Per-session overrides : --agent 对一个会话的优先级高于此密钥
{
"agent" : "code-reviewer"
}
插件自己的 settings.json 也可以提供此密钥;请参阅 Ship default settings with your plugin 。
`crossSessionInbound`
选择此会话如何处理 来自您其他 Claude Code 会话的消息 。当没有值适用时,Claude Code 根据两个会话的权限模式类从每条消息中决定。需要 Claude Code v2.1.224 或更高版本。
Scope : Any file 。项目或本地值仅在严格于托管设置、--settings 标志或用户设置提供的值时才适用。
Type : string,以下之一:
"accept": Claude Code 将消息传递给 Claude
"hold": Claude Code 显示消息通知而不传递它
"refuse": Claude Code 丢弃消息
Default : 未设置,因此 Claude Code 从每条消息中决定
{
"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 当您设置它无法识别的值时。当该值存在于用户、项目、本地或 --settings 文件中时,Claude Code 会保留入站消息,即使优先级更高的源设置 accept。另一个源设置的 refuse 仍然适用。修复或删除该值以清除保留。
当无法识别的值在 managed settings 中时,Claude Code 改为将其视为 refuse,直到管理员修复它。在 v2.1.248 之前,Claude Code 忽略无法识别的值而不发出警告。
`disableAgentView`
关闭 background agents and agent view :claude agents、--bg、/background 和按需主管。在 managed settings 中设置它以为组织强制执行。
Scope : Any file
Type : Boolean
true: Claude Code 关闭 claude agents、--bg、/background 和按需主管
false: agent view 可用
Default : 未设置,因此 agent view 可用
Per-session overrides : CLAUDE_CODE_DISABLE_AGENT_VIEW 为一个会话关闭 agent view;无论两者中哪一个关闭它,另一个都无法将其打开
{
"disableAgentView" : true
}
`isolatePeerMachines`
在 Claude 的 SendMessage 到达此机器之外的您的会话之前,需要您的明确批准;请参阅 Require approval for cross-machine messages 。即使在 bypassPermissions mode 中,批准提示也会出现。
Scope : Any file 。来自任何范围的 true 都适用,因此签入的项目文件可以打开要求但不能关闭。
Type : Boolean
true: Claude Code 在 Claude 的 SendMessage 到达此机器之外的您的会话之前要求您的批准
false: 跨机器消息不提示
Default : 未设置,因此跨机器消息不提示
{
"isolatePeerMachines" : true
}
跨机器 SendMessage 批准需要 Claude Code v2.1.224 或更高版本。
`processWrapper`
在 macOS 和 Linux 上,在 Claude Code 启动的后台进程 前面放置公司启动器命令。Claude Code 使用其自己的命令行附加运行启动器,因此启动器必须执行到 Claude Code;请参阅 Run Claude Code behind a corporate launcher 了解启动器合约。需要 Claude Code v2.1.210 或更高版本。
{
"processWrapper" : "/opt/corp/launcher --profile claude"
}
Claude Code 在 Windows 上忽略启动器并启动每个进程不包装。需要 Claude Code v2.1.210 或更高版本。
`teammateMode`
选择 Claude Code 显示 agent team 队友的位置:在您的主终端窗格内,或在您的终端支持时在分割窗格中。请参阅 Choose a display mode 。
Scope : Any file 。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 对此密钥的一个会话优先级更高
{
"teammateMode" : "auto"
}
iterm2 值需要 Claude Code v2.1.186 或更高版本。
`worktree`
配置 Claude Code 如何为 --worktree、EnterWorktree 工具以及隔离的 subagents 和后台会话创建和管理 git worktrees 。
Scope : Any file
Type : object with baseRef, symlinkDirectories, sparsePaths, and bgIsolation
Default : 未设置
此示例从您当前的 HEAD 分支新工作树,并将 node_modules 符号链接到每个工作树中:
{
"worktree" : {
"baseRef" : "head" ,
"symlinkDirectories" : [ "node_modules" ]
}
}
要将 gitignored 文件(如 .env)复制到新工作树中,请改为在项目根目录中添加 .worktreeinclude file ,而不是设置。
`worktree.baseRef`
选择新工作树从哪个 ref 分支。"fresh" 从 origin/<default-branch> 分支以获得与远程匹配的干净树;"head" 从您当前的本地 HEAD 分支,因此未推送的提交和功能分支状态存在于工作树中。
Scope : Any file
Type : string,以下之一:
"fresh": 新工作树从 origin/<default-branch> 分支
"head": 新工作树从您当前的本地 HEAD 分支,包括未推送的提交
Default : "fresh"
{
"worktree" : {
"baseRef" : "head"
}
}
在链接的工作树内,"head" 解析为该工作树的 HEAD,而不是主检出的。
`worktree.symlinkDirectories`
将目录从主存储库符号链接到每个工作树中,以便您不会在磁盘上复制大型目录。
Scope : Any file
Type : array of strings,相对于存储库根目录的目录路径
Default : 未设置,因此 Claude Code 不符号链接任何目录
此示例将 node_modules 和 .cache 从主存储库符号链接到每个新工作树中:
{
"worktree" : {
"symlinkDirectories" : [ "node_modules" , ".cache" ]
}
}
`worktree.sparsePaths`
通过 git sparse-checkout 在每个工作树中仅检出列出的目录。Claude Code 仅将这些目录加上根级文件写入磁盘,这在大型 monorepos 中更快;请参阅 Check out only the directories you need 。
Scope : Any file
Type : array of strings,相对于存储库根目录的目录路径
Default : 未设置,因此每个工作树检出整个树
此示例在每个工作树中仅检出 packages/my-app 和 shared/utils,加上根级文件:
{
"worktree" : {
"sparsePaths" : [ "packages/my-app" , "shared/utils" ]
}
}
当稀疏工作树存在时,git 在存储库的共享 .git/config 中启用 extensions.worktreeConfig。
`worktree.bgIsolation`
选择 background sessions 如何隔离其文件编辑。使用 "worktree",Claude Code 在会话调用 EnterWorktree 之前阻止主检出中的 Edit 和 Write;使用 "none",后台作业直接编辑工作副本。对于 git worktrees 不切实际的存储库,设置 "none"。
Scope : Any file
Type : string,以下之一:
"worktree": Claude Code 在会话调用 EnterWorktree 之前阻止主检出中的 Edit 和 Write
"none": 后台作业直接编辑工作副本
Default : "worktree"
{
"worktree" : {
"bgIsolation" : "none"
}
}
在 git 存储库之外,失败的 WorktreeCreate hook 释放块,以便会话可以就地编辑工作目录;该释放需要 Claude Code v2.1.203 或更高版本。
远程、桌面和通知
配置远程控制、云环境、桌面应用和 Claude Code 在需要你时发送的通知。请参阅远程控制 。
`agentPushNotifEnabled`
允许 Claude 在认为值得发送时向你的手机发送推送通知,例如当长任务完成时。Claude Code 将此选择同步到你的账户,推送在远程控制 连接时到达。在 /config 中显示为Claude 决定时推送 。
作用域 : 任何文件 。Claude Code 也会读取由旧版本留在 ~/.claude.json 中的值。
类型 : 布尔值
true: Claude 可以在认为值得时向你的手机发送推送通知
false: Claude 不发送这些通知
默认值 : false
{
"agentPushNotifEnabled" : true
}
请参阅移动推送通知 。
`awaySummaryEnabled`
当你离开终端几分钟后返回时,显示一行会话摘要。将其设置为 false,或在 /config 中关闭会话摘要 ,以停止摘要。
{
"awaySummaryEnabled" : false
}
Claude Code 在非交互模式下永远不会显示摘要。
`disableArtifact`
改用 enableArtifact 来关闭 Artifact 工具,该工具将会话输出发布为 claude.ai 上的私有网页。当你在 /config 中关闭Artifacts 行时,Claude Code 会将 enableArtifact 写入你的用户设置并清除此键。
作用域 : 任何文件
类型 : 布尔值
true: Claude Code 为该文件适用的每个会话关闭 Artifact 工具,且没有其他文件将其打开。在 v2.1.242 之前,优先级较高的文件可能会覆盖较低文件的 true,而不是该键充当锁定
false: 被忽略;要保持工具打开,请删除该键
默认值 : 未设置,因此工具遵循你账户的可用性
每个会话的覆盖 : CLAUDE_CODE_DISABLE_ARTIFACT 设置为 1 会为一个会话关闭工具
{
"disableArtifact" : true
}
禁用 artifacts 列出了关闭工具的每种方式。
`disableDeepLinkRegistration`
阻止 Claude Code 向操作系统注册 claude-cli:// 协议处理程序,否则在你发送交互式会话的第一个提示后会进行注册。深链接 允许外部工具使用预填充的提示打开 Claude Code 会话。在协议处理程序注册受限或单独管理的环境中设置此项。
作用域 : 任何文件
类型 : 字符串 "disable"
默认值 : 未设置,因此 Claude Code 注册处理程序
{
"disableDeepLinkRegistration" : "disable"
}
`disableDesktopLocalSessions`
在桌面应用 中关闭在设备上运行的 Code 会话,用于开发人员应该通过 SSH 在远程机器上工作的部署。在 Code 选项卡中,本地 环境保留在环境下拉列表中,但呈灰显状态且无法选择,工具提示显示你的组织已关闭它;在 Windows 上,WSL 条目以相同方式呈灰显,尽管 WSL 会话是否在托管设备上运行由单独管理 。新会话默认为第一个SSH 连接 (如果已配置),应用拒绝在设备上启动或恢复会话,包括返回同一机器的 SSH 连接。到其他主机的 SSH 会话和云会话不受影响。桌面应用读取此键;终端 CLI 忽略它。需要 Claude Desktop v1.37937.0 或更高版本。
作用域 : 托管
类型 : 布尔值;仅 JSON 布尔值 true 生效
true: 桌面应用不提供设备上的 Code 会话;现有本地会话保留在列表中但无法继续
false: 本地会话保持可用
默认值 : 未设置,因此本地会话可用
{
"disableDesktopLocalSessions" : true
}
桌面应用忽略任何其他值,非布尔值(如字符串 "true" 或 1)也会记录警告。将其与 sshConfigs 配对,以便用户登陆到工作连接,并与 sshHostAllowlist 配对以限制他们可以访问的主机。请参阅托管设备上的本地会话 。
Claude Desktop 为 Code 会话提供从你的桌面配置派生的策略,例如出口允许列表、文件系统沙箱和第三方部署中的 MCP 限制。每当存在管理员源 时,Claude Code 忽略这些父设置:服务器管理的设置、MDM 或操作系统级别的策略或托管设置文件。通过其中一个在之前没有的设备上部署此键(如在第三方部署中),因此会停止桌面派生的策略应用。让嵌入主机添加策略 涵盖了父设置何时仍可合并;这适用于你以这种方式部署的任何键,不仅仅是这个。
`disableRemoteControl`
关闭远程控制 :Claude Code 随后拒绝 claude remote-control、--remote-control 标志、自动启动和会话内切换,并报告你的组织的策略已禁用它。将其放在托管设置 中以进行每个设备的 MDM 强制执行。
作用域 : 任何文件
类型 : 布尔值
true: Claude Code 拒绝 claude remote-control、--remote-control 标志、自动启动和会话内切换
false: 远程控制保持可用
默认值 : false
{
"disableRemoteControl" : true
}
`enableArtifact`
关闭 Artifact 工具,该工具将会话输出发布为 claude.ai 上的私有网页。当你在 /config 中关闭Artifacts 行时,Claude Code 会将此键写入你的用户设置,因此你通常不需要手动编辑它。需要 Claude Code v2.1.196 或更高版本。
作用域 : 任何文件 。每个文件都可以关闭工具,但没有文件可以将其打开。
类型 : 布尔值
默认值 : 未设置,因此工具遵循你账户的可用性
{
"enableArtifact" : false
}
当除你自己的用户设置之外的源保持工具关闭时,Claude Code 在 /config 中隐藏Artifacts 行,因为在那里打开它不会改变任何东西。禁用 artifacts 列出了关闭工具的每种方式。在 v2.1.242 之前,Claude Code 在项目和本地设置中忽略此键,优先级堆栈 中较高的文件可能会在较低文件的关闭上打开工具。
当权限提示或问题等待你的输入时,在你的手机上获得推送通知。Claude Code 仅在远程控制 连接时发送这些通知。在 /config 中显示为需要操作时推送 。
作用域 : 任何文件 。Claude Code 也会读取由旧版本留在 ~/.claude.json 中的值。
类型 : 布尔值
true: 当权限提示或问题等待时,你会在手机上获得推送通知,同时远程控制已连接
false: Claude Code 不发送此类通知
默认值 : false
{
"inputNeededNotifEnabled" : true
}
请参阅移动推送通知 。
`preferredNotifChannel`
选择 Claude Code 在任务完成或权限提示等待时如何通知你。在 /config 中显示为本地通知 。
作用域 : 任何文件 。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"
{
"preferredNotifChannel" : "terminal_bell"
}
使用 "auto" 时,Claude Code 在 iTerm2、Ghostty 和 Kitty 中发送桌面通知。在 Terminal.app 中,仅当你关闭了 Terminal 的可听铃声时才响铃字符,在其他终端中不执行任何操作。设置 "terminal_bell" 以在任何终端中响铃字符。请参阅获取终端铃声或通知 。
`remote.defaultEnvironmentId`
为你从 CLI 创建的云会话(例如使用 claude --cloud)选择默认云环境 。当你使用 /remote-env 选择环境时,Claude Code 会将此键写入你的用户设置。
作用域 : 任何文件 。对于自托管环境 ID,仅用户或托管设置或 --settings 标志。
类型 : 字符串,环境 ID,如 env_... 或 ccpool_...
默认值 : 未设置,因此当你的列表有 Anthropic 托管环境时 Claude Code 使用它,否则使用列表中不是远程控制桥接环境 的第一个环境,或当每个都是桥接环境时使用第一个环境
每个会话的覆盖 : --environment 优先于此键用于它创建的一个云会话
{
"remote" : {
"defaultEnvironmentId" : "env_0123abcd"
}
}
Anthropic 托管的环境 ID(以 env_ 开头)遵循标准设置优先级,因此存储库的项目设置中的值会覆盖你的用户级别选择。自托管环境 ID(以 ccpool_ 开头)仅从用户设置、托管设置和 --settings 标志中获得尊重;Claude Code 忽略存储库的项目或本地设置中的一个,/remote-env 显示它忽略了哪个值,因此签入的文件无法将会话引导到你未选择的自托管环境。
`remoteControlAtStartup`
当每个交互式会话启动时自动连接远程控制 ,而不是等待 /remote-control。将其设置为 true 以打开自动连接,false 以关闭。在 /config 中显示为为所有会话启用远程控制 。
作用域 : 任何文件 。Claude Code 也会读取由旧版本留在 ~/.claude.json 中的值。
类型 : 布尔值
true: Claude Code 在每个交互式会话启动时自动连接远程控制
false: Claude Code 等待 /remote-control
默认值 : 未设置,因此自动连接遵循你的组织的管理员默认值(如果已设置),否则遵循 Claude Code 的当前默认值
每个会话的覆盖 : --remote-control 即使此键为 false 也会为一个会话打开远程控制,没有标志会为一个会话关闭它
{
"remoteControlAtStartup" : true
}
Claude Code 忽略项目或本地设置中的 true,因此存储库可以为其检出关闭自动连接,但无法打开。有关完整的每个作用域行为,请参阅为所有会话启用远程控制 和应用更严格值的安全键 。
`sshConfigs`
将 SSH 连接添加到桌面 环境下拉列表。管理员使用它向团队分发共享连接。你在托管设置中定义的连接显示为托管,因此用户可以选择它们,但无法在应用中编辑或删除它们。
作用域 : 用户或托管 。桌面应用读取此键。
类型 : 对象数组,每个都有必需的 id、name 和 sshHost 以及可选的 sshPort 和 sshIdentityFile
默认值 : 未设置
此示例添加一个名为 Dev VM 的连接,连接到 user@dev.example.com:
{
"sshConfigs" : [
{
"id" : "dev-vm" ,
"name" : "Dev VM" ,
"sshHost" : "user@dev.example.com"
}
]
}
`sshHostAllowlist`
限制桌面 SSH 会话 可以连接到的主机。仅桌面应用读取此键;CLI 不读取。模式不区分大小写:* 匹配任何主机,*.example.com 匹配 example.com 和每个子域,其他任何内容都是针对 ~/.ssh/config 解析后的主机名的精确匹配。空数组关闭 SSH 会话。
作用域 : 托管
类型 : 主机名模式数组
默认值 : 未设置,因此允许任何主机
此示例允许 devboxes.example.com 及其子域,加上精确主机 bastion.example.com:
{
"sshHostAllowlist" : [ "*.devboxes.example.com" , "bastion.example.com" ]
}
身份验证和提供商
通过辅助脚本提供凭证,对于组织,强制使用登录方法或组织。请参阅身份验证 。
`apiKeyHelper`
运行您自己的命令来生成 Claude Code 随模型请求发送的凭证。Claude Code 通过系统 shell 运行该命令,在 macOS 和 Linux 上为 /bin/sh,在 Windows 上为 cmd,并将其输出作为 X-Api-Key 和 Authorization: Bearer 标头发送。将其用于动态或轮换凭证,例如从保管库获取的短期令牌。
Scope : Any file
Type : string,shell 命令行
Default : 未设置,因此 Claude Code 不运行辅助程序
{
"apiKeyHelper" : "/bin/generate_temp_api_key.sh"
}
Claude Code 缓存该值并在以下情况下重新运行该命令:
最后两种情况仅在辅助程序的输出是 Claude Code 发送的凭证且未设置 ANTHROPIC_AUTH_TOKEN 时适用。
在交互式会话中,当命令来自项目或本地设置时,Claude Code 在您接受工作区信任提示之前不会运行它。请参阅凭证管理 。
`awsAuthRefresh`
运行您自己的命令(例如 aws sso login),以在 Claude Code 用于 Amazon Bedrock 的凭证停止工作时刷新 .aws 目录中的凭证。Claude Code 首先根据 STS 检查当前凭证,仅在该检查失败时运行该命令,然后读取刷新的 .aws 目录。
Scope : Any file
Type : string,shell 命令行
Default : 未设置,因此 Claude Code 不为您刷新 AWS 凭证
{
"awsAuthRefresh" : "aws sso login --profile myprofile"
}
当您的刷新流写入 .aws 时使用此密钥;当它打印凭证时使用 awsCredentialExport 。请参阅高级凭证配置 。
`awsCredentialExport`
运行您自己的命令,该命令将 AWS 凭证打印为 JSON,以便 Claude Code 可以使用不存在于 .aws 目录中的凭证调用 Amazon Bedrock 。Claude Code 接受 aws sts 输出形状和平面 aws configure export-credentials 形状,并将凭证范围限定为其自己的 Bedrock 客户端,因此 Claude Code 运行的 shell 命令仍然看到您的环境凭证。
Scope : Any file
Type : string,shell 命令行
Default : 未设置,因此 Claude Code 使用环境 AWS 凭证链
{
"awsCredentialExport" : "/bin/generate_aws_grant.sh"
}
与 awsAuthRefresh 不同,Claude Code 在设置此命令时始终运行它,而不首先检查环境凭证。请参阅高级凭证配置 。
`forceLoginMethod`
限制人们可以使用哪种帐户登录。设置 "claudeai" 以仅允许 claude.ai 帐户,设置 "console" 以仅允许 Claude Console 帐户,或设置 "gateway" 以将人们发送到 cloud gateway 而不是第一方登录。管理员在托管设置中设置它,并将其与 forceLoginOrgUUID 配对,以将开发人员的 claude.ai 登录保持在一个组织内。如果您在任何设置文件中将其设置为 "claudeai" 或 "console",Claude Code 也会停止在该文件适用的会话中提供无密钥 Console 登录 。
Scope : Any file 。Claude Code 仅从机器上的托管源(managed-settings.json、macOS plist 或 Windows HKLM 注册表或策略辅助程序)接受 "gateway"。它在用户、项目、本地、HKCU 和服务器托管设置中将 "gateway" 视为未设置,与 forceLoginGatewayUrl 的规则相同。
Type : string,以下之一:
"claudeai":仅 claude.ai 帐户可以登录
"console":仅 Claude Console 帐户可以登录
"gateway":Claude Code 将人们发送到 cloud gateway 而不是第一方登录
Default : 未设置,因此人们选择登录方法
{
"forceLoginMethod" : "claudeai"
}
每个第一方登录路径都应用该限制,包括 VS Code 扩展 、Agent SDK、claude setup-token 和 /install-github-app,除了终端的交互式登录屏幕(通过 /login 或首次运行入门到达),它预选择该方法而不强制执行。在 v2.1.212 之前,仅终端登录应用了它。请参阅限制登录到您的组织 ,了解如何处理每个登录路径、环境凭证和第三方提供商。
当机器上的托管源设置 "gateway" 时,Claude Code 不使用剩余登录、API 密钥或 apiKeyHelper 凭证。请参阅管理员策略需要 Cloud gateway 登录 ,了解每个凭证生成的消息。如果您通过 CLAUDE_CODE_USE_BEDROCK 或类似的环境变量选择云提供商,该会话不需要网关登录。在 v2.1.261 之前,Claude Code 在这些机器上使用了剩余登录。
`forceLoginGatewayUrl`
设置 /login Cloud gateway 屏幕连接到的网关 URL,以便人们可以到达您的 cloud gateway 而无需输入其地址。该屏幕没有 URL 字段:设置此密钥后,它显示您的网关 URL 并在人们按 Enter 时连接;不设置时,它告诉他们联系其 IT 管理员。
此密钥或 forceLoginMethod: "gateway" 使机器仅限网关,因此 /login 在 Cloud gateway 屏幕上打开,没有登录方法选择器。请参阅管理员策略需要 Cloud gateway 登录 ,了解剩余第一方登录或 API 密钥会发生什么。设置两个密钥,以便屏幕连接而不是显示错误。
Scope : Managed 。仅从机器上的源读取:managed-settings.json、macOS plist 或 Windows HKLM 注册表或策略辅助程序。Claude Code 在 HKCU 和服务器托管设置中忽略它。
Type : string,包括方案的完整 URL
Default : 未设置,因此 Cloud gateway 屏幕显示错误,告诉人们联系其 IT 管理员
{
"forceLoginGatewayUrl" : "https://claude-gateway.example.com"
}
如果该值不是有效的 URL,登录屏幕会报告它,托管设置文件的其余部分仍然适用。请参阅设置网关 URL 。
`forceLoginOrgUUID`
从托管源,要求 claude.ai 帐户登录属于一个 Anthropic 组织(给定为单个 UUID)或属于多个组织(给定为数组)。从任何设置文件,Claude Code 也使用单个 UUID 在 claude.ai 或 Claude Console 登录期间预选择该组织,对于数组预选择任何内容。如果您在任何设置文件中设置该密钥,Claude Code 也会停止在该文件适用的会话中提供无密钥 Console 登录 ,并改为创建 API 密钥。
Scope : Any file 。仅托管源强制执行限制;任何其他设置文件中的单个 UUID 在登录期间预选择组织而不限制它。
Type : string,一个 UUID,或字符串数组,多个 UUID
Default : 未设置,因此任何组织都可以登录
此示例接受来自两个组织之一的登录,而不预选择一个:
{
"forceLoginOrgUUID" : [ "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" , "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" ]
}
如果托管源设置空数组或 Claude Code 无法解析的值,Claude Code 会使用错误配置消息阻止每个登录。
请参阅限制登录到您的组织 ,了解 Claude Code 如何处理 Claude Console 登录、其他登录路径和环境凭证。
`gatewayInternalNetworks`
声明您的组织从其内部网络编号的公共 IPv4 块,以便 /login 在那里接受 cloud gateway 。需要 Claude Code v2.1.268 或更高版本。
没有此密钥,/login 连接到私有地址上的任何网关,仅此而已。有了它,/login 也接受列出的块内的网关,仅通过直接连接。该机器在该连接上的自身地址也必须在同一块内。
Scope : Managed 。仅从机器上的源读取:managed-settings.json、macOS plist 或 Windows HKLM 注册表或策略辅助程序。Claude Code 在 HKCU 和服务器托管设置中忽略它。
Type : 字符串数组,最多四个 IPv4 CIDR 块,每个 /8 到 /32,彼此不重叠,且都不与私有空间重叠。
Default : 未设置,因此 /login 仅接受私有地址上的网关
{
"gatewayInternalNetworks" : [ "203.0.113.0/24" ]
}
将示例中的文档范围替换为您自己的块。Claude Code 拒绝文档范围、VPN 和 NAT64 客户端在本地使用的范围,以及保留空间(没有网络从其编号),例如多播。
如果条目无效或值不是字符串列表,/login 会命名问题,并拒绝机器上的每个新网关登录,直到您修复该值。现有登录继续工作。请参阅允许网关在您拥有的公共地址空间上 ,了解完整规则和开发人员看到的内容。
`gcpAuthRefresh`
运行您自己的命令以在 Claude Code 发现 Google Cloud Application Default Credentials 已过期或无法加载时刷新它们,以便 Google Cloud's Agent Platform 请求继续工作,而无需您手动重新身份验证。
Scope : Any file
Type : string,shell 命令行
Default : 未设置,因此 Claude Code 的凭证错误告诉您自己运行 gcloud auth application-default login
{
"gcpAuthRefresh" : "gcloud auth application-default login"
}
请参阅高级凭证配置 。
运行您自己的命令以生成 Claude Code 随 OpenTelemetry 导出发送的标头,用于令牌轮换的后端。Claude Code 在启动时运行它,之后定期运行,并期望在 stdout 上获得字符串标头值的 JSON 对象。
Scope : Any file
Type : string,可执行路径或 shell 命令行
Default : 未设置,因此 Claude Code 不添加辅助程序生成的标头
{
"otelHeadersHelper" : "/bin/generate_otel_headers.sh"
}
使用 CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS 设置刷新间隔。请参阅动态标头 ,了解脚本要求以及 Claude Code 报告失败辅助程序的位置。
更新和版本控制
选择更新渠道,对于组织,可以固定人们可以运行的版本。请参阅更新 Claude Code 。
`autoUpdatesChannel`
选择发布渠道 ,背景自动更新和 claude update 遵循该渠道。设置 "stable" 以获得通常约一周前的版本,并跳过有重大回归的发布,或设置 "latest" 以获得最新发布。
Scope : Any file 。在托管设置中设置以在整个组织中强制执行一个渠道。
Type : string,以下之一:
"latest":更新遵循最新发布
"stable":更新遵循通常约一周前的版本,并跳过有重大回归的发布
Default : 未设置,所以 Claude Code 遵循 "latest"
{
"autoUpdatesChannel" : "stable"
}
当您在 /config 中的自动更新渠道 下选择它时,Claude Code 会将 "stable" 写入您的用户设置,当您在那里切换回最新版本时会删除该键。claude install stable 和 claude install latest 也会保存您命名的渠道。在 /config 中从 "latest" 切换到 "stable" 会询问是否允许降级或保持当前版本;保持设置 minimumVersion 。Homebrew 安装会忽略此键:claude-code cask 跟踪稳定版,claude-code@latest 跟踪最新版,claude update 遵循 brew upgrade。要完全关闭自动更新,请在 env 中设置 DISABLE_AUTOUPDATER 。
`minimumVersion`
防止背景自动更新和 claude update 安装低于此版本的任何版本,因此移动到 "stable" 渠道不会从较新的 "latest" 构建中降级您。当您在 /config 中选择在切换渠道时保持当前版本时,Claude Code 会为您写入此键,当您切换回 "latest" 时会清除它。
Scope : Any file 。在托管设置中设置以固定组织范围的最小值,用户和项目设置无法降低。
Type : string,版本号,例如 "2.1.100";不是有效版本的值会被忽略
Default : 未设置,所以更新可以安装渠道提供的任何版本
此示例遵循稳定渠道,并拒绝安装低于 2.1.100 的任何版本:
{
"autoUpdatesChannel" : "stable" ,
"minimumVersion" : "2.1.100"
}
此键仅约束更新。要使 Claude Code 拒绝在版本以下启动,请改用 requiredMinimumVersion 。请参阅固定最小版本 。
`requiredMaximumVersion`
设置您的组织允许启动的最新 Claude Code 版本。当运行版本较新时,Claude Code 在启动时退出,并告诉用户通过您组织的批准方法安装批准的版本;claude install <version> 也可能有效。需要 Claude Code v2.1.163 或更高版本。
Scope : Managed 。Claude Code 在其他地方忽略该键时不会发出警告。
Type : string,版本号,例如 "2.1.150";不是有效版本的值会被忽略
Default : 未设置,所以不适用上限
{
"requiredMaximumVersion" : "2.1.150"
}
背景自动更新和 claude update 跳过上限以上的版本,因此范围内的安装保持在范围内。claude update、claude install 和 claude doctor 在上限以上继续工作,以便用户可以恢复。将其与 requiredMinimumVersion 配对以强制执行范围。
`requiredMinimumVersion`
设置您的组织允许启动的最旧 Claude Code 版本。当运行版本较旧时,Claude Code 在启动时退出,并告诉用户通过您组织的批准方法进行更新。检查仅在启动时运行,因此已在运行的会话会继续。需要 Claude Code v2.1.163 或更高版本。
Scope : Managed 。Claude Code 在其他地方忽略该键时不会发出警告。
Type : string,版本号,例如 "2.1.150";不是有效版本的值会被忽略
Default : 未设置,所以不适用下限
{
"requiredMinimumVersion" : "2.1.150"
}
claude update、claude install 和 claude doctor 在下限以下继续工作,以便用户可以恢复。与仅防止降级的 minimumVersion 不同,此键会阻止启动。将其与 requiredMaximumVersion 配对以强制执行范围。
在 Claude Code 桌面应用 中关闭特定工具。终端 CLI 会忽略这些密钥。有关工具本身,请参阅 Claude 可用的工具 。
`browserExternalPageTools`
阻止 Claude 在桌面应用的 浏览器窗格 中使用其工具读取或作用于外部页面。您组织中的人员仍然可以自己打开外部网站,本地开发服务器预览继续与 Claude 的工具一起工作。桌面应用读取此密钥;终端 CLI 会忽略它。
Scope : Managed
Type : string,"disabled";桌面应用也接受 "disable",在任何一种情况下
Default : 未设置,因此 Claude 的工具可在外部页面上工作
{
"browserExternalPageTools" : "disabled"
}
任何其他值都会使 Claude 的工具保持打开状态,非空字符串如果不是两个接受的值之一,则会记录警告。要同时阻止人员和 Claude 访问外部网站,请改为设置 disableBrowserExternalNavigation 。请参阅 为您的组织限制外部浏览 。
`disableBrowserExternalNavigation`
在桌面应用的 浏览器窗格 中为人员和 Claude 关闭外部浏览。Localhost 开发服务器预览继续工作。桌面应用读取此密钥;终端 CLI 会忽略它。
Scope : Managed
Type : Boolean;仅 JSON Boolean true 生效
true:桌面应用在浏览器窗格中为人员和 Claude 关闭外部浏览;localhost 预览继续工作
false:外部浏览保持打开
Default : 未设置,因此外部浏览是打开的
{
"disableBrowserExternalNavigation" : true
}
桌面应用会忽略任何其他值,非 Boolean 的值(例如字符串 "true" 或 1)也会记录警告。要保持外部浏览打开但在外部页面上关闭 Claude 的工具,请改为设置 browserExternalPageTools 。请参阅 为您的组织限制外部浏览 。
阻止 Claude 的工具用于桌面应用的 iOS 模拟器窗格 。人员保持对窗格的手动使用;仅移除 Claude 的访问权限,任何人都无法从应用内部将其重新打开。桌面应用读取此密钥;终端 CLI 会忽略它。
Scope : Managed
Type : Boolean;仅 JSON Boolean true 生效
true:桌面应用阻止 Claude 的工具用于 iOS 模拟器窗格
false:Claude 的模拟器工具遵循桌面应用中每个人的设置切换
Default : 未设置,因此 Claude 的模拟器工具遵循桌面应用中每个人的设置切换
{
"disableMobileSimulatorTools" : true
}
桌面应用会忽略任何其他值,非 Boolean 的值(例如字符串 "true" 或 1)也会记录警告。
隐私和遥测
控制 Claude Code 保留会话数据的时间以及它发送的内容。关闭使用指标和错误报告的开关是环境变量,而不是设置键:在 env 键中或在 shell 中设置 DISABLE_TELEMETRY、DISABLE_ERROR_REPORTING 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC。遥测服务 说明了每个变量的作用。两个例外可以从设置文件中关闭:下面的 feedbackDrafts 用于 Claude 起草的反馈,下面的 feedbackSurveyRate 用于会话调查。
`cleanupPeriodDays`
设置 Claude Code 在删除之前保留会话记录和其他应用程序数据 的天数。Claude Code 在会话开始后作为后台扫描运行删除,只要它能够安全地确定保留期。
范围 : 任何文件
类型 : 天数,整数,最小值 1
默认值 : 30
{
"cleanupPeriodDays" : 20
}
设置 0 会导致验证失败,因此请选择一个较大的值,例如 3650 以实现长期保留。要停止 Claude Code 完全写入记录,请参阅纯文本存储 。
`desktopSessionCleanupPeriodDays`
为您在 Claude Desktop 或 Cowork 中启动或最近继续的会话的记录设置天数年龄限制。没有此键,Claude Code 会无限期地保留这些记录 。Claude Code 在每个记录的年龄超过此限制和 cleanupPeriodDays 时删除它,因此当 cleanupPeriodDays 处于其默认值 30 时,值 7 仍会保留它们 30 天。当托管设置设置 cleanupPeriodDays 时,该期间改为适用,此键被忽略。需要 Claude Code v2.1.248 或更高版本。
范围 : 用户或托管 。Claude Code 也从您使用 --settings 传递的文件中读取该键,并在项目和本地设置中忽略它。
类型 : 天数,整数,最小值 0
默认值 : 0,不设置年龄限制
{
"desktopSessionCleanupPeriodDays" : 90
}
`feedbackDrafts`
控制 Claude 起草的反馈 :Claude 是否可以为您排队反馈草稿以供审查,以及 Claude Code 在 Claude 排队时是否显示卡片。
范围 : 用户或托管
类型 : 字符串,"notify"、"quiet" 或 "off" 之一
"notify":当 Claude 排队草稿时,Claude Code 在提示上方显示卡片,默认情况下一个会话中最多三张卡片
"quiet":Claude 在没有卡片的情况下起草。您在提示页脚中看到排队草稿的计数,并在 /feedback 中审查它们
"off":Claude Code 删除 SendFeedback 工具,因此 Claude 无法排队草稿
默认值 : "notify"
每个会话的覆盖 : CLAUDE_CODE_SEND_FEEDBACK 设置为 0 会关闭一个会话的此功能
{
"feedbackDrafts" : "quiet"
}
在 /config 中显示为Claude 起草的反馈 ,它将此键写入您的用户设置。您只在 Claude 可以起草反馈的会话中 看到 /config 行;设置 "off" 不会隐藏它,因此您可以从同一行重新打开此功能。托管设置中的值优先于您的用户设置,因此当管理员设置此键时,该行显示托管值,更改它无效。Claude Code 在项目和本地设置中忽略此键。
`feedbackSurveyRate`
设置会话质量调查 在会话符合条件时出现的概率。设置 0 以防止调查出现。
范围 : 任何文件
类型 : 0 到 1 之间的数字
默认值 : 未设置,因此 Claude Code 使用 Anthropic 远程设置的速率,或在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的内置速率 0.005,这些不接收远程配置
每个会话的覆盖 : CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY 设置为 1 会关闭一个会话的调查,无论此键设置的速率如何
{
"feedbackSurveyRate" : 0.05
}
相同的速率适用于 VS Code 扩展中的调查。
`skipWebFetchPreflight`
跳过 WebFetch 域安全检查 ,该检查在获取之前将每个请求的主机名发送到 api.anthropic.com。在阻止到 Anthropic 的流量的环境中设置 true,例如 Amazon Bedrock、Google Cloud 的 Agent Platform 或具有限制性出站的 Microsoft Foundry 部署。
范围 : 任何文件
类型 : 布尔值
true:Claude Code 跳过 WebFetch 域安全检查
false:检查在会话中首次获取每个主机名之前运行,以及对于其早期检查被阻止或失败的主机名再次运行
默认值 : 未设置,因此检查在会话中首次获取每个主机名之前运行
{
"skipWebFetchPreflight" : true
}
跳过检查后,WebFetch 尝试任何 URL 而不查询阻止列表,因此如果您需要限制 Claude 可以访问的域,请将其与 WebFetch 权限规则 配对。
企业和托管设置
组织用来计算、刷新和合并托管设置的密钥。请参阅设置托管设置 。
`disableSideloadFlags`
在启动时拒绝 --plugin-dir、--plugin-url、--agents 和 --mcp-config CLI 标志,用户可能会通过这些标志来绕过 strictKnownMarketplaces 进行单次运行。Claude Code 会以错误退出并命名被拒绝的标志,并对在内部使用这些标志启动 CLI 的表面应用相同的检查,目前在桌面应用中的 Cowork 本地会话。在云会话 中,Claude Code 会删除服务器通过 --mcp-config 传递的 MCP 服务器,除了进程内 type: "sdk" 条目,并启动会话。需要 Claude Code v2.1.193 或更高版本。
Scope : Managed
Type : Boolean
true: Claude Code 在启动时拒绝 --plugin-dir、--plugin-url、--agents 和 --mcp-config,并以错误退出并命名它们,除了在云会话中它会删除服务器通过 --mcp-config 传递的 MCP 服务器,除了进程内 type: "sdk" 条目,并启动会话
false: Claude Code 接受这些标志
Default : false
{
"disableSideloadFlags" : true
}
Claude Code 仍然接受其服务器都是进程内 type: "sdk" 条目的 --mcp-config,因此 Agent SDK 和 VS Code 扩展继续工作。用户仍然可以使用 claude mcp add 或 .mcp.json 文件添加服务器;为了进行每个服务器的控制,也可以设置 allowedMcpServers 。需要 Claude Code v2.1.193 或更高版本。
相同的检查涵盖在 CLAUDE_CODE_PLUGIN_DIRS 环境变量中命名的插件文件夹,这需要 Claude Code v2.1.280 或更高版本。当变量命名一个文件夹时,Claude Code 以相同的错误退出,错误说要取消设置该变量。
在云会话中,Claude Code 也会忽略服务器传递的中途 MCP 更新,这是云会话配置和 SDK setMcpServers() 调用背后的路径,这些调用到达这些会话。进程内 type: "sdk" 条目在那里仍然豁免。在 v2.1.239 之前,服务器传递的 --mcp-config 会阻止云会话启动。
`forceRemoteSettingsRefresh`
阻止 CLI 启动,直到 Claude Code 已经新鲜获取服务器管理的设置 。如果获取失败,Claude Code 会退出而不是继续使用缓存或无设置。当您的环境无法接受即使是短暂的窗口(在该窗口中会话在没有其托管策略的情况下运行)时,请设置它。
当密钥未设置时,Claude Code 不会在获取时阻止启动,尽管当开发者在启动时登录时,它会等待最多五秒钟以进行获取。Cloud 网关会话总是等待,如果无法到达网关则退出。
Scope : Managed 。Claude Code 从任何管理员控制的托管源(即使不是最高优先级源)中接受 true。
Type : Boolean
true: Claude Code 阻止启动,直到它已经新鲜获取服务器管理的设置,如果获取失败则退出
false: Claude Code 不会在获取时阻止启动,尽管在登录启动时它会等待最多五秒钟以进行获取
Default : false
{
"forceRemoteSettingsRefresh" : true
}
在 MDM 配置文件或托管设置文件中设置它以在第一个服务器有效负载到达之前强制执行故障关闭启动。Claude Code 仅在获取服务器管理的设置的会话中应用检查,因此不获取它们 的会话启动时不会等待。claude auth 子命令豁免,因此用户可以在过期凭证是获取失败原因时重新身份验证。请参阅强制执行故障关闭启动 。
`managedSourcesBehavior`
选择 Claude Code 是仅应用您的组织提供的最高优先级托管源 ,还是合并它提供的每个管理员源。默认情况下,Claude Code 采用携带策略密钥 的最高优先级源并忽略其余的。策略密钥是除了这个密钥和 wslInheritsWindowsSettings 之外的任何设置密钥。因此,一旦服务器管理的设置或 MDM 策略提供策略密钥,managed-settings.json 文件仅贡献 Claude Code 从每个管理员源读取的密钥 。使用 "merge",您提供的每个管理员源都会将其密钥贡献给一个合并的策略。需要 Claude Code v2.1.242 或更高版本。
仅在您排名 在最高优先级源下方的每个源都在管理员的控制下时设置 "merge",因为 Claude Code 然后从较低源(例如 permissions.allow 规则)添加条目到策略。
Scope : Managed 。Claude Code 从携带此密钥或策略密钥的最高优先级源读取此密钥,并忽略排名较低的每个源中的此密钥,因此较低源无法选择自己合并到上面的源。Windows HKCU 注册表和来自嵌入主机的父设置 都不参与合并。
Type : string,其中之一:
Default : "first-wins"
在您部署的最高优先级源中提供密钥。从不接收服务器管理的设置的机器也需要在其 MDM 配置文件中使用该密钥,因为 Claude Code 从携带它或策略密钥的最高优先级源读取该密钥。managed-settings.json 文件是最低排名的管理员源,因此在那里设置的 "merge" 没有下面的源可以合并。在服务器管理的设置中,密钥看起来像这样:
{
"managedSourcesBehavior" : "merge"
}
在 "merge" 下,Claude Code 按其类型合并每个密钥。此表给出每种类型的规则。限制允许列表、整体取值和仅最高源行命名它们覆盖的每个密钥,其他行给出示例:
整体取值 sandbox.credentials.awsPairs 和 sandbox.ripgrep 需要 Claude Code v2.1.257 或更高版本。
几个密钥添加了表格未显示的条件:
要确认机器上合并了哪些源,请运行 /status 并读取 Setting sources 行 。
`parentSettingsBehavior`
选择 Claude Code 是否应用由嵌入主机进程(例如 Agent SDK 或 IDE 扩展)提供的托管设置,当管理员部署的托管层也存在时。使用 "first-wins",Claude Code 会删除主机提供的设置;使用 "merge",它通过限制性过滤器在管理员层下应用它们。当主机需要将其自己的限制传递给它启动的会话时,设置 "merge",例如 Claude Desktop 传递网关的出口允许列表。
Scope : Managed 。Claude Code 从最高优先级管理员控制的托管源读取它。
Type : string,其中之一:
"first-wins": 当管理员部署的托管层存在时,Claude Code 会删除主机提供的设置
"merge": Claude Code 通过限制性过滤器在管理员层下应用主机提供的设置
Default : "first-wins"
{
"parentSettingsBehavior" : "merge"
}
当不存在管理员部署的托管层时,此密钥无效:主机的设置然后应用为唯一的托管层,仍然过滤为限制性值。有关过滤器的限制以及托管源如何交互,请参阅来自嵌入主机的父设置 和限制父设置 。
`policyHelper`
运行您部署的可执行文件,在启动时计算托管设置,因此您可以从设备状态、身份或远程服务而不是静态文件派生策略。Claude Code 在接受第一个提示之前运行帮助程序,并将其发出的设置视为会话的托管设置。
Scope : Managed 。从 macOS plist、Windows HKLM 注册表或托管设置文件读取。Claude Code 从携带策略密钥 的最高优先级托管源读取密钥,并仅当该源是这三个之一时才运行帮助程序;它忽略服务器管理的设置、HKCU 注册表和主机提供的父设置中的密钥。
Type : 具有 path、timeoutMs 和 refreshIntervalMs 的对象
Default : 未设置,因此不运行帮助程序
当服务器管理的设置在启动时提供策略时,它们优先于帮助程序的源,帮助程序不运行。
如果稍后的设置获取报告服务器管理的设置已删除,Claude Code 此时运行帮助程序,而不是等待下一次启动。其输出管理会话的其余部分,失败的运行以与失败的启动运行 相同的消息结束会话。
此示例使用 5 秒超时运行帮助程序,并每五分钟重新运行一次:
{
"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 报告无错误:
{
"managedSettings" : {
"permissions" : { "deny" : [ "Read(//etc/secrets/**)" ] }
}
}
当帮助程序发出 managedSettings 时,该对象成为运行的唯一托管设置源:Claude Code 忽略 MDM、文件和 HKCU 源,仅从帮助程序的输出读取跨源密钥 ,并且从不合并父设置 。
启动 forceRemoteSettingsRefresh 检查在帮助程序之前运行并读取任何管理员源。以 0 退出且信封省略 managedSettings 的帮助程序不贡献托管设置,其他源照常应用。
帮助程序失败
帮助程序运行在以下情况下失败:
path 违反 policyHelper.path 中的规则。
path 处没有常规文件。Claude Code 在启动帮助程序之前检查文件,在相同的 timeoutMs 预算内,因此无响应的网络挂载可能导致运行失败。
帮助程序以非零退出、在 timeoutMs 经过时仍在运行,或根本不启动,例如因为它不可执行。
帮助程序向 stdout 或 stderr 写入超过 1 MiB。
stdout 不是单个 JSON 对象,或其 managedSettings 有 Claude Code 无法修复的架构违规 。
当启动运行失败时,Claude Code 打印原因并拒绝启动。非零退出后,原因包括帮助程序的 stderr,或当 stderr 为空时的 stdout。超时后,原因命名 timeoutMs 限制,不包括帮助程序的任何输出。拒绝涵盖交互式会话、claude -p、Agent SDK 会话、后台会话 和大多数子命令。
拒绝是故意的,因此需要中断恢复能力的帮助程序应该从自己的缓存提供并以 0 退出。
当后台刷新失败时,Claude Code 保持最后成功的策略有效,/status 显示失败的刷新及其原因,直到刷新成功。每次刷新在与启动运行相同的 timeoutMs 和失败规则下运行。
使用 --debug,Claude Code 将每次运行的帮助程序的 stderr 写入调试日志 。
Claude Code 将无效的 policyHelper 值报告为删除的条目 ,并在剩余的托管设置上启动会话而不运行帮助程序。无效值包括裸路径字符串和低于其最小值 的 timeoutMs。
要关闭帮助程序,请从设置它的源中删除密钥。
`policyHelper.path`
命名 Claude Code 运行的帮助程序可执行文件。有关路径违反以下规则时发生的情况,请参阅帮助程序失败 。
Scope : Managed 。从 macOS plist、Windows HKLM 注册表或托管设置文件读取,无论 policyHelper 在哪里读取。
Type : string,规范化形式的绝对路径,没有 . 或 .. 段;在 Windows 上,以 .exe 结尾的驱动器字母或 UNC 路径
Default : 无;当设置 policyHelper 时需要
{
"policyHelper" : {
"path" : "/usr/local/bin/claude-policy"
}
}
`policyHelper.timeoutMs`
设置 Claude Code 在将运行视为失败之前等待帮助程序的时间。超时的运行失败方式与非零退出相同,因此在启动时 Claude Code 拒绝启动。
Scope : Managed 。从 macOS plist、Windows HKLM 注册表或托管设置文件读取,无论 policyHelper 在哪里读取。
Type : integer,毫秒,最小 1000
Default : 10000
{
"policyHelper" : {
"path" : "/usr/local/bin/claude-policy" ,
"timeoutMs" : 5000
}
}
`policyHelper.refreshIntervalMs`
让 Claude Code 在后台按间隔重新运行帮助程序,以便策略更改到达运行中的会话。当刷新成功时,其输出替换之前的托管设置而不重启;当刷新失败时,Claude Code 保持它已有的策略。
Scope : Managed 。从 macOS plist、Windows HKLM 注册表或托管设置文件读取,无论 policyHelper 在哪里读取。
Type : integer,毫秒:0 禁用刷新,否则至少 60000
Default : 未设置,因此 Claude Code 仅在启动时运行帮助程序一次
此示例每五分钟重新运行帮助程序:
{
"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\ 下没有托管设置文件或删除项提供策略密钥 时才读取 /etc/claude-code。设置它以将您已在 Windows 上部署的策略扩展到同一机器上的 WSL 会话,以便它们遵循与主机会话相同的规则。Claude Code 仅在 HKLM 注册表密钥或 C:\Program Files\ClaudeCode\ 下的托管设置文件或删除项中设置时才接受它,两者都需要 Windows 管理员写入。
Scope : Managed 。在管理员控制的 Windows 源中。
Type : Boolean
true: WSL 上的 Claude Code 从 Windows 策略链读取托管设置,并仅在 C:\Program Files\ClaudeCode\ 下没有托管设置文件或删除项提供策略密钥 时才读取 /etc/claude-code
false: WSL 仅读取 /etc/claude-code
Default : false,因此 WSL 仅读取 /etc/claude-code
{
"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(外部终端) 。
作用域 : 全局配置
类型 : 布尔值
true: 当你从外部终端启动 Claude Code 时,它会自动连接到正在运行的 IDE
false: Claude Code 不会从外部终端自动连接;在 VS Code 或 JetBrains 终端内,或使用 --ide,它仍然会连接
默认值 : false
每个会话的覆盖 : CLAUDE_CODE_AUTO_CONNECT_IDE 在任一方向上优先于此键,持续一个会话
{
"autoConnectIde" : true
}
Claude Code 在 settings.json 中忽略此键。
`autoInstallIdeExtension`
当你从 VS Code 终端运行 Claude Code 时,自动安装 Claude Code IDE 扩展。当你在 VS Code 或 JetBrains 终端内运行 Claude Code 时,在 /config 中显示为自动安装 IDE 扩展 。
{
"autoInstallIdeExtension" : false
}
Claude Code 在 settings.json 中忽略此键。
`copyOnSelect`
当你在全屏渲染 或代理视图 中用鼠标完成文本选择时,自动将文本复制到剪贴板。在全屏渲染打开时,在 /config 中显示为选择时复制 。
作用域 : 全局配置
类型 : 布尔值
true: 当你完成文本选择时,Claude Code 会将文本复制到剪贴板
false: 选择文本不会改变你的剪贴板,你用键盘快捷键复制选择
默认值 : true
{
"copyOnSelect" : false
}
Claude Code 在 settings.json 中忽略此键。
选择 Claude Code 在连接VS Code 或JetBrains IDE 时显示其提议的 Edit 或 Write 更改的 diff 的位置:"auto" 在 IDE 的 diff 查看器中打开它,"terminal" 将其保留在终端中。仅当 Claude Code 连接到 VS Code 或 JetBrains IDE 时,在 /config 中显示为Diff 工具 。
作用域 : 全局配置
类型 : 字符串,以下之一:
"auto": 当连接到 VS Code 或 JetBrains IDE 时,Claude Code 在 IDE 的 diff 查看器中打开 diff
"terminal": Claude Code 将 diff 保留在终端中
默认值 : "auto"
{
"diffTool" : "terminal"
}
Claude Code 在 settings.json 中忽略此键。
`externalEditorContext`
当你按 Ctrl+G 时,Claude Code 在你的外部编辑器 中打开你正在输入的提示。启用此键后,编辑器缓冲区以 Claude 的上一个响应作为 # 注释行开始,因此你可以在写入时读取它,Claude Code 在你保存时删除这些行。在 /config 中显示为在外部编辑器中显示最后响应 。
作用域 : 全局配置
类型 : 布尔值
true: 编辑器缓冲区以 Claude 的上一个响应作为 # 注释行开始,Claude Code 在保存时删除这些行
false: 编辑器缓冲区仅以你的提示打开
默认值 : false
{
"externalEditorContext" : true
}
启用后,Claude Code 打开的缓冲区如下所示,只有标记行下方的文本才会作为你的提示发送:
# ─── 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.256 及更早版本中,你可以在 Bash 或 PowerShell 权限提示上按 Ctrl+E 查看模型生成的命令说明,并将此键设置为 false 以关闭该快捷键。
作用域 : 全局配置 。在 v2.1.256 及更早版本上。
类型 : 布尔值
默认值 : true
`teammateDefaultModel`
在 v2.1.233 及更早版本中,你将此键设置为代理团队 队友的模型,你的提示没有为其命名模型:一个别名如 "sonnet",或 null 以遵循主导的模型。有关 Claude Code 现在为此类队友选择的模型,请参阅指定队友和模型 。
作用域 : 全局配置 。在 v2.1.233 及更早版本上。
类型 : 字符串,模型别名或完整模型 ID,或 null
默认值 : 未设置
另请参阅
590 />590 />
591 591
592 | 键 | 描述 | 主题 | 范围 |592 | 键 | 描述 | 主题 | 范围 |
593 | :---------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- | :---------------------- |593 | :- | :- | :- | :- |
594 | [`advisorModel`](#advisormodel) | 选择当 Claude 使用[顾问工具](/docs/zh-CN/advisor)时哪个模型来回答 | 模型和响应 | Any file |594 | [`advisorModel`](#advisormodel) | 选择当 Claude 使用[顾问工具](/docs/zh-CN/advisor)时哪个模型来回答 | 模型和响应 | Any file |
595 | [`agent`](#agent) | 将每个会话作为具有其提示、工具和模型的命名[子代理](/docs/zh-CN/sub-agents)启动 | 代理、会话和工作树 | Any file |595 | [`agent`](#agent) | 将每个会话作为具有其提示、工具和模型的命名[子代理](/docs/zh-CN/sub-agents)启动 | 代理、会话和工作树 | Any file |
596 | [`agentPushNotifEnabled`](#agentpushnotifenabled) | 让 Claude 在决定时向您的手机发送[推送通知](/docs/zh-CN/remote-control#mobile-push-notifications) | 远程、桌面和通知 | Any file |596 | [`agentPushNotifEnabled`](#agentpushnotifenabled) | 让 Claude 在决定时向您的手机发送[推送通知](/docs/zh-CN/remote-control#mobile-push-notifications) | 远程、桌面和通知 | Any file |
1133 该键采用两个字段,一个用于行本身,一个用于它们是替换内置阵容还是添加到它。1133 该键采用两个字段,一个用于行本身,一个用于它们是替换内置阵容还是添加到它。
1134 1134
1135 | Field | Type | What it does |1135 | Field | Type | What it does |
1136 | :---------------------- | :------------------------------------------------ | :--------------------------------------------------------------------------------------------------- |1136 | :- | :- | :- |
1137 | `options` | 行的数组,每个都有必需的 `model` 和可选的 `label` 和 `description` | 选择器显示的行,按此顺序,除了灰显的行移到底部。没有 `label`,Claude Code 用它知道的模型的内置名称标记行,或模型 ID 否则,没有 `description` 它写一个通用的第二行 |1137 | `options` | 行的数组,每个都有必需的 `model` 和可选的 `label` 和 `description` | 选择器显示的行,按此顺序,除了灰显的行移到底部。没有 `label`,Claude Code 用它知道的模型的内置名称标记行,或模型 ID 否则,没有 `description` 它写一个通用的第二行 |
1138 | `replaceBuiltInOptions` | Boolean,默认 `false` | 将其设置为 `true` 以仅显示这些行、**默认**和会话已在使用的模型的行。保留未设置以在内置阵容之后添加这些行 |1138 | `replaceBuiltInOptions` | Boolean,默认 `false` | 将其设置为 `true` 以仅显示这些行、**默认**和会话已在使用的模型的行。保留未设置以在内置阵容之后添加这些行 |
1139 1139
1190 </h4>1190 </h4>
1191 1191
1192 | Field | Type | What it does |1192 | Field | Type | What it does |
1193 | :----------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |1193 | :- | :- | :- |
1194 | `multiplier` | 大于 0 且最多 10 的数字 | 缩放 Claude Code 计算的每个成本,无论 `overrides` 行是否覆盖它。低于 1 是折扣,高于 1 是加价 |1194 | `multiplier` | 大于 0 且最多 10 的数字 | 缩放 Claude Code 计算的每个成本,无论 `overrides` 行是否覆盖它。低于 1 是折扣,高于 1 是加价 |
1195 | `overrides` | 模型 ID 到具有 `input`、`output`、`cacheRead` 和 `cacheWrite` 的费率对象的映射,每个 0 到 10000 | 该模型的美元每百万令牌费率,全部四个必需。`cacheWrite` 涵盖五分钟和一小时缓存写入。请参阅[`modelPricing` 行适用于哪些模型](#which-models-a-modelpricing-row-applies-to) |1195 | `overrides` | 模型 ID 到具有 `input`、`output`、`cacheRead` 和 `cacheWrite` 的费率对象的映射,每个 0 到 10000 | 该模型的美元每百万令牌费率,全部四个必需。`cacheWrite` 涵盖五分钟和一小时缓存写入。请参阅[`modelPricing` 行适用于哪些模型](#which-models-a-modelpricing-row-applies-to) |
1196 1196
1535 每行显示一个规则形状及其匹配的内容。1535 每行显示一个规则形状及其匹配的内容。
1536 1536
1537 | 规则 | 它匹配的内容 |1537 | 规则 | 它匹配的内容 |
1538 | :----------------------------- | :------------------ |1538 | :- | :- |
1539 | `Bash` | 每个 Bash 命令 |1539 | `Bash` | 每个 Bash 命令 |
1540 | `Bash(npm run *)` | 以 `npm run` 开头的命令 |1540 | `Bash(npm run *)` | 以 `npm run` 开头的命令 |
1541 | `Read(./.env)` | 读取 `.env` 文件 |1541 | `Read(./.env)` | 读取 `.env` 文件 |
1932 `allowWrite`、`denyWrite`、`denyRead`、`allowRead` 和 [`credentials.files`](#sandbox-credentials-files) 中的路径按其前缀解析:1932 `allowWrite`、`denyWrite`、`denyRead`、`allowRead` 和 [`credentials.files`](#sandbox-credentials-files) 中的路径按其前缀解析:
1933 1933
1934 | 前缀 | 含义 | 示例 |1934 | 前缀 | 含义 | 示例 |
1935 | :-------- | :------------------------------------ | :---------------------------------------------------------------- |1935 | :- | :- | :- |
1936 | `/` | 从文件系统根目录的绝对路径 | `/tmp/build` 保持 `/tmp/build` |1936 | `/` | 从文件系统根目录的绝对路径 | `/tmp/build` 保持 `/tmp/build` |
1937 | `~/` | 相对于主目录 | `~/.kube` 变为 `$HOME/.kube` |1937 | `~/` | 相对于主目录 | `~/.kube` 变为 `$HOME/.kube` |
1938 | `./` 或无前缀 | 相对于项目根目录(用于项目设置)或 `~/.claude`(用于用户设置) | `.claude/settings.json` 中的 `./output` 解析为 `<project-root>/output` |1938 | `./` 或无前缀 | 相对于项目根目录(用于项目设置)或 `~/.claude`(用于用户设置) | `.claude/settings.json` 中的 `./output` 解析为 `<project-root>/output` |
2335 `mask` 条目接受这些可选字段。没有 `extract` 或 `decode`,Claude Code 用一个哨兵替换整个文件内容。在启用文件系统隔离的 macOS 上,Claude Code 在 `extract` 或 `decode` 运行之前将 `mask` 条目应用为 `deny`;请参阅 [Mask credential files](/docs/zh-CN/sandboxing#mask-credential-files)。2335 `mask` 条目接受这些可选字段。没有 `extract` 或 `decode`,Claude Code 用一个哨兵替换整个文件内容。在启用文件系统隔离的 macOS 上,Claude Code 在 `extract` 或 `decode` 运行之前将 `mask` 条目应用为 `deny`;请参阅 [Mask credential files](/docs/zh-CN/sandboxing#mask-credential-files)。
2336 2336
2337 | 字段 | 类型 | 它做什么 |2337 | 字段 | 类型 | 它做什么 |
2338 | :----------------- | :----------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2338 | :- | :- | :- |
2339 | `extract` | 字符串,至少有一个捕获组的正则表达式 | 仅掩盖每个匹配的第 1 组捕获的文本,因此文件的其余部分保持可解析。设置 `decode` 后,Claude Code 检查每个捕获作为可能的 JWT,而不是直接替换它。需要 v2.1.221 或更高版本 |2339 | `extract` | 字符串,至少有一个捕获组的正则表达式 | 仅掩盖每个匹配的第 1 组捕获的文本,因此文件的其余部分保持可解析。设置 `decode` 后,Claude Code 检查每个捕获作为可能的 JWT,而不是直接替换它。需要 v2.1.221 或更高版本 |
2340 | `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 或更高版本 |2340 | `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 或更高版本 |
2341 | `decode` | 字符串 `"jwt"` | 在文件中查找 JSON Web Tokens (JWTs),使用内置模式或设置 `extract` 时,验证每个候选,并用结构有效的假令牌替换它,因此沙箱内解码令牌的代码保持工作。当没有候选验证时,`onExtractNoMatch` 管理结果。需要 v2.1.224 或更高版本 |2341 | `decode` | 字符串 `"jwt"` | 在文件中查找 JSON Web Tokens (JWTs),使用内置模式或设置 `extract` 时,验证每个候选,并用结构有效的假令牌替换它,因此沙箱内解码令牌的代码保持工作。当没有候选验证时,`onExtractNoMatch` 管理结果。需要 v2.1.224 或更高版本 |
2410 `mask` 条目接受这些可选字段。没有 `extract` 或 `decode`,Claude Code 用一个哨兵替换整个值。`extract` 和 `decode` 不能在同一条目上组合。2410 `mask` 条目接受这些可选字段。没有 `extract` 或 `decode`,Claude Code 用一个哨兵替换整个值。`extract` 和 `decode` 不能在同一条目上组合。
2411 2411
2412 | 字段 | 类型 | 它做什么 |2412 | 字段 | 类型 | 它做什么 |
2413 | :----------------- | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |2413 | :- | :- | :- |
2414 | `extract` | 字符串,至少有一个捕获组的正则表达式 | 仅掩盖每个匹配的第 1 组捕获的文本,例如 `DATABASE_URL` 连接字符串内的密码,因此值的其余部分保持可解析。需要 v2.1.224 或更高版本 |2414 | `extract` | 字符串,至少有一个捕获组的正则表达式 | 仅掩盖每个匹配的第 1 组捕获的文本,例如 `DATABASE_URL` 连接字符串内的密码,因此值的其余部分保持可解析。需要 v2.1.224 或更高版本 |
2415 | `onExtractNoMatch` | `"warn"`、`"deny"` 或 `"error"`;默认 `"warn"`。在带有 `decode` 的条目上,仅接受 `"warn"` | 当 `extract` 匹配不到任何内容时会发生什么。`warn` 未掩盖地传递变量,`deny` 在沙箱内取消设置它,`error` 停止沙箱设置直到您修复配置。需要 v2.1.224 或更高版本 |2415 | `onExtractNoMatch` | `"warn"`、`"deny"` 或 `"error"`;默认 `"warn"`。在带有 `decode` 的条目上,仅接受 `"warn"` | 当 `extract` 匹配不到任何内容时会发生什么。`warn` 未掩盖地传递变量,`deny` 在沙箱内取消设置它,`error` 停止沙箱设置直到您修复配置。需要 v2.1.224 或更高版本 |
2416 | `decode` | 字符串 `"jwt"` | 验证整个值是 JWT 并用结构有效的假令牌替换它,因此沙箱内解码令牌的代码保持工作;代理在出口上替换整个真实令牌。不验证的值未掩盖地传递并带有警告。需要 v2.1.224 或更高版本 |2416 | `decode` | 字符串 `"jwt"` | 验证整个值是 JWT 并用结构有效的假令牌替换它,因此沙箱内解码令牌的代码保持工作;代理在出口上替换整个真实令牌。不验证的值未掩盖地传递并带有警告。需要 v2.1.224 或更高版本 |
3389 每个条目的 URL、标签和徽章计数受以下限制:3389 每个条目的 URL、标签和徽章计数受以下限制:
3390 3390
3391 | 约束 | 行为 |3391 | 约束 | 行为 |
3392 | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------- |3392 | :- | :- |
3393 | URL 源 | 捕获的值是 URL 编码的,构造的 URL 必须共享模板的字面源。捕获可以填充路径段或查询值,但不能改变链接指向的位置 |3393 | URL 源 | 捕获的值是 URL 编码的,构造的 URL 必须共享模板的字面源。捕获可以填充路径段或查询值,但不能改变链接指向的位置 |
3394 | URL 长度 | 长于 2048 个字符的构造 URL 被丢弃 |3394 | URL 长度 | 长于 2048 个字符的构造 URL 被丢弃 |
3395 | URL 方案 | 必须是 `https`、`http` 或公认的编辑器或工作区深层链接方案:`vscode`、`vscode-insiders`、`cursor`、`windsurf`、`zed`、`jetbrains`、`idea`、`slack`、`linear`、`notion`、`figma` |3395 | URL 方案 | 必须是 `https`、`http` 或公认的编辑器或工作区深层链接方案:`vscode`、`vscode-insiders`、`cursor`、`windsurf`、`zed`、`jetbrains`、`idea`、`slack`、`linear`、`notion`、`figma` |
3578 每个 `tips` 条目是纯字符串或具有这些字段的对象:3578 每个 `tips` 条目是纯字符串或具有这些字段的对象:
3579 3579
3580 | 字段 | 必需 | 描述 |3580 | 字段 | 必需 | 描述 |
3581 | :----------------- | :- | :--------------------------------------------------------------------------------------------------------- |3581 | :- | :- | :- |
3582 | `id` | 是 | 最多 64 个字母、数字、`.`、`_` 或 `-`。Claude Code 在其上键入提示的显示历史,因此提示的冷却期在重新排序列表后仍然存在。在两个具有相同 id 的条目中,Claude Code 使用第一个 |3582 | `id` | 是 | 最多 64 个字母、数字、`.`、`_` 或 `-`。Claude Code 在其上键入提示的显示历史,因此提示的冷却期在重新排序列表后仍然存在。在两个具有相同 id 的条目中,Claude Code 使用第一个 |
3583 | `text` | 是 | 提示,最多 500 个字符的一行。Claude Code 剥离 ANSI 转义和控制字符,并折叠空格 |3583 | `text` | 是 | 提示,最多 500 个字符的一行。Claude Code 剥离 ANSI 转义和控制字符,并折叠空格 |
3584 | `cooldownSessions` | 否 | Claude Code 在再次显示提示之前等待的会话数,`0` 到 `1000`,默认 `0` |3584 | `cooldownSessions` | 否 | Claude Code 在再次显示提示之前等待的会话数,`0` 到 `1000`,默认 `0` |
4652 下面每个条目显示每个源类型的一个允许列表条目及其接受的字段。大多数类型精确匹配;`hostPattern` 和 `pathPattern` 按正则表达式匹配,`github` 条目可以使用 [owner 通配符](#owner-wildcards)。4652 下面每个条目显示每个源类型的一个允许列表条目及其接受的字段。大多数类型精确匹配;`hostPattern` 和 `pathPattern` 按正则表达式匹配,`github` 条目可以使用 [owner 通配符](#owner-wildcards)。
4653 4653
4654 | Source | Example entry | Fields |4654 | Source | Example entry | Fields |
4655 | :------------ | :------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------- |4655 | :- | :- | :- |
4656 | `github` | `{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }` | `repo` 必需;`ref` 是分支或标签;`path` 是子目录 |4656 | `github` | `{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }` | `repo` 必需;`ref` 是分支或标签;`path` 是子目录 |
4657 | `git` | `{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git", "ref": "production" }` | `url` 必需;`ref` 和 `path` 与 `github` 相同 |4657 | `git` | `{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git", "ref": "production" }` | `url` 必需;`ref` 和 `path` 与 `github` 相同 |
4658 | `url` | `{ "source": "url", "url": "https://plugins.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }` | `url` 必需;`headers` 为经过身份验证的访问添加 HTTP 标头 |4658 | `url` | `{ "source": "url", "url": "https://plugins.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }` | `url` 必需;`headers` 为经过身份验证的访问添加 HTTP 标头 |
4697 两个设置之间的匹配规则不同:4697 两个设置之间的匹配规则不同:
4698 4698
4699 | Rule | `strictKnownMarketplaces` | `blockedMarketplaces` |4699 | Rule | `strictKnownMarketplaces` | `blockedMarketplaces` |
4700 | --------- | ------------------------------------------------------ | ------------------------------------ |4700 | - | - | - |
4701 | 匹配源拼写 | 仅 `owner/repo` 形式。克隆同一存储库的 git URL 不匹配 | 任何拼写,包括解析为同一 github.com 存储库的 git URL |4701 | 匹配源拼写 | 仅 `owner/repo` 形式。克隆同一存储库的 git URL 不匹配 | 任何拼写,包括解析为同一 github.com 存储库的 git URL |
4702 | Owner 大小写 | 区分大小写,如精确条目匹配 | 不区分大小写 |4702 | Owner 大小写 | 区分大小写,如精确条目匹配 | 不区分大小写 |
4703 | `ref` | 遵循精确条目规则:带 `ref` 的条目仅匹配具有该精确 ref 的源,没有的条目仅匹配不指定 ref 的源 | 没有 `ref` 的条目阻止它匹配的存储库的所有 refs |4703 | `ref` | 遵循精确条目规则:带 `ref` 的条目仅匹配具有该精确 ref 的源,没有的条目仅匹配不指定 ref 的源 | 没有 `ref` 的条目阻止它匹配的存储库的所有 refs |
4747 两个键做不同的工作。此表比较它们:4747 两个键做不同的工作。此表比较它们:
4748 4748
4749 | Aspect | `strictKnownMarketplaces` | `extraKnownMarketplaces` |4749 | Aspect | `strictKnownMarketplaces` | `extraKnownMarketplaces` |
4750 | ----------------- | ------------------------- | ------------------------------- |4750 | - | - | - |
4751 | Purpose | 组织策略执行 | 团队便利 |4751 | Purpose | 组织策略执行 | 团队便利 |
4752 | Settings file | 仅托管设置 | 任何设置文件 |4752 | Settings file | 仅托管设置 | 任何设置文件 |
4753 | Behavior | 阻止非允许列表的添加 | 注册缺失的 marketplaces |4753 | Behavior | 阻止非允许列表的添加 | 注册缺失的 marketplaces |
6265 在 `"merge"` 下,Claude Code 按其类型合并每个密钥。此表给出每种类型的规则。限制允许列表、整体取值和仅最高源行命名它们覆盖的每个密钥,其他行给出示例:6265 在 `"merge"` 下,Claude Code 按其类型合并每个密钥。此表给出每种类型的规则。限制允许列表、整体取值和仅最高源行命名它们覆盖的每个密钥,其他行给出示例:
6266 6266
6267 | 密钥类型 | Claude Code 如何合并它 | 密钥 |6267 | 密钥类型 | Claude Code 如何合并它 | 密钥 |
6268 | :----------------------------------------- | :----------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |6268 | :- | :- | :- |
6269 | Lists | 合并来自每个源的条目 | [`permissions.allow`](#permissions-allow)、[`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 和其他列表密钥 |6269 | Lists | 合并来自每个源的条目 | [`permissions.allow`](#permissions-allow)、[`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 和其他列表密钥 |
6270 | Locks | 应用任何源设置的最严格值。当没有源设置严格值时,仅从最高源应用较宽松的值 | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly)、[`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 和其他布尔值或枚举锁 |6270 | Locks | 应用任何源设置的最严格值。当没有源设置严格值时,仅从最高源应用较宽松的值 | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly)、[`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 和其他布尔值或枚举锁 |
6271 | Restriction allowlists | 从设置它的最高源整体取值,不从较低源添加条目。当最高源未设置时,从下一个源整体取值 | [`availableModels`](#availablemodels)、[`allowedMcpServers`](#allowedmcpservers)、[`strictKnownMarketplaces`](#strictknownmarketplaces)、[`allowedChannelPlugins`](#allowedchannelplugins) 和 [`fallbackModel`](#fallbackmodel) 链 |6271 | Restriction allowlists | 从设置它的最高源整体取值,不从较低源添加条目。当最高源未设置时,从下一个源整体取值 | [`availableModels`](#availablemodels)、[`allowedMcpServers`](#allowedmcpservers)、[`strictKnownMarketplaces`](#strictknownmarketplaces)、[`allowedChannelPlugins`](#allowedchannelplugins) 和 [`fallbackModel`](#fallbackmodel) 链 |