2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.
4 4
5# Claude Code 设置5# 设置文件和优先级
6 6
7> 使用全局和项目级设置以及环境变量配置 Claude Code。7> 更改 Claude Code 设置，选择键所属的作用域，验证更改，并了解当键在多个位置设置时 Claude Code 使用哪个值。
8 8
9Claude Code 提供多种设置来配置其行为以满足您的需求。您可以通过运行 `/config` 命令来配置 Claude Code，这会打开一个选项卡式设置界面，您可以在其中查看状态信息并修改配置选项。从 v2.1.181 开始，您可以通过向 `/config` 传递 `key=value` 来更改单个选项而无需打开界面，例如 `/config verbose=true`。9export const SettingsPrecedence = () => {
10 10 const LEVELS = [{
11<h2 id="configuration-scopes">11 n: 1,
12 配置作用域12 name: 'Managed settings',
13</h2>13 file: 'managed-settings.json, MDM, or the claude.ai console',
14 14 who: 'Your organization',
15Claude Code 使用作用域系统来确定配置应用的位置以及与谁共享。了解作用域可以帮助您决定如何为个人使用、团队协作或企业部署配置 Claude Code。15 w: 390
16 16 }, {
17<h3 id="available-scopes">17 n: 2,
18 可用作用域18 name: 'Command line',
19</h3>19 file: 'claude --settings',
20 who: 'You, this session',
21 w: 420
22 }, {
23 n: 3,
24 name: 'Project local',
25 file: '.claude/settings.local.json',
26 who: 'You, this project',
27 w: 480
28 }, {
29 n: 4,
30 name: 'Shared project',
31 file: '.claude/settings.json',
32 who: 'Everyone in the project',
33 w: 540
34 }, {
35 n: 5,
36 name: 'User',
37 file: '~/.claude/settings.json',
38 who: 'You, every project',
39 w: 600
40 }];
41 const W = 760;
42 const ROW = 58;
43 const GAP = 8;
44 const TOP = 34;
45 const H = TOP + LEVELS.length * (ROW + GAP) + 30;
46 const cx = W / 2;
47 const mono = 'var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace)';
48 const sans = 'var(--font-sans, system-ui, -apple-system, sans-serif)';
49 return <div className="sp-root not-prose" role="img" aria-label="Settings precedence, highest first: managed settings, command line, project local, shared project, user. A key set at a higher level overrides the same key set lower down.">
50 <style>{`
51 .sp-root { --sp-text: #1A1918; --sp-sub: #5E5D59; --sp-faint: #8A8880; --sp-fill: #F5F4EF; --sp-stroke: rgba(0,0,0,0.12); --sp-top: #D97757; --sp-top-fill: rgba(217,119,87,0.14); --sp-arrow: #8A8880; margin: 1.25rem 0; }
52 .dark .sp-root { --sp-text: #F1EFE9; --sp-sub: #B8B5AD; --sp-faint: #8A8880; --sp-fill: #24231F; --sp-stroke: rgba(255,255,255,0.12); --sp-top-fill: rgba(217,119,87,0.22); --sp-arrow: #8A8880; }
53 .sp-root svg { width: 100%; height: auto; display: block; max-width: ${W}px; margin: 0 auto; }
54 `}</style>
55 <svg viewBox={`0 0 ${W} ${H}`} xmlns="http://www.w3.org/2000/svg">
56 <text x={cx} y={18} textAnchor="middle" fontFamily={sans} fontSize="12.5" fontWeight="600" fill="var(--sp-sub)">Highest precedence</text>
57 {LEVELS.map((l, i) => {
58 const y = TOP + i * (ROW + GAP);
59 const x = cx - l.w / 2;
60 const top = i === 0;
61 return <g key={l.n}>
62 <rect x={x} y={y} width={l.w} height={ROW} rx={10} fill={top ? 'var(--sp-top-fill)' : 'var(--sp-fill)'} stroke={top ? 'var(--sp-top)' : 'var(--sp-stroke)'} strokeWidth={top ? 1.5 : 1} />
63 <text x={x + 14} y={y + 24} fontFamily={sans} fontSize="14" fontWeight="600" fill="var(--sp-text)">{l.n}. {l.name}</text>
64 <text x={x + 14} y={y + 43} fontFamily={mono} fontSize="11.5" fill="var(--sp-sub)">{l.file}</text>
65 <text x={x + l.w - 14} y={y + 24} textAnchor="end" fontFamily={sans} fontSize="12" fill="var(--sp-faint)">{l.who}</text>
66 </g>;
67 })}
68 <text x={cx} y={H - 10} textAnchor="middle" fontFamily={sans} fontSize="12.5" fontWeight="600" fill="var(--sp-sub)">Lowest precedence</text>
69 <g stroke="var(--sp-arrow)" strokeWidth="1.5" fill="none">
70 <line x1={W - 40} y1={TOP + 10} x2={W - 40} y2={H - 38} />
71 <path d={`M ${W - 46} ${TOP + 18} L ${W - 40} ${TOP + 10} L ${W - 34} ${TOP + 18}`} />
72 </g>
73 <text x={W - 40} y={H - 22} textAnchor="middle" fontFamily={sans} fontSize="10.5" fill="var(--sp-faint)">overrides</text>
74 </svg>
75 </div>;
76};
77
78export const SettingsScope = ({defaultSelected = 'project'}) => {
79 const FILES = [{
80 id: 'user',
81 path: '~/.claude/settings.json'
82 }, {
83 id: 'project',
84 path: 'acme-app/.claude/settings.json'
85 }, {
86 id: 'local',
87 path: 'acme-app/.claude/settings.local.json'
88 }, {
89 id: 'managed',
90 path: 'Managed settings',
91 ring: 'managed-settings.json, MDM, or the claude.ai console'
92 }];
93 const SHORT = {
94 user: '~/.claude/settings.json',
95 project: 'acme-app/.claude/settings.json',
96 local: 'acme-app/.claude/settings.local.json',
97 managed: 'managed-settings.json, MDM, or the claude.ai console'
98 };
99 const TILE_MARK = {
100 project: 'settings.json',
101 local: 'settings.local.json'
102 };
103 const initial = FILES.some(f => f.id === defaultSelected) ? defaultSelected : 'project';
104 const [sel, setSel] = useState(initial);
105 const [scale, setScale] = useState(1);
106 const [isFullscreen, setIsFullscreen] = useState(false);
107 const rootRef = useRef(null);
108 const frameRef = useRef(null);
109 const CANVAS_W = 862;
110 const CANVAS_H = 240;
111 useEffect(() => {
112 const el = frameRef.current;
113 if (!el) return;
114 const measure = () => setScale(Math.min(1, el.clientWidth / CANVAS_W));
115 measure();
116 if (typeof ResizeObserver === 'undefined') {
117 window.addEventListener('resize', measure);
118 return () => window.removeEventListener('resize', measure);
119 }
120 const ro = new ResizeObserver(measure);
121 ro.observe(el);
122 return () => ro.disconnect();
123 }, []);
124 useEffect(() => {
125 const onFsChange = () => setIsFullscreen(!!document.fullscreenElement);
126 document.addEventListener('fullscreenchange', onFsChange);
127 return () => document.removeEventListener('fullscreenchange', onFsChange);
128 }, []);
129 const toggleFullscreen = () => {
130 if (!rootRef.current) return;
131 if (document.fullscreenElement) document.exitFullscreen(); else rootRef.current.requestFullscreen().catch(() => {});
132 };
133 const COVERAGE = {
134 user: ['website', 'api', 'yacme'],
135 project: ['yacme', 'tacme', 'cacme'],
136 local: ['yacme'],
137 managed: ['website', 'api', 'yacme', 'tacme', 'cacme']
138 };
139 const RINGS = {
140 local: {
141 l: 282,
142 t: 50,
143 w: 142,
144 h: 124
145 },
146 project: {
147 l: 282,
148 t: 50,
149 w: 560,
150 h: 124
151 },
152 user: {
153 l: 2,
154 t: 34,
155 w: 446,
156 h: 198
157 },
158 managed: {
159 l: 0,
160 t: 32,
161 w: 862,
162 h: 204
163 }
164 };
165 const TILES = [{
166 id: 'website',
167 name: 'website/',
168 left: 30,
169 caption: ''
170 }, {
171 id: 'api',
172 name: 'api/',
173 left: 160,
174 caption: ''
175 }, {
176 id: 'yacme',
177 name: 'acme-app/',
178 left: 290,
179 caption: ''
180 }, {
181 id: 'tacme',
182 name: 'acme-app/',
183 left: 497,
184 caption: sel === 'project' ? 'their clone, once you commit the file' : 'their clone'
185 }, {
186 id: 'cacme',
187 name: 'acme-app/',
188 left: 704,
189 caption: sel === 'project' ? 'fresh clone, once you commit the file' : sel === 'managed' ? 'server-managed only' : 'fresh clone'
190 }];
191 const FILE_AT = {
192 user: {
193 machine: 'you',
194 tiles: []
195 },
196 project: {
197 machine: null,
198 tiles: ['yacme', 'tacme', 'cacme']
199 },
200 local: {
201 machine: null,
202 tiles: ['yacme']
203 },
204 managed: {
205 machine: null,
206 tiles: []
207 }
208 };
209 const fileAt = FILE_AT[sel];
210 const coverage = COVERAGE[sel];
211 const ring = RINGS[sel];
212 const selFile = FILES.find(f => f.id === sel);
213 const FolderIcon = ({open}) => <svg width="15" height="15" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinejoin="round" aria-hidden="true">
214 <path d="M1.5 4.5a1 1 0 0 1 1-1h3.2l1.3 1.5h6a1 1 0 0 1 1 1V12a1 1 0 0 1-1 1h-10.5a1 1 0 0 1-1-1z" />
215 {open && <path d="M1.5 7.5h13" />}
216 </svg>;
217 const FileIcon = () => <svg width="10" height="10" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinejoin="round" aria-hidden="true">
218 <path d="M4 1.5h5.5L13 5v9.5H4z" />
219 <path d="M9.5 1.5V5H13" />
220 </svg>;
221 const CloudIcon = () => <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinejoin="round" aria-hidden="true">
222 <path d="M4.5 12.5h7a2.5 2.5 0 0 0 .4-4.97A3.5 3.5 0 0 0 5.2 6.6 3 3 0 0 0 4.5 12.5z" />
223 </svg>;
224 const LaptopIcon = () => <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinejoin="round" aria-hidden="true">
225 <rect x="2.5" y="3" width="11" height="7.5" rx="1" />
226 <path d="M1 12.5h14" />
227 </svg>;
228 return <div ref={rootRef} className={'ssc-root not-prose' + (isFullscreen ? ' ssc-fs' : '')}>
229 <style>{`
230 .ssc-root {
231 --ssc-bg: #FFFFFF;
232 --ssc-text: #1A1918;
233 --ssc-sub: #5E5D59;
234 --ssc-faint: #8A8880;
235 --ssc-border: rgba(0,0,0,0.12);
236 --ssc-panel: #F5F4EF;
237 --ssc-tile: #FAFAF8;
238 --ssc-clay: #D97757;
239 --ssc-clay-bg: rgba(217,119,87,0.14);
240 --ssc-label: #B0562F;
241 --ssc-hover: rgba(115,114,108,0.10);
242 font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
243 background: var(--ssc-bg);
244 color: var(--ssc-text);
245 border: 1px solid var(--ssc-border);
246 border-radius: 16px;
247 padding: 20px 24px 24px;
248 margin: 1.5rem 0;
249 box-sizing: border-box;
250 }
251 .dark .ssc-root {
252 --ssc-bg: #1B1A18;
253 --ssc-text: #F1EFE9;
254 --ssc-sub: #B8B5AD;
255 --ssc-faint: #8A8880;
256 --ssc-border: rgba(255,255,255,0.12);
257 --ssc-panel: #24231F;
258 --ssc-tile: #2A2925;
259 --ssc-clay-bg: rgba(217,119,87,0.20);
260 --ssc-label: #EBC9B7;
261 }
262 .ssc-fs { display: flex; flex-direction: column; justify-content: center; align-items: center; margin: 0; border-radius: 0; height: 100vh; }
263 .ssc-fs .ssc-head { width: 100%; max-width: ${CANVAS_W}px; }
264 .ssc-fs .ssc-frame { width: 100%; }
265 .ssc-mono { font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace); }
266 .ssc-head { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; margin-bottom: 20px; }
267 .ssc-files { display: flex; gap: 8px; flex-wrap: wrap; }
268 .ssc-file {
269 font-size: 12.5px; font-weight: 430; padding: 8px 13px; border-radius: 10px; cursor: pointer;
270 border: 0.5px solid var(--ssc-border); background: var(--ssc-tile); color: var(--ssc-text);
271 white-space: nowrap; transition: background 0.2s, border-color 0.2s;
272 }
273 .ssc-file:hover { filter: brightness(0.97); }
274 .ssc-file[aria-pressed="true"] { font-weight: 600; border: 1.5px solid var(--ssc-clay); background: var(--ssc-clay-bg); }
275 .ssc-fsbtn {
276 display: flex; align-items: center; justify-content: center; width: 28px; height: 28px; flex-shrink: 0;
277 border: none; background: none; border-radius: 6px; cursor: pointer; color: var(--ssc-faint); font-size: 15px;
278 }
279 .ssc-fsbtn:hover { background: var(--ssc-hover); }
280 .ssc-frame { width: 100%; max-width: ${CANVAS_W}px; margin: 0 auto; }
281 .ssc-canvas { position: relative; width: ${CANVAS_W}px; height: ${CANVAS_H}px; transform-origin: top left; }
282 .ssc-machine { position: absolute; top: 42px; height: 182px; background: var(--ssc-panel); border-radius: 16px; }
283 .ssc-machine-label { position: absolute; top: 192px; display: flex; align-items: center; gap: 8px; font-size: 13.5px; font-weight: 600; }
284 .ssc-tile {
285 position: absolute; top: 58px; width: 126px; height: 108px; border-radius: 12px; padding: 11px 12px; box-sizing: border-box;
286 background: var(--ssc-tile); border: 0.5px solid var(--ssc-border); opacity: 0.6;
287 transition: background 0.25s, border-color 0.25s, opacity 0.25s;
288 }
289 .ssc-tile.ssc-on { background: var(--ssc-clay-bg); border: 1px solid var(--ssc-clay); opacity: 1; }
290 .ssc-tile-name { display: flex; align-items: center; gap: 6px; color: var(--ssc-faint); }
291 .ssc-tile.ssc-on .ssc-tile-name { color: var(--ssc-clay); }
292 .ssc-tile-name span { font-size: 12px; font-weight: 430; white-space: nowrap; color: var(--ssc-text); }
293 .ssc-tile.ssc-on .ssc-tile-name span { font-weight: 600; }
294 .ssc-tile-caption { font-size: 10.5px; color: var(--ssc-sub); margin-top: 5px; line-height: 1.35; }
295 .ssc-filemark {
296 position: absolute; left: 5px; right: 5px; bottom: 8px; display: inline-flex; align-items: center; justify-content: center; gap: 2px;
297 font-size: 8.5px; color: var(--ssc-label); background: var(--ssc-bg); border: 1px solid var(--ssc-clay);
298 border-radius: 6px; padding: 2px 3px; white-space: nowrap; overflow: hidden;
299 }
300 .ssc-filemark svg { flex-shrink: 0; }
301 .ssc-machine-filemark { display: inline-flex; align-items: center; gap: 4px; margin-left: 10px; font-size: 10.5px; font-weight: 500; color: var(--ssc-label); }
302 .ssc-ring {
303 position: absolute; border: 2px solid var(--ssc-clay); border-radius: 18px; pointer-events: none;
304 transition: left 0.35s ease, top 0.35s ease, width 0.35s ease, height 0.35s ease;
305 }
306 .ssc-ring-label {
307 position: absolute; font-size: 12px; font-weight: 600; color: var(--ssc-label); white-space: nowrap; pointer-events: none;
308 transition: left 0.35s ease, top 0.35s ease;
309 }
310 `}</style>
311
312 <div className="ssc-head">
313 <div className="ssc-files" role="group" aria-label="Settings file">
314 {FILES.map(f => <button key={f.id} type="button" className="ssc-file ssc-mono" aria-pressed={f.id === sel} onClick={() => setSel(f.id)}>{f.path}</button>)}
315 </div>
316 <button type="button" className="ssc-fsbtn" onClick={toggleFullscreen} aria-label={isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'} title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}>{isFullscreen ? '⤡' : '⛶'}</button>
317 </div>
318
319 <div ref={frameRef} className="ssc-frame" style={{
320 height: CANVAS_H * scale + 'px'
321 }}>
322 <div className="ssc-canvas" style={{
323 transform: 'scale(' + scale + ')'
324 }}>
325 <div className="ssc-machine" style={{
326 left: '10px',
327 width: '430px'
328 }} />
329 <span className="ssc-machine-label" style={{
330 left: '30px'
331 }}><LaptopIcon />Your machine{fileAt.machine === 'you' && <span className="ssc-machine-filemark ssc-mono"><FileIcon />{selFile.path}</span>}</span>
332 <div className="ssc-machine" style={{
333 left: '460px',
334 width: '200px'
335 }} />
336 <span className="ssc-machine-label" style={{
337 left: '470px'
338 }}><LaptopIcon />A teammate’s machine</span>
339 <div className="ssc-machine" style={{
340 left: '682px',
341 width: '170px'
342 }} />
343 <span className="ssc-machine-label" style={{
344 left: '692px'
345 }}><CloudIcon />A cloud session</span>
346
347 {TILES.map(t => {
348 const on = coverage.includes(t.id);
349 return <div key={t.id} className={'ssc-tile' + (on ? ' ssc-on' : '')} style={{
350 left: t.left + 'px'
351 }}>
352 <div className="ssc-tile-name"><FolderIcon open={on} /><span className="ssc-mono">{t.name}</span></div>
353 {t.caption && <div className="ssc-tile-caption">{t.caption}</div>}
354 {fileAt.tiles.includes(t.id) && <span className="ssc-filemark ssc-mono" title={SHORT[sel]}><FileIcon />{TILE_MARK[sel]}</span>}
355 </div>;
356 })}
357
358 <div className="ssc-ring" style={{
359 left: ring.l + 'px',
360 top: ring.t + 'px',
361 width: ring.w + 'px',
362 height: ring.h + 'px'
363 }} />
364 <span className="ssc-ring-label ssc-mono" style={{
365 left: ring.l + 14 + 'px',
366 top: ring.t - 26 + 'px'
367 }}>{selFile.ring || selFile.path}</span>
368 </div>
369 </div>
370 </div>;
371};
372
373设置是改变 Claude Code 行为方式的 JSON 键：它启动时使用的模型、它可以在不询问的情况下运行的内容、它无法读取的文件、它在终端中的外观，以及您的组织强制执行的内容。
374
375<Tip>
376 要查找特定键，请转到[所有设置](/docs/zh-CN/settings-reference)，其中列出了每个键、设置它的文件、其默认值和示例。
377</Tip>
378
379Claude Code 从 JSON 设置文件（如 `~/.claude/settings.json`）读取设置。它在几个位置查找它们，[它读取设置的文件决定了设置适用于谁](#settings-files-and-who-they-affect)。本页涵盖这些文件：将设置放在哪个文件中、如何更改设置并确认它已应用，以及当同一键在多个文件中设置时 Claude Code 使用哪个值。[配置权限](/docs/zh-CN/permissions)涵盖 Claude Code 可以在不询问的情况下运行的内容以及如何编写 `allow`、`ask` 和 `deny` 规则。
20 380
21| 作用域 | 位置 | 影响范围 | 与团队共享？ |381<Note>
22| :---------- | :----------------------------------------------- | :---------------------------------------------------------- | :------------ |382 本页涵盖在您的机器上运行的 Claude Code：终端、[VS Code](/docs/zh-CN/vs-code) 和 [JetBrains](/docs/zh-CN/jetbrains) 扩展，以及[桌面应用](/docs/zh-CN/desktop)，它们都读取相同的设置文件。[Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 上的云会话在不同的机器上运行并仅读取其中一些；请参阅[云会话中的设置](#settings-in-cloud-sessions)。
23| **Managed** | 服务器管理的设置、plist / 注册表或系统级 `managed-settings.json` | 服务器管理交付的所有组织成员；plist、HKLM 注册表和文件交付的机器上的所有用户；HKCU 注册表交付的当前用户 | 是（由 IT 部署） |383</Note>
24| **User** | `~/.claude/` 目录 | 您，跨所有项目 | 否 |
25| **Project** | 存储库中的 `.claude/` | 此存储库上的所有协作者 | 是（提交到 git） |
26| **Local** | `.claude/settings.local.json` | 您，仅在此存储库中 | 否（gitignored） |
27 384
28<h3 id="when-to-use-each-scope">385<span id="settings-files" />
29 何时使用每个作用域
30</h3>
31 386
32**Managed 作用域**用于：387<span id="configuration-scopes" />
33 388
34* 必须在整个组织范围内强制执行的安全策略389<span id="available-scopes" />
35* 无法被覆盖的合规要求
36* 由 IT/DevOps 部署的标准化配置
37 390
38**User 作用域**最适合：391<span id="when-to-use-each-scope" />
39 392
40* 您想在任何地方使用的个人偏好设置（主题、编辑器设置）393<span id="what-uses-scopes" />
41* 您在所有项目中使用的工具和插件
42* API 密钥和身份验证（安全存储）
43 394
44**Project 作用域**最适合：395<span id="subagent-configuration" />
45 396
46* 团队共享的设置（权限、hooks、MCP servers）397<span id="where-settings-live" />
47* 整个团队应该拥有的插件
48* 跨协作者标准化工具
49 398
50**Local 作用域**最适合：399<h2 id="settings-files-and-who-they-affect">
400 设置文件及其影响范围
401</h2>
51 402
52* 特定项目的个人覆盖403Claude Code 从四个文件读取设置，组织也可以从 claude.ai 控制台提供托管设置。每个来源都有一个范围：设置应用的人员和项目集合，可能是仅你、项目中的所有人或组织中的所有人。
53* 在与团队共享之前测试配置
54* 对其他人不适用的特定于机器的设置
55 404
56<h3 id="how-scopes-interact">405| 范围 | 文件 | 影响对象 | 用途 |
57 作用域如何相互作用406| :--- | :----------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :-------------------------- |
58</h3>407| 用户 | `~/.claude/settings.json` | 你，在这台机器上的每个项目中 | 个人偏好：主题、编辑器模式、默认模型、你自己的权限规则 |
408| 共享项目 | `.claude/settings.json` | 所有在包含该文件的文件夹中工作的人。在 git 仓库中，提交它以便队友获得它 | 团队权限、hooks、插件和项目需要的环境变量 |
409| 项目本地 | `.claude/settings.local.json` | 仅你，在这个项目中。Claude Code 在创建文件时将其排除在 git 之外；如果你手动创建它，自己将其添加到 `.gitignore` | 一个项目的个人覆盖，以及在共享前的测试 |
410| 托管 | `managed-settings.json` 和其他[托管来源](/docs/zh-CN/managed-settings#delivery-mechanisms) | 你的组织部署到的所有人；你设置的任何内容都不会覆盖它，除了少数[安全敏感的例外](#exceptions-to-managed-settings-precedence) | 安全策略和合规要求 |
59 411
60当在多个作用域中出现相同的设置时，Claude Code 按优先级顺序应用它们：412在"文件"列中，`~/.claude` 是你主目录中的 `.claude` 文件夹，而单独的 `.claude` 是项目内的 `.claude` 文件夹。
61 413
621. **Managed**（最高）- 无法被任何内容覆盖414<span id="where-each-file-applies" />
632. **命令行参数** - 临时会话覆盖
643. **Local** - 覆盖项目和用户设置
654. **Project** - 覆盖用户设置
665. **User**（最低）- 当没有其他内容指定设置时应用
67 415
68例如，如果您的用户设置将 `spinnerTipsEnabled` 设置为 `true`，而项目设置将其设置为 `false`，则项目值适用。权限规则的行为不同，因为它们跨作用域合并而不是覆盖。请参阅 [Settings precedence](#settings-precedence)。416<span id="compare-what-each-file-reaches" />
69 417
70<h3 id="what-uses-scopes">418<h3 id="compare-the-scope-of-each-settings-file">
71 哪些功能使用作用域419 比较每个设置文件的范围
72</h3>420</h3>
73 421
74作用域适用于许多 Claude Code 功能：422假设你的机器上有三个项目 `website/`、`api/` 和 `acme-app/`，一个队友有他们自己的 `acme-app/` 克隆，你在 `acme-app/` 上启动了一个[云会话](#settings-in-cloud-sessions)。
75
76| 功能 | User 位置 | Project 位置 | Local 位置 |
77| :-------------- | :------------------------ | :-------------------------------- | :---------------------------- |
78| **Settings** | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |
79| **Subagents** | `~/.claude/agents/` | `.claude/agents/` | 无 |
80| **MCP servers** | `~/.claude.json` | `.mcp.json` | `~/.claude.json`（每个项目） |
81| **Plugins** | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |
82| **CLAUDE.md** | `~/.claude/CLAUDE.md` | `CLAUDE.md` 或 `.claude/CLAUDE.md` | `CLAUDE.local.md` |
83
84在 Windows 上，显示为 `~/.claude` 的路径解析为 `%USERPROFILE%\.claude`。
85 423
86***424下面的图表显示当你从这些文件夹启动 Claude Code 时，设置应用在哪些文件夹中。点击一个设置文件以查看它到达的文件夹。
87 425
88<h2 id="settings-files">426<SettingsScope />
89 设置文件
90</h2>
91
92`settings.json` 文件是通过分层设置配置 Claude Code 的官方机制：
93
94* **用户设置**在 `~/.claude/settings.json` 中定义，适用于所有项目。
95* **项目设置**保存在您的项目目录中：
96 * `.claude/settings.json` 用于检入源代码管理并与您的团队共享的设置
97 * `.claude/settings.local.json` 用于未检入的设置，适用于个人偏好和实验。Claude Code 创建 `.claude/settings.local.json` 时，会配置 git 以忽略该文件。如果您自己创建该文件，请手动将其添加到 gitignore。
98
99 因为此文件属于您而不是存储库，其权限 `allow` 规则生效时无需 [workspace trust](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust) 步骤，而 `.claude/settings.json` allow 规则需要此步骤。如果存储库提供该文件，例如通过提交它，workspace trust 仍然适用。
100* **Managed 设置**：对于需要集中控制的组织，Claude Code 支持多种 managed 设置的交付机制。所有机制都使用相同的 JSON 格式，无法被用户或项目设置覆盖：
101
102 * **服务器管理的设置**：通过 Anthropic 的服务器从 claude.ai 管理员控制台交付，或从自托管的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway)。请参阅[服务器管理的设置](/docs/zh-CN/server-managed-settings)。
103 * **MDM/OS 级别策略**：通过 macOS 和 Windows 上的本机设备管理交付：
104 * macOS：`com.anthropic.claudecode` managed preferences 域。plist 的顶级键镜像 `managed-settings.json`，嵌套设置为字典，数组为 plist 数组。通过 Jamf、Iru (Kandji) 或类似 MDM 工具中的配置文件部署。
105 * Windows：`HKLM\SOFTWARE\Policies\ClaudeCode` 注册表项，带有包含 JSON 的 `Settings` 值（REG\_SZ 或 REG\_EXPAND\_SZ）（通过组策略或 Intune 部署）
106 * Windows（用户级）：`HKCU\SOFTWARE\Policies\ClaudeCode`（最低策略优先级，仅在不存在管理员级源时使用）
107 * **基于文件**：`managed-settings.json` 和 `managed-mcp.json` 部署到系统目录：
108 427
109 * macOS：`/Library/Application Support/ClaudeCode/`428* **`~/.claude/settings.json`**：你机器上的每个项目，以及队友或云会话中的任何内容都不会
110 * Linux 和 WSL：`/etc/claude-code/`429* **`acme-app/.claude/settings.json`**：你的 `acme-app/`。只有当你将文件提交到版本控制时，它才会到达你队友的克隆和云会话；在此之前，它就像任何其他文件一样在你的磁盘上，没有人有它
111 * Windows：`C:\Program Files\ClaudeCode\`430* **`acme-app/.claude/settings.local.json`**：仅你的 `acme-app/`。Claude Code 第一次写入文件时将其添加到你的全局 git 排除项，所以它不会进入你的提交；如果你手动创建文件，[自己将其添加到 `.gitignore`](#keep-personal-settings-out-of-a-repository)
431* **托管设置**，无论是 `managed-settings.json` 文件、MDM 策略还是来自 claude.ai 控制台的[服务器托管设置](/docs/zh-CN/server-managed-settings)：你的组织部署到的每台机器上的每个项目，或你使用组织账户登录的地方。只有服务器托管设置才能到达云会话
112 432
113 <Warning>433<span id="which-files-you-have" />
114 自 v2.1.75 起，不再支持旧的 Windows 路径 `C:\ProgramData\ClaudeCode\managed-settings.json`。已将设置部署到该位置的管理员必须将文件迁移到 `C:\Program Files\ClaudeCode\managed-settings.json`。
115 </Warning>
116 434
117 基于文件的 managed 设置还支持在与 `managed-settings.json` 相同的系统目录中的 `managed-settings.d/` 放入目录。这让独立的团队可以部署独立的策略片段，而无需协调对单个文件的编辑。435<h3 id="find-or-create-your-settings-files">
118 436 查找或创建你的设置文件
119 遵循 systemd 约定，`managed-settings.json` 首先作为基础合并，然后放入目录中的所有 `*.json` 文件按字母顺序排序并合并在顶部。对于标量值，后面的文件覆盖前面的文件；数组被连接和去重；对象被深度合并。以 `.` 开头的隐藏文件被忽略。437</h3>
120
121 使用数字前缀来控制合并顺序，例如 `10-telemetry.json` 和 `20-security.json`。
122 438
123 请参阅 [managed 设置](/docs/zh-CN/permissions#managed-only-settings) 和 [Managed MCP 配置](/docs/zh-CN/managed-mcp) 了解详情。439安装 Claude Code 不会创建任何设置文件。如果你的机器或项目已经有一个，它来自以下来源之一：
124 440
125 此[存储库](https://github.com/anthropics/claude-code/tree/main/examples/mdm)包含 Jamf、Iru (Kandji)、Intune 和组策略的启动部署模板。使用这些作为起点并根据您的需求进行调整。441* **托管**：你的组织部署它。你不创建或编辑它。
442* **共享项目**：已经使用 Claude Code 的项目可能有一个已提交。如果没有，在项目文件夹中的 `.claude/settings.json` 处创建它。
443* **用户**和**项目本地**：自己创建它们，或让 Claude Code 创建它们。当你在 `/config` 菜单中更改存储在用户设置中的选项（如主题）时，它会写入 `~/.claude/settings.json`，当你在权限提示上给予常设批准时（如对 Bash 命令的"是的，不要再问"），它会写入 `.claude/settings.local.json`。一些 `/config` 选项，包括**显示提示**，保存到 `.claude/settings.local.json` 而不是用户文件。
126 444
127 <Note>445<Info>
128 Managed 部署还可以使用 `strictKnownMarketplaces` 限制**插件市场添加**。有关更多信息，请参阅 [Managed 市场限制](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions)。446 在 Windows 上，`~/.claude` 表示 `%USERPROFILE%\.claude`。要将主目录文件保存在其他地方，设置 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars)；Claude Code 然后将你的设置、会话历史和插件存储在那里。
129 </Note>447</Info>
130* **其他配置**存储在 `~/.claude.json` 中。此文件包含您的 OAuth 会话、[MCP server](/docs/zh-CN/mcp) 配置（用于用户和本地作用域）、每个项目的状态（允许的工具、信任设置）和各种缓存。项目作用域的 MCP servers 单独存储在 `.mcp.json` 中。
131 448
132<Note>449Claude Code 还保留第五个文件 [`~/.claude.json`](/docs/zh-CN/claude-directory#ce-claude-json)，它为自己写入；你不需要编辑它。它保存你的登录会话、[MCP 服务器](/docs/zh-CN/mcp)配置、每个项目的状态（如信任决定）和 `/config` 为你写入的[全局配置键](/docs/zh-CN/settings-reference#global-config-settings)。
133 Claude Code 自动创建配置文件的时间戳备份，并保留最近五个备份以防止数据丢失。
134</Note>
135 450
136```JSON Example settings.json theme={null}451<h3 id="share-settings-with-your-team">
137{452 与你的团队共享设置
138 "$schema": "https://json.schemastore.org/claude-code-settings.json",453</h3>
139 "permissions": {
140 "allow": [
141 "Bash(npm run lint)",
142 "Bash(npm run test *)",
143 "Read(~/.zshrc)"
144 ],
145 "deny": [
146 "Bash(curl *)",
147 "Read(./.env)",
148 "Read(./.env.*)",
149 "Read(./secrets/**)"
150 ]
151 },
152 "env": {
153 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
154 "OTEL_METRICS_EXPORTER": "otlp"
155 },
156 "companyAnnouncements": [
157 "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
158 "Reminder: Code reviews required for all PRs",
159 "New security policy in effect"
160 ]
161}
162```
163 454
164上面示例中的 `$schema` 行指向 Claude Code 设置的[官方 JSON 架构](https://json.schemastore.org/claude-code-settings.json)。将其添加到您的 `settings.json` 可在 VS Code、Cursor 和任何其他支持 JSON 架构验证的编辑器中启用自动完成和内联验证。455提交 `.claude/settings.json` 以便克隆仓库的每个人都获得相同的权限、hooks、遥测和插件。每个队友仍然可以在他们自己的 `.claude/settings.local.json` 中为自己覆盖它，所以个人例外不需要提交。有关完整的团队文件，请参阅[团队的共享设置](/docs/zh-CN/settings-example#a-teams-shared-settings)。
165 456
166已发布的架构会定期更新，可能不包括最近 CLI 版本中添加的设置，因此最近记录的字段上的验证警告不一定意味着您的配置无效。457你提交的一些内容等待每个队友[信任文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)，少数键永远不会从仓库文件生效；[排查不适用的设置](#common-cases)涵盖两者。
167 458
168<h3 id="when-edits-take-effect">459<span id="local-settings-file" />
169 编辑何时生效
170</h3>
171 460
172Claude Code 监视您的设置文件，并在它们更改时重新加载它们，因此对大多数键的编辑会在运行的会话中应用，无需重启。这包括 `permissions`、`hooks` 和凭证助手（如 `apiKeyHelper`）。重新加载涵盖用户、项目、本地和 managed 设置，并为每个检测到的更改触发 [`ConfigChange` hook](/docs/zh-CN/hooks#configchange)。461<span id="where-claude-code-saves-the-project-local-file" />
173 462
174少数几个键在会话启动时读取一次，并在下次重启时应用：463<span id="the-project-local-file" />
175 464
176* `model`：使用 [`/model`](/docs/zh-CN/model-config#setting-your-model) 在会话中切换465<span id="keep-personal-settings-out-of-the-repository" />
177* [`outputStyle`](/docs/zh-CN/output-styles)：系统提示的一部分，在 `/clear` 或重启时重建
178 466
179<h3 id="invalid-entries-in-managed-settings">467<h3 id="keep-personal-settings-out-of-a-repository">
180 Managed 设置中的无效条目468 将个人设置保留在仓库之外
181</h3>469</h3>
182 470
183Managed 设置宽容地解析。当 managed 配置包含验证架构失败的条目时，Claude Code 会删除该条目，记录警告，并强制执行所有剩余的有效策略。单个拼写错误无法禁用组织的其余策略。运行 [`/doctor`](/docs/zh-CN/debug-your-config#check-resolved-settings) 以列出被删除的条目及其源文件和字段。此行为在所有三种交付机制中一致：[服务器管理的设置](/docs/zh-CN/server-managed-settings)、通过 MDM 部署的 plist 和注册表策略，以及 `managed-settings.json` 文件。需要 Claude Code v2.1.169 或更高版本。471要在一个项目中为自己更改设置而不为队友更改它，将其保存在项目内的 `.claude/settings.local.json` 中。Claude Code 在提交的 `.claude/settings.json` 上应用该文件，所以如果你的团队文件设置 `"model": "claude-sonnet-5"` 而你想要 Opus，在你的本地文件中放入 `"model": "claude-opus-4-8"`，只有你的会话会改变。
184 472
185安全强制字段按字段处理，而不是在存在但无效时被整体删除：473关于本地文件有三件事要知道：
186 474
187| 字段 | 存在但无效时的行为 |475* **Claude Code 也写入它。** 当 Claude 要求权限运行 Bash 命令而你选择"是的，不要再问"时，Claude Code 将该[权限批准](/docs/zh-CN/permissions#permission-system)保存为 `allow` 规则。
188| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------ |476* **你不需要自己 gitignore 它，除非你手动创建了它。** Claude Code 第一次在不已经忽略它的 git 仓库中写入文件时，它将 `**/.claude/settings.local.json` 添加到你的全局 git 排除文件，所以该文件在每个仓库中都不会进入你的提交。该文件是 `core.excludesFile`，当你的全局 git 配置将其设置为绝对路径或 `~` 前缀路径时；否则它是 `$XDG_CONFIG_HOME/git/ignore`，或当 `XDG_CONFIG_HOME` 未设置时是 `~/.config/git/ignore`。如果你手动创建了文件而 Claude Code 还没有写入它，自己将其添加到 `.gitignore`。
189| `allowedMcpServers` | 作为空允许列表强制执行，因此在修复值之前不允许任何 MCP servers。单个无效条目被删除，有效子集被强制执行。 |477* **其 allow 规则在文件保持未跟踪时不等待信任。** 因为文件是你的而不是仓库的，Claude Code 应用其 `allow` 规则而不需要它对提交文件要求的[工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)步骤。如果文件由 git 跟踪，信任步骤也适用于它；请参阅[当你的本地设置文件需要信任](/docs/zh-CN/permissions#when-your-local-settings-file-needs-trust)。
190| `allowManagedMcpServersOnly` | 视为 `true`。 |
191| `availableModels` | 作为空允许列表强制执行，因此在修复值之前仅默认模型可用。单个非字符串条目被删除，有效子集被强制执行。适用于 v2.1.175 及更高版本。 |
192| `enforceAvailableModels` | 视为 `true`。适用于 v2.1.175 及更高版本。 |
193| `forceLoginOrgUUID` | 在修复值之前不允许任何组织登录。 |
194| `deniedMcpServers` | 单个无效条目被删除，有效子集被强制执行。完全无效的值被丢弃并显示警告，因为拒绝每个 server 会阻止策略从未命名的 servers。 |
195| `sandbox.credentials` | 在 `files` 或 `envVars` 中的单个无效条目被删除并显示警告，有效子集被强制执行。完全无效的 `credentials` 值被丢弃并显示警告，同时 `sandbox` 的其余部分仍然适用。适用于 v2.1.191 及更高版本。 |
196 478
197`requiredMinimumVersion` 和 `requiredMaximumVersion` 通过设计失败开放：无效值被删除而不是强制执行，因此坏策略推送无法阻止 Claude Code 启动。479<span id="where-claude-code-looks-for-each-file" />
198 480
199验证错误出现在三个地方：481<span id="how-claude-code-keeps-the-local-file-out-of-git" />
200 482
201* 交互式会话在启动时显示列出无效条目的对话框。483<span id="local-allow-rules-dont-wait-for-workspace-trust" />
202* 使用 `-p` 的无头运行将摘要打印到 stderr。
203* [`claude doctor`](/docs/zh-CN/debug-your-config) 列出每个无效条目及其源和字段。
204 484
205在将策略更改部署到整个机队之前，在测试机器上运行 `claude doctor` 来验证策略更改。485<h4 id="where-claude-code-keeps-the-local-file-in-a-git-repository">
486 Claude Code 在 git 仓库中保留本地文件的位置
487</h4>
206 488
207此容限仅适用于 managed 设置。用户、项目和本地设置文件保持严格：验证失败的文件被整体拒绝并报告。489当 Claude 要求权限运行 Bash 命令而你选择"是的，不要再问"时，Claude Code 将该批准保存为 `.claude/settings.local.json` 中的 `allow` 规则。如果你在 git 仓库的子目录中启动 Claude Code，它在仓库根目录读取和写入该文件，并在整个仓库中应用批准。在[工作树](/docs/zh-CN/worktrees)中，它使用主检出根目录处的文件。
208 490
209<h3 id="available-settings">491两条规则限定根位置：
210 可用设置
211</h3>
212 492
213`settings.json` 支持多个选项：493* **当文件与 `.claude/settings.json` 保持在一起时**：在 git 仓库外，当仓库根是你的主目录时，在 Windows 上，或当仓库根或其 `.git` 或 `.claude` 条目不由你的用户拥有时。
214 494* **文件中的路径不在仓库根处锚定**：以 `/` 开头的权限规则或相对沙箱路径[在会话的主工作目录处锚定](/docs/zh-CN/permissions#read-and-edit)。
215| 键 | 描述 | 示例 |
216| :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ |
217| `advisorModel` | 服务器端 [advisor tool](/docs/zh-CN/advisor) 的模型。接受模型别名，如 `"opus"`、`"sonnet"` 或 `"fable"`（v2.1.170+），或完整模型 ID。当您运行 `/advisor` 时自动写入。取消设置以禁用 advisor | `"opus"` |
218| `agent` | 将主线程作为命名 subagent 运行，并为从 `claude agents` 分派的会话设置默认 agent。应用该 subagent 的系统提示、工具限制和模型。请参阅[显式调用 subagents](/docs/zh-CN/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |
219| `agentPushNotifEnabled` | **默认**：`false`。当[远程控制](/docs/zh-CN/remote-control)已连接时，允许 Claude 向您的手机发送主动推送通知，例如当长任务完成时。在 `/config` 中显示为**Claude 决定时推送**。请参阅[移动推送通知](/docs/zh-CN/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更高版本 | `true` |
220| `allowAllClaudeAiMcps` | （仅 Managed 设置）加载 claude.ai connectors 与部署的 `managed-mcp.json` 一起，否则后者会获得独占控制并抑制它们。请参阅 [Managed MCP 配置](/docs/zh-CN/managed-mcp) | `true` |
221| `allowedChannelPlugins` | （仅 Managed 设置）可能推送消息的频道插件的允许列表。设置后替换默认 Anthropic 允许列表。未定义 = 回退到默认值，空数组 = 阻止所有频道插件。需要 `channelsEnabled: true`。请参阅[限制哪些频道插件可以运行](/docs/zh-CN/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |
222| `allowedHttpHookUrls` | HTTP hooks 可能针对的 URL 模式的允许列表。支持 `*` 作为通配符。设置后，具有不匹配 URL 的 hooks 被阻止。未定义 = 无限制，空数组 = 阻止所有 HTTP hooks。数组跨设置源合并。请参阅 [Hook 配置](#hook-configuration) | `["https://hooks.example.com/*"]` |
223| `allowedMcpServers` | 在 managed-settings.json 中设置时，用户可以配置的 MCP servers 的允许列表。未定义 = 无限制，空数组 = 锁定。适用于所有作用域。拒绝列表优先。请参阅 [Managed MCP 配置](/docs/zh-CN/managed-mcp) | `[{ "serverName": "github" }]` |
224| `allowManagedHooksOnly` | （仅 Managed 设置）仅加载 managed hooks、SDK hooks 和在 managed 设置 `enabledPlugins` 中强制启用的插件中的 hooks。用户、项目和所有其他插件 hooks 被阻止。请参阅 [Hook 配置](#hook-configuration) | `true` |
225| `allowManagedMcpServersOnly` | （仅 Managed 设置）仅尊重来自 managed 设置的 `allowedMcpServers`。`deniedMcpServers` 仍从所有源合并。用户仍可以添加 MCP servers，但仅应用管理员定义的允许列表。请参阅 [Managed MCP 配置](/docs/zh-CN/managed-mcp) | `true` |
226| `allowManagedPermissionRulesOnly` | （仅 Managed 设置）防止用户和项目设置定义 `allow`、`ask` 或 `deny` 权限规则。仅应用 managed 设置中的规则。请参阅 [Managed 专用设置](/docs/zh-CN/permissions#managed-only-settings) | `true` |
227| `alwaysThinkingEnabled` | 为所有会话默认启用[扩展思考](/docs/zh-CN/model-config#extended-thinking)。通常通过 `/config` 命令而不是直接编辑来配置。要强制禁用思考，无论此设置如何，请在 `env` 中设置 [`MAX_THINKING_TOKENS=0`](/docs/zh-CN/env-vars)，这会禁用 Anthropic API 上的思考，除了 Fable 5，它无法关闭思考。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，这会省略 `thinking` 参数，自适应推理模型仍可能思考 | `true` |
228| `apiKeyHelper` | 自定义脚本，在系统 shell（macOS 和 Linux 上为 `/bin/sh`，Windows 上为 `cmd`）中运行，以生成身份验证值。此值将作为 `X-Api-Key` 和 `Authorization: Bearer` 标头发送用于模型请求。使用 [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/docs/zh-CN/env-vars) 设置刷新间隔 | `/bin/generate_temp_api_key.sh` |
229| `askUserQuestionTimeout` | **默认**：`"never"`。未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框自动继续的空闲时间，使用您已选择的任何选项。接受 `"60s"`、`"5m"`、`"10m"` 或 `"never"`。使用默认值，问题等待您回答。在 `/config` 中显示为**问题自动继续超时**，将此键写入用户设置。不从项目或本地设置读取。需要 Claude Code v2.1.200 或更高版本 | `"5m"` |
230| `attribution` | 自定义 git 提交和拉取请求的归属。请参阅[归属设置](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |
231| `autoCompactEnabled` | **默认**：`true`。当上下文接近限制时自动压缩对话。在 `/config` 中显示为**自动压缩**。要通过环境变量禁用，请在 `env` 中设置 [`DISABLE_AUTO_COMPACT`](/docs/zh-CN/env-vars) | `false` |
232| `autoMemoryDirectory` | [自动内存](/docs/zh-CN/memory#storage-location)存储的自定义目录。接受绝对路径或 `~/` 前缀的路径。从项目或本地设置接受，仅在您接受工作区信任对话框后，因为克隆的存储库可能提供此文件 | `"~/my-memory-dir"` |
233| `autoMemoryEnabled` | **默认**：`true`。启用[自动内存](/docs/zh-CN/memory#enable-or-disable-auto-memory)。当为 `false` 时，Claude 不从自动内存目录读取或写入。您也可以在会话期间使用 `/memory` 切换此选项。要通过环境变量禁用，请在 `env` 中设置 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/docs/zh-CN/env-vars) | `false` |
234| `autoMode` | 自定义[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器阻止和允许的内容。包含 `environment`、`allow`、`soft_deny` 和 `hard_deny` 散文规则数组。在数组中包含字面字符串 `"$defaults"` 以在该位置继承内置规则。请参阅[配置自动模式](/docs/zh-CN/auto-mode-config)。仅从用户设置、`--settings` 标志和 managed 设置读取。在项目 `.claude/settings.json` 和本地 `.claude/settings.local.json` 中被忽略。在 v2.1.207 之前，`.claude/settings.local.json` 也被读取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |
235| `autoMode.classifyAllShell` | **默认**：`false`。当为 `true` 时，在自动模式活跃时暂停每个 Bash 和 PowerShell 允许规则，以便所有 shell 命令通过分类器路由，而不仅仅是匹配任意代码执行模式的规则。请参阅[通过分类器路由所有 shell 命令](/docs/zh-CN/auto-mode-config#route-all-shell-commands-through-the-classifier)。需要 Claude Code v2.1.193 或更高版本 | `true` |
236| `autoScrollEnabled` | **默认**：`true`。在[全屏渲染](/docs/zh-CN/fullscreen)中，跟随新输出到对话的底部。在 `/config` 中显示为**自动滚动**。权限提示仍在此关闭时滚动到视图中 | `false` |
237| `autoUpdatesChannel` | **默认**：`"latest"`。遵循更新的发布渠道。使用 `"stable"` 获取通常约一周前的版本并跳过有主要回归的版本，或使用 `"latest"` 获取最新版本。要完全禁用自动更新，请在 `env` 中设置 [`DISABLE_AUTOUPDATER`](/docs/zh-CN/setup#disable-auto-updates) | `"stable"` |
238| `availableModels` | 限制用户可以为主会话、[subagents](/docs/zh-CN/sub-agents)、[skills](/docs/zh-CN/skills) 和 [advisor](/docs/zh-CN/advisor) 选择的模型。不影响默认选项，除非 `enforceAvailableModels` 也被设置。请参阅[限制模型选择](/docs/zh-CN/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |
239| `awaySummaryEnabled` | 在您离开终端几分钟后返回时显示单行会话回顾。设置为 `false` 或在 `/config` 中关闭会话回顾以禁用。与 [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/docs/zh-CN/env-vars) 相同 | `true` |
240| `awsAuthRefresh` | 修改 `.aws` 目录的自定义脚本（请参阅[高级凭证配置](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration)） | `aws sso login --profile myprofile` |
241| `awsCredentialExport` | 输出包含 AWS 凭证的 JSON 的自定义脚本（请参阅[高级凭证配置](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration)） | `/bin/generate_aws_grant.sh` |
242| `axScreenReader` | 渲染屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。屏幕阅读器模式使用经典渲染器，因此在其活跃时 `tui` 设置无效；附加的[后台会话](/docs/zh-CN/agent-view)仍渲染全屏。[`CLAUDE_AX_SCREEN_READER`](/docs/zh-CN/env-vars) 环境变量和 [`--ax-screen-reader`](/docs/zh-CN/cli-reference#cli-flags) 标志优先。需要 Claude Code v2.1.181 或更高版本 | `true` |
243| `blockedMarketplaces` | （仅 Managed 设置）市场源的阻止列表。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在设置策略之前添加的市场无法用于获取插件。被阻止的源在下载前被检查，因此它们永远不会接触文件系统。请参阅 [Managed 市场限制](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |
244| `browserExternalPageTools` | （仅 Managed 设置）设置为 `"disabled"` 以防止 Claude 使用工具读取或作用于桌面应用[浏览器窗格](/docs/zh-CN/desktop#browse-external-sites)中的外部页面。用户仍可以自己导航到外部站点，本地开发服务器预览不受影响 | `"disabled"` |
245| `channelsEnabled` | （仅 Managed 设置）为组织允许 [channels](/docs/zh-CN/channels)。在 claude.ai Team 和 Enterprise 计划上，当此项未设置或为 `false` 时，channels 被阻止。对于使用 API 密钥身份验证的 [Anthropic Console](/docs/zh-CN/authentication#claude-console-authentication) 账户，channels 默认被允许，除非您的组织部署 managed 设置，在这种情况下此键必须设置为 `true` | `true` |
246| `claudeMd` | （仅 Managed 设置）CLAUDE.md 风格的说明，作为组织管理的内存注入。仅在 managed 或策略设置中设置时被尊重，在用户、项目和本地设置中被忽略。请参阅[组织范围的 CLAUDE.md](/docs/zh-CN/memory#deploy-organization-wide-claude-md) | `"Always run make lint before committing."` |
247| `claudeMdExcludes` | 加载[内存](/docs/zh-CN/memory)时要跳过的 `CLAUDE.md` 文件的 Glob 模式或绝对路径。模式与绝对文件路径匹配。仅适用于用户、项目和本地内存；managed 策略文件无法被排除 | `["**/vendor/**/CLAUDE.md"]` |
248| `cleanupPeriodDays` | **默认**：`30` 天，最少 `1`。Claude Code 删除[会话文件和其他应用程序数据](/docs/zh-CN/claude-directory#cleaned-up-automatically)早于此期间的在启动时。设置 `0` 会被拒绝并显示验证错误。相同的年龄截止也适用于[孤立 worktrees](/docs/zh-CN/worktrees#clean-up-worktrees) 在启动时自动删除。如果 Claude Code 无法读取或解析设置文件，它会暂停保留清理扫描并在 `/status` 中显示警告，直到您修复文件，除非 [managed 设置](/docs/zh-CN/server-managed-settings)提供 `cleanupPeriodDays`，在这种情况下扫描以 managed 值运行。在 v2.1.203 之前，清理以 30 天默认值在该状态下运行，可能删除较长 `cleanupPeriodDays` 打算保留的记录；30 天以上的文件从未被删除。要完全禁用记录写入，请设置 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/zh-CN/env-vars) 环境变量。在非交互模式中，与 `-p` 一起传递 `--no-session-persistence` 或在 Agent SDK 中设置 `persistSession: false`。 | `20` |
249| `companyAnnouncements` | 在启动时显示给用户的公告。如果提供多个公告，它们将随机循环显示。 | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |
250| `defaultShell` | **默认**：`"bash"`，或在 Bash 不可用时在 Windows 上为 `"powershell"`。输入框 `!` 命令的默认 shell。接受 `"bash"` 或 `"powershell"`。设置 `"powershell"` 会在 Windows 上通过 PowerShell 路由交互式 `!` 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。请参阅 [PowerShell tool](/docs/zh-CN/tools-reference#powershell-tool) | `"powershell"` |
251| `deniedMcpServers` | 在 managed-settings.json 中设置时，明确阻止的 MCP servers 的拒绝列表。适用于所有作用域，包括 managed servers。拒绝列表优先于允许列表。请参阅 [Managed MCP 配置](/docs/zh-CN/managed-mcp) | `[{ "serverName": "filesystem" }]` |
252| `disableAgentView` | 设置为 `true` 以关闭[后台代理和代理视图](/docs/zh-CN/agent-view)：`claude agents`、`--bg`、`/background` 和按需主管。通常在 [managed 设置](/docs/zh-CN/permissions#managed-settings)中设置。等同于将 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 设置为 `1` | `true` |
253| `disableAllHooks` | 禁用所有 [hooks](/docs/zh-CN/hooks) 和任何自定义[状态行](/docs/zh-CN/statusline) | `true` |
254| `disableArtifact` | 设置为 `true` 以禁用 [Artifact](/docs/zh-CN/artifacts) 工具，该工具将会话输出发布为 claude.ai 上的私有网页。等同于将 `CLAUDE_CODE_DISABLE_ARTIFACT` 设置为 `1` | `true` |
255| `disableAutoMode` | 设置为 `"disable"` 以防止[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)被激活。从 `Shift+Tab` 循环中删除 `auto` 并在启动时拒绝 `--permission-mode auto`。在[managed 设置](/docs/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它 | `"disable"` |
256| `disableBrowserExternalNavigation` | （仅 Managed 设置）设置为 `true` 以关闭桌面应用[浏览器窗格](/docs/zh-CN/desktop#browse-external-sites)中的外部浏览。用户和 Claude 都无法导航到外部站点，localhost 开发服务器预览不受影响。值必须是 JSON 布尔值 `true`；字符串 `"true"` 被忽略 | `true` |
257| `disableBundledSkills` | 设置为 `true` 以禁用 Claude Code 附带的 [skills](/docs/zh-CN/skills) 和工作流：捆绑的 skills 和工作流被完全删除，而内置斜杠命令（如 `/init`）保持可键入但对模型隐藏。`/doctor` 保持可键入，如内置命令；用 [`DISABLE_DOCTOR_COMMAND`](/docs/zh-CN/env-vars) 隐藏它。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影响。等同于将 `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` 设置为 `1` | `true` |
258| `disableClaudeAiConnectors` | 禁用 [claude.ai MCP connectors](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)，以便它们不被自动获取或连接。在任何设置作用域中设置。任何源中的 `true` 优先，因此已检入的项目 `.claude/settings.json` 可以选择存储库退出云连接器，但项目级 `false` 无法覆盖用户或策略级 `true`。通过 `--mcp-config` 显式传递的 servers 不受影响。要拒绝单个连接器而不是所有连接器，请改用 [`deniedMcpServers`](/docs/zh-CN/managed-mcp)。需要 Claude Code v2.1.182 或更高版本 | `true` |
259| `disableDeepLinkRegistration` | 设置为 `"disable"` 以防止 Claude Code 在启动时向操作系统注册 `claude-cli://` 协议处理程序。[深链接](/docs/zh-CN/deep-links)让外部工具通过预填充的提示打开 Claude Code 会话。在协议处理程序注册受限或单独管理的环境中很有用 | `"disable"` |
260| `disabledMcpjsonServers` | 要拒绝的 `.mcp.json` 文件中特定 MCP servers 的列表 | `["filesystem"]` |
261| `disableRemoteControl` | 禁用[远程控制](/docs/zh-CN/remote-control)：阻止 `claude remote-control`、`--remote-control` 标志、自动启动和会话内切换。通常放在[managed 设置](/docs/zh-CN/permissions#managed-settings)中用于每设备 MDM 强制执行，但适用于任何作用域。需要 Claude Code v2.1.128 或更高版本 | `true` |
262| `disableSideloadFlags` | （仅 Managed 设置）在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` CLI 标志，用户可能会传递这些标志以绕过单次运行的 [`strictKnownMarketplaces`](#strictknownmarketplaces)。也拒绝从任何内部生成带有它们的 CLI 的表面这些标志，当前 [Cowork](/docs/zh-CN/desktop) 桌面应用中的本地会话。其服务器都是进程内 `type: "sdk"` 条目的 `--mcp-config` 仍被接受，因此 Agent SDK 和 VS Code 扩展保持工作。不阻止 `claude mcp add`、`.mcp.json` 或 SDK `setMcpServers()`；与 [`allowedMcpServers`](/docs/zh-CN/managed-mcp) 配对以获得每个 server 的 MCP 控制。需要 Claude Code v2.1.193 或更高版本 | `true` |
263| `disableSkillShellExecution` | 禁用 [skills](/docs/zh-CN/skills) 和来自用户、项目、插件或额外目录源的自定义命令中的 `` !`...` `` 和 ` ```! ` 块的内联 shell 执行。命令被替换为 `[shell command execution disabled by policy]` 而不是被运行。捆绑和 managed skills 不受影响。在[managed 设置](/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它 | `true` |
264| `disableWorkflows` | **默认**：`false`。禁用[动态工作流](/docs/zh-CN/workflows#turn-workflows-off)和捆绑的工作流命令。等同于将 `CLAUDE_CODE_DISABLE_WORKFLOWS` 设置为 `1` | `true` |
265| `editorMode` | **默认**：`"normal"`。输入提示的快捷键模式：`"normal"` 或 `"vim"`。在 `/config` 中显示为**快捷键模式** | `"vim"` |
266| `effortLevel` | 跨会话持久化[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。接受 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`。当您运行 `/effort` 时自动写入，带有这些值之一。`--effort` 和 [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars) 覆盖此用于一个会话。请参阅[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level)了解支持的模型 | `"xhigh"` |
267| `enableAllProjectMcpServers` | 自动批准项目 `.mcp.json` 文件中定义的所有 MCP servers。从 v2.1.196 开始，`claude mcp list` 和 `claude mcp get` 仅在[未检入存储库的设置文件](/docs/zh-CN/mcp#managing-your-servers)中的不受信任的文件夹中尊重此键 | `true` |
268| `enableArtifact` | 为此用户启用或禁用 [Artifact](/docs/zh-CN/artifacts) 工具。未设置时，默认遵循该功能对您账户的[可用性](/docs/zh-CN/artifacts#availability)。`/config` 中的**Artifacts** 行写入此键。managed `disableArtifact` 和您的组织的[管理员设置](/docs/zh-CN/artifacts#manage-artifacts-for-your-organization)优先，该键在项目和本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中被忽略，存储库可能会检入。需要 Claude Code v2.1.196 或更高版本 | `true` |
269| `enabledMcpjsonServers` | 要批准的 `.mcp.json` 文件中特定 MCP servers 的列表。从 v2.1.196 开始，`claude mcp list` 和 `claude mcp get` 仅在[未检入存储库的设置文件](/docs/zh-CN/mcp#managing-your-servers)中的不受信任的文件夹中尊重此键 | `["memory", "github"]` |
270| `enforceAvailableModels` | 将 `availableModels` 允许列表扩展到默认模型。当在 managed 设置中为 `true` 且 `availableModels` 是非空数组时，默认选项回退到第一个可用的允许列表条目，但仅当默认模型会解析为的模型（当应用[组织默认](/docs/zh-CN/model-config#organization-default-model)时，否则账户类型默认）不在允许列表中时；允许列表默认保持原样。当 `availableModels` 未设置或为空时无效。请参阅[为默认模型强制执行允许列表](/docs/zh-CN/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更高版本 | `true` |
271| `env` | 应用于每个会话和 Claude Code 从其生成的子进程的环境变量。将变量设置为 `""` 以用空字符串覆盖 shell 导出，Claude Code 将其视为未设置用于提供商选择。子进程仍继承空值。`NO_COLOR` 和 `FORCE_COLOR` 在此处设置仅到达子进程；要改变 Claude Code 自己的界面颜色，在启动 `claude` 前在您的 shell 中设置它们。从 v2.1.195 开始，Claude Code 的托管环境设置的身份变量，例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`，在此处设置时被忽略 | `{"FOO": "bar"}` |
272| `fallbackModel` | 当主模型过载或不可用时按顺序尝试的备用模型。Claude Code 为该轮的其余部分切换到链中的下一个可用模型并显示通知。`"default"` 扩展为默认模型。链限制为三个模型；额外条目被忽略。与大多数数组设置不同，此键不跨设置文件合并：定义它的最高优先级文件提供整个链。[`--fallback-model`](/docs/zh-CN/cli-reference#cli-flags) 标志覆盖此用于一个会话。请参阅[备用模型链](/docs/zh-CN/model-config#fallback-model-chains) | `["claude-sonnet-5", "claude-haiku-4-5"]` |
273| `fastMode` | 为可用的会话打开[快速模式](/docs/zh-CN/fast-mode)。使用 `/fast` 切换会在用户设置中写入 `true`，当您关闭快速模式时删除键 | `true` |
274| `fastModePerSessionOptIn` | 当为 `true` 时，快速模式不会跨会话持久化。每个会话都以快速模式关闭开始，需要用户使用 `/fast` 启用它。用户的快速模式偏好仍被保存。请参阅[需要每个会话的选择加入](/docs/zh-CN/fast-mode#require-per-session-opt-in) | `true` |
275| `feedbackSurveyRate` | 概率（0–1）[会话质量调查](/docs/zh-CN/data-usage#session-quality-surveys)在符合条件时出现。设置为 `0` 以完全抑制，或在 `env` 中设置 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/docs/zh-CN/env-vars)。在使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 时很有用，其中默认采样率不适用 | `0.05` |
276| `fileCheckpointingEnabled` | **默认**：`true`。在每次编辑前快照文件，以便 [`/rewind`](/docs/zh-CN/checkpointing) 可以恢复它们。在 `/config` 中显示为**回退代码（checkpoints）**。要通过环境变量禁用，请在 `env` 中设置 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/docs/zh-CN/env-vars) | `false` |
277| `fileSuggestion` | 为 `@` 文件自动完成配置自定义脚本。请参阅[文件建议设置](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |
278| `footerLinksRegexes` | 当正则表达式匹配轮次输出时渲染额外的可点击徽章在页脚中。每个条目有一个 `pattern`、一个 URL 模板，其中 `{name}` 占位符从命名捕获组填充，以及一个可选的 `label`。仅从用户、`--settings` 标志和 managed 设置读取。请参阅[页脚链接徽章](#footer-link-badges)了解 URL 约束、方案允许列表和限制。需要 Claude Code v2.1.176 或更高版本 | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |
279| `forceLoginMethod` | 使用 `claudeai` 限制登录到 Claude.ai 账户，`console` 限制登录到 Claude Console 账户，或 `gateway` 限制登录到云网关；请参阅 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway)。在 managed 设置中设置为任何值时，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话在启动时被阻止，因为环境凭证无法满足所需的登录方法。第三方提供商会话（如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry）不被阻止：它们针对您的云提供商而不是 Anthropic 进行身份验证 | `claudeai` |
280| `forceLoginGatewayUrl` | 在 `/login` 云网关屏幕上预填充并锁定网关 URL。此键或 `forceLoginMethod: "gateway"` 中的任一个都会显示该屏幕；同时设置两者以便 URL 被填充。仅在 managed 策略层受尊重；在用户和项目设置中被忽略。请参阅 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway#set-the-gateway-url) | `"https://claude-gateway.example.com"` |
281| `forceLoginOrgUUID` | 要求登录属于特定 Anthropic 组织。接受单个 UUID 字符串（也在登录期间预选该组织）或 UUID 数组，其中任何列出的组织都被接受而无需预选。在 managed 设置中设置时，如果经过身份验证的账户不属于列出的组织，登录失败；由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话在启动时被阻止，因为无法为它们验证组织成员身份。第三方提供商会话（如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry）不被阻止：使用您的云 IAM 限制哪些云账户可以被使用。空数组失败关闭并使用配置错误消息阻止登录 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 或 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |
282| `forceRemoteSettingsRefresh` | （仅 Managed 设置）阻止 CLI 启动，直到从服务器新鲜获取远程 managed 设置。如果获取失败，CLI 退出而不是继续使用缓存或无设置。未设置时，启动继续而不等待远程设置。请参阅[失败关闭强制执行](/docs/zh-CN/server-managed-settings#enforce-fail-closed-startup) | `true` |
283| `gcpAuthRefresh` | 当 GCP Application Default Credentials 过期或无法加载时刷新它们的自定义脚本。请参阅[高级凭证配置](/docs/zh-CN/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |
284| `hooks` | 配置自定义命令以在生命周期事件处运行。请参阅 [hooks 文档](/docs/zh-CN/hooks) 了解格式 | 请参阅 [hooks](/docs/zh-CN/hooks) |
285| `httpHookAllowedEnvVars` | HTTP hooks 可能插入到标头中的环境变量名称的允许列表。设置后，每个 hook 的有效 `allowedEnvVars` 是与此列表的交集。未定义 = 无限制。数组跨设置源合并。请参阅 [Hook 配置](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |
286| `includeGitInstructions` | **默认**：`true`。在 Claude 的系统提示中包含内置提交和 PR 工作流说明和 git 状态快照。设置为 `false` 以删除这两者，例如在使用您自己的 git 工作流 skills 时。`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 环境变量在设置时优先于此设置 | `false` |
287| `inputNeededNotifEnabled` | **默认**：`false`。当[远程控制](/docs/zh-CN/remote-control)已连接时，当权限提示或问题等待您的输入时向您的手机发送推送通知。在 `/config` 中显示为**需要操作时推送**。请参阅[移动推送通知](/docs/zh-CN/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更高版本 | `true` |
288| `language` | 配置 Claude 的首选响应语言（例如 `"japanese"`、`"spanish"`、`"french"`）。Claude 将默认以此语言响应。也设置[语音听写](/docs/zh-CN/voice-dictation#change-the-dictation-language)语言和自动生成的会话标题。从 v2.1.176 开始，未设置时，会话标题与您的对话语言匹配 | `"japanese"` |
289| `minimumVersion` | 防止后台自动更新和 `claude update` 安装低于此版本的版本。从 `"latest"` 渠道切换到 `"stable"` 时通过 `/config` 提示您保持在当前版本或允许降级。选择保持设置此值。也在[managed 设置](/docs/zh-CN/permissions#managed-settings)中有用，以固定组织范围的最低版本。对于阻止启动的硬下限，请参阅 `requiredMinimumVersion` | `"2.1.100"` |
290| `model` | 覆盖用于 Claude Code 的默认模型。`--model` 和 [`ANTHROPIC_MODEL`](/docs/zh-CN/model-config#environment-variables) 覆盖此用于一个会话 | `"claude-sonnet-5"` |
291| `modelOverrides` | 将 Anthropic 模型 ID 映射到特定于提供商的模型 ID，例如 Amazon Bedrock 推理配置文件 ARN。每个模型选择器条目在调用提供商 API 时使用其映射值。请参阅[按版本覆盖模型 ID](/docs/zh-CN/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |
292| `otelHeadersHelper` | 生成动态 OpenTelemetry 标头的脚本。在启动时和定期运行。使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/docs/zh-CN/env-vars) 设置刷新间隔。请参阅[动态标头](/docs/zh-CN/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |
293| `outputStyle` | 配置输出样式以调整系统提示。请参阅[输出样式文档](/docs/zh-CN/output-styles) | `"Explanatory"` |
294| `parentSettingsBehavior` | （仅 Managed 设置）**默认**：`"first-wins"`。控制由嵌入主机进程（例如 Agent SDK 或 IDE 扩展）以编程方式提供的 managed 设置在同时存在管理员部署的 managed 层时是否应用。`"first-wins"`：父级提供的设置被丢弃，仅应用管理员层。`"merge"`：父级提供的设置在管理员层下应用，经过筛选以便它们可以收紧策略但不能放松策略。当未部署管理员层时无效。需要 Claude Code v2.1.133 或更高版本 | `"merge"` |
295| `permissions` | 请参阅下表了解权限的结构。 | |
296| `plansDirectory` | **默认**：`~/.claude/plans`。自定义 Plan Mode 文件的存储位置。路径相对于项目根目录。 | `"./plans"` |
297| `pluginSuggestionMarketplaces` | （仅 Managed 设置）其插件可以显示为上下文安装建议的市场名称。无市场声明的建议出现而不需要此允许列表；内置的第一方前端设计提示不受影响。建议来自每个插件在其市场条目中的 `relevance` 声明。名称仅在市场在机器上注册且其注册源也在 managed 设置中声明时才生效，作为该名称的 `extraKnownMarketplaces` 条目或 `strictKnownMarketplaces` 的条目。从不同源注册的市场在允许列表名称下被忽略。官方市场豁免于源要求：仅允许列表其名称就足够了，因为该名称只能从官方 Anthropic 源注册。 | `["acme-corp-plugins"]` |
298| `pluginTrustMessage` | （仅 Managed 设置）在安装前显示的插件信任警告中附加的自定义消息。使用此添加组织特定的上下文，例如确认来自您内部市场的插件已获批准。 | `"All plugins from our marketplace are approved by IT"` |
299| `policyHelper` | 管理员部署的可执行文件，在启动时动态计算 managed 设置。仅从 MDM 或系统 `managed-settings.json` 文件受尊重。请参阅[使用策略助手计算 managed 设置](#compute-managed-settings-with-a-policy-helper)。需要 Claude Code v2.1.136 或更高版本 | `{"path": "/usr/local/bin/claude-policy"}` |
300| `preferredNotifChannel` | **默认**：`"auto"`。任务完成和权限提示通知的方法：`"auto"`、`"terminal_bell"`、`"iterm2"`、`"iterm2_with_bell"`、`"kitty"`、`"ghostty"` 或 `"notifications_disabled"`。`"auto"` 在 iTerm2、Ghostty 和 Kitty 中发送桌面通知，在其他终端中不执行任何操作。设置 `"terminal_bell"` 以在任何终端中响铃。在 `/config` 中显示为**通知**。请参阅[获取终端铃声或通知](/docs/zh-CN/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |
301| `prefersReducedMotion` | 减少或禁用 UI 动画（微调器、闪烁、闪光效果）以实现可访问性 | `true` |
302| `prUrlTemplate` | PR 徽章的 URL 模板，显示在页脚和工具结果摘要中。替换来自 `gh` 报告的 PR URL 中的 `{host}`、`{owner}`、`{repo}`、`{number}` 和 `{url}`。使用指向内部代码审查工具而不是 `github.com` 的 PR 链接。不影响 Claude 散文中的 `#123` 自动链接 | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |
303| `remoteControlAtStartup` | 当每个交互式会话启动时自动连接[远程控制](/docs/zh-CN/remote-control)，而不是等待 `/remote-control`。设置为 `true` 以始终自动连接，`false` 以从不自动连接，或保留未设置以遵循您的组织的默认值。在 `/config` 中显示为**为所有会话启用远程控制**。请参阅[为所有会话启用远程控制](/docs/zh-CN/remote-control#enable-remote-control-for-all-sessions) | `false` |
304| `requiredMaximumVersion` | 仅 Managed 设置。允许启动的最大 Claude Code 版本。如果运行版本较新，Claude Code 在启动时退出并指示用户通过组织的批准方法安装批准的版本；`claude install <version>` 也可能有效。后台自动更新和 `claude update` 跳过高于上限的版本，因此在范围内的安装保持在范围内。`claude update`、`claude install` 和 `claude doctor` 在上限以上保持工作，以便用户可以恢复。早于此设置的版本忽略它 | `"2.1.150"` |
305| `requiredMinimumVersion` | 仅 Managed 设置。启动所需的最小 Claude Code 版本。如果运行版本较旧，Claude Code 在启动时退出并指示用户通过组织的批准方法更新。`claude update`、`claude install` 和 `claude doctor` 在下限以下保持工作，以便用户可以恢复。与 `minimumVersion` 不同，后者防止降级但从不阻止启动。早于此设置的版本忽略它 | `"2.1.150"` |
306| `respectGitignore` | **默认**：`true`。控制 `@` 文件选择器是否尊重 `.gitignore` 模式。当为 `true` 时，匹配 `.gitignore` 模式的文件被排除在建议之外 | `false` |
307| `respondToBashCommands` | **默认**：`true`。Claude 在输入框 `!` shell 命令运行后是否响应。设置为 `false` 以将命令输出添加到上下文而不响应。请参阅[带 `!` 前缀的 Shell 模式](/docs/zh-CN/interactive-mode#shell-mode-with-prefix)。需要 Claude Code v2.1.186 或更高版本 | `false` |
308| `showClearContextOnPlanAccept` | **默认**：`false`。在 Plan Mode 接受屏幕上显示"清除上下文"选项。设置为 `true` 以恢复该选项 | `true` |
309| `showThinkingSummaries` | **默认**：`false`。在交互式会话中显示[扩展思考](/docs/zh-CN/model-config#extended-thinking)摘要。未设置或 `false` 时，思考块由 API 编辑并显示为折叠的存根。编辑仅改变您看到的内容，而不是模型生成的内容：要减少思考支出，[降低预算或禁用思考](/docs/zh-CN/model-config#extended-thinking)。此设置在非交互模式（`-p`）、Agent SDK 或 IDE 扩展（如 VS Code）中无效 | `true` |
310| `showTurnDuration` | **默认**：`true`。在响应后显示轮次持续时间消息，例如"Cooked for 1m 6s"。在 `/config` 中显示为**显示轮次持续时间** | `false` |
311| `skillListingBudgetFraction` | **默认**：`0.01`。为[skill 列表](/docs/zh-CN/skills#skill-descriptions-are-cut-short)预留的模型上下文窗口的分数，Claude 每轮看到。当列表超过预算时，最少使用的 skills 的描述被删除，仅列出其名称，以便 Claude 仍可以调用它们但不会看到它们的作用。提高以保持更多描述可见，代价是每轮更多上下文。`/doctor` 估计列表成本与预算 | `0.02` |
312| `skillListingMaxDescChars` | **默认**：`1536`。[skill 列表](/docs/zh-CN/skills#skill-descriptions-are-cut-short)中每个 skill 的 `description` 和 `when_to_use` 文本组合的字符上限。超过此长度的文本被截断。提高以保持长描述完整，代价是每轮更多上下文；降低以在 [`skillListingBudgetFraction`](#available-settings) 下适应更多 skills | `2048` |
313| `skillOverrides` | 按 skill 名称键入的每个 skill 可见性覆盖。值为 `"on"`、`"name-only"`、`"user-invocable-only"` 或 `"off"`。让您隐藏或折叠 skill 而无需编辑其 SKILL.md。不适用于插件 skills，这些通过 `/plugin` 管理。`/skills` 菜单将这些写入 `.claude/settings.local.json`。请参阅[从设置覆盖 skill 可见性](/docs/zh-CN/skills#override-skill-visibility-from-settings)。需要 Claude Code v2.1.129 或更高版本 | `{"legacy-context": "name-only", "deploy": "off"}` |
314| `skipWebFetchPreflight` | 跳过[WebFetch 域安全检查](/docs/zh-CN/data-usage#webfetch-domain-safety-check)，该检查在获取前将每个请求的主机名发送到 `api.anthropic.com`。在阻止到 Anthropic 的流量的环境中设置为 `true`，例如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 部署，具有限制性出站。跳过时，WebFetch 尝试任何 URL 而不咨询阻止列表 | `true` |
315| `spinnerTipsEnabled` | **默认**：`true`。在 Claude 工作时在微调器中显示提示。设置为 `false` 以禁用提示 | `false` |
316| `spinnerTipsOverride` | 使用自定义字符串覆盖微调器提示。`tips`：提示字符串数组。`excludeDefault`：如果为 `true`，仅显示自定义提示；如果为 `false` 或不存在，自定义提示与内置提示合并 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |
317| `spinnerVerbs` | 自定义在微调器中显示的操作动词。将 `mode` 设置为 `"replace"` 以仅使用您的动词，或 `"append"` 以将它们添加到默认值 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |
318| `sshConfigs` | 要在[桌面](/docs/zh-CN/desktop#pre-configure-ssh-connections-for-your-team)环境下拉菜单中显示的 SSH 连接。每个条目需要 `id`、`name` 和 `sshHost`；`sshPort`、`sshIdentityFile` 和 `startDirectory` 是可选的。在 managed 设置中设置时，连接对用户是只读的。仅从 managed 和用户设置读取 | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |
319| `statusLine` | 配置自定义状态行以显示上下文。对象的可选 `padding`、`refreshInterval` 和 `hideVimModeIndicator` 字段控制间距、定期重新运行和是否隐藏提示下方的内置 vim 模式指示器。请参阅[`statusLine` 文档](/docs/zh-CN/statusline#manually-configure-a-status-line) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |
320| `strictKnownMarketplaces` | （仅 Managed 设置）插件市场源的允许列表。未定义 = 无限制，空数组 = 锁定。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在设置策略之前添加的市场无法用于获取插件。请参阅 [Managed 市场限制](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |
321| `strictPluginOnlyCustomization` | （仅 Managed 设置）阻止 skills、agents、hooks 和 MCP servers 来自用户和项目源，因此它们只能来自插件或 managed 设置。`true` 锁定所有四个表面；数组仅锁定命名的表面。请参阅 [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | `["skills", "hooks"]` |
322| `syntaxHighlightingDisabled` | 禁用 diffs、代码块和文件预览中的语法高亮 | `true` |
323| `teammateMode` | **默认**：`in-process`。[agent team](/docs/zh-CN/agent-teams) 队友的显示方式：`in-process`、`auto`（在 tmux 或 iTerm2 中选择分割窗格，否则进程内）、`tmux`（使用 tmux 或 iTerm2 选择分割窗格，从您的终端检测）或 }`iterm2`（iTerm2 本机分割窗格通过 `it2` CLI，在 v2.1.186 中添加）。默认在 v2.1.179 中从 `auto` 更改。`--teammate-mode` 覆盖此用于一个会话。请参阅[选择显示模式](/docs/zh-CN/agent-teams#choose-a-display-mode) | `"auto"` |
324| `terminalProgressBarEnabled` | **默认**：`true`。在支持的终端中显示终端进度条：ConEmu、Ghostty 1.2.0+ 和 iTerm2 3.6.6+。在 `/config` 中显示为**终端进度条** | `false` |
325| `theme` | **默认**：`"dark"`。界面的颜色主题：`"auto"`、`"dark"`、`"light"`、`"dark-daltonized"`、`"light-daltonized"`、`"dark-ansi"`、`"light-ansi"` 或自定义主题参考，如 `"custom:<slug>"` 或 `"custom:<plugin-name>:<slug>"`。请参阅[创建自定义主题](/docs/zh-CN/terminal-config#create-a-custom-theme)。在 `/config` 中显示为**主题** | `"dark"` |
326| `tui` | 终端 UI 渲染器。使用 `"fullscreen"` 获取无闪烁的[替代屏幕渲染器](/docs/zh-CN/fullscreen)，具有虚拟化滚动条。使用 `"default"` 获取经典主屏幕渲染器。通过 `/tui` 设置。您也可以设置 [`CLAUDE_CODE_NO_FLICKER`](/docs/zh-CN/env-vars) 环境变量。后台会话从[代理视图](/docs/zh-CN/agent-view)打开始终使用全屏渲染器，无论此设置如何 | `"fullscreen"` |
327| `ultracode` | 为会话打开 [ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)。此键不从 `settings.json` 读取。通过 `/effort ultracode`、`--settings` 或 Agent SDK 控制请求设置。要启动已打开 ultracode 的会话，使用 `claude --effort ultracode` 启动，需要 Claude Code v2.1.203 或更高版本 | `true` |
328| `useAutoModeDuringPlan` | **默认**：`true`。Plan Mode 在自动模式可用时是否使用自动模式语义。不从共享项目设置读取。在 `/config` 中显示为"在计划期间使用自动模式" | `false` |
329| `verbose` | **默认**：`false`。显示完整工具输出而不是截断的摘要。在 `/config` 中显示为**详细输出**。`--verbose` 标志覆盖此用于一个会话 | `true` |
330| `viewMode` | 启动时的默认记录视图模式：`"default"`、`"verbose"` 或 `"focus"`。设置时覆盖粘性 `/focus` 选择。`--verbose` 标志覆盖此用于一个会话 | `"verbose"` |
331| `vimInsertModeRemaps` | 将两键 INSERT 模式序列映射到 Escape 在[vim 编辑器模式](/docs/zh-CN/interactive-mode#vim-editor-mode)中。每个键恰好是两个按顺序键入的可打印字符，`"<Esc>"` 是唯一支持的目标；其他条目被忽略。仅从用户、`--settings` 标志和 managed 设置读取，因此存储库的已检入设置无法重新映射您的按键。除非 `editorMode` 为 `"vim"`，否则无效。请参阅[重新映射 INSERT 模式键序列](/docs/zh-CN/interactive-mode#remap-insert-mode-key-sequences)。需要 Claude Code v2.1.208 或更高版本 | `{"jj": "<Esc>"}` |
332| `voice` | [语音听写](/docs/zh-CN/voice-dictation)设置：`enabled` 打开听写，`mode` 选择 `"hold"` 或 `"tap"`，`autoSubmit` 在保持模式下按键释放时发送提示。当您运行 `/voice` 时自动写入。需要 Claude.ai 账户 | `{ "enabled": true, "mode": "tap" }` |
333| `voiceEnabled` | `voice.enabled` 的旧别名。优先使用 `voice` 对象 | `true` |
334| `wheelScrollAccelerationEnabled` | **默认**：`true`。在[全屏渲染](/docs/zh-CN/fullscreen#mouse-wheel-scrolling)中，加速鼠标滚轮滚动速度在快速滚动期间。设置为 `false` 以获得每个滚轮缺口的恒定滚动速率。需要 Claude Code v2.1.174 或更高版本 | `false` |
335| `workflowKeywordTriggerEnabled` | **默认**：`true`。提示中的单词 `ultracode` 是否触发[动态工作流](/docs/zh-CN/workflows#ask-for-a-workflow-in-your-prompt)。设置为 `false` 以键入单词而不触发一个。Ultracode 努力设置、`/workflows` 和保存的工作流命令不受影响。在 `/config` 中显示为**Ultracode 关键字触发**。在 v2.1.157 中添加；在 v2.1.160 之前触发关键字是 `workflow` | `false` |
336| `wslInheritsWindowsSettings` | （仅 Windows managed 设置）当为 `true` 时，WSL 上的 Claude Code 除了 `/etc/claude-code` 外还从 Windows 策略链读取 managed 设置，Windows 源优先。仅在 HKLM 注册表项或 `C:\Program Files\ClaudeCode\managed-settings.json` 中设置时被尊重，两者都需要 Windows 管理员权限才能写入。为了让 HKCU 策略也在 WSL 上应用，该标志还必须在 HKCU 本身中设置。对本机 Windows 无效 | `true` |
337
338<h3 id="global-config-settings">
339 全局配置设置
340</h3>
341 495
342这些设置存储在 `~/.claude.json` 中，而不是 `settings.json`。将它们添加到 `settings.json` 将触发架构验证错误。496在 v2.1.211 之前，Claude Code 在启动目录中保留文件。它仍然读取早期版本在根文件旁边留下的文件；当两者都设置相同的键时，根的值适用，两个文件的权限规则都适用。Agent SDK 的 [`resolveSettings()`](/docs/zh-CN/agent-sdk/typescript#resolvesettings) 助手总是从启动目录读取文件。
343 497
344<Note>498Claude Code 从会话的[主工作目录](/docs/zh-CN/permissions#working-directories)读取共享的 `.claude/settings.json`，所以要使用在仓库根处提交的文件，在那里启动 Claude Code。在你[使用 `/cd` 移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory)后，Claude Code 改为从新目录读取两个项目文件，按相同规则放置本地文件。从你移动到的目录读取它们需要 Claude Code v2.1.246 或更高版本。
345 v2.1.119 之前的版本也在此处而不是在 `settings.json` 中存储多个 `/config` 偏好键，包括 `theme`、`verbose`、`editorMode`、`autoCompactEnabled` 和 `preferredNotifChannel`。
346</Note>
347 499
348| 键 | 描述 | 示例 |500<span id="managed-settings-delivery" />
349| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- |
350| `autoConnectIde` | **默认**：`false`。当 Claude Code 从外部终端启动时自动连接到运行的 IDE。在 VS Code 或 JetBrains 终端外运行时在 `/config` 中显示为**自动连接到 IDE（外部终端）**。[`CLAUDE_CODE_AUTO_CONNECT_IDE`](/docs/zh-CN/env-vars) 环境变量在设置时覆盖此 | `true` |
351| `autoInstallIdeExtension` | **默认**：`true`。从 VS Code 终端运行时自动安装 Claude Code IDE 扩展。在 VS Code 或 JetBrains 终端内运行时在 `/config` 中显示为**自动安装 IDE 扩展**。您也可以设置 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/docs/zh-CN/env-vars) 环境变量 | `false` |
352| `externalEditorContext` | **默认**：`false`。当您使用 `Ctrl+G` 打开外部编辑器时，将 Claude 的上一个响应作为 `#` 注释上下文前置。在 `/config` 中显示为**在外部编辑器中显示最后响应** | `true` |
353| `permissionExplainerEnabled` | **默认**：`true`。当您在 Bash 或 PowerShell 权限提示上按 `Ctrl+E` 时显示模型生成的[命令说明](/docs/zh-CN/permissions#permission-system)。设置为 `false` 以关闭快捷键 | `false` |
354| `teammateDefaultModel` | [agent team](/docs/zh-CN/agent-teams) 队友的默认模型，当生成提示未指定时。设置为模型别名（如 `"sonnet"`），或 `null` 以继承主导的当前 `/model` 选择。在 `/config` 中显示为**默认队友模型** | `"sonnet"` |
355| `workflowSizeGuideline` | **默认**：`unrestricted`，不发送指南。设置[动态工作流](/docs/zh-CN/workflows#set-a-size-guideline)中 Claude 针对的[代理计数](/docs/zh-CN/workflows#set-a-size-guideline)。Claude Code 将值作为建议而不是强制上限发送给 Claude。接受 `unrestricted`、`small`、`medium` 或 `large`。在 `/config` 中显示为**动态工作流大小**。您也可以使用 `/config workflowSizeGuideline=small` 直接设置它。需要 Claude Code v2.1.202 或更高版本。指南的代理计数也替换[`Large workflow` 警告](/docs/zh-CN/workflows#cost)的默认阈值；该行为需要 Claude Code v2.1.203 或更高版本 | `"small"` |
356
357<h3 id="worktree-settings">
358 Worktree 设置
359</h3>
360 501
361配置 `--worktree` 如何创建和管理 git worktrees。502<span id="precedence-within-the-managed-tier" />
362 503
363| 键 | 描述 | 示例 |504<span id="parent-settings-from-embedding-hosts" />
364| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |
365| `worktree.baseRef` | 新 worktrees 分支的参考。`"fresh"`（默认）从 `origin/<default-branch>` 分支以获得与远程匹配的干净树。`"head"` 从您当前的本地 `HEAD` 分支，因此未推送的提交和特性分支状态存在于 worktree 中。在 linked worktree 内，`"head"` 解析为该 worktree 的 `HEAD`，而不是主检出的。适用于 `--worktree`、`EnterWorktree` 工具和 subagent 隔离 | `"head"` |
366| `worktree.symlinkDirectories` | 要从主存储库符号链接到每个 worktree 的目录，以避免在磁盘上复制大型目录。默认情况下不符号链接任何目录 | `["node_modules", ".cache"]` |
367| `worktree.sparsePaths` | 通过 git sparse-checkout 在每个 worktree 中检出的目录。仅将列出的目录加上根级文件写入磁盘，在大型 monorepos 中更快。当 sparse worktree 存在时，git 在存储库的共享 `.git/config` 中启用 `extensions.worktreeConfig`；请参阅[仅检出您需要的目录](/docs/zh-CN/large-codebases#check-out-only-the-directories-you-need) | `["packages/my-app", "shared/utils"]` |
368| `worktree.bgIsolation` | [后台会话](/docs/zh-CN/agent-view#how-file-edits-are-isolated)的隔离模式。`"worktree"`（默认）在调用 `EnterWorktree` 之前阻止主检出中的 `Edit`/`Write`。在 git 存储库外，失败的 [`WorktreeCreate` hook](/docs/zh-CN/worktrees#non-git-version-control) 释放块，以便会话可以就地编辑工作目录；需要 Claude Code v2.1.203 或更高版本。`"none"` 让后台作业直接编辑工作副本。需要 Claude Code v2.1.143 或更高版本 | `"none"` |
369 505
370要将 gitignored 文件（如 `.env`）复制到新的 worktrees，请在项目根目录中使用 [`.worktreeinclude` 文件](/docs/zh-CN/worktrees#copy-gitignored-files-into-worktrees)，而不是设置。506<span id="enforce-settings-for-an-organization" />
371 507
372<h3 id="permission-settings">508<span id="settings-your-organization-manages" />
373 权限设置
374</h3>
375 509
376| 键 | 描述 | 示例 |510<h3 id="check-what-your-organization-enforces">
377| :---------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |511 检查你的组织强制执行的内容
378| `allow` | 允许工具使用的权限规则数组。工具名称 globs 仅在字面 `mcp__<server>__` 前缀后的工具位置支持，例如 `mcp__github__get_*`；server 段必须无 glob。请参阅下面的[权限规则语法](#permission-rule-syntax)了解模式匹配详情 | `[ "Bash(git diff *)" ]` |
379| `ask` | 在工具使用时要求确认的权限规则数组。请参阅下面的[权限规则语法](#permission-rule-syntax) | `[ "Bash(git push *)" ]` |
380| `deny` | 拒绝工具使用的权限规则数组。使用此排除敏感文件不被 Claude Code 访问。工具名称接受 glob 模式：`"*"` 拒绝每个工具，`"mcp__*"` 拒绝所有 MCP 工具。请参阅[权限规则语法](#permission-rule-syntax)和 [Bash 权限限制](/docs/zh-CN/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |
381| `additionalDirectories` | Claude 有权访问的额外[工作目录](/docs/zh-CN/permissions#working-directories)。大多数 `.claude/` 配置[未从这些目录发现](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |
382| `defaultMode` | 打开 Claude Code 时的默认[权限模式](/docs/zh-CN/permission-modes)。有效值：`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 和 }`manual` 作为 `default` 的别名，CLI、VS Code 和 JetBrains 扩展以及桌面应用中标记为 Manual 的模式。`manual` 别名需要 Claude Code v2.1.200 或更高版本。从 Claude Code v2.1.142 开始，当在项目或本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中设置时，`auto` 被忽略，因此存储库无法授予自己自动模式。改为在 `~/.claude/settings.json` 中设置它。在 v2.1.142 之前，项目设置可以设置 `auto`。`--permission-mode` CLI 标志覆盖此设置用于单个会话 | `"acceptEdits"` |
383| `disableBypassPermissionsMode` | 设置为 `"disable"` 以防止激活 `bypassPermissions` 模式。禁用 `--dangerously-skip-permissions` 标志。通常放在[managed 设置](/docs/zh-CN/permissions#managed-settings)中以强制执行组织策略，但适用于任何作用域 | `"disable"` |
384| `skipDangerousModePermissionPrompt` | 跳过通过 `--dangerously-skip-permissions` 或 `defaultMode: "bypassPermissions"` 进入 bypass permissions 模式前显示的确认提示。在项目设置（`.claude/settings.json`）中设置时被忽略，以防止不受信任的存储库自动绕过提示 | `true` |
385
386<h3 id="permission-rule-syntax">
387 权限规则语法
388</h3>512</h3>
389 513
390权限规则遵循 `Tool` 或 `Tool(specifier)` 的格式。规则按顺序评估：首先是拒绝规则，然后是询问，最后是允许。第一个匹配的规则确定结果，无论规则特异性如何。请参阅[权限规则评估顺序](/docs/zh-CN/permissions#manage-permissions)了解详情。514如果你的组织管理 Claude Code，某些设置是为你决定的，你在自己的文件中放入的任何内容都不会改变它们。要查看哪些，运行 `/status`：`Setting sources` 行命名适用于你的托管来源。托管设置在这台机器上 Claude Code 运行的任何地方都适用；[开发人员可以更改的内容](/docs/zh-CN/managed-settings#what-a-developer-can-change)涵盖本地管理员权限和 Claude Code 以外的工具。
391
392快速示例：
393
394| 规则 | 效果 |
395| :----------------------------- | :-------------------- |
396| `Bash` | 匹配所有 Bash 命令 |
397| `Bash(npm run *)` | 匹配以 `npm run` 开头的命令 |
398| `Read(./.env)` | 匹配读取 `.env` 文件 |
399| `WebFetch(domain:example.com)` | 匹配对 example.com 的获取请求 |
400
401有关完整的规则语法参考，包括通配符行为、Read、Edit、WebFetch、MCP 和 Agent 规则的工具特定模式，以及 Bash 模式的安全限制，请参阅[权限规则语法](/docs/zh-CN/permissions#permission-rule-syntax)。
402
403<h3 id="sandbox-settings">
404 Sandbox 设置
405</h3>
406 515
407配置高级 sandboxing 行为。Sandboxing 将 bash 命令与您的文件系统和网络隔离。请参阅 [Sandboxing](/docs/zh-CN/sandboxing) 了解详情。516托管设置通过托管设置页面上的[交付机制](/docs/zh-CN/managed-settings#delivery-mechanisms)到达你，最常见的是：
408
409| 键 | 描述 | 示例 |
410| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------- |
411| `enabled` | 启用 bash sandboxing（macOS、Linux 和 WSL2）。默认：false | `true` |
412| `failIfUnavailable` | 如果 `sandbox.enabled` 为 true 但 sandbox 无法启动（缺少依赖项或不支持的平台），则在启动时以错误退出。当为 false（默认）时，显示警告，命令无 sandbox 运行。用于需要 sandboxing 作为硬门的 managed 设置部署 | `true` |
413| `autoAllowBashIfSandboxed` | 当 sandboxed 时自动批准 bash 命令。默认：true | `true` |
414| `excludedCommands` | 应在 sandbox 外运行的命令 | `["docker *"]` |
415| `allowUnsandboxedCommands` | 允许命令通过 `dangerouslyDisableSandbox` 参数在 sandbox 外运行。当设置为 `false` 时，`dangerouslyDisableSandbox` 逃生舱口完全禁用，所有命令必须 sandboxed（或在 `excludedCommands` 中）。对于需要严格 sandboxing 的企业策略很有用。默认：true | `false` |
416| `filesystem.allowWrite` | sandboxed 命令可以写入的额外路径。数组跨所有设置作用域合并：用户、项目和 managed 路径组合，不替换。也与 `Edit(...)` 允许权限规则中的路径合并。请参阅下面的[路径前缀](#sandbox-path-prefixes)。 | `["/tmp/build", "~/.kube"]` |
417| `filesystem.denyWrite` | sandboxed 命令无法写入的路径。数组跨所有设置作用域合并。也与 `Edit(...)` 拒绝权限规则中的路径合并。 | `["/etc", "/usr/local/bin"]` |
418| `filesystem.denyRead` | sandboxed 命令无法读取的路径。数组跨所有设置作用域合并。也与 `Read(...)` 拒绝权限规则中的路径合并。 | `["~/.aws/credentials"]` |
419| `filesystem.allowRead` | 在 `denyRead` 区域内重新允许读取的路径。`allowRead` 路径在更广泛的 `denyRead` 区域内重新打开读取，`denyRead` 中的精确路径在更广泛的 `allowRead` 内保持被阻止；请参阅[重叠表](/docs/zh-CN/sandboxing#configure-sandboxing)了解示例。数组跨所有设置作用域合并。使用此创建仅工作区读取访问模式。 | `["."]` |
420| `filesystem.allowManagedReadPathsOnly` | （仅 Managed 设置）仅尊重来自 managed 设置的 `filesystem.allowRead` 路径。`denyRead` 仍从所有源合并。默认：false | `true` |
421| `credentials.files` | Credential 文件或目录，sandboxed 命令无法读取。应用与 `filesystem.denyRead` 相同的读取块；单独的键将凭证路径与 `credentials.envVars` 分组，与一般文件系统规则分开。每个条目是 `{ "path": "...", "mode": "deny" }`，仅支持 `deny`。路径使用与 `filesystem.*` 设置相同的[前缀](#sandbox-path-prefixes)。数组跨所有设置作用域合并。需要 Claude Code v2.1.187 或更高版本。 | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |
422| `credentials.envVars` | 要[保护免受 sandboxed 命令](/docs/zh-CN/sandboxing#protect-credentials)的环境变量。每个条目有一个 `name` 和一个 `mode`；名称必须以字母或下划线开头，仅包含字母、数字和下划线。`deny` 从 sandboxed 命令的环境中删除变量。需要 Claude Code v2.1.187 或更高版本。}`mask` 在 sandbox 内用每个会话的哨兵值替换变量，同时 sandbox 代理在对该条目的 `injectHosts` 的出站请求上替换真实值；它需要 `network.tlsTerminate` 和 Claude Code v2.1.199 或更高版本。`mask` 条目仅从用户、managed 或 CLI `--settings` 设置受尊重，不从 `.claude/settings.json` 或 `.claude/settings.local.json`。数组跨所有设置作用域合并，当同一变量同时出现两种模式时 `deny` 优先。 | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |
423| `credentials.envVars[].injectHosts` | sandbox 代理替换 `mask` 条目真实值的主机。每个主机也必须由 `network.allowedDomains` 覆盖，要么完全要么通过通配符。未设置时，代理在对 `network.allowedDomains` 中每个主机的请求上替换值。当 `mode` 为 `deny` 时被接受但忽略。需要 Claude Code v2.1.199 或更高版本。} | `["api.github.com"]` |
424| `credentials.allowPlaintextInject` | 允许 `mask` 替换在纯 HTTP 请求以及 TLS 终止的 HTTPS 上。在纯 HTTP 上上游身份未验证，凭证以明文形式传输，因此在受信任的测试网络外保持此关闭。仅从用户、managed 或 CLI `--settings` 设置受尊重，不从 `.claude/settings.json` 或 `.claude/settings.local.json`。默认：false。需要 Claude Code v2.1.199 或更高版本。} | `true` |
425| `network.allowUnixSockets` | （仅 macOS）sandbox 中可访问的 Unix socket 路径。在 Linux 和 WSL2 上被忽略，其中 seccomp 过滤器无法检查 socket 路径；改用 `allowAllUnixSockets`。 | `["~/.ssh/agent-socket"]` |
426| `network.allowAllUnixSockets` | 允许 sandbox 中的所有 Unix socket 连接。在 Linux 和 WSL2 上这是允许 Unix sockets 的唯一方式，因为它跳过了 seccomp 过滤器，否则会阻止 `socket(AF_UNIX, ...)` 调用。默认：false | `true` |
427| `network.allowLocalBinding` | 允许绑定到 localhost 端口（仅 macOS）。默认：false | `true` |
428| `network.allowMachLookup` | sandbox 可能查找的额外 XPC/Mach 服务名称（仅 macOS）。支持单个尾部 `*` 用于前缀匹配。对于通过 XPC 通信的工具（如 iOS 模拟器或 Playwright）是必需的。 | `["com.apple.coresimulator.*"]` |
429| `network.allowedDomains` | 允许出站网络流量的域数组。支持通配符（例如 `*.example.com`）。 | `["github.com", "*.npmjs.org"]` |
430| `network.deniedDomains` | 阻止出站网络流量的域数组。支持与 `allowedDomains` 相同的通配符语法。当两者都匹配时优先于 `allowedDomains`。无论 `allowManagedDomainsOnly` 如何，都从所有设置源合并。 | `["sensitive.cloud.example.com"]` |
431| `network.allowManagedDomainsOnly` | （仅 Managed 设置）仅尊重来自 managed 设置的 `allowedDomains` 和 `WebFetch(domain:...)` 允许规则。来自用户、项目和本地设置的域被忽略。非允许的域自动被阻止，不提示用户。拒绝的域仍从所有源受尊重。默认：false | `true` |
432| `network.httpProxyPort` | 如果您想自带代理，使用的 HTTP 代理端口。如果未指定，Claude 将运行自己的代理。 | `8080` |
433| `network.socksProxyPort` | 如果您想自带代理，使用的 SOCKS5 代理端口。如果未指定，Claude 将运行自己的代理。 | `8081` |
434| `network.tlsTerminate` | 实验性。在 sandbox 代理内终止 TLS，以便它可以读取 HTTPS 请求的内容。[凭证替换](/docs/zh-CN/sandboxing#protect-credentials)的 `mask` 需要。设置 `{}` 以为会话生成临时证书颁发机构，或设置 `caCertPath` 和 `caKeyPath` 以使用您自己的。仅从用户、managed 或 CLI `--settings` 设置受尊重，不从 `.claude/settings.json` 或 `.claude/settings.local.json`。需要 Claude Code v2.1.199 或更高版本。} | `{}` |
435| `enableWeakerNestedSandbox` | 为无特权 Docker 环境启用较弱的 sandbox（仅 Linux 和 WSL2）。**降低安全性。** 默认：false | `true` |
436| `enableWeakerNetworkIsolation` | （仅 macOS）允许在 sandbox 中访问系统 TLS 信任服务（`com.apple.trustd.agent`）。对于 Go 基础工具（如 `gh`、`gcloud` 和 `terraform`）在使用 `httpProxyPort` 与 MITM 代理和自定义 CA 时验证 TLS 证书是必需的。**通过打开潜在的数据泄露路径降低安全性**。默认：false | `true` |
437| `allowAppleEvents` | （仅 macOS）允许 sandboxed 命令发送 Apple Events。对于 `open`、`osascript` 和在浏览器中打开 URL 的工具是必需的，否则会失败并显示错误 `-600`。**删除代码执行隔离。** Sandboxed 命令可以无用户提示地启动其他应用程序无 sandbox；它们也可以向运行的应用程序（如 Terminal）发送 AppleScript 命令，受每个应用程序 macOS 自动化同意提示（TCC）的约束。仅从用户、managed 或 CLI 设置受尊重，不从项目设置。默认：false | `true` |
438| `bwrapPath` | （仅 Managed 设置，Linux/WSL2）bubblewrap (`bwrap`) 二进制文件的绝对路径。覆盖通过 `PATH` 的自动检测。仅从 [managed 设置](/docs/zh-CN/settings#settings-precedence)受尊重，不从用户或项目设置。在 managed 环境中 `bwrap` 安装在非标准位置时很有用。 | `/opt/admin/bwrap` |
439| `socatPath` | （仅 Managed 设置，Linux/WSL2）用于 sandbox 网络代理的 `socat` 二进制文件的绝对路径。覆盖通过 `PATH` 的自动检测。仅从 managed 设置受尊重。 | `/opt/admin/socat` |
440
441<h4 id="sandbox-path-prefixes">
442 Sandbox 路径前缀
443</h4>
444 517
445`filesystem.allowWrite`、`filesystem.denyWrite`、`filesystem.denyRead`、`filesystem.allowRead` 和 `credentials.files` 中的路径支持这些前缀：518* [服务器托管设置](/docs/zh-CN/server-managed-settings)，Claude Code 从 claude.ai 管理控制台或自托管的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)获取
519* MDM 或操作系统级别的策略，以及系统目录中的 `managed-settings.json` 文件
520* 嵌入主机（如 Claude Desktop），通过 SDK `managedSettings` 选项；请参阅[从嵌入主机控制策略](/docs/zh-CN/managed-settings#parent-settings-from-embedding-hosts)
446 521
447| 前缀 | 含义 | 示例 |522在在 Claude Desktop 应用中在你的机器上运行的 [Cowork](https://claude.com/docs/cowork/overview) 会话中，Claude Code 不从 claude.ai 管理控制台获取服务器托管设置，它读取部署到你的设备的策略，除非你的组织的 Claude Desktop 配置设置 `requireCoworkFullVmSandbox`。[策略应用的位置和时间](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies)涵盖 Cowork 和云会话。
448| :-------- | :---------------------------------- | :---------------------------------------------------------------- |
449| `/` | 从文件系统根目录的绝对路径 | `/tmp/build` 保持 `/tmp/build` |
450| `~/` | 相对于主目录 | `~/.kube` 变为 `$HOME/.kube` |
451| `./` 或无前缀 | 相对于项目设置的项目根目录，或相对于用户设置的 `~/.claude` | `./output` 在 `.claude/settings.json` 中解析为 `<project-root>/output` |
452 523
453较旧的 `//path` 前缀用于绝对路径仍然有效。如果您之前使用单斜杠 `/path` 期望项目相对解析，请切换到 `./path`。此语法与[读取和编辑权限规则](/docs/zh-CN/permissions#read-and-edit)不同，后者使用 `//path` 用于绝对和 `/path` 用于项目相对。Sandbox 文件系统路径使用标准约定：`/tmp/build` 是绝对路径。524如果你是管理员，[为你的组织设置 Claude Code](/docs/zh-CN/admin-setup) 会指导你选择要强制执行的内容，[部署托管设置](/docs/zh-CN/managed-settings)涵盖交付以及如何确认策略生效。
454 525
455**配置示例：**526<h2 id="change-a-setting">
527 更改设置
528</h2>
456 529
457```json theme={null}530您可以从 `/config` 菜单、通过编辑设置文件或对一个会话从命令行更改设置。
458{
459 "sandbox": {
460 "enabled": true,
461 "autoAllowBashIfSandboxed": true,
462 "excludedCommands": ["docker *"],
463 "filesystem": {
464 "allowWrite": ["/tmp/build", "~/.kube"],
465 "denyRead": ["~/.aws/credentials"]
466 },
467 "network": {
468 "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
469 "deniedDomains": ["uploads.github.com"],
470 "allowUnixSockets": [
471 "/var/run/docker.sock"
472 ],
473 "allowLocalBinding": true
474 }
475 }
476}
477```
478 531
479**文件系统和网络限制**可以通过两种合并在一起的方式配置：532<span id="system-prompt" />
480 533
481* **`sandbox.filesystem` 设置**（如上所示）：在 OS 级 sandbox 边界处控制路径。这些限制适用于所有子进程命令（例如 `kubectl`、`terraform`、`npm`），而不仅仅是 Claude 的文件工具。534Claude Code 的系统提示未发布。要给 Claude 常设指令，使用 [`CLAUDE.md` 文件](/docs/zh-CN/memory)或 `--append-system-prompt` 标志。
482* **权限规则**：使用 `Edit` 允许/拒绝规则控制 Claude 的文件工具访问，`Read` 拒绝规则阻止读取，`WebFetch` 允许/拒绝规则控制网络域。这些规则中的路径也合并到 sandbox 配置中。
483 535
484<h3 id="attribution-settings">536<h3 id="use-the-/config-menu">
485 归属设置537 使用 /config 菜单
486</h3>538</h3>
487 539
488Claude Code 为 git 提交和拉取请求添加归属。这些分别配置：540在 Claude Code 内运行 `/config` 并打开**配置**选项卡。它列出了一小组个人选项，如主题、编辑器模式和详细输出，而不是每个设置键。选择一个选项来更改它；Claude Code 为您保存它：
489
490* 提交默认使用 [git trailers](https://git-scm.com/docs/git-interpret-trailers)（如 `Co-Authored-By`），可以自定义或禁用
491* 拉取请求描述是纯文本
492 541
493| 键 | 描述 |542* **大多数选项**：`~/.claude/settings.json`
494| :----------- | :------------------------------------------------------------------------------------------------------------- |543* **一些选项，如显示提示**：`.claude/settings.local.json`
495| `commit` | git 提交的归属，包括任何 trailers。空字符串隐藏提交归属 |544* **[全局配置选项](/docs/zh-CN/settings-reference#global-config-settings)**：`~/.claude.json`
496| `pr` | 拉取请求描述的归属。空字符串隐藏拉取请求归属 |
497| `sessionUrl` | 当从 web 或远程控制会话运行时，是否将 claude.ai 会话链接作为提交上的 `Claude-Session` trailer 和拉取请求描述中的链接附加。默认为 `true`。设置为 `false` 以省略链接 |
498 545
499**默认提交归属：**546要设置一个选项而不使用菜单，传递 `key=value`，例如 `/config verbose=true`。
500
501```text theme={null}
502Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
503```
504
505会话的活跃模型在 trailer 中反映。
506
507**默认拉取请求归属：**
508
509```text theme={null}
510🤖 Generated with [Claude Code](https://claude.com/claude-code)
511```
512
513**示例：**
514
515```json theme={null}
516{
517 "attribution": {
518 "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
519 "pr": ""
520 }
521}
522```
523 547
524<Note>548<Note>
525 `attribution` 设置优先于已弃用的 `includeCoAuthoredBy` 设置。要隐藏所有归属，将 `commit` 和 `pr` 设置为空字符串，并将 `sessionUrl` 设置为 `false`。549 `/config` 是终端界面的一部分。[VS Code](/docs/zh-CN/vs-code) 聊天面板和[桌面应用](/docs/zh-CN/desktop)不打开它；通过编辑设置文件或通过这些应用自己的设置在那里更改设置。
526</Note>550</Note>
527 551
528<h3 id="file-suggestion-settings">552<h3 id="edit-a-settings-file">
529 文件建议设置553 编辑设置文件
530</h3>
531
532为 `@` 文件路径自动完成配置自定义命令。内置文件建议使用快速文件系统遍历，但大型 monorepos 可能受益于项目特定的索引，例如预构建的文件索引或自定义工具。
533
534```json theme={null}
535{
536 "fileSuggestion": {
537 "type": "command",
538 "command": "~/.claude/file-suggestion.sh"
539 }
540}
541```
542
543该命令使用与 [hooks](/docs/zh-CN/hooks) 相同的环境变量运行，包括 `CLAUDE_PROJECT_DIR`。它通过 stdin 接收包含 `query` 字段的 JSON：
544
545```json theme={null}
546{"query": "src/comp"}
547```
548
549将换行符分隔的文件路径输出到 stdout（当前限制为 15）：
550
551```text theme={null}
552src/components/Button.tsx
553src/components/Modal.tsx
554src/components/Form.tsx
555```
556
557**示例：**
558
559```bash theme={null}
560#!/bin/bash
561query=$(cat | jq -r '.query')
562# 用您自己的文件搜索命令替换 your-repo-file-index
563your-repo-file-index --query "$query" | head -20
564```
565
566<h3 id="footer-link-badges">
567 页脚链接徽章
568</h3>554</h3>
569 555
570`footerLinksRegexes` 设置在输入框下方的页脚中渲染额外的可点击徽章。使用它将项目 CLI 打印的 ID（如审查工具和问题跟踪器）转换为会话链接。556在您的编辑器中打开您想要的作用域的设置文件并添加或更改键。设置文件是严格的 JSON：`//` 注释或尾部逗号是语法错误，Claude Code 在下次启动时将文件报告为[设置错误](#fix-a-broken-settings-file)。例如，要让 Claude Code 在不询问的情况下运行您的 lint 和测试命令并阻止它读取 `.env` 文件，将此添加到 `~/.claude/settings.json`：
571
572每个条目的 `pattern` 正则表达式与轮次输出匹配：工具结果，包括文件内容和获取的页面，以及 Claude 自己的响应。`url` 和 `label` 中的 `{name}` 占位符从模式中的命名捕获组填充。
573
574以下示例在问题键（如 `PROJ-1234`）出现在轮次输出中时渲染徽章。`(?<key>...)` 命名组捕获键，`{key}` 将其替换到 URL 和标签中：
575 557
576```json ~/.claude/settings.json theme={null}558```json ~/.claude/settings.json theme={null}
577{559{
578 "footerLinksRegexes": [560 "$schema": "https://json.schemastore.org/claude-code-settings.json",
579 {561 "permissions": {
580 "type": "regex",562 "allow": [
581 "pattern": "\\b(?<key>PROJ-\\d+)\\b",563 "Bash(npm run lint)",
582 "url": "https://issues.example.com/browse/{key}",564 "Bash(npm run test *)"
583 "label": "{key}"565 ],
584 }566 "deny": [
567 "Read(./.env)",
568 "Read(./.env.*)"
585 ]569 ]
570 }
586}571}
587```572```
588 573
589配置此后，当 `PROJ-1234` 出现在工具结果或 Claude 的回复中时，一个 `PROJ-1234` 徽章出现在页脚中，链接到 `https://issues.example.com/browse/PROJ-1234`。574`permissions` 下的每个条目是一个命名工具及其可能做什么的规则；[配置权限](/docs/zh-CN/permissions)解释语法。`$schema` 行指向 Claude Code 设置的[已发布 JSON 架构](https://json.schemastore.org/claude-code-settings.json)，它在 VS Code、Cursor 和任何其他支持 JSON 架构的编辑器中为您提供自动完成和内联验证。架构可能滞后于最新的 CLI 版本，因此最近记录的键上的验证警告并不意味着您的配置无效。
590
591以下约束适用于每个条目：
592 575
593| 约束 | 行为 |576保存后，在 Claude Code 内运行 `/status` 以确认文件已加载；[确认已加载的内容](#check-what-loaded)说明 `Setting sources` 行显示什么以及如何报告损坏的文件。
594| :----- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
595| URL 源 | 捕获的值是 URL 编码的，构造的 URL 必须与模板的字面源共享。捕获可以填充路径段或查询值，但无法改变链接指向的位置 |
596| URL 长度 | 超过 2048 字符的构造 URL 被丢弃 |
597| URL 方案 | 必须是 `https`、`http` 或公认的编辑器或工作区深链接方案：`vscode`、`vscode-insiders`、`cursor`、`windsurf`、`zed`、`jetbrains`、`idea`、`slack`、`linear`、`notion`、`figma` |
598| 标签 | 默认为匹配的文本，截断为 28 个显示列 |
599| 徽章计数 | 最多 5 个徽章渲染。最旧的被较新的匹配替换，`/clear` 删除它们 |
600| 设置作用域 | 仅从用户设置、`--settings` 标志和 managed 设置读取。在项目 `.claude/settings.json` 和本地 `.claude/settings.local.json` 中被忽略 |
601 577
602当轮次完成时，Claude Code 在主线程上将每个条目的 `pattern` 正则表达式与轮次输出匹配，因此缓慢的正则表达式会阻止 UI，直到完成。嵌套量词（如 `(a+)+$`）可能对某些输入花费指数级长时间并冻结会话，因此保持每个 `pattern` 线性并避免嵌套 `+` 或 `*`。578有关完整的个人文件、团队文件和组织文件，每个都带有每个键的注释，请参阅[示例设置文件](/docs/zh-CN/settings-example)。
603 579
604页脚徽章与[自定义状态行](/docs/zh-CN/statusline)一起渲染，当配置了一个时；两者都不替换另一个。使用状态行用于从会话数据计算自己内容的脚本驱动行，使用页脚徽章将对话中的 ID 转换为链接，无需脚本。580<span id="pass-settings-for-one-session" />
605 581
606<h3 id="hook-configuration">582<h3 id="change-a-setting-for-one-session">
607 Hook 配置583 为一个会话更改设置
608</h3>584</h3>
609 585
610这些设置控制允许运行哪些 hooks 以及 HTTP hooks 可以访问什么。`allowManagedHooksOnly` 设置只能在 [managed 设置](#settings-files)中配置。URL 和环境变量允许列表可以在任何设置级别设置并跨源合并。586要尝试一个值而不保存它，在启动 Claude Code 时设置它。该值适用于该会话，您的设置文件保持原样。您有三种方式做到：
611
612**当 `allowManagedHooksOnly` 为 `true` 时的行为：**
613 587
614* 加载 Managed hooks 和 SDK hooks588* **`--settings`**：将键作为 JSON 传递，内联或作为文件路径。Claude Code 在您的用户、项目和本地文件上方以及托管设置下方应用它。它可以设置您的用户设置文件可以设置的任何键；它不能设置 `Managed` 或 `Global config` 键。
615* 从在 managed 设置 `enabledPlugins` 中强制启用的插件加载 Hooks。这让管理员通过组织市场分发经过审查的 hooks，同时阻止其他所有内容。信任由完整的 `plugin@marketplace` ID 授予，因此来自不同市场的同名插件保持被阻止589* **该键的标志**：某些键有自己的标志，如 `--model` 用于 `model` 和 `--effort` 用于 `effortLevel` 和 `modelSettings`。
616* 用户 hooks、项目 hooks 和所有其他插件 hooks 被阻止590* **环境变量**：在运行 `claude` 之前导出键的配对变量，如 `ANTHROPIC_MODEL` 用于 `model`。
617 591
618**限制 HTTP hook URL：**592每个键在[设置参考](/docs/zh-CN/settings-reference)上的条目列出其每个会话覆盖以及哪个优先，因此检查您想更改的键的条目。
619 593
620限制 HTTP hooks 可以针对的 URL。支持 `*` 作为匹配的通配符。定义数组后，针对不匹配 URL 的 HTTP hooks 被静默阻止。主机名匹配不区分大小写，忽略尾部 FQDN 点，匹配 DNS 语义。594您在会话内运行的命令大多保存您的选择：当您在 `/config` 中更改设置时，Claude Code 将其写入您的设置文件，`/model` 将值保存为您新会话的默认值。
621
622```json theme={null}
623{
624 "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
625}
626```
627 595
628**限制 HTTP hook 环境变量：**596如果您在 `/model` 选择器中按 `s`，Claude Code 切换模型而不将其保存为您的用户默认值。[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level)说明哪些 `/effort` 选择 Claude Code 保存为您使用的模型的默认值，哪些仅适用于当前会话。
629 597
630限制 HTTP hooks 可以插入到标头值中的环境变量名称。每个 hook 的有效 `allowedEnvVars` 是其自己列表与此设置的交集。598例如，要在 Opus 上启动一个会话而不更改您的默认值：
631 599
632```json theme={null}600```bash theme={null}
633{601claude --settings '{"model": "claude-opus-4-8"}'
634 "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
635}
636```602```
637 603
638<h3 id="compute-managed-settings-with-a-policy-helper">604<h3 id="when-edits-take-effect">
639 使用策略助手计算 managed 设置605 编辑何时生效
640</h3>606</h3>
641 607
642`policyHelper` 设置指向一个可执行文件，在启动时动态计算 managed 设置，因此管理员可以从设备状态、身份或远程服务而不是静态文件派生策略。从 MDM 或系统 `managed-settings.json` 文件配置它。Claude Code 在 `policyHelper` 出现在任何其他作用域时忽略它，包括用户设置、项目设置、HKCU 注册表配置单元和[服务器管理的设置](/docs/zh-CN/server-managed-settings)。608Claude Code 监视您的设置文件并在它们更改时重新加载它们，因此它在运行的会话中应用大多数编辑而不需要重启，包括对 `permissions`、`hooks` 和凭证助手（如 `apiKeyHelper`）的编辑。Claude Code 也在会话中期加载您创建的设置文件，如果其文件夹在会话启动时存在。对于项目的 `.claude/` 文件夹，即使您在同一会话中创建文件夹，它也加载文件。
643 609
644该设置接受这些键：610重新加载涵盖用户、项目、本地和托管设置，Claude Code 为每个它检测到的设置文件更改运行 [`ConfigChange` hook](/docs/zh-CN/hooks#configchange)，而不是来自 MDM 或 claude.ai 控制台的托管设置。来自 MDM 或 claude.ai 控制台的托管设置按计划而不是保存时到达运行的会话；[传递表](/docs/zh-CN/managed-settings#choose-a-delivery-mechanism)给出每个来源的。
645 611
646| 键 | 类型 | 描述 |612Claude Code 仅在会话启动时读取某些键一次，因此对其中一个的编辑不会到达运行的会话。也等待重启的管理员端键，如 `requiredMinimumVersion`，在[策略适用的位置和时间](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies)下列出。您最可能在会话中期编辑的：
647| ------------------- | ------ | -------------------------------------- |
648| `path` | string | 助手可执行文件的绝对路径 |
649| `timeoutMs` | number | 在将运行视为失败之前等待助手多长时间 |
650| `refreshIntervalMs` | number | 在后台重新运行助手的频率。设置为 `0` 以禁用刷新，或至少 `60000` |
651 613
652助手将 JSON 信封写入 stdout。将设置放在 `managedSettings` 键下而不是顶级，因为裸设置对象解析时 `managedSettings` 未定义并应用任何内容：614* [`model`](/docs/zh-CN/settings-reference#model)：使用 [`/model`](/docs/zh-CN/model-config#setting-your-model) 在会话中期切换。每个模型有自己的提示缓存，因此切换后的第一个请求重新读取整个对话未缓存；请参阅[切换模型](/docs/zh-CN/prompt-caching#switching-models)
615* [`effortLevel`](/docs/zh-CN/settings-reference#effortlevel) 和 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings)：使用 [`/effort`](/docs/zh-CN/model-config#adjust-effort-level) 在会话中期更改努力
653 616
654```json theme={null}617<span id="verify-active-settings" />
655{
656 "managedSettings": {
657 "permissions": { "deny": ["Read(//etc/secrets/**)"] }
658 },
659 "claudeMd": "# Organization context\n...",
660 "appendSystemPrompt": "Always cite the internal style guide."
661}
662```
663 618
664当助手发出 `managedSettings` 时，该对象替换该运行的基于文件的 managed 设置。当助手在启动时以非零状态退出时，Claude Code 打印错误并拒绝启动，因此需要中断恢复的助手应从其自己的缓存提供并以 `0` 退出。619<span id="check-what-loaded" />
665 620
666<h3 id="settings-precedence">621<h3 id="confirm-what-loaded">
667 设置优先级622 确认已加载的内容
668</h3>623</h3>
669 624
670设置按优先级顺序应用。从最高到最低：625在 Claude Code 内运行 `/status` 以查看哪些设置来源处于活跃状态。**状态**选项卡包含一个 `Setting sources` 行，列出 Claude Code 为当前会话加载的每个设置文件，如 `User settings` 或 `Project local settings`。当[托管设置](/docs/zh-CN/admin-setup#decide-how-settings-reach-devices)生效时，托管设置条目在括号中显示它们如何到达您的机器。
671
6721. **Managed 设置**（[服务器管理](/docs/zh-CN/server-managed-settings)、[MDM/OS 级别策略](#configuration-scopes) 或 [managed 设置](#settings-files)）
673 * 由 IT 通过服务器交付、MDM 配置文件、注册表策略或 managed 设置文件部署的策略
674 * 无法被任何其他级别覆盖，包括命令行参数
675 * 在 managed 层内，仅使用一个源，其他源被忽略而不是合并。优先级，从最高到最低：
676 * [`policyHelper`](#compute-managed-settings-with-a-policy-helper) 输出：当配置时，这是唯一使用的 managed 源
677 * 远程（claude.ai [服务器管理](/docs/zh-CN/server-managed-settings) 或 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 交付）
678 * MDM/OS 级别策略
679 * 基于文件（`managed-settings.d/*.json` 和 `managed-settings.json`，合并在一起）
680 * HKCU 注册表（仅 Windows）
681 * 少数几个键是例外，当任何管理员控制的 managed 源设置它们时被尊重，而不仅仅是获胜的源。用户可写的 HKCU 注册表源被排除。例外键是：
682 * sandbox 锁定键 `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`，带有其关联的允许列表
683 * `allowAllClaudeAiMcps`
684 * sandbox 二进制路径 `sandbox.bwrapPath` 和 `sandbox.socatPath`
685 * [`forceRemoteSettingsRefresh`](/docs/zh-CN/server-managed-settings)
686 * 嵌入主机（如 Claude Desktop）可以通过 SDK `managedSettings` 选项提供策略。默认情况下，当存在任何管理员部署的 managed 源时，这被忽略：服务器管理的设置、MDM 或 OS 级别策略或 managed 设置文件。用户可写的 HKCU 注册表回退不计为管理员部署的源。管理员可以通过将 [`parentSettingsBehavior`](#available-settings) 设置为 `"merge"` 来选择加入。嵌入器的值被筛选，以便它们可以收紧 managed 策略但不能放松它。
687 626
6882. **命令行参数**627该行确认 Claude Code 读取了哪些文件；它不显示哪个文件提供了每个键。要列出 Claude Code 拒绝的条目，运行 [`claude doctor`](/docs/zh-CN/debug-your-config)；对于项目或托管设置设置的模型，启动标头命名设置它的文件。`/status` 和 `/config` 在不同选项卡上打开相同的对话框，**配置**选项卡不是您的 `settings.json` 内容的视图。
689 * 特定会话的临时覆盖。通过 `--settings <file-or-json>` 传递的 JSON 使用与其他层相同的规则与基于文件的设置合并：此处设置的键覆盖本地、项目或用户设置中的相同键，省略键会保留较低层的值
690 628
6913. **本地项目设置**（`.claude/settings.local.json`）629<h3 id="fix-a-broken-settings-file">
692 * 个人项目特定设置630 修复损坏的设置文件
631</h3>
693 632
6944. **共享项目设置**（`.claude/settings.json`）633如果您拼错 JSON 或将键设置为 Claude Code 不接受的值，Claude Code 在交互式会话启动时告诉您。它显示的内容取决于文件受影响的程度：
695 * 源代码管理中的团队共享项目设置
696 634
6975. **用户设置**（`~/.claude/settings.json`）635* **设置错误**：用户、项目或本地文件有无效的 JSON 或架构拒绝的值。在交互式会话启动时，Claude Code 显示一个对话框，让您在 Claude 的帮助下修复文件、退出或继续使用损坏的设置。
698 * 个人全局设置636* **设置警告**：仅单个条目失败，如格式错误的权限规则或未知的 hook 事件名称。Claude Code 跳过这些值并保持文件的其余部分生效。
637* **托管设置**：Claude Code 继续强制执行文件的其余部分。[托管设置中的无效条目](/docs/zh-CN/managed-settings#invalid-entries-in-managed-settings)说明它删除什么以及哪些键回退到更严格的值，直到您修复它们。对于不是有效 JSON 的托管设置文档，请参阅[托管设置文档无法解析](/docs/zh-CN/errors#managed-settings-document-could-not-be-parsed)。
638* **配置错误**：`~/.claude.json` 无法解析。Claude Code 将损坏的文件复制到 `~/.claude/backups/.claude.json.corrupted.<timestamp>` 并询问是否退出并手动修复它或重置为默认配置；`-p` 运行打印错误并退出。要恢复您之前的状态，复制回 `~/.claude/backups/` 中最近五个 `.claude.json.backup.<timestamp>` 文件之一，Claude Code 在写入文件前保存。
699 639
700此层次结构确保组织策略始终被强制执行，同时仍允许团队和个人自定义其体验。无论您从 CLI、[VS Code 扩展](/docs/zh-CN/vs-code) 还是 [JetBrains IDE](/docs/zh-CN/jetbrains) 运行 Claude Code，相同的优先级都适用。640在您继续后，运行 `/status` 以查看受影响的文件，`claude doctor` 以查看每个错误的详情。
701 641
702例如，如果您的用户设置将 `permissions.defaultMode` 设置为 `acceptEdits`，而项目的共享设置将其设置为 `default`，则项目值适用。下面的示例涵盖了数组值设置（如权限规则）如何组合的方式。642`-p` 运行显示无对话框。除非[托管设置文档无法解析](/docs/zh-CN/errors#managed-settings-document-could-not-be-parsed)，Claude Code 跳过损坏的文件或值并继续其余的，因此在忽略设置的 `-p` 运行后，运行 `claude doctor` 以查看它删除了什么。
703 643
704<Note>644<span id="how-scopes-interact" />
705 **数组设置跨作用域合并。** 当相同的数组值设置（例如 `sandbox.filesystem.allowWrite` 或 `permissions.allow`）出现在多个作用域中时，数组被**连接和去重**，而不是替换。这意味着较低优先级的作用域可以添加条目而不覆盖由较高优先级作用域设置的条目，反之亦然。例如，如果 managed 设置将 `allowWrite` 设置为 `["/opt/company-tools"]`，用户添加 `["~/.kube"]`，则最终配置中包含两个路径。
706 645
707 两个数组设置不以这种方式合并：646<span id="key-points-about-the-configuration-system" />
708 647
709 * [`fallbackModel`](#available-settings) 是一个有序链，其中位置具有意义：定义它的最高优先级文件提供整个值。648<span id="which-value-claude-code-uses" />
710 * [`availableModels`](#available-settings)：当[最高优先级 managed 源](/docs/zh-CN/server-managed-settings#settings-precedence)定义它时，该列表按原样应用，用户、项目和本地条目无法扩展它。跨非 managed 作用域，数组照常合并。请参阅[合并行为](/docs/zh-CN/model-config#merge-behavior)。
711</Note>
712 649
713<h3 id="verify-active-settings">650<span id="which-value-wins" />
714 验证活跃设置
715</h3>
716 651
717在 Claude Code 中运行 `/status` 以查看哪些设置源处于活跃状态。在菜单中，**状态**选项卡包含一个 `Setting sources` 行，列出 Claude Code 为当前会话加载的每个层，例如 `User settings` 或 `Project local settings`。当[managed 设置](/docs/zh-CN/admin-setup#decide-how-settings-reach-devices)生效时，该条目在括号中显示交付渠道，例如 `Enterprise managed settings (remote)`、`(plist)`、`(HKLM)`、`(HKCU)` 或 `(file)`。仅当该源被加载且至少有一个键时，层才出现在列表中，因此空列表意味着未找到设置源。652<h2 id="settings-precedence">
653 设置优先级
654</h2>
718 655
719`Setting sources` 行确认正在读取哪些源。它不显示哪一层提供了每个单独的键。同一对话框中的**配置**选项卡是一个编辑器，用于一组固定的切换，例如主题和详细输出，而不是您的 `settings.json` 内容的视图。656当同一键出现在多个位置时，Claude Code 使用设置它的最高级别的值。下面的堆栈显示级别，最高在顶部；更高级别的键覆盖它在下面任何地方的相同键。
720 657
721如果设置文件包含错误，例如无效的 JSON 或验证失败的值，`/status` 列出受影响的文件。运行 `/doctor` 以查看每个错误的详情。658<SettingsPrecedence />
722 659
723<h3 id="key-points-about-the-configuration-system">660按顺序，最高优先级优先：
724 配置系统的关键点
725</h3>
726 661
727* **内存文件（`CLAUDE.md`）**：包含 Claude 在启动时加载的说明和上下文6621. **托管设置**：您的组织部署的设置，通过 `managed-settings.json` 文件、MDM 策略或来自 claude.ai 控制台的[服务器管理设置](/docs/zh-CN/server-managed-settings)。您设置的任何内容都不会覆盖它们：您使用 `--settings` 传递的键不会覆盖相同的托管键，`--model` 等标志仅从您的组织允许的模型中选择。托管 `model` 设置每个会话启动的模型，您仍然可以使用 `/model` 切换；锁定是 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels)，它限制 `/model`、`--model` 和您自己文件中的 `model` 键。当您的组织传递多个托管来源时，[托管层内的优先级](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)的规则说 Claude Code 从每个读取什么。
728* **设置文件（JSON）**：配置权限、环境变量和工具行为6632. **命令行参数**：您在从终端启动 `claude` 时传递的标志，用于一个会话；请参阅[为一个会话更改设置](#change-a-setting-for-one-session)。Claude Code 使用与其他级别相同的规则将您使用 `--settings <file-or-json>` 传递的 JSON 与您的设置文件合并：它在此处设置的键优先于本地、项目或用户设置中的相同键，省略的键保持较低级别的值。
729* **Skills**：可以使用 `/skill-name` 调用或由 Claude 自动加载的自定义提示6643. **项目本地设置** (`.claude/settings.local.json`)：您对此项目的个人设置。
730* **MCP servers**：使用额外的工具和集成扩展 Claude Code6654. **共享项目设置** (`.claude/settings.json`)：您的团队检入源代码管理的设置。
731* **优先级**：更高级别的配置（Managed）覆盖较低级别的配置（User/Project）6665. **用户设置** (`~/.claude/settings.json`)：您对每个项目的个人设置。
732* **继承**：设置被合并跨作用域；来自较高优先级作用域的标量值覆盖，数组连接，有两个例外，如[数组合并注释](#settings-precedence)中所述
733 667
734<h3 id="system-prompt">668环境变量不是此堆栈中的级别。当行为同时有 shell 变量和设置键时，哪个适用是按对决定的，而不是按级别：在您的 shell 中导出的 `ANTHROPIC_MODEL` 适用于任何文件中的 `model` 键，而 `ANTHROPIC_DEFAULT_MODEL` 仅当没有文件设置 `model` 时适用。[环境变量参考](/docs/zh-CN/env-vars#precedence)说哪些键有对以及 Claude Code 首先读取哪个。设置文件内的 `env` 块是普通键并遵循上面的级别。
735 系统提示
736</h3>
737 669
738Claude Code 的内部系统提示未发布。要添加自定义说明，请使用 `CLAUDE.md` 文件或 `--append-system-prompt` 标志。670对于少数安全敏感的键，Claude Code 尊重来自较低级别的更严格值而不是托管值；[托管设置优先级的例外](#exceptions-to-managed-settings-precedence)列出它们。
739 671
740<h3 id="exclude-sensitive-files">672<h3 id="lists-merge-instead-of-overriding">
741 排除敏感文件673 列表合并而不是覆盖
742</h3>674</h3>
743 675
744要防止 Claude Code 访问包含敏感信息（如 API 密钥、secrets 和环境文件）的文件，请在您的 `.claude/settings.json` 文件中使用 `permissions.deny` 设置：676当您在多个文件中设置相同的列表键（如 `permissions.allow`）时，Claude Code 组合列表而不是选择一个，因此每个文件可以添加条目而不删除另一个文件的。四个保存模型列表或每个模型条目的键遵循自己的规则：
745
746```json theme={null}
747{
748 "permissions": {
749 "deny": [
750 "Read(./.env)",
751 "Read(./.env.*)",
752 "Read(./secrets/**)",
753 "Read(./config/credentials.json)",
754 "Read(./build)"
755 ]
756 }
757}
758```
759
760这替代了已弃用的 `ignorePatterns` 配置。匹配这些模式的文件被排除在文件发现和搜索结果之外，这些文件上的读取操作被拒绝。
761
762<h2 id="subagent-configuration">
763 Subagent 配置
764</h2>
765 677
766Claude Code 支持可在用户和项目级别配置的自定义 AI subagents。这些 subagents 存储为带有 YAML frontmatter 的 Markdown 文件：678* [`fallbackModel`](/docs/zh-CN/settings-reference#fallbackmodel) 是一个有序链，其中位置具有意义，因此 Claude Code 从定义它的最高优先级文件获取整个值。
679* [`modelPicker`](/docs/zh-CN/settings-reference#modelpicker) 保存一个有序的行列表加上替换标志，因此 Claude Code 永远不会合并来自两个来源的行。它从托管设置、`--settings` 和用户设置中定义它的最高获取整个值，并忽略项目和本地设置中的键。需要 Claude Code v2.1.242 或更高版本。
680* [`availableModels`](/docs/zh-CN/settings-reference#availablemodels)：当 Claude Code 应用的托管设置定义它时，Claude Code 按原样应用该列表并忽略您在用户、项目或本地设置中添加的条目，除非嵌入 Claude Code 的应用提供自己的模型列表；请参阅[托管设置优先级的例外](#exceptions-to-managed-settings-precedence)。跨托管来源列表也永远不会合并；[Claude Code 如何组合托管来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说哪个来源的列表适用。跨非托管作用域 Claude Code 照常合并数组。
681* [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings)：Claude Code 一次解决它一个模型，与 [`effortLevel`](/docs/zh-CN/settings-reference#effortlevel) 一起。`modelSettings` 条目说明哪个文件的值适用于模型。
767 682
768* **用户 subagents**：`~/.claude/agents/`，在所有项目中可用683<span id="examples" />
769* **项目 subagents**：`.claude/agents/`，特定于您的项目，可与您的团队共享
770 684
771Subagent 文件定义具有自定义提示和工具权限的专门 AI 助手。在 [subagents 文档](/docs/zh-CN/sub-agents)中了解有关创建和使用 subagents 的更多信息。685<h3 id="precedence-examples">
772 686 优先级示例
773<h2 id="plugin-configuration">
774 插件配置
775</h2>
776
777Claude Code 支持一个插件系统，让您可以使用 skills、agents、hooks 和 MCP servers 扩展功能。插件通过市场分发，可以在用户和存储库级别配置。
778
779<h3 id="plugin-settings">
780 插件设置
781</h3>687</h3>
782 688
783`settings.json` 中的插件相关设置：689当 Claude 工作时，Claude Code 在微调器下显示一行提示，如"使用 /config 更改您的默认权限模式（包括 Plan Mode）"。假设您想关闭这些提示，因此您在 `~/.claude/settings.json` 中将 [`spinnerTipsEnabled`](/docs/zh-CN/settings-reference#spinnertipsenabled) 设置为 `false`。下面的每个场景是可以打开它们的东西，以及您可以做什么。
784
785```json theme={null}
786{
787 "enabledPlugins": {
788 "formatter@acme-tools": true,
789 "deployer@acme-tools": true,
790 "analyzer@security-plugins": false
791 },
792 "extraKnownMarketplaces": {
793 "acme-tools": {
794 "source": {
795 "source": "github",
796 "repo": "acme-corp/claude-plugins"
797 }
798 }
799 }
800}
801```
802 690
803<h4 id="enabledplugins">691<h4 id="team-settings-override-personal-settings">
804 `enabledPlugins`692 团队设置覆盖个人设置
805</h4>693</h4>
806 694
807控制启用哪些插件。格式：`"plugin-name@marketplace-name": true/false`。没有在任何作用域中有条目的插件会回退到其 [`defaultEnabled`](/docs/zh-CN/plugins-reference#default-enablement) 值。695您的团队的 `.claude/settings.json` 将其设置为 `true`。Claude Code 使用项目值，因为共享项目位于用户上方，因此您在该项目中看到提示，其他地方都没有。
808 696
809**作用域**：697您可以恢复您的值：在该项目中的 `.claude/settings.local.json` 中添加 `"spinnerTipsEnabled": false`。项目本地位于共享项目上方，因此您的会话停止显示提示，您队友的会话不改变。
810
811* **用户设置**（`~/.claude/settings.json`）：个人插件偏好
812* **项目设置**（`.claude/settings.json`）：与团队共享的项目特定插件
813* **本地设置**（`.claude/settings.local.json`）：每台机器的覆盖，Claude Code 创建时被 gitignored
814* **Managed 设置**（`managed-settings.json`）：组织范围的策略覆盖，在所有作用域中阻止安装并从市场隐藏插件
815
816<Note>
817 项目设置优先于用户设置，因此在 `~/.claude/settings.json` 中将插件设置为 `false` 不会禁用项目的 `.claude/settings.json` 启用的插件。要在您的机器上选择退出项目启用的插件，请改为在 `.claude/settings.local.json` 中将其设置为 `false`。
818
819 由 managed 设置强制启用的插件无法以这种方式禁用，因为 managed 设置会覆盖本地设置。
820
821 从外部源（如 GitHub 存储库或 npm 包）在项目的 `.claude/settings.json` 中启用插件不会为其他人安装它。从 Claude Code v2.1.195 开始，加载插件的每条路径都会要求每个用户在运行前[安装并信任插件](/docs/zh-CN/discover-plugins#configure-team-marketplaces)。
822</Note>
823
824**示例**：
825
826```json theme={null}
827{
828 "enabledPlugins": {
829 "code-formatter@team-tools": true,
830 "deployment-tools@team-tools": true,
831 "experimental-features@personal": false
832 }
833}
834```
835 698
836<h4 id="pluginconfigs">699<h4 id="organization-settings-override-everything">
837 `pluginConfigs`700 组织设置覆盖一切
838</h4>701</h4>
839 702
840存储插件的 [`userConfig`](/docs/zh-CN/plugins-reference#user-configuration) 提示收集的非敏感选项值，按插件 ID 键入。当您填写插件的配置对话框时，Claude Code 会将此键写入用户设置，因此您无需手动编辑它。敏感选项存储在 macOS Keychain 中，或在没有支持的 keychain 的平台上存储在 `~/.claude/.credentials.json` 中。703您的组织的托管设置将其设置为 `true`。您在用户、项目或本地设置中放入的任何内容都不会关闭提示，`--settings` 也不会。托管是最高级别。
841
842此示例为从 `acme-tools` 市场安装的插件存储一个选项：
843
844```json theme={null}
845{
846 "pluginConfigs": {
847 "deployer@acme-tools": {
848 "options": {
849 "api_endpoint": "https://api.example.com"
850 }
851 }
852 }
853}
854```
855 704
856`pluginConfigs` 仅从用户设置、`--settings` 标志和 managed 设置中读取。项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的条目被忽略，因为这些值被替换到插件 hook、MCP 和 LSP 配置中，克隆的存储库不得能够提供它们。在 v2.1.207 之前，项目和本地设置也被读取。705您无法恢复您的值。运行 `/status` 以查看哪个托管来源适用，并询问您的管理员策略是否应改变。
857 706
858<h4 id="extraknownmarketplaces">707<h4 id="the-command-line-overrides-your-files-for-one-session">
859 `extraKnownMarketplaces`708 命令行为一个会话覆盖您的文件
860</h4>709</h4>
861 710
862定义应为存储库提供的额外市场。通常在存储库级别设置中使用，以确保团队成员有权访问所需的插件源。711您使用 `claude --settings '{"spinnerTipsEnabled": true}'` 启动了会话。命令行位于除托管外的每个文件上方，因此该会话显示提示，即使您的文件说 `false`。
863
864**当存储库包含 `extraKnownMarketplaces` 时**：
865
8661. 当他们信任文件夹时，团队成员被提示安装市场
8672. 然后团队成员被提示从该市场安装插件
8683. 用户可以跳过不需要的市场或插件（存储在用户设置中）
8694. 安装尊重信任边界并需要明确同意
870
871**示例**：
872
873```json theme={null}
874{
875 "extraKnownMarketplaces": {
876 "acme-tools": {
877 "source": {
878 "source": "github",
879 "repo": "acme-corp/claude-plugins"
880 }
881 },
882 "security-plugins": {
883 "source": {
884 "source": "git",
885 "url": "https://git.example.com/security/plugins.git"
886 }
887 }
888 }
889}
890```
891
892**市场源类型**：
893
894* `github`：GitHub 存储库（使用 `repo`）
895* `git`：任何 git URL（使用 `url`）
896* `directory`：本地文件系统路径（使用 `path`，仅用于开发）
897* `hostPattern`：正则表达式模式以匹配市场主机（使用 `hostPattern`）
898* `settings`：直接在 settings.json 中声明的内联市场，无需单独的托管存储库（使用 `name` 和 `plugins`）
899
900`git` 源类型适用于任何 git 托管服务，包括自托管的 GitLab 和 Bitbucket。Claude Code 使用与该机器上 `git clone` 相同的身份验证克隆存储库：配置的凭证助手或 SSH 密钥。提供者令牌（如 `GITHUB_TOKEN`）仅通过读取它的凭证助手生效。有关设置详情，请参阅[私有存储库](/docs/zh-CN/plugin-marketplaces#private-repositories)。
901 712
902对于 `github` 和 `git` 源，在 `source` 对象内设置 `"skipLfs": true`（与 `repo` 或 `url` 一起）以在 Claude Code 克隆或更新市场存储库时跳过 Git LFS 下载。LFS 指针文件保持为指针而不是下载其内容。当存储库包含与插件内容无关的大型 LFS 对象时，使用此选项。需要 Claude Code v2.1.153 或更高版本。713您在下一个会话上恢复您的值；`--settings` 持续一个会话并不写入任何文件。
903
904每个市场条目还接受可选的 `autoUpdate` 布尔值。在 `source` 旁边设置 `"autoUpdate": true` 以使 Claude Code 在启动时刷新该市场并更新其已安装的插件。省略时，官方 Anthropic 市场默认为 `true`，所有其他市场默认为 `false`。请参阅[配置自动更新](/docs/zh-CN/discover-plugins#configure-auto-updates)。
905
906使用 `source: 'settings'` 声明一小组插件内联，无需设置托管市场存储库。此处列出的插件必须引用外部源，例如 GitHub 或 npm。您仍需要在 `enabledPlugins` 中单独启用每个插件。
907
908```json theme={null}
909{
910 "extraKnownMarketplaces": {
911 "team-tools": {
912 "source": {
913 "source": "settings",
914 "name": "team-tools",
915 "plugins": [
916 {
917 "name": "code-formatter",
918 "source": {
919 "source": "github",
920 "repo": "acme-corp/code-formatter"
921 }
922 }
923 ]
924 }
925 }
926 }
927}
928```
929 714
930<h4 id="strictknownmarketplaces">715<h4 id="a-flag-or-environment-variable-sets-the-same-thing">
931 `strictKnownMarketplaces`716 标志或环境变量设置相同的东西
932</h4>717</h4>
933 718
934**仅 Managed 设置**：控制用户允许添加和安装插件的插件市场。此设置只能在 [managed 设置](/docs/zh-CN/settings#settings-files) 中配置，为管理员提供对市场源的严格控制。719某些键有命令行标志或环境变量，无论哪个文件设置它都覆盖设置值：`ANTHROPIC_MODEL` 覆盖 [`model`](/docs/zh-CN/settings-reference#model) 设置，`--model` 为一个会话覆盖两者。
935
936**Managed 设置文件位置**：
937
938* **macOS**：`/Library/Application Support/ClaudeCode/managed-settings.json`
939* **Linux 和 WSL**：`/etc/claude-code/managed-settings.json`
940* **Windows**：`C:\Program Files\ClaudeCode\managed-settings.json`
941
942**关键特征**：
943
944* 仅在 managed 设置（`managed-settings.json`）中可用
945* 无法被用户或项目设置覆盖（最高优先级）
946* 在网络/文件系统操作之前强制执行（被阻止的源永远不会执行）
947* 对源规范使用精确匹配（包括 `ref`、`path` 用于 git 源），除了 `hostPattern` 和 `pathPattern`，它们使用正则表达式匹配
948
949**允许列表行为**：
950
951* `undefined`（默认）：无限制 - 用户可以添加任何市场
952* 空数组 `[]`：完全锁定 - 用户无法添加任何新市场
953* 源列表：用户只能添加与之完全匹配的市场
954
955**所有支持的源类型**：
956
957允许列表支持多种市场源类型。大多数源使用精确匹配，而 `hostPattern` 和 `pathPattern` 分别使用正则表达式匹配市场主机和文件系统路径。
958
9591. **GitHub 存储库**：
960
961```json theme={null}
962{ "source": "github", "repo": "acme-corp/approved-plugins" }
963{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
964{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }
965```
966
967字段：`repo`（必需）、`ref`（可选：分支或标签）、`path`（可选：子目录）
968
9692. **Git 存储库**：
970
971```json theme={null}
972{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
973{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
974{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }
975```
976
977字段：`url`（必需）、`ref`（可选：分支或标签）、`path`（可选：子目录）
978
9793. **基于 URL 的市场**：
980
981```json theme={null}
982{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
983{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }
984```
985
986字段：`url`（必需）、`headers`（可选：用于身份验证访问的 HTTP 标头）
987
988<Note>
989 基于 URL 的市场仅下载 `marketplace.json` 文件。它们不从服务器下载插件文件。基于 URL 的市场中的插件必须使用外部源（GitHub、npm 或 git URL）而不是相对路径。对于具有相对路径的插件，改用基于 Git 的市场。请参阅[故障排除](/docs/zh-CN/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)了解详情。
990</Note>
991
9924. **NPM 包**：
993
994```json theme={null}
995{ "source": "npm", "package": "@acme-corp/claude-plugins" }
996{ "source": "npm", "package": "@acme-corp/approved-marketplace" }
997```
998
999字段：`package`（必需，支持作用域包）
1000
10015. **文件路径**：
1002
1003```json theme={null}
1004{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
1005{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }
1006```
1007
1008字段：`path`（必需：marketplace.json 文件的绝对路径）
1009
10106. **目录路径**：
1011
1012```json theme={null}
1013{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
1014{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }
1015```
1016
1017字段：`path`（必需：包含 `.claude-plugin/marketplace.json` 的目录的绝对路径）
1018
10197. **主机模式匹配**：
1020
1021```json theme={null}
1022{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
1023{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }
1024```
1025
1026字段：`hostPattern`（必需：与市场主机匹配的正则表达式模式）
1027
1028当您想允许来自特定主机的所有市场而不枚举每个存储库时，使用主机模式匹配。这对于具有内部 GitHub Enterprise 或 GitLab 服务器的组织很有用，开发人员在其中创建自己的市场。
1029
1030按源类型的主机提取：
1031
1032* `github`：始终与 `github.com` 匹配
1033* `git`：从 URL 提取主机名（支持 HTTPS 和 SSH 格式）
1034* `url`：从 URL 提取主机名
1035* `npm`、`file`、`directory`：不支持主机模式匹配
1036
10378. **路径模式匹配**：
1038
1039```json theme={null}
1040{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
1041{ "source": "pathPattern", "pathPattern": ".*" }
1042```
1043
1044字段：`pathPattern`（必需：与 `file` 和 `directory` 源的 `path` 字段匹配的正则表达式模式）
1045
1046使用路径模式匹配来允许基于文件系统的市场与网络源的 `hostPattern` 限制一起使用。设置 `".*"` 以允许所有本地路径，或使用更窄的模式来限制特定目录。
1047
1048**配置示例**：
1049
1050示例：仅允许特定市场：
1051
1052```json theme={null}
1053{
1054 "strictKnownMarketplaces": [
1055 {
1056 "source": "github",
1057 "repo": "acme-corp/approved-plugins"
1058 },
1059 {
1060 "source": "github",
1061 "repo": "acme-corp/security-tools",
1062 "ref": "v2.0"
1063 },
1064 {
1065 "source": "url",
1066 "url": "https://plugins.example.com/marketplace.json"
1067 },
1068 {
1069 "source": "npm",
1070 "package": "@acme-corp/compliance-plugins"
1071 }
1072 ]
1073}
1074```
1075
1076示例：禁用所有市场添加：
1077
1078```json theme={null}
1079{
1080 "strictKnownMarketplaces": []
1081}
1082```
1083
1084示例：允许来自内部 git 服务器的所有市场：
1085
1086```json theme={null}
1087{
1088 "strictKnownMarketplaces": [
1089 {
1090 "source": "hostPattern",
1091 "hostPattern": "^github\\.example\\.com$"
1092 }
1093 ]
1094}
1095```
1096
1097**精确匹配要求**：
1098
1099市场源必须精确匹配才能允许用户的添加。对于基于 git 的源（`github` 和 `git`），这包括所有可选字段：
1100
1101* `repo` 或 `url` 必须精确匹配
1102* `ref` 字段必须精确匹配（或两者都未定义）
1103* `path` 字段必须精确匹配（或两者都未定义）
1104 720
1105不匹配的源示例：721您是否可以恢复您的值取决于键：取消设置变量或删除标志，并检查[设置参考](/docs/zh-CN/settings-reference)上的键条目和[环境变量参考](/docs/zh-CN/env-vars)上的变量行，了解 Claude Code 使用哪个。
1106 722
1107```json theme={null}723<span id="keys-ignored-in-a-repository-file" />
1108// 这些是不同的源：
1109{ "source": "github", "repo": "acme-corp/plugins" }
1110{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }
1111 724
1112// 这些也是不同的：725<span id="keys-only-you-or-your-organization-can-set" />
1113{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
1114{ "source": "github", "repo": "acme-corp/plugins" }
1115```
1116
1117**与 `extraKnownMarketplaces` 的比较**：
1118
1119| 方面 | `strictKnownMarketplaces` | `extraKnownMarketplaces` |
1120| ---------- | ------------------------- | ------------------------ |
1121| **目的** | 组织策略强制执行 | 团队便利 |
1122| **设置文件** | 仅 `managed-settings.json` | 任何设置文件 |
1123| **行为** | 阻止非允许列表的添加 | 自动安装缺失的市场 |
1124| **何时强制执行** | 在网络/文件系统操作之前 | 在用户信任提示之后 |
1125| **可以被覆盖** | 否（最高优先级） | 是（由更高优先级设置） |
1126| **源格式** | 直接源对象 | 具有嵌套源的命名市场 |
1127| **用例** | 合规、安全限制 | 入职、标准化 |
1128 726
1129**格式差异**：727<span id="common-cases" />
1130 728
1131`strictKnownMarketplaces` 使用直接源对象：729<span id="which-value-applies-in-common-situations" />
1132 730
1133```json theme={null}731<h3 id="troubleshoot-a-setting-that-doesn’t-apply">
1134{732 排除不适用的设置
1135 "strictKnownMarketplaces": [733</h3>
1136 { "source": "github", "repo": "acme-corp/plugins" }
1137 ]
1138}
1139```
1140 734
1141`extraKnownMarketplaces` 需要命名市场：735当您设置键而 Claude Code 不表现得好像您有时，从 `/status` 开始以查看它加载了哪些文件，然后在下面找到您的症状。[调试您的配置](/docs/zh-CN/debug-your-config)涵盖更广泛的检查，包括干净配置测试。
1142 736
1143```json theme={null}737<h4 id="a-value-you-set-is-ignored">
1144{738 您设置的值被忽略
1145 "extraKnownMarketplaces": {739</h4>
1146 "acme-tools": {
1147 "source": { "source": "github", "repo": "acme-corp/plugins" }
1148 }
1149 }
1150}
1151```
1152 740
1153**同时使用两者**：741其他东西设置相同的键，文件无法设置该值，或文件没有加载：
1154 742
1155`strictKnownMarketplaces` 是一个策略门：它控制用户可能添加什么，但不注册任何市场。要同时限制和为所有用户预注册市场，请在 `managed-settings.json` 中设置两者：743* **更高级别设置它。** 另一个设置文件、`--settings` 标志或托管来源在您的上方设置键；[堆栈](#settings-precedence)说哪个。标志或环境变量也可以自己覆盖键，按键决定；[设置参考](/docs/zh-CN/settings-reference)上的键条目说 Claude Code 使用哪个，[`env` 条目](/docs/zh-CN/settings-reference#env)涵盖托管 `env` 值与 shell 导出。
744* **安全键保持其严格值。** 对于少数几个键 Claude Code 尊重任何文件的限制值，因此项目 `true` 用于 [`disableClaudeAiConnectors`](/docs/zh-CN/settings-reference#disableclaudeaiconnectors) 保持开启；请参阅[托管设置优先级的例外](#exceptions-to-managed-settings-precedence)。
745* **文件无法设置该值。** [`permissions.defaultMode`](/docs/zh-CN/settings-reference#permissions-defaultmode) 值 `auto` 和 `bypassPermissions` 不从项目或本地设置生效；改为在用户或托管设置中设置它们，或为一个会话传递 `--permission-mode`。在 v2.1.257 之前，`bypassPermissions` 从任何文件生效。
746* **文件损坏。** 无效的 JSON 或拒绝的值使 Claude Code 跳过文件或条目；请参阅[修复损坏的设置文件](#fix-a-broken-settings-file)。
1156 747
1157```json theme={null}748<h4 id="a-change-you-made-in-claude-code-is-lost-in-new-sessions">
1158{749 您在 Claude Code 中所做的更改在新会话中丢失
1159 "strictKnownMarketplaces": [750</h4>
1160 { "source": "github", "repo": "acme-corp/plugins" }
1161 ],
1162 "extraKnownMarketplaces": {
1163 "acme-tools": {
1164 "source": { "source": "github", "repo": "acme-corp/plugins" }
1165 }
1166 }
1167}
1168```
1169 751
1170仅设置 `strictKnownMarketplaces` 时，用户仍可以通过 `/plugin marketplace add` 手动添加允许的市场，但它不会自动可用。752当您从 Claude Code 内保存新会话的选择时，如使用 `/model` 的默认模型，Claude Code 将其写入您的用户设置文件 `~/.claude/settings.json`。如果您无法写入该文件，例如因为另一个工具生成它或将其链接到只读副本，更改适用于当前会话并在下一个会话中消失。在生成文件的工具中设置键，或用您可以写入的文件替换文件。
1171 753
1172**重要说明**：754如果您可以写入文件而更改仍然不持续，检查更改是否[仅用于一个会话](#change-a-setting-for-one-session)或[更高级别设置相同的键](#a-value-you-set-is-ignored)。对于 `model` 键，[新会话在与您选择的不同的模型上启动](/docs/zh-CN/model-config#a-new-session-starts-on-a-different-model-than-you-picked)列出更多原因。
1173 755
1174* 限制在任何网络请求或文件系统操作之前检查756<h4 id="a-managed-change-hasn’t-reached-you">
1175* 被阻止时，用户看到清晰的错误消息，指示源被 managed 策略阻止757 托管更改还没有到达您
1176* 限制在市场添加和插件安装、更新、刷新和自动更新时强制执行。在策略设置之前添加的市场一旦其源不再与允许列表匹配，就无法用于安装或更新插件758</h4>
1177* Managed 设置具有最高优先级，无法被覆盖
1178 759
1179请参阅 [Managed 市场限制](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions)了解面向用户的文档。760托管来源按[传递表](/docs/zh-CN/managed-settings#choose-a-delivery-mechanism)中的计划到达运行的会话，因此首先重启会话。如果 `/status` 然后命名与您的管理员更改的不同的来源，更高优先级的来源适用；[Claude Code 如何组合托管来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)给出顺序。
1180 761
1181<h4 id="strictpluginonlycustomization">762<h4 id="a-committed-key-doesn’t-reach-teammates">
1182 `strictPluginOnlyCustomization`763 提交的键不到达队友
1183</h4>764</h4>
1184 765
1185**仅 Managed 设置**：阻止 skills、agents、hooks 和 MCP servers 来自用户和项目源，因此它们只能来自插件或 managed 设置。将其与 `strictKnownMarketplaces` 结合以控制完整的自定义供应链：市场允许列表控制用户可以安装哪些插件，此设置阻止所有不来自插件或 managed 设置的内容。766两件事阻止 `.claude/settings.json` 中的键为克隆它的每个人应用：
1186
1187该值要么是 `true` 以锁定所有四个表面，要么是命名要锁定的表面的数组：
1188 767
1189```json theme={null}768* **Claude Code 忽略存储库文件中的键。** 在[设置索引](/docs/zh-CN/settings-reference#settings-index)的作用域列中查找 `User, local, or managed`、`User or managed`、`Managed` 或 `Global config`；这些键永远不会从共享文件应用，除了 [`autoContinueAtUsageLimit`](/docs/zh-CN/settings-reference#autocontinueatusagelimit)，存储库文件仍然可以关闭：当文件设置键而没有用户、`--settings` 或托管值时，Claude Code 读取设置为关闭。`Global config` 键仅从 `~/.claude.json` 应用。
1190{769* **键等待信任。** `permissions.allow` 规则、`permissions.additionalDirectories`、`extraKnownMarketplaces` 和大多数 [`env`](/docs/zh-CN/settings-reference#env) 值仅在每个队友[信任文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)后应用。在那之前他们仍然看到提示并不从文件声明的市场获得插件。`deny` 和 `ask` 规则立即应用。
1191 "strictPluginOnlyCustomization": ["skills", "hooks"]
1192}
1193```
1194 770
1195对于每个锁定的表面，Claude Code 跳过用户级和项目级源，仅加载插件提供的和 managed 源：771<h4 id="permission-rules-combine-differently-than-you-expected">
772 权限规则组合方式与您预期不同
773</h4>
1196 774
1197| 表面 | 锁定时被阻止 | 仍然加载 |775* **您在权限提示上选择了"是的，不要再问"但仍然为相同的工具获得提示。** 该选择将 `allow` 规则保存到您的本地文件，本地的 `allow` 规则不优先于项目或托管文件中的 `ask` 规则；[权限规则如何组合](/docs/zh-CN/permissions#settings-precedence)解释顺序。在 VS Code 扩展中，批准卡让您选择目标文件，包括项目的共享文件，这改变了每个人的规则；在 CLI 中，Claude Code 仅写入您的本地文件。
1198| :------- | :------------------------------------ | :---------------------------------------------------------- |776* **您的组织的允许规则仍然与您的一起应用。** 这是预期的：Claude Code 跨作用域合并 [`permissions.allow`](/docs/zh-CN/settings-reference#permissions-allow)，除非您的组织设置 [`allowManagedPermissionRulesOnly`](/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly)。
1199| `skills` | `~/.claude/skills/`、`.claude/skills/` | 插件 skills、捆绑 skills、managed 策略目录中的 skills |
1200| `agents` | `~/.claude/agents/`、`.claude/agents/` | 插件 agents、内置 agents、managed 策略目录中的 agents |
1201| `hooks` | 用户、项目和本地 `settings.json` 中的 hooks | 插件 hooks、managed 设置中的 hooks |
1202| `mcp` | `~/.claude.json` 和 `.mcp.json` 中的服务器 | 插件 MCP servers、[`managed-mcp.json`](/docs/zh-CN/managed-mcp) 服务器 |
1203 777
1204Claude Code 版本不识别的表面名称被忽略而不是导致设置文件失败，因此您可以在所有客户端更新之前添加新的表面名称。778<span id="security-keys-where-the-stricter-value-applies" />
1205 779
1206<h3 id="manage-plugins">780<h3 id="exceptions-to-managed-settings-precedence">
1207 管理插件781 托管设置优先级的例外
1208</h3>782</h3>
1209 783
1210使用 `/plugin` 命令以交互方式管理插件：784对于少数几个值限制会话的键，Claude Code 尊重来自否则无法覆盖托管设置的作用域的限制值。在此表中找到键以查看它尊重哪个值以及从哪里。
1211 785
1212* 浏览市场中的可用插件786| 键 | Claude Code 尊重的值 | 注释 |
1213* 安装/卸载插件787| :--------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
1214* 启用/禁用插件788| [`disableClaudeAiConnectors`](/docs/zh-CN/settings-reference#disableclaudeaiconnectors) | 来自任何作用域的 `true` | 即使托管来源设置 `false` 也被尊重 |
1215* 查看插件详情（提供的 skills、agents、hooks）789| [`enableArtifact`](/docs/zh-CN/settings-reference#enableartifact) | 来自任何作用域的 `false`，以及来自任何作用域的 `disableArtifact: true` | 即使托管来源设置 `true` 也被尊重；没有什么打开[Artifact 工具](/docs/zh-CN/artifacts#disable-artifacts)。需要 Claude Code v2.1.242 或更高版本 |
1216* 添加/删除市场790| [`isolatePeerMachines`](/docs/zh-CN/settings-reference#isolatepeermachines) | 来自任何作用域的 `true` | 即使托管来源设置 `false` 也被尊重 |
791| [`remoteControlAtStartup`](/docs/zh-CN/settings-reference#remotecontrolatstartup) | 来自 `.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使托管来源设置 `true` 也被尊重；项目或本地 `true` 被忽略 |
792| [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) | 来自 `.claude/settings.json` 或 `.claude/settings.local.json` 的更严格值，在 `accept` \< `hold` \< `refuse` 梯形上 | 在托管、`--settings` 和用户值上被尊重；不是更严格的项目或本地值被忽略 |
793| [`useAutoModeDuringPlan`](/docs/zh-CN/settings-reference#useautomodeduringplan) | 来自任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使获胜的托管来源设置 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |
794| [`syncClaudeAiSkills`](/docs/zh-CN/settings-reference#syncclaudeaiskills) | 来自任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使获胜的托管来源设置 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |
795| [`maxEffortLevel`](/docs/zh-CN/settings-reference#maxeffortlevel) | 来自任何作用域（包括 `--settings`）的较低上限 | 即使 Claude Code 应用的托管设置设置更高的上限也被尊重；最低的上限适用。需要 Claude Code v2.1.267 或更高版本 |
1217 796
1218在[插件文档](/docs/zh-CN/plugins)中了解有关插件系统的更多信息。797运行 Claude Code 的应用并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 也是例外。Claude Code 从该应用的模型配置优先于来自每个托管来源的 `model`、`fallbackModel`、`modelPicker` 和 `modelOverrides` 键，以及托管 `env` 块中的模型选择变量，如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列。Claude Code 保持托管 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels) 允许列表生效，除非应用提供自己的。
1219 798
1220<h2 id="environment-variables">799<h2 id="settings-in-cloud-sessions">
1221 环境变量800 云会话中的设置
1222</h2>801</h2>
1223 802
1224环境变量让您可以控制 Claude Code 行为而无需编辑设置文件。任何变量也可以在 [`settings.json`](#available-settings) 中的 `env` 键下配置，以将其应用于每个会话或将其推出到您的团队。803云会话，在 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 或从 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-web)，在[云环境](/docs/zh-CN/cloud-environments)中运行在您的存储库的新克隆上，而不是在您的机器上。这改变了哪些设置到达它：
1225
1226请参阅[环境变量参考](/docs/zh-CN/env-vars)了解完整列表。
1227
1228<h2 id="tools-available-to-claude">
1229 Claude 可用的工具
1230</h2>
1231 804
1232Claude Code 可以访问一组用于读取、编辑、搜索、运行命令和编排 subagents 的工具。工具名称是您在权限规则和 hook 匹配器中使用的确切字符串。805* **共享项目设置** (`.claude/settings.json`)：读取，因为文件是克隆的一部分。在那里提交设置以在云会话中应用它。
806* **用户和项目本地设置** (`~/.claude/settings.json` 和 `.claude/settings.local.json`)：不读取。两者都保持在您的机器上，本地文件不在克隆中。
807* **托管设置**：仅[服务器管理设置](/docs/zh-CN/server-managed-settings)到达云会话；您设备上的 `managed-settings.json` 文件或 MDM 配置文件不会。[自托管环境](/docs/zh-CN/self-hosted-environments)也读取其运行器镜像中的托管设置文件。[Claude Code 如何组合托管来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说该文件何时适用。
808* **`/config`**：在网络上，打开您的 claude.ai 设置的 Claude Code 部分而不是更改值。要为云会话更改设置，在环境上设置[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)或将键提交到存储库的 `.claude/settings.json`。
1233 809
1234请参阅[工具参考](/docs/zh-CN/tools-reference)了解完整列表和 Bash 工具行为详情。810[从您的设置中携带什么](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)列出其余的：`CLAUDE.md`、skills、MCP 服务器、插件和凭证。
1235 811
1236<h2 id="see-also">812<h2 id="what’s-next">
1237 另请参阅813 接下来是什么
1238</h2>814</h2>
1239 815
1240* [权限](/docs/zh-CN/permissions)：权限系统、规则语法、工具特定模式和 managed 策略816* [所有设置](/docs/zh-CN/settings-reference)：每个键，以及您在哪里设置它和示例
1241* [身份验证](/docs/zh-CN/authentication)：设置用户对 Claude Code 的访问817* [示例设置文件](/docs/zh-CN/settings-example)：个人文件、团队文件和组织的托管文件
1242* [调试您的配置](/docs/zh-CN/debug-your-config)：诊断为什么设置、hook 或 MCP 服务器没有生效818* [配置权限](/docs/zh-CN/permissions)：允许、询问和拒绝规则，以及 Claude Code 在不询问的情况下运行什么
1243* [故障排除安装和登录](/docs/zh-CN/troubleshoot-install)：安装、身份验证和平台问题819* [环境变量](/docs/zh-CN/env-vars)：Claude Code 读取的变量和 `env` 块
820* [调试您的配置](/docs/zh-CN/debug-your-config)：当设置不适用时
821* [Claude 目录参考](/docs/zh-CN/claude-directory)：Claude Code 读取的每个文件，包括 subagents、MCP 服务器、插件和 `CLAUDE.md`
