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 版本開始,您可以透過將 `key=value` 傳遞給 `/config` 來變更單一選項,而無需開啟介面,例如 `/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-TW/settings-reference),其中列出每個金鑰及其設定位置、預設值和範例。
377</Tip>
378
379Claude Code 從 JSON 設定檔案(例如 `~/.claude/settings.json`)讀取設定。它在幾個位置尋找它們,而[它讀取設定的檔案決定了設定適用於誰](#settings-files-and-who-they-affect)。本頁涵蓋這些檔案:將設定放在哪個檔案中、如何變更設定並確認其已應用,以及當相同金鑰在多個檔案中設定時 Claude Code 使用哪個值。[設定權限](/docs/zh-TW/permissions)涵蓋 Claude Code 可以在不詢問的情況下執行的內容以及如何編寫 `allow`、`ask` 和 `deny` 規則。
20 380
21| 範圍 | 位置 | 影響對象 | 與團隊共享? |381<Note>
22| :---------- | :----------------------------------------------- | :---------------------------------------------------------- | :------------ |382 本頁涵蓋在您的機器上執行的 Claude Code:終端機、[VS Code](/docs/zh-TW/vs-code) 和 [JetBrains](/docs/zh-TW/jetbrains) 擴充功能,以及[桌面應用程式](/docs/zh-TW/desktop),它們都讀取相同的設定檔案。[Claude Code on the web](/docs/zh-TW/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* 您在所有專案中使用的工具和 plugins
42* API 金鑰和身份驗證(安全儲存)
43 394
44**Project 範圍**最適合:395<span id="subagent-configuration" />
45 396
46* 團隊共享的設定(權限、hooks、MCP servers)397<span id="where-settings-live" />
47* 整個團隊應該擁有的 plugins
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、plugins 和專案需要的環境變數 |
409| 專案本機 | `.claude/settings.local.json` | 您,僅在此一個專案中。Claude Code 在建立檔案時將其保留在 git 之外;如果您手動建立,請自行將其新增至 `.gitignore` | 一個專案的個人覆寫,以及在共享前進行測試 |
410| 受管 | `managed-settings.json` 和其他[受管來源](/docs/zh-TW/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)。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| 功能 | 使用者位置 | 專案位置 | 本機位置 |
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` 規則會生效,無需 `.claude/settings.json` allow 規則所需的[工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)步驟。如果儲存庫提供該檔案,例如透過提交它,工作區信任仍然適用。
100* **Managed 設定**:對於需要集中控制的組織,Claude Code 支援多種 managed 設定的傳遞機制。所有機制都使用相同的 JSON 格式,無法被使用者或專案設定覆蓋:
101
102 * **伺服器管理的設定**:透過 Anthropic 的伺服器或自託管的 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 在登入時遠端傳遞,可從 claude.ai 管理員主控台或自託管 Claude apps gateway 傳遞。請參閱[伺服器管理的設定](/docs/zh-TW/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` 登錄機碼,其中包含 `Settings` 值(REG\_SZ 或 REG\_EXPAND\_SZ)包含 JSON(透過群組原則或 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-TW/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-TW/permissions#managed-only-settings) 和 [Managed MCP 設定](/docs/zh-TW/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`,例如佈景主題,以及在您第一次在權限提示上給予常設核准時寫入 `.claude/settings.local.json`,例如「是的,不要再問」以取得 Bash 命令。少數 `/config` 選項,包括**顯示提示**,改為儲存至 `.claude/settings.local.json` 而不是使用者檔案。
126 444
127 <Note>445<Info>
128 Managed 部署也可以使用 `strictKnownMarketplaces` 限制 **plugin marketplace 新增**。如需詳細資訊,請參閱 [Managed marketplace 限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)。446 在 Windows 上,`~/.claude` 表示 `%USERPROFILE%\.claude`。若要將主目錄檔案保留在其他地方,請設定 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars);Claude Code 會改為在那裡儲存您的設定、工作階段歷史記錄和 plugins。
129 </Note>447</Info>
130* **其他設定**儲存在 `~/.claude.json` 中。此檔案包含您的 OAuth 工作階段、[MCP server](/docs/zh-TW/mcp) 設定(用於使用者和本機範圍)、每個專案的狀態(允許的工具、信任設定)和各種快取。專案範圍的 MCP servers 分別儲存在 `.mcp.json` 中。
131 448
132<Note>449Claude Code 也保留第五個檔案 [`~/.claude.json`](/docs/zh-TW/claude-directory#ce-claude-json),它為自己寫入;您不需要編輯它。它保留您的登入工作階段、[MCP 伺服器](/docs/zh-TW/mcp)設定、每個專案的狀態(例如信任決定),以及 `/config` 為您寫入的[全域設定金鑰](/docs/zh-TW/settings-reference#global-config-settings)。
133 Claude Code 會自動建立設定檔案的時間戳記備份,並保留最近五個備份以防止資料遺失。
134</Note>
135 450
136```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、遙測和 plugins。每個隊友仍然可以在自己的 `.claude/settings.local.json` 中為自己覆寫它,因此個人例外不需要提交。如需完整的團隊檔案,請參閱[團隊的共享設定](/docs/zh-TW/settings-example#a-teams-shared-settings)。
165 456
166已發佈的架構會定期更新,可能不包含最新 CLI 版本中新增的設定,因此最近記錄的欄位上的驗證警告不一定表示您的設定無效。457您提交的某些內容會等到每個隊友[信任資料夾](/docs/zh-TW/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-TW/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-TW/model-config#setting-your-model) 在工作階段中切換465<span id="keep-personal-settings-out-of-the-repository" />
177* [`outputStyle`](/docs/zh-TW/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-TW/debug-your-config#check-resolved-settings) 以列出被移除的項目及其來源檔案和欄位。471若要在一個專案中為自己變更設定而不為隊友變更,請將其儲存在專案內的 `.claude/settings.local.json` 中。Claude Code 在提交的 `.claude/settings.json` 上應用該檔案,因此如果您的團隊檔案設定 `"model": "claude-sonnet-5"` 而您想要 Opus,請在本機檔案中放入 `"model": "claude-opus-4-8"`,只有您的工作階段會變更。
184 472
185此行為在所有三種傳遞機制中一致:[伺服器管理的設定](/docs/zh-TW/server-managed-settings)、透過 MDM 部署的 plist 和登錄政策,以及 `managed-settings.json` 檔案。需要 Claude Code v2.1.169 或更新版本。473關於本機檔案,有三件事要知道:
186 474
187安全強制欄位按欄位處理,而不是在存在但無效時被整體移除:475* **Claude Code 也寫入它。** 當 Claude 要求執行 Bash 命令的權限,而您選擇「是的,不要再問」時,Claude Code 會將該[權限核准](/docs/zh-TW/permissions#permission-system)儲存在此處作為 `allow` 規則。
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`。
477* **其 allow 規則在檔案保持未追蹤時不等待信任。** 因為檔案是您的而不是儲存庫的,Claude Code 應用其 `allow` 規則而不需要它對提交檔案要求的[工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)步驟。如果檔案由 git 追蹤,信任步驟也適用於它;請參閱[當您的本機設定檔案需要信任時](/docs/zh-TW/permissions#when-your-local-settings-file-needs-trust)。
188 478
189| 欄位 | 存在但無效時的行為 |479<span id="where-claude-code-looks-for-each-file" />
190| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
191| `allowedMcpServers` | 作為空白名單強制執行,因此在修復值之前不允許任何 MCP servers。個別無效項目會被移除,有效子集會被強制執行。 |
192| `allowManagedMcpServersOnly` | 視為 `true`。 |
193| `availableModels` | 作為空白名單強制執行,因此在修復值之前僅預設模型可用。個別非字串項目會被移除,有效子集會被強制執行。適用於 v2.1.175 及更新版本。 |
194| `enforceAvailableModels` | 視為 `true`。適用於 v2.1.175 及更新版本。 |
195| `forceLoginOrgUUID` | 在修復值之前,不允許任何組織登入。 |
196| `deniedMcpServers` | 個別無效項目會被移除,有效子集會被強制執行。完全無效的值會被丟棄並出現警告,因為拒絕每個 server 會阻止政策從未命名的 servers。 |
197| `sandbox.credentials` | 在 `files` 或 `envVars` 中的個別無效項目會被移除並出現警告,有效子集會被強制執行。完全無效的 `credentials` 值會被丟棄並出現警告,而 `sandbox` 的其餘部分仍然適用。適用於 v2.1.191 及更新版本。 |
198 480
199`requiredMinimumVersion` 和 `requiredMaximumVersion` 設計上會失敗開放:無效的值會被移除而不是強制執行,因此不良的政策推送無法防止 Claude Code 啟動。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 484
203* 互動式工作階段在啟動時顯示列出無效項目的對話框。485<h4 id="where-claude-code-keeps-the-local-file-in-a-git-repository">
204* 使用 `-p` 的無頭執行會將摘要列印到 stderr。486 Claude Code 在 git 儲存庫中保留本機檔案的位置
205* [`claude doctor`](/docs/zh-TW/debug-your-config) 列出每個無效項目及其來源和欄位。487</h4>
206
207在整個機隊部署政策變更之前,在測試機器上執行 `claude doctor` 以驗證政策變更。
208 488
209此寬容性僅適用於 managed 設定。使用者、專案和本機設定檔案保持嚴格:驗證失敗的檔案會被整體拒絕並報告。489當 Claude 要求執行 Bash 命令的權限,而您選擇「是的,不要再問」時,Claude Code 會將該核准儲存為 `.claude/settings.local.json` 中的 `allow` 規則。如果您在 git 儲存庫的子目錄中啟動 Claude Code,它會在儲存庫根目錄讀取和寫入該檔案,並在整個儲存庫中應用核准。在 [worktree](/docs/zh-TW/worktrees) 中,它使用主簽出根目錄的檔案。
210 490
211<h3 id="available-settings">491兩個規則限定根位置:
212 可用的設定
213</h3>
214 492
215`settings.json` 支援多個選項:493* **當檔案改為與 `.claude/settings.json` 保持在一起時**:在 git 儲存庫之外,當儲存庫根目錄是您的主目錄時,在 Windows 上,或當儲存庫根目錄或其 `.git` 或 `.claude` 項目不由您的使用者擁有時。
216 494* **檔案中的路徑不在儲存庫根目錄錨定**:以 `/` 開頭的權限規則或相對沙箱路徑[改為在工作階段的主要工作目錄錨定](/docs/zh-TW/permissions#read-and-edit)。
217| 金鑰 | 說明 | 範例 |
218| :--------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
219| `advisorModel` | 伺服器端 [advisor tool](/docs/zh-TW/advisor) 的模型。接受模型別名,例如 `"opus"`、`"sonnet"` 或 `"fable"`(v2.1.170+),或完整模型 ID。當您執行 `/advisor` 時自動寫入。取消設定以停用 advisor | `"opus"` |
220| `agent` | 將主執行緒作為命名 subagent 執行,並為從 `claude agents` 分派的工作階段設定預設 agent。應用該 subagent 的系統提示、工具限制和模型。請參閱[明確叫用 subagents](/docs/zh-TW/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |
221| `agentPushNotifEnabled` | **預設**:`false`。當[遠端控制](/docs/zh-TW/remote-control)已連線時,允許 Claude 主動傳送推播通知到您的手機,例如當長時間工作完成時。在 `/config` 中顯示為**Claude 決定時推播**。請參閱[行動推播通知](/docs/zh-TW/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更新版本 | `true` |
222| `allowAllClaudeAiMcps` | (Managed 設定僅限)載入 claude.ai connectors 以及部署的 `managed-mcp.json`,否則會取得獨佔控制並抑制它們。請參閱 [Managed MCP 設定](/docs/zh-TW/managed-mcp) | `true` |
223| `allowedChannelPlugins` | (Managed 設定僅限)可能推送訊息的頻道 plugins 白名單。在設定時替換預設 Anthropic 白名單。未定義 = 回退到預設值,空陣列 = 阻止所有頻道 plugins。需要 `channelsEnabled: true`。請參閱[限制哪些頻道 plugins 可以執行](/docs/zh-TW/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |
224| `allowedHttpHookUrls` | HTTP hooks 可能針對的 URL 模式白名單。支援 `*` 作為萬用字元。設定時,具有不匹配 URL 的 hooks 會被阻止。未定義 = 無限制,空陣列 = 阻止所有 HTTP hooks。陣列跨設定來源合併。請參閱 [Hook 設定](#hook-configuration) | `["https://hooks.example.com/*"]` |
225| `allowedMcpServers` | 在 managed-settings.json 中設定時,使用者可以設定的 MCP servers 白名單。未定義 = 無限制,空陣列 = 鎖定。適用於所有範圍。拒絕清單優先。請參閱 [Managed MCP 設定](/docs/zh-TW/managed-mcp) | `[{ "serverName": "github" }]` |
226| `allowManagedHooksOnly` | (Managed 設定僅限)僅載入 managed hooks、SDK hooks 和在 managed 設定 `enabledPlugins` 中強制啟用的 plugins 中的 hooks。使用者、專案和所有其他 plugin hooks 被阻止。請參閱 [Hook 設定](#hook-configuration) | `true` |
227| `allowManagedMcpServersOnly` | (Managed 設定僅限)僅尊重 managed 設定中的 `allowedMcpServers`。`deniedMcpServers` 仍從所有來源合併。使用者仍可新增 MCP servers,但僅適用管理員定義的白名單。請參閱 [Managed MCP 設定](/docs/zh-TW/managed-mcp) | `true` |
228| `allowManagedPermissionRulesOnly` | (Managed 設定僅限)防止使用者和專案設定定義 `allow`、`ask` 或 `deny` 權限規則。僅適用 managed 設定中的規則。請參閱 [Managed 專用設定](/docs/zh-TW/permissions#managed-only-settings) | `true` |
229| `alwaysThinkingEnabled` | 為所有工作階段預設啟用[擴展思考](/docs/zh-TW/model-config#extended-thinking)。通常透過 `/config` 命令而不是直接編輯來設定。若要強制思考關閉,無論此設定如何,請在 `env` 中設定 [`MAX_THINKING_TOKENS=0`](/docs/zh-TW/env-vars),這會停用 Anthropic API 上的思考,除了 Fable 5,無法關閉思考。在[第三方提供者](/docs/zh-TW/third-party-integrations)上,這會改為省略 `thinking` 參數,自適應推理模型仍可能思考 | `true` |
230| `apiKeyHelper` | 自訂指令碼,在系統 shell(macOS 和 Linux 上為 `/bin/sh`,Windows 上為 `cmd`)中執行,以產生驗證值。此值將作為 `X-Api-Key` 和 `Authorization: Bearer` 標頭傳送以進行模型請求。使用 [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/docs/zh-TW/env-vars) 設定重新整理間隔 | `/bin/generate_temp_api_key.sh` |
231| `askUserQuestionTimeout` | **預設**:`"never"`。未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框在自動繼續前的閒置時間,使用您已選擇的任何選項。接受 `"60s"`、`"5m"`、`"10m"` 或 `"never"`。使用預設值,問題會等待您回答。在 `/config` 中顯示為**問題自動繼續逾時**,會將此金鑰寫入使用者設定。不從專案或本機設定讀取。需要 Claude Code v2.1.200 或更新版本 | `"5m"` |
232| `attribution` | 自訂 git 提交和拉取請求的歸屬。請參閱[歸屬設定](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |
233| `autoCompactEnabled` | **預設**:`true`。當內容接近限制時自動壓縮對話。在 `/config` 中顯示為**自動壓縮**。若要透過環境變數停用,請在 `env` 中設定 [`DISABLE_AUTO_COMPACT`](/docs/zh-TW/env-vars) | `false` |
234| `autoMemoryDirectory` | [自動記憶](/docs/zh-TW/memory#storage-location)儲存的自訂目錄。接受絕對路徑或 `~/` 前綴的路徑。從專案或本機設定接受,此設定在您接受工作區信任對話後才受尊重,因為複製的儲存庫可能提供此檔案 | `"~/my-memory-dir"` |
235| `autoMemoryEnabled` | **預設**:`true`。啟用[自動記憶](/docs/zh-TW/memory#enable-or-disable-auto-memory)。當為 `false` 時,Claude 不會從自動記憶目錄讀取或寫入。您也可以在工作階段期間使用 `/memory` 切換此設定。若要透過環境變數停用,請在 `env` 中設定 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/docs/zh-TW/env-vars) | `false` |
236| `autoMode` | 自訂[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)分類器阻止和允許的內容。包含 `environment`、`allow`、`soft_deny` 和 `hard_deny` 陣列的散文規則。在陣列中包含字面字串 `"$defaults"` 以在該位置繼承內建規則。請參閱[設定自動模式](/docs/zh-TW/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"]}` |
237| `autoMode.classifyAllShell` | **預設**:`false`。當為 `true` 時,在自動模式使用中時暫停每個 Bash 和 PowerShell 允許規則,以便所有 shell 命令透過分類器路由,而不僅僅是符合任意程式碼執行模式的規則。請參閱[透過分類器路由所有 shell 命令](/docs/zh-TW/auto-mode-config#route-all-shell-commands-through-the-classifier)。需要 Claude Code v2.1.193 或更新版本 | `true` |
238| `autoScrollEnabled` | **預設**:`true`。在[全螢幕渲染](/docs/zh-TW/fullscreen)中,跟隨新輸出到對話的底部。在 `/config` 中顯示為**自動捲軸**。當此設定關閉時,權限提示仍會捲軸進入檢視 | `false` |
239| `autoUpdatesChannel` | **預設**:`"latest"`。遵循更新的發行頻道。使用 `"stable"` 以取得通常約一週舊的版本並跳過有重大迴歸的版本,或 `"latest"` 以取得最新版本。若要完全停用自動更新,請在 `env` 中設定 [`DISABLE_AUTOUPDATER`](/docs/zh-TW/setup#disable-auto-updates) | `"stable"` |
240| `availableModels` | 限制使用者可以為主工作階段、[subagents](/docs/zh-TW/sub-agents)、[skills](/docs/zh-TW/skills) 和 [advisor](/docs/zh-TW/advisor) 選擇的模型。不影響預設選項,除非 `enforceAvailableModels` 也設定。請參閱[限制模型選擇](/docs/zh-TW/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |
241| `awaySummaryEnabled` | 在您離開終端機幾分鐘後返回時顯示單行工作階段摘要。設定為 `false` 或在 `/config` 中關閉工作階段摘要以停用。與 [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/docs/zh-TW/env-vars) 相同 | `true` |
242| `awsAuthRefresh` | 修改 `.aws` 目錄的自訂指令碼(請參閱[進階認證設定](/docs/zh-TW/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |
243| `awsCredentialExport` | 輸出包含 AWS 認證的 JSON 的自訂指令碼(請參閱[進階認證設定](/docs/zh-TW/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |
244| `axScreenReader` | 渲染螢幕閱讀器友善的輸出:沒有裝飾邊框或動畫的平面文字。螢幕閱讀器模式使用經典渲染器,因此在其使用中時 `tui` 設定無效;附加的[背景工作階段](/docs/zh-TW/agent-view)仍會全螢幕渲染。[`CLAUDE_AX_SCREEN_READER`](/docs/zh-TW/env-vars) 環境變數和 [`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 | `true` |
245| `blockedMarketplaces` | (Managed 設定僅限)marketplace 來源的黑名單。在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行,因此在設定政策之前新增的 marketplace 無法用於擷取 plugins。在下載前檢查被阻止的來源,因此它們永遠不會接觸檔案系統。請參閱 [Managed marketplace 限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |
246| `browserExternalPageTools` | (Managed 設定僅限)設定為 `"disabled"` 以防止 Claude 使用工具讀取或作用於桌面應用程式[瀏覽器窗格](/docs/zh-TW/desktop#browse-external-sites)中的外部頁面。使用者仍可自行導覽到外部網站,本機開發伺服器預覽不受影響 | `"disabled"` |
247| `channelsEnabled` | (Managed 設定僅限)允許組織使用[頻道](/docs/zh-TW/channels)。在 claude.ai Team 和 Enterprise 方案上,當此設定未設定或為 `false` 時,頻道會被阻止。對於使用 API 金鑰驗證的 [Anthropic Console](/docs/zh-TW/authentication#claude-console-authentication) 帳戶,除非您的組織部署 managed 設定(在這種情況下此金鑰必須設定為 `true`),否則預設允許頻道 | `true` |
248| `claudeMd` | (Managed 設定僅限)CLAUDE.md 樣式的指示,作為組織管理的記憶注入。僅在 managed 或政策設定中設定時受尊重,在使用者、專案和本機設定中被忽略。請參閱[組織範圍的 CLAUDE.md](/docs/zh-TW/memory#deploy-organization-wide-claude-md) | `"Always run make lint before committing."` |
249| `claudeMdExcludes` | 載入[記憶](/docs/zh-TW/memory)時要跳過的 `CLAUDE.md` 檔案的 Glob 模式或絕對路徑。模式與絕對檔案路徑相符。僅適用於使用者、專案和本機記憶;managed 政策檔案無法排除 | `["**/vendor/**/CLAUDE.md"]` |
250| `cleanupPeriodDays` | **預設**:`30` 天,最少 `1`。Claude Code 刪除[工作階段檔案和其他應用程式資料](/docs/zh-TW/claude-directory#cleaned-up-automatically)超過此期間的檔案在啟動時。設定 `0` 會失敗並出現驗證錯誤。相同的年齡截止也適用於[孤立 worktrees](/docs/zh-TW/worktrees#clean-up-worktrees) 在啟動時的自動移除。如果 Claude Code 無法讀取或解析設定檔案,它會暫停保留清理掃描並在 `/status` 中顯示警告,直到您修復檔案,除非 [managed 設定](/docs/zh-TW/server-managed-settings)提供 `cleanupPeriodDays`,在這種情況下掃描以 managed 值執行。在 v2.1.203 之前,清理以 30 天預設執行,並可能刪除較長 `cleanupPeriodDays` 打算保留的文字記錄;新於 30 天的檔案永遠不會被移除。若要完全停用文字記錄寫入,請設定 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/zh-TW/env-vars) 環境變數。在非互動模式中,使用 `--no-session-persistence` 與 `-p` 一起傳遞或在 Agent SDK 中設定 `persistSession: false`。 | `20` |
251| `companyAnnouncements` | 在啟動時向使用者顯示的公告。如果提供多個公告,它們將隨機循環。 | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |
252| `defaultShell` | **預設**:`"bash"`,或在 Bash 不可用時 Windows 上為 `"powershell"`。輸入框 `!` 命令的預設 shell。接受 `"bash"` 或 `"powershell"`。設定 `"powershell"` 會在 Windows 上透過 PowerShell 路由互動式 `!` 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。請參閱 [PowerShell tool](/docs/zh-TW/tools-reference#powershell-tool) | `"powershell"` |
253| `deniedMcpServers` | 在 managed-settings.json 中設定時,明確阻止的 MCP servers 拒絕清單。適用於所有範圍,包括 managed servers。拒絕清單優先於白名單。請參閱 [Managed MCP 設定](/docs/zh-TW/managed-mcp) | `[{ "serverName": "filesystem" }]` |
254| `disableAgentView` | 設定為 `true` 以關閉[背景代理和代理檢視](/docs/zh-TW/agent-view):`claude agents`、`--bg`、`/background` 和隨選主管。通常在 [managed 設定](/docs/zh-TW/permissions#managed-settings) 中設定。等同於將 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 設定為 `1` | `true` |
255| `disableAllHooks` | 停用所有 [hooks](/docs/zh-TW/hooks) 和任何自訂[狀態行](/docs/zh-TW/statusline) | `true` |
256| `disableArtifact` | 設定為 `true` 以停用 [Artifact](/docs/zh-TW/artifacts) 工具,該工具將工作階段輸出發佈為 claude.ai 上的私人網頁。等同於將 `CLAUDE_CODE_DISABLE_ARTIFACT` 設定為 `1` | `true` |
257| `disableAutoMode` | 設定為 `"disable"` 以防止[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)被啟用。從 `Shift+Tab` 循環中移除 `auto` 並在啟動時拒絕 `--permission-mode auto`。在[managed 設定](/docs/zh-TW/permissions#managed-settings)中最有用,使用者無法覆蓋它 | `"disable"` |
258| `disableBrowserExternalNavigation` | (Managed 設定僅限)設定為 `true` 以關閉桌面應用程式[瀏覽器窗格](/docs/zh-TW/desktop#browse-external-sites)中的外部瀏覽。使用者和 Claude 都無法導覽到外部網站,localhost 開發伺服器預覽不受影響。值必須是 JSON 布林值 `true`;字串 `"true"` 會被忽略 | `true` |
259| `disableBundledSkills` | 設定為 `true` 以停用隨 Claude Code 一起提供的 [skills](/docs/zh-TW/skills) 和工作流程:bundled skills 和工作流程會被完全移除,而內建斜線命令(如 `/init`)保持可輸入但對模型隱藏。`/doctor` 保持可輸入,如內建命令;改用 [`DISABLE_DOCTOR_COMMAND`](/docs/zh-TW/env-vars) 隱藏它。來自 plugins、`.claude/skills/` 和 `.claude/commands/` 的 Skills 不受影響。等同於將 `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` 設定為 `1` | `true` |
260| `disableClaudeAiConnectors` | 停用 [claude.ai MCP connectors](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai),使其不會自動擷取或連線。在任何設定範圍中設定。任何來源中的 `true` 優先,因此簽入的專案 `.claude/settings.json` 可以選擇退出雲端 connectors,但專案層級的 `false` 無法覆蓋使用者或政策層級的 `true`。透過 `--mcp-config` 明確傳遞的 Servers 不受影響。若要拒絕個別 connectors 而不是所有 connectors,請改用 [`deniedMcpServers`](/docs/zh-TW/managed-mcp)。需要 Claude Code v2.1.182 或更新版本 | `true` |
261| `disableDeepLinkRegistration` | 設定為 `"disable"` 以防止 Claude Code 在啟動時向作業系統註冊 `claude-cli://` 協議處理程式。[深層連結](/docs/zh-TW/deep-links)讓外部工具透過預先填入的提示開啟 Claude Code 工作階段。在協議處理程式註冊受限或單獨管理的環境中很有用 | `"disable"` |
262| `disabledMcpjsonServers` | 要拒絕的 `.mcp.json` 檔案中特定 MCP servers 的清單 | `["filesystem"]` |
263| `disableRemoteControl` | 停用[遠端控制](/docs/zh-TW/remote-control):阻止 `claude remote-control`、`--remote-control` 旗標、自動啟動和工作階段內切換。通常放在[managed 設定](/docs/zh-TW/permissions#managed-settings)中以進行每個裝置的 MDM 強制執行,但適用於任何範圍。需要 Claude Code v2.1.128 或更新版本 | `true` |
264| `disableSideloadFlags` | (Managed 設定僅限)在啟動時拒絕 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` CLI 旗標,使用者可能會傳遞這些旗標以繞過 [`strictKnownMarketplaces`](#strictknownmarketplaces) 進行單一執行。也拒絕從任何內部產生 CLI 的表面傳遞這些旗標,目前[Cowork](/docs/zh-TW/desktop) 桌面應用程式中的本機工作階段。其 servers 全部為進程內 `type: "sdk"` 項目的 `--mcp-config` 仍被接受,因此 Agent SDK 和 VS Code 擴充功能保持工作。不阻止 `claude mcp add`、`.mcp.json` 或 SDK `setMcpServers()`;與 [`allowedMcpServers`](/docs/zh-TW/managed-mcp) 配對以進行每個 server 的 MCP 控制。需要 Claude Code v2.1.193 或更新版本 | `true` |
265| `disableSkillShellExecution` | 停用 [skills](/docs/zh-TW/skills) 和來自使用者、專案、plugin 或其他目錄來源的自訂命令中的內嵌 shell 執行(`` !`...` `` 和 ` ```! ` 區塊)。命令會被替換為 `[shell command execution disabled by policy]` 而不是被執行。Bundled 和 managed skills 不受影響。在[managed 設定](/zh-TW/permissions#managed-settings)中最有用,使用者無法覆蓋它 | `true` |
266| `disableWorkflows` | **預設**:`false`。停用[動態工作流程](/docs/zh-TW/workflows#turn-workflows-off)和 bundled workflow 命令。等同於將 `CLAUDE_CODE_DISABLE_WORKFLOWS` 設定為 `1` | `true` |
267| `editorMode` | **預設**:`"normal"`。輸入提示的快捷鍵模式:`"normal"` 或 `"vim"`。在 `/config` 中顯示為**編輯器模式** | `"vim"` |
268| `effortLevel` | 跨工作階段持久化[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。接受 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`。當您執行 `/effort` 時自動寫入,其中包含其中一個值。`--effort` 和 [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-TW/env-vars) 會覆蓋此設定以進行一個工作階段。請參閱[調整努力等級](/docs/zh-TW/model-config#adjust-effort-level)以了解支援的模型 | `"xhigh"` |
269| `enableAllProjectMcpServers` | 自動批准專案 `.mcp.json` 檔案中定義的所有 MCP servers。自 v2.1.196 起,`claude mcp list` 和 `claude mcp get` 在不受信任的資料夾中僅從[未簽入儲存庫的設定檔案](/docs/zh-TW/mcp#managing-your-servers)中尊重此金鑰 | `true` |
270| `enableArtifact` | 為此使用者啟用或停用 [Artifact](/docs/zh-TW/artifacts) 工具。未設定時,預設遵循功能的[可用性](/docs/zh-TW/artifacts#availability)以取得您的帳戶。`/config` 中的 **Artifacts** 列寫入此金鑰。Managed `disableArtifact` 和您組織的[管理員設定](/docs/zh-TW/artifacts#manage-artifacts-for-your-organization)優先,該金鑰在專案和本機設定(`.claude/settings.json`、`.claude/settings.local.json`)中被忽略,儲存庫可能會簽入。需要 Claude Code v2.1.196 或更新版本 | `true` |
271| `enabledMcpjsonServers` | 要批准的 `.mcp.json` 檔案中特定 MCP servers 的清單。自 v2.1.196 起,`claude mcp list` 和 `claude mcp get` 在不受信任的資料夾中僅從[未簽入儲存庫的設定檔案](/docs/zh-TW/mcp#managing-your-servers)中尊重此金鑰 | `["memory", "github"]` |
272| `enforceAvailableModels` | 將 `availableModels` 白名單擴展到預設模型。當在 managed 設定中為 `true` 且 `availableModels` 是非空陣列時,預設選項會回退到第一個可用的白名單項目,但僅當使用者帳戶類型的預設模型不在白名單中時;白名單預設會保持原樣。當 `availableModels` 未設定或為空時無效。請參閱[為預設模型強制執行白名單](/docs/zh-TW/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更新版本 | `true` |
273| `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"}` |
274| `fallbackModel` | 當主模型過載或不可用時按順序嘗試的備用模型。Claude Code 會為該輪的其餘部分切換到鏈中的下一個可用模型並顯示通知。`"default"` 擴展為預設模型。鏈限制為三個模型;額外項目會被忽略。與大多數陣列設定不同,此金鑰不跨設定檔案合併:定義它的最高優先順序檔案提供整個鏈。[`--fallback-model`](/docs/zh-TW/cli-reference#cli-flags) 旗標會覆蓋此設定以進行一個工作階段。請參閱[備用模型鏈](/docs/zh-TW/model-config#fallback-model-chains) | `["claude-sonnet-5", "claude-haiku-4-5"]` |
275| `fastMode` | 為可用的工作階段開啟[快速模式](/docs/zh-TW/fast-mode)。使用 `/fast` 切換會在使用者設定中寫入 `true`,當您關閉快速模式時移除金鑰 | `true` |
276| `fastModePerSessionOptIn` | 當為 `true` 時,快速模式不會跨工作階段持久化。每個工作階段都以快速模式關閉開始,需要使用者使用 `/fast` 啟用它。使用者的快速模式偏好仍會儲存。請參閱[需要每個工作階段的選擇加入](/docs/zh-TW/fast-mode#require-per-session-opt-in) | `true` |
277| `feedbackSurveyRate` | [工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys)出現時符合條件的機率(0–1)。設定為 `0` 以完全抑制,或設定 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/docs/zh-TW/env-vars) 在 `env` 中。在使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 時很有用,其中預設樣本率不適用 | `0.05` |
278| `fileCheckpointingEnabled` | **預設**:`true`。在每次編輯前快照檔案,以便 [`/rewind`](/docs/zh-TW/checkpointing) 可以還原它們。在 `/config` 中顯示為**倒帶程式碼(檢查點)**。若要透過環境變數停用,請在 `env` 中設定 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/docs/zh-TW/env-vars) | `false` |
279| `fileSuggestion` | 為 `@` 檔案自動完成設定自訂指令碼。請參閱[檔案建議設定](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |
280| `footerLinksRegexes` | 當 regex 符合輪次輸出時在頁尾中渲染額外的可點擊徽章。每個項目都有一個 `pattern`、一個包含 `{name}` 佔位符的 URL 範本(從命名擷取群組填入),以及一個選用的 `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}"}]` |
281| `forceLoginMethod` | 使用 `claudeai` 限制登入到 Claude.ai 帳戶,`console` 限制登入到 Claude Console 帳戶,或 `gateway` 限制登入到雲端閘道;請參閱 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway)。在 managed 設定中設定為任何值時,由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的工作階段在啟動時被阻止,因為環境認證無法滿足所需的登入方法。第三方提供者工作階段(例如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry)不被阻止:它們針對您的雲端提供者而不是 Anthropic 進行驗證 | `claudeai` |
282| `forceLoginGatewayUrl` | 在 `/login` 雲端閘道畫面上預先填入並鎖定閘道 URL。此金鑰或 `forceLoginMethod: "gateway"` 會顯示該畫面;同時設定兩者以便 URL 被填入。僅在 managed 政策層級受尊重;在使用者和專案設定中被忽略。請參閱 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway#set-the-gateway-url) | `"https://claude-gateway.example.com"` |
283| `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"]` |
284| `forceRemoteSettingsRefresh` | (Managed 設定僅限)阻止 CLI 啟動,直到從伺服器新鮮擷取遠端 managed 設定。如果擷取失敗,CLI 會結束而不是繼續使用快取或無設定。未設定時,啟動會繼續而不等待遠端設定。請參閱[失敗關閉強制執行](/docs/zh-TW/server-managed-settings#enforce-fail-closed-startup) | `true` |
285| `gcpAuthRefresh` | 當 GCP Application Default Credentials 過期或無法載入時重新整理它們的自訂指令碼。請參閱[進階認證設定](/docs/zh-TW/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |
286| `hooks` | 設定自訂命令以在生命週期事件執行。請參閱 [hooks 文件](/docs/zh-TW/hooks)以了解格式 | 請參閱 [hooks](/docs/zh-TW/hooks) |
287| `httpHookAllowedEnvVars` | HTTP hooks 可能插入到標頭中的環境變數名稱白名單。設定時,每個 hook 的有效 `allowedEnvVars` 是與此清單的交集。未定義 = 無限制。陣列跨設定來源合併。請參閱 [Hook 設定](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |
288| `includeGitInstructions` | **預設**:`true`。在 Claude 的系統提示中包含內建提交和 PR 工作流程指示和 git 狀態快照。設定為 `false` 以移除兩者,例如在使用您自己的 git 工作流程 skills 時。`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 環境變數在設定時優先於此設定 | `false` |
289| `inputNeededNotifEnabled` | **預設**:`false`。當[遠端控制](/docs/zh-TW/remote-control)已連線時,當權限提示或問題等待您的輸入時傳送推播通知到您的手機。在 `/config` 中顯示為**需要操作時推播**。請參閱[行動推播通知](/docs/zh-TW/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更新版本 | `true` |
290| `language` | 設定 Claude 的首選回應語言(例如 `"japanese"`、`"spanish"`、`"french"`)。Claude 預設會以此語言回應。也設定[語音聽寫](/docs/zh-TW/voice-dictation#change-the-dictation-language)語言和自動產生的工作階段標題。自 v2.1.176 起,未設定時,工作階段標題符合您對話的語言 | `"japanese"` |
291| `minimumVersion` | 防止背景自動更新和 `claude update` 安裝低於此版本的版本。當從 `"latest"` 頻道切換到 `"stable"` 時透過 `/config` 提示您保持在目前版本或允許降級。選擇保持設定此值。也適用於[managed 設定](/docs/zh-TW/permissions#managed-settings)以釘選組織範圍的最小值。如需完全阻止啟動的硬底線,請參閱 `requiredMinimumVersion` | `"2.1.100"` |
292| `model` | 覆蓋 Claude Code 使用的預設模型。`--model` 和 [`ANTHROPIC_MODEL`](/docs/zh-TW/model-config#environment-variables) 會覆蓋此設定以進行一個工作階段 | `"claude-sonnet-5"` |
293| `modelOverrides` | 將 Anthropic 模型 ID 對應到提供者特定的模型 ID,例如 Amazon Bedrock 推論設定檔 ARN。每個模型選擇器項目在呼叫提供者 API 時使用其對應的值。請參閱[按版本覆蓋模型 ID](/docs/zh-TW/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |
294| `otelHeadersHelper` | 產生動態 OpenTelemetry 標頭的指令碼。在啟動時和定期執行。使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/docs/zh-TW/env-vars) 設定重新整理間隔。請參閱[動態標頭](/docs/zh-TW/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |
295| `outputStyle` | 設定輸出樣式以調整系統提示。請參閱[輸出樣式文件](/docs/zh-TW/output-styles) | `"Explanatory"` |
296| `parentSettingsBehavior` | (Managed 設定僅限)**預設**:`"first-wins"`。控制由嵌入主機流程(例如 Agent SDK 或 IDE 擴充功能)以程式設計方式提供的 managed 設定在同時存在管理員部署的 managed 層級時是否適用。`"first-wins"`:父級提供的設定被丟棄,僅適用管理員層級。`"merge"`:父級提供的設定適用於管理員層級下方,經過篩選以便它們可以收緊 managed 政策但不能放鬆政策。當未部署管理員層級時無效。需要 Claude Code v2.1.133 或更新版本 | `"merge"` |
297| `permissions` | 請參閱下表以了解權限的結構。 | |
298| `plansDirectory` | **預設**:`~/.claude/plans`。自訂 Plan Mode 檔案的儲存位置。路徑相對於專案根目錄。 | `"./plans"` |
299| `pluginSuggestionMarketplaces` | (Managed 設定僅限)其 plugins 可以作為內容相關安裝建議出現的 marketplace 名稱。沒有 marketplace 宣告的建議會出現而不需要此白名單;內建第一方前端設計提示不受影響。建議來自每個 plugin 在其 marketplace 項目中的 `relevance` 宣告。名稱僅在 marketplace 在機器上註冊且其註冊來源也在 managed 設定中宣告時才生效,作為該名稱的 `extraKnownMarketplaces` 項目或 `strictKnownMarketplaces` 的項目。從不同來源在白名單名稱下註冊的 marketplace 會被忽略。官方 marketplace 豁免於來源要求:白名單其名稱就足夠了,因為該名稱只能從官方 Anthropic 來源註冊。 | `["acme-corp-plugins"]` |
300| `pluginTrustMessage` | (Managed 設定僅限)在安裝前顯示的 plugin 信任警告中附加的自訂訊息。使用此選項新增組織特定的內容,例如確認來自您內部 marketplace 的 plugins 已經過審查。 | `"All plugins from our marketplace are approved by IT"` |
301| `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"}` |
302| `preferredNotifChannel` | **預設**:`"auto"`。工作完成和權限提示通知的方法:`"auto"`、`"terminal_bell"`、`"iterm2"`、`"iterm2_with_bell"`、`"kitty"`、`"ghostty"` 或 `"notifications_disabled"`。`"auto"` 在 iTerm2、Ghostty 和 Kitty 中傳送桌面通知,在其他終端機中不執行任何操作。設定 `"terminal_bell"` 以在任何終端機中響鈴字元。在 `/config` 中顯示為**通知**。請參閱[取得終端機鈴聲或通知](/docs/zh-TW/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |
303| `prefersReducedMotion` | 減少或停用 UI 動畫(微調器、閃爍、閃光效果)以提高可訪問性 | `true` |
304| `prUrlTemplate` | PR 徽章的 URL 範本,顯示在頁尾和工具結果摘要中。替換 `gh` 報告的 PR URL 中的 `{host}`、`{owner}`、`{repo}`、`{number}` 和 `{url}`。使用以指向內部程式碼審查工具而不是 `github.com`。不影響 Claude 散文中的 `#123` 自動連結 | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |
305| `remoteControlAtStartup` | 當每個互動式工作階段啟動時自動連線[遠端控制](/docs/zh-TW/remote-control),而不是等待 `/remote-control`。設定為 `true` 以始終自動連線,`false` 以永不自動連線,或保留未設定以遵循您組織的預設。在 `/config` 中顯示為**為所有工作階段啟用遠端控制**。請參閱[為所有工作階段啟用遠端控制](/docs/zh-TW/remote-control#enable-remote-control-for-all-sessions) | `false` |
306| `requiredMaximumVersion` | Managed 設定僅限。允許啟動的最大 Claude Code 版本。如果執行中的版本較新,Claude Code 會在啟動時結束並指示使用者透過組織的核准方法安裝核准的版本;`claude install <version>` 也可能有效。背景自動更新和 `claude update` 會跳過高於上限的版本,因此在範圍內的安裝保持在範圍內。`claude update`、`claude install` 和 `claude doctor` 在上限以上保持工作,以便使用者可以恢復。早於此設定的版本會忽略它 | `"2.1.150"` |
307| `requiredMinimumVersion` | Managed 設定僅限。啟動所需的最小 Claude Code 版本。如果執行中的版本較舊,Claude Code 會在啟動時結束並指示使用者透過組織的核准方法更新。`claude update`、`claude install` 和 `claude doctor` 在底線以下保持工作,以便使用者可以恢復。與 `minimumVersion` 不同,後者防止降級但永遠不會阻止啟動。早於此設定的版本會忽略它 | `"2.1.150"` |
308| `respectGitignore` | **預設**:`true`。控制 `@` 檔案選擇器是否尊重 `.gitignore` 模式。當為 `true` 時,符合 `.gitignore` 模式的檔案會從建議中排除 | `false` |
309| `respondToBashCommands` | **預設**:`true`。輸入框 `!` shell 命令執行後 Claude 是否回應。設定為 `false` 以將命令輸出新增到內容而不回應。請參閱[使用 `!` 前綴的 Shell 模式](/docs/zh-TW/interactive-mode#shell-mode-with-prefix)。需要 Claude Code v2.1.186 或更新版本 | `false` |
310| `showClearContextOnPlanAccept` | **預設**:`false`。在 Plan Mode 接受畫面上顯示「清除內容」選項。設定為 `true` 以還原選項 | `true` |
311| `showThinkingSummaries` | **預設**:`false`。在互動式工作階段中顯示[擴展思考](/docs/zh-TW/model-config#extended-thinking)摘要。未設定或 `false` 時,思考區塊由 API 編輯並顯示為摺疊的存根。編輯只會改變您看到的內容,而不是模型生成的內容:若要減少思考支出,請[降低預算或停用思考](/docs/zh-TW/model-config#extended-thinking)。此設定在非互動模式(`-p`)、Agent SDK 或 IDE 擴充功能(例如 VS Code)中無效 | `true` |
312| `showTurnDuration` | **預設**:`true`。在回應後顯示輪次持續時間訊息,例如「Cooked for 1m 6s」。在 `/config` 中顯示為**顯示輪次持續時間** | `false` |
313| `skillListingBudgetFraction` | **預設**:`0.01`。為 Claude 每輪看到的[skill 清單](/docs/zh-TW/skills#skill-descriptions-are-cut-short)保留的模型內容視窗分數。當清單超過預算時,最少使用的 skills 的描述會摺疊為裸名稱,以便 Claude 仍可叫用它們,但不會看到原因。提高以保持更多描述可見,代價是每輪更多內容。`/doctor` 估計清單成本對預算 | `0.02` |
314| `skillListingMaxDescChars` | **預設**:`1536`。[skill 清單](/docs/zh-TW/skills#skill-descriptions-are-cut-short)中每個 skill 的字元上限,Claude 每輪看到的 `description` 和 `when_to_use` 文字的組合。超過此長度的文字會被截斷。提高以保持長描述完整,代價是每輪更多內容;降低以在 [`skillListingBudgetFraction`](#available-settings) 下適應更多 skills | `2048` |
315| `skillOverrides` | 按 skill 名稱鍵入的每個 skill 可見性覆蓋。值為 `"on"`、`"name-only"`、`"user-invocable-only"` 或 `"off"`。讓您隱藏或摺疊 skill 而無需編輯其 SKILL.md。不適用於 plugin skills,這些由 `/plugin` 管理。`/skills` 功能表將這些寫入 `.claude/settings.local.json`。請參閱[從設定覆蓋 skill 可見性](/docs/zh-TW/skills#override-skill-visibility-from-settings)。需要 Claude Code v2.1.129 或更新版本 | `{"legacy-context": "name-only", "deploy": "off"}` |
316| `skipWebFetchPreflight` | 跳過[WebFetch 網域安全檢查](/docs/zh-TW/data-usage#webfetch-domain-safety-check),該檢查在擷取前將每個請求的主機名稱傳送到 `api.anthropic.com`。在阻止流量到 Anthropic 的環境中設定為 `true`,例如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 部署,具有限制性的出站。跳過時,WebFetch 嘗試任何 URL 而不諮詢黑名單 | `true` |
317| `spinnerTipsEnabled` | **預設**:`true`。在 Claude 工作時在微調器中顯示提示。設定為 `false` 以停用提示 | `false` |
318| `spinnerTipsOverride` | 使用自訂字串覆蓋微調器提示。`tips`:提示字串陣列。`excludeDefault`:如果為 `true`,僅顯示自訂提示;如果為 `false` 或不存在,自訂提示會與內建提示合併 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |
319| `spinnerVerbs` | 自訂在微調器中顯示的動作動詞。將 `mode` 設定為 `"replace"` 以僅使用您的動詞,或 `"append"` 以將它們新增到預設值 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |
320| `sshConfigs` | 要在[桌面](/docs/zh-TW/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"}]` |
321| `statusLine` | 設定自訂狀態行以顯示內容。物件的選用 `padding`、`refreshInterval` 和 `hideVimModeIndicator` 欄位控制間距、定期重新執行和是否隱藏提示下方的內建 vim 模式指示器。請參閱 [`statusLine` 文件](/docs/zh-TW/statusline#manually-configure-a-status-line) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |
322| `strictKnownMarketplaces` | (Managed 設定僅限)plugin marketplaces 白名單。未定義 = 無限制,空陣列 = 鎖定。在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行,因此在設定政策之前新增的 marketplace 無法用於擷取 plugins。請參閱 [Managed marketplace 限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |
323| `strictPluginOnlyCustomization` | (Managed 設定僅限)阻止 skills、agents、hooks 和 MCP servers 來自使用者和專案來源,因此它們只能來自 plugins 或 managed 設定。`true` 鎖定所有四個表面;陣列僅鎖定命名的表面。請參閱 [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | `["skills", "hooks"]` |
324| `syntaxHighlightingDisabled` | 停用 diffs、程式碼區塊和檔案預覽中的語法醒目提示 | `true` |
325| `teammateMode` | **預設**:`in-process`。[agent team](/docs/zh-TW/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-TW/agent-teams#choose-a-display-mode) | `"auto"` |
326| `terminalProgressBarEnabled` | **預設**:`true`。在支援的終端機中顯示終端機進度條:ConEmu、Ghostty 1.2.0+ 和 iTerm2 3.6.6+。在 `/config` 中顯示為**終端機進度條** | `false` |
327| `theme` | **預設**:`"dark"`。介面的色彩主題:`"auto"`、`"dark"`、`"light"`、`"dark-daltonized"`、`"light-daltonized"`、`"dark-ansi"`、`"light-ansi"` 或自訂主題參考,例如 `"custom:<slug>"` 或 `"custom:<plugin-name>:<slug>"`。請參閱[建立自訂主題](/docs/zh-TW/terminal-config#create-a-custom-theme)。在 `/config` 中顯示為**主題** | `"dark"` |
328| `tui` | 終端機 UI 渲染器。使用 `"fullscreen"` 以取得無閃爍[替代螢幕渲染器](/docs/zh-TW/fullscreen),具有虛擬化捲軸。使用 `"default"` 以取得經典主螢幕渲染器。透過 `/tui` 設定。您也可以設定 [`CLAUDE_CODE_NO_FLICKER`](/docs/zh-TW/env-vars) 環境變數。背景工作階段從[代理檢視](/docs/zh-TW/agent-view)開啟時,無論此設定如何,始終使用全螢幕渲染器 | `"fullscreen"` |
329| `ultracode` | 為工作階段開啟 [ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)。此金鑰不從 `settings.json` 讀取。透過 `/effort ultracode`、`--settings` 或 Agent SDK 控制請求設定。若要以 ultracode 已開啟的狀態啟動工作階段,請使用 `claude --effort ultracode` 啟動,需要 Claude Code v2.1.203 或更新版本 | `true` |
330| `useAutoModeDuringPlan` | **預設**:`true`。Plan Mode 在自動模式可用時是否使用自動模式語義。不從共享專案設定讀取。在 `/config` 中顯示為「在計畫期間使用自動模式」 | `false` |
331| `verbose` | **預設**:`false`。顯示完整工具輸出而不是截斷摘要。在 `/config` 中顯示為**詳細輸出**。`--verbose` 旗標會覆蓋此設定以進行一個工作階段 | `true` |
332| `viewMode` | 啟動時的預設文字記錄檢視模式:`"default"`、`"verbose"` 或 `"focus"`。設定時覆蓋粘性 `/focus` 選擇。`--verbose` 旗標會覆蓋此設定以進行一個工作階段 | `"verbose"` |
333| `vimInsertModeRemaps` | 將兩個按鍵 INSERT 模式序列對應到 Escape 在[vim 編輯器模式](/docs/zh-TW/interactive-mode#vim-editor-mode)中。每個金鑰恰好是兩個按順序輸入的可列印字元,`"<Esc>"` 是唯一支援的目標;其他項目被忽略。僅從使用者、`--settings` 旗標和 managed 設定讀取,因此儲存庫的簽入設定無法重新對應您的按鍵。除非 `editorMode` 為 `"vim"`,否則無效。請參閱[重新對應 INSERT 模式按鍵序列](/docs/zh-TW/interactive-mode#remap-insert-mode-key-sequences)。需要 Claude Code v2.1.208 或更新版本 | `{"jj": "<Esc>"}` |
334| `voice` | [語音聽寫](/docs/zh-TW/voice-dictation)設定:`enabled` 開啟聽寫,`mode` 選擇 `"hold"` 或 `"tap"`,`autoSubmit` 在保持模式中按鍵釋放時傳送提示。當您執行 `/voice` 時自動寫入。需要 Claude.ai 帳戶 | `{ "enabled": true, "mode": "tap" }` |
335| `voiceEnabled` | `voice.enabled` 的舊版別名。偏好 `voice` 物件 | `true` |
336| `wheelScrollAccelerationEnabled` | **預設**:`true`。在[全螢幕渲染](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)中,加速滑鼠滾輪捲軸速度在快速捲軸期間。設定為 `false` 以取得每個滾輪缺口的恆定捲軸速率。需要 Claude Code v2.1.174 或更新版本 | `false` |
337| `workflowKeywordTriggerEnabled` | **預設**:`true`。提示中的單詞 `ultracode` 是否觸發[動態工作流程](/docs/zh-TW/workflows#ask-for-a-workflow-in-your-prompt)。設定為 `false` 以輸入單詞而不觸發一個。Ultracode 努力設定、`/workflows` 和儲存的工作流程命令不受影響。在 `/config` 中顯示為**Ultracode 關鍵字觸發**。在 v2.1.160 之前,觸發關鍵字是 `workflow` | `false` |
338| `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` |
339
340<h3 id="global-config-settings">
341 全域設定設定
342</h3>
343 495
344這些設定儲存在 `~/.claude.json` 中,而不是 `settings.json`。將它們新增到 `settings.json` 將觸發架構驗證錯誤。496在 v2.1.211 之前,Claude Code 在啟動目錄中保留檔案。它仍然讀取較早版本在根檔案旁邊留下的檔案;當兩者設定相同金鑰時,根的值適用,兩個檔案的權限規則適用。Agent SDK 的 [`resolveSettings()`](/docs/zh-TW/agent-sdk/typescript#resolvesettings) 協助程式始終從啟動目錄讀取檔案。
345 497
346<Note>498Claude Code 從工作階段的[主要工作目錄](/docs/zh-TW/permissions#working-directories)讀取共享 `.claude/settings.json`,因此若要使用在儲存庫根目錄提交的檔案,請從那裡啟動 Claude Code。在您[使用 `/cd` 移動工作階段](/docs/zh-TW/permissions#move-the-session-to-another-directory)後,Claude Code 改為從新目錄讀取兩個專案檔案,按相同規則放置本機檔案。從您移動到的目錄讀取它們需要 Claude Code v2.1.246 或更新版本。
347 v2.1.119 之前的版本也會在此處儲存許多 `/config` 偏好金鑰,而不是在 `settings.json` 中,包括 `theme`、`verbose`、`editorMode`、`autoCompactEnabled` 和 `preferredNotifChannel`。
348</Note>
349 499
350| 金鑰 | 說明 | 範例 |500<span id="managed-settings-delivery" />
351| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- |
352| `autoConnectIde` | **預設**:`false`。當 Claude Code 從外部終端機啟動時自動連線到執行中的 IDE。在 VS Code 或 JetBrains 終端機外執行時在 `/config` 中顯示為**自動連線到 IDE(外部終端機)**。[`CLAUDE_CODE_AUTO_CONNECT_IDE`](/docs/zh-TW/env-vars) 環境變數在設定時會覆蓋此設定 | `true` |
353| `autoInstallIdeExtension` | **預設**:`true`。從 VS Code 終端機執行時自動安裝 Claude Code IDE 擴充功能。在 VS Code 或 JetBrains 終端機內執行時在 `/config` 中顯示為**自動安裝 IDE 擴充功能**。您也可以設定 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/docs/zh-TW/env-vars) 環境變數 | `false` |
354| `externalEditorContext` | **預設**:`false`。當您使用 `Ctrl+G` 開啟外部編輯器時,將 Claude 的前一個回應作為 `#` 註解內容前置。在 `/config` 中顯示為**在外部編輯器中顯示最後回應** | `true` |
355| `permissionExplainerEnabled` | **預設**:`true`。當您在 Bash 或 PowerShell 權限提示上按 `Ctrl+E` 時顯示模型產生的[命令說明](/docs/zh-TW/permissions#permission-system)。設定為 `false` 以關閉快捷鍵 | `false` |
356| `teammateDefaultModel` | [agent team](/docs/zh-TW/agent-teams) 隊友在生成提示未指定時的預設模型。設定為模型別名(例如 `"sonnet"`),或 `null` 以繼承主管的目前 `/model` 選擇。在 `/config` 中顯示為**預設隊友模型** | `"sonnet"` |
357| `workflowSizeGuideline` | **預設**:`unrestricted`,不傳送任何指南。設定 Claude 在其撰寫的動態工作流程中目標的[代理計數](/docs/zh-TW/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-TW/workflows#cost)的預設閾值;該行為需要 Claude Code v2.1.203 或更新版本 | `"small"` |
358
359<h3 id="worktree-settings">
360 Worktree 設定
361</h3>
362 501
363設定 `--worktree` 如何建立和管理 git worktrees。502<span id="precedence-within-the-managed-tier" />
364 503
365| 金鑰 | 說明 | 範例 |504<span id="parent-settings-from-embedding-hosts" />
366| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |
367| `worktree.baseRef` | 新 worktrees 分支的來源 ref。`"fresh"`(預設)從 `origin/<default-branch>` 分支以取得與遠端相符的乾淨樹。`"head"` 從您目前的本機 `HEAD` 分支,所以未推送的提交和功能分支狀態存在於 worktree 中。在連結的 worktree 內,`"head"` 解析為該 worktree 的 `HEAD`,而不是主簽出的。適用於 `--worktree`、`EnterWorktree` 工具和 subagent 隔離 | `"head"` |
368| `worktree.symlinkDirectories` | 要從主儲存庫符號連結到每個 worktree 的目錄,以避免在磁碟上複製大型目錄。預設不符號連結任何目錄 | `["node_modules", ".cache"]` |
369| `worktree.sparsePaths` | 要在每個 worktree 中透過 git sparse-checkout 簽出的目錄。僅將列出的目錄加上根層級檔案寫入磁碟,在大型 monorepos 中速度更快。當稀疏 worktree 存在時,git 在儲存庫的共享 `.git/config` 中啟用 `extensions.worktreeConfig`;請參閱[僅簽出您需要的目錄](/docs/zh-TW/large-codebases#check-out-only-the-directories-you-need) | `["packages/my-app", "shared/utils"]` |
370| `worktree.bgIsolation` | [背景工作階段](/docs/zh-TW/agent-view#how-file-edits-are-isolated)的隔離模式。`"worktree"`(預設)在呼叫 `EnterWorktree` 之前阻止主簽出中的 `Edit`/`Write`。在 git 儲存庫外,失敗的 [`WorktreeCreate` hook](/docs/zh-TW/worktrees#non-git-version-control) 會釋放區塊,以便工作階段可以就地編輯工作目錄;需要 Claude Code v2.1.203 或更新版本。`"none"` 讓背景工作直接編輯工作副本。需要 Claude Code v2.1.143 或更新版本 | `"none"` |
371 505
372若要將 gitignored 檔案(如 `.env`)複製到新的 worktrees,請改用專案根目錄中的 [`.worktreeinclude` 檔案](/docs/zh-TW/worktrees#copy-gitignored-files-into-worktrees),而不是設定。506<span id="enforce-settings-for-an-organization" />
373 507
374<h3 id="permission-settings">508<span id="settings-your-organization-manages" />
375 權限設定
376</h3>
377 509
378| 金鑰 | 說明 | 範例 |510<h3 id="check-what-your-organization-enforces">
379| :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |511 檢查您的組織強制執行的內容
380| `allow` | 允許工具使用的權限規則陣列。工具名稱 globs 僅在字面 `mcp__<server>__` 前綴之後的工具位置支援,例如 `mcp__github__get_*`;server 段必須無 glob。請參閱下面的[權限規則語法](#permission-rule-syntax)以了解模式匹配詳細資訊 | `[ "Bash(git diff *)" ]` |
381| `ask` | 要求在工具使用時確認的權限規則陣列。請參閱下面的[權限規則語法](#permission-rule-syntax) | `[ "Bash(git push *)" ]` |
382| `deny` | 拒絕工具使用的權限規則陣列。使用此選項從 Claude Code 存取中排除敏感檔案。工具名稱接受 glob 模式:`"*"` 拒絕每個工具,`"mcp__*"` 拒絕所有 MCP 工具。請參閱[權限規則語法](#permission-rule-syntax)和 [Bash 權限限制](/docs/zh-TW/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |
383| `additionalDirectories` | Claude 有權存取的其他[工作目錄](/docs/zh-TW/permissions#working-directories)。大多數 `.claude/` 設定[未從這些目錄發現](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |
384| `defaultMode` | 開啟 Claude Code 時的預設[權限模式](/docs/zh-TW/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"` |
385| `disableBypassPermissionsMode` | 設定為 `"disable"` 以防止啟用 `bypassPermissions` 模式。這會停用 `--dangerously-skip-permissions` 旗標。在[managed 設定](/docs/zh-TW/permissions#managed-settings)中最有用,使用者無法覆蓋它 | `"disable"` |
386| `skipDangerousModePermissionPrompt` | 跳過透過 `--dangerously-skip-permissions` 或 `defaultMode: "bypassPermissions"` 進入 bypass permissions 模式之前顯示的確認提示。在專案設定(`.claude/settings.json`)中設定時被忽略,以防止不受信任的儲存庫自動繞過提示 | `true` |
387
388<h3 id="permission-rule-syntax">
389 權限規則語法
390</h3>512</h3>
391 513
392權限規則遵循 `Tool` 或 `Tool(specifier)` 的格式。規則按順序評估:首先是拒絕規則,然後是詢問,最後是允許。第一個匹配的規則決定結果,無論規則特異性如何。請參閱[權限規則評估順序](/docs/zh-TW/permissions#manage-permissions)以了解詳細資訊。514如果您的組織管理 Claude Code,某些設定是為您決定的,您在自己的檔案中放入的任何內容都不會變更它們。若要查看哪些,請執行 `/status`:`Setting sources` 行命名適用於您的受管來源。受管設定在此機器上 Claude Code 執行的任何地方適用;[開發人員可以變更的內容](/docs/zh-TW/managed-settings#what-a-developer-can-change)涵蓋本機管理員權限和 Claude Code 以外的工具。
393
394快速範例:
395
396| 規則 | 效果 |
397| :----------------------------- | :-------------------- |
398| `Bash` | 符合所有 Bash 命令 |
399| `Bash(npm run *)` | 符合以 `npm run` 開頭的命令 |
400| `Read(./.env)` | 符合讀取 `.env` 檔案 |
401| `WebFetch(domain:example.com)` | 符合對 example.com 的擷取請求 |
402
403如需完整的規則語法參考,包括萬用字元行為、Read、Edit、WebFetch、MCP 和 Agent 規則的工具特定模式,以及 Bash 模式的安全限制,請參閱[權限規則語法](/docs/zh-TW/permissions#permission-rule-syntax)。
404
405<h3 id="sandbox-settings">
406 Sandbox 設定
407</h3>
408 515
409設定進階 sandboxing 行為。Sandboxing 將 bash 命令與您的檔案系統和網路隔離。請參閱 [Sandboxing](/docs/zh-TW/sandboxing) 以了解詳細資訊。516受管設定通過受管設定頁面上的[傳遞機制](/docs/zh-TW/managed-settings#delivery-mechanisms)到達您,最常見的是:
410
411| 金鑰 | 說明 | 範例 |
412| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------- |
413| `enabled` | 啟用 bash sandboxing(macOS、Linux 和 WSL2)。預設:false | `true` |
414| `failIfUnavailable` | 如果 `sandbox.enabled` 為 true 但 sandbox 無法啟動(遺失相依性、不支援的平台),則在啟動時以錯誤結束。當為 false(預設)時,會顯示警告,命令會以 unsandboxed 方式執行。適用於需要 sandboxing 作為硬閘門的 managed 設定部署 | `true` |
415| `autoAllowBashIfSandboxed` | 在 sandboxed 時自動批准 bash 命令。預設:true | `true` |
416| `excludedCommands` | 應在 sandbox 外執行的命令 | `["docker *"]` |
417| `allowUnsandboxedCommands` | 允許命令透過 `dangerouslyDisableSandbox` 參數在 sandbox 外執行。當設定為 `false` 時,`dangerouslyDisableSandbox` 逃脫艙口完全停用,所有命令必須 sandboxed(或在 `excludedCommands` 中)。適用於需要嚴格 sandboxing 的企業政策。預設:true | `false` |
418| `filesystem.allowWrite` | sandboxed 命令可以寫入的其他路徑。陣列跨所有設定範圍合併:使用者、專案和 managed 路徑合併,不替換。也與 `Edit(...)` 允許權限規則中的路徑合併。請參閱下面的[路徑前綴](#sandbox-path-prefixes)。 | `["/tmp/build", "~/.kube"]` |
419| `filesystem.denyWrite` | sandboxed 命令無法寫入的路徑。陣列跨所有設定範圍合併。也與 `Edit(...)` 拒絕權限規則中的路徑合併。 | `["/etc", "/usr/local/bin"]` |
420| `filesystem.denyRead` | sandboxed 命令無法讀取的路徑。陣列跨所有設定範圍合併。也與 `Read(...)` 拒絕權限規則中的路徑合併。 | `["~/.aws/credentials"]` |
421| `filesystem.allowRead` | 在 `denyRead` 區域內重新允許讀取的路徑。`allowRead` 路徑在更廣泛的 `denyRead` 區域內重新開啟讀取,`denyRead` 中的精確路徑在更廣泛的 `allowRead` 內保持被阻止;請參閱[重疊表](/docs/zh-TW/sandboxing#configure-sandboxing)以了解範例。陣列跨所有設定範圍合併。使用此選項建立僅工作區讀取存取模式。 | `["."]` |
422| `filesystem.allowManagedReadPathsOnly` | (Managed 設定僅限)僅尊重 managed 設定中的 `filesystem.allowRead` 路徑。`denyRead` 仍從所有來源合併。預設:false | `true` |
423| `credentials.files` | Sandboxed 命令無法讀取的認證檔案或目錄。應用與 `filesystem.denyRead` 相同的讀取區塊;單獨的金鑰將認證路徑與 `credentials.envVars` 分組,並與一般檔案系統規則分開。每個項目為 `{ "path": "...", "mode": "deny" }`,僅支援 `deny`。路徑使用與 `filesystem.*` 設定相同的[前綴](#sandbox-path-prefixes)。陣列跨所有設定範圍合併。需要 Claude Code v2.1.187 或更新版本。 | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |
424| `credentials.envVars` | 環境變數以[保護免受 sandboxed 命令](/docs/zh-TW/sandboxing#protect-credentials)。每個項目有一個 `name` 和一個 `mode`;名稱必須以字母或底線開頭,並僅包含字母、數字和底線。`deny` 從 sandboxed 命令的環境中移除變數。需要 Claude Code v2.1.187 或更新版本。}`mask` 在 sandbox 內用每個工作階段的 sentinel 值替換變數,而 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" }]` |
425| `credentials.envVars[].injectHosts` | Sandbox 代理替換 `mask` 項目真實值的主機。每個主機也必須由 `network.allowedDomains` 涵蓋,無論是精確還是通過萬用字元。未設定時,代理在 `network.allowedDomains` 中的每個主機上替換值。當 `mode` 為 `deny` 時被接受但忽略。需要 Claude Code v2.1.199 或更新版本。} | `["api.github.com"]` |
426| `credentials.allowPlaintextInject` | 允許 `mask` 替換在純 HTTP 請求以及 TLS 終止的 HTTPS 上。在純 HTTP 上,上游身份未驗證,認證以明文形式傳輸,因此在受信任的測試網路外保持此設定關閉。僅從使用者、managed 或 CLI `--settings` 設定受尊重,不從 `.claude/settings.json` 或 `.claude/settings.local.json`。預設:false。需要 Claude Code v2.1.199 或更新版本。} | `true` |
427| `network.allowUnixSockets` | (macOS 僅限)sandbox 中可存取的 Unix socket 路徑。在 Linux 和 WSL2 上被忽略,其中 seccomp 篩選器無法檢查 socket 路徑;改用 `allowAllUnixSockets`。 | `["~/.ssh/agent-socket"]` |
428| `network.allowAllUnixSockets` | 允許 sandbox 中的所有 Unix socket 連線。在 Linux 和 WSL2 上,這是允許 Unix sockets 的唯一方式,因為它跳過了 seccomp 篩選器,否則會阻止 `socket(AF_UNIX, ...)` 呼叫。預設:false | `true` |
429| `network.allowLocalBinding` | 允許繫結到 localhost 連接埠(macOS 僅限)。預設:false | `true` |
430| `network.allowMachLookup` | sandbox 可能查詢的其他 XPC/Mach 服務名稱(macOS 僅限)。支援單一尾部 `*` 用於前綴匹配。iOS 模擬器或 Playwright 等透過 XPC 通訊的工具需要。 | `["com.apple.coresimulator.*"]` |
431| `network.allowedDomains` | 允許出站網路流量的網域陣列。支援萬用字元(例如 `*.example.com`)。 | `["github.com", "*.npmjs.org"]` |
432| `network.deniedDomains` | 允許阻止出站網路流量的網域陣列。支援與 `allowedDomains` 相同的萬用字元語法。當兩者都符合時優先於 `allowedDomains`。無論 `allowManagedDomainsOnly` 如何,都從所有設定來源合併。 | `["sensitive.cloud.example.com"]` |
433| `network.allowManagedDomainsOnly` | (Managed 設定僅限)僅尊重 managed 設定中的 `allowedDomains` 和 `WebFetch(domain:...)` 允許規則。來自使用者、專案和本機設定的網域會被忽略。非允許的網域會自動阻止,不會提示使用者。拒絕的網域仍從所有來源受尊重。預設:false | `true` |
434| `network.httpProxyPort` | 如果您想帶上自己的代理,使用的 HTTP 代理連接埠。如果未指定,Claude 將執行自己的代理。 | `8080` |
435| `network.socksProxyPort` | 如果您想帶上自己的代理,使用的 SOCKS5 代理連接埠。如果未指定,Claude 將執行自己的代理。 | `8081` |
436| `network.tlsTerminate` | 實驗性。在 sandbox 代理內終止 TLS,以便它可以讀取 HTTPS 請求的內容。[credential substitution](/docs/zh-TW/sandboxing#protect-credentials) 的 `mask` 需要。設定 `{}` 以為工作階段產生臨時憑證授權單位,或設定 `caCertPath` 和 `caKeyPath` 以使用您自己的。僅從使用者、managed 或 CLI `--settings` 設定受尊重,不從 `.claude/settings.json` 或 `.claude/settings.local.json`。需要 Claude Code v2.1.199 或更新版本。} | `{}` |
437| `enableWeakerNestedSandbox` | 為無特權 Docker 環境啟用較弱的 sandbox(Linux 和 WSL2 僅限)。**降低安全性。** 預設:false | `true` |
438| `enableWeakerNetworkIsolation` | (macOS 僅限)允許在 sandbox 中存取系統 TLS 信任服務(`com.apple.trustd.agent`)。使用 `httpProxyPort` 和自訂 CA 的 MITM 代理時,Go 型工具(如 `gh`、`gcloud` 和 `terraform`)需要驗證 TLS 憑證。**透過開啟潛在的資料外洩路徑降低安全性**。預設:false | `true` |
439| `allowAppleEvents` | (macOS 僅限)允許 sandboxed 命令傳送 Apple Events。`open`、`osascript` 和在瀏覽器中開啟 URL 的工具需要,否則會失敗並出現錯誤 `-600`。**移除程式碼執行隔離。** Sandboxed 命令可以啟動其他應用程式 unsandboxed,無需使用者提示;它們也可以傳送 AppleScript 命令到執行中的應用程式(例如終端機),受限於每個應用程式的 macOS 自動化同意提示 (TCC)。僅從使用者、managed 或 CLI 設定受尊重,不從專案設定。預設:false | `true` |
440| `bwrapPath` | (Managed 設定僅限,Linux/WSL2)bubblewrap (`bwrap`) 二進位檔的絕對路徑。覆蓋透過 `PATH` 的自動偵測。僅從 [managed 設定](/docs/zh-TW/settings#settings-files)受尊重,不從使用者或專案設定。在 managed 環境中 `bwrap` 安裝在非標準位置時很有用。 | `/opt/admin/bwrap` |
441| `socatPath` | (Managed 設定僅限,Linux/WSL2)用於 sandbox 網路代理的 `socat` 二進位檔的絕對路徑。覆蓋透過 `PATH` 的自動偵測。僅從 managed 設定受尊重。 | `/opt/admin/socat` |
442
443<h4 id="sandbox-path-prefixes">
444 Sandbox 路徑前綴
445</h4>
446 517
447`filesystem.allowWrite`、`filesystem.denyWrite`、`filesystem.denyRead`、`filesystem.allowRead` 和 `credentials.files` 中的路徑支援這些前綴:518* [伺服器受管設定](/docs/zh-TW/server-managed-settings),Claude Code 從 claude.ai 管理主控台或自託管[Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)擷取
519* MDM 或作業系統層級政策,以及系統目錄中的 `managed-settings.json` 檔案
520* 嵌入主機(例如 Claude Desktop),通過 SDK `managedSettings` 選項;請參閱[從嵌入主機控制政策](/docs/zh-TW/managed-settings#parent-settings-from-embedding-hosts)
448 521
449| 前綴 | 含義 | 範例 |522在在 Claude Desktop 應用程式中在您的機器上執行的 [Cowork](https://claude.com/docs/cowork/overview) 工作階段中,Claude Code 不會從 claude.ai 管理主控台擷取伺服器受管設定,它讀取部署到您的裝置的政策,除非您的組織的 Claude Desktop 設定設定 `requireCoworkFullVmSandbox`。[政策適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)涵蓋 Cowork 和雲端工作階段。
450| :-------- | :---------------------------------------- | :---------------------------------------------------------------- |
451| `/` | 從檔案系統根目錄的絕對路徑 | `/tmp/build` 保持 `/tmp/build` |
452| `~/` | 相對於主目錄 | `~/.kube` 變成 `$HOME/.kube` |
453| `./` 或無前綴 | 相對於專案根目錄(用於專案設定)或相對於 `~/.claude`(用於使用者設定) | `./output` 在 `.claude/settings.json` 中解析為 `<project-root>/output` |
454 523
455較舊的 `//path` 前綴用於絕對路徑仍然有效。如果您之前使用單斜線 `/path` 期望專案相對解析,請切換到 `./path`。此語法與[讀取和編輯權限規則](/docs/zh-TW/permissions#read-and-edit)不同,後者使用 `//path` 用於絕對和 `/path` 用於專案相對。Sandbox 檔案系統路徑使用標準慣例:`/tmp/build` 是絕對路徑。524如果您是管理員,[為您的組織設定 Claude Code](/docs/zh-TW/admin-setup) 會逐步說明選擇要強制執行的內容,而[部署受管設定](/docs/zh-TW/managed-settings)涵蓋傳遞以及如何確認政策生效。
456 525
457**設定範例:**526<h2 id="change-a-setting">
527 變更設定
528</h2>
458 529
459```json theme={null}530您可以從 `/config` 功能表、編輯設定檔案或一個工作階段的命令列變更設定。
460{
461 "sandbox": {
462 "enabled": true,
463 "autoAllowBashIfSandboxed": true,
464 "excludedCommands": ["docker *"],
465 "filesystem": {
466 "allowWrite": ["/tmp/build", "~/.kube"],
467 "denyRead": ["~/.aws/credentials"]
468 },
469 "network": {
470 "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
471 "deniedDomains": ["uploads.github.com"],
472 "allowUnixSockets": [
473 "/var/run/docker.sock"
474 ],
475 "allowLocalBinding": true
476 }
477 }
478}
479```
480 531
481**檔案系統和網路限制**可以透過兩種合併在一起的方式設定:532<span id="system-prompt" />
482 533
483* **`sandbox.filesystem` 設定**(如上所示):在 OS 層級 sandbox 邊界控制路徑。這些限制適用於所有子流程命令(例如 `kubectl`、`terraform`、`npm`),而不僅僅是 Claude 的檔案工具。534Claude Code 的系統提示未發佈。若要給 Claude 常設指示,請使用 [`CLAUDE.md` 檔案](/docs/zh-TW/memory)或 `--append-system-prompt` 旗標。
484* **權限規則**:使用 `Edit` 允許/拒絕規則控制 Claude 的檔案工具存取,`Read` 拒絕規則阻止讀取,`WebFetch` 允許/拒絕規則控制網路網域。這些規則中的路徑也會合併到 sandbox 設定中。
485 535
486<h3 id="attribution-settings">536<h3 id="use-the-/config-menu">
487 歸屬設定537 使用 /config 功能表
488</h3>538</h3>
489 539
490Claude Code 將歸屬新增到 git 提交和拉取請求。這些分別設定:540在 Claude Code 內執行 `/config` 並開啟 **Config** 標籤。它列出一小組個人選項,例如主題、編輯器模式和詳細輸出,而不是每個設定金鑰。選擇一個選項來變更它;Claude Code 為您儲存它:
491 541
492* 提交預設使用 [git trailers](https://git-scm.com/docs/git-interpret-trailers)(如 `Co-Authored-By`),可以自訂或停用542* **大多數選項**:`~/.claude/settings.json`
493* 拉取請求說明是純文字543* **少數選項,例如顯示提示**:`.claude/settings.local.json`
544* **[全域設定選項](/docs/zh-TW/settings-reference#global-config-settings)**:`~/.claude.json`
494 545
495| 金鑰 | 說明 |546若要設定一個選項而不使用功能表,請傳遞 `key=value`,例如 `/config verbose=true`。
496| :----------- | :------------------------------------------------------------------------------------------------------------- |
497| `commit` | git 提交的歸屬,包括任何 trailers。空字串隱藏提交歸屬 |
498| `pr` | 拉取請求說明的歸屬。空字串隱藏拉取請求歸屬 |
499| `sessionUrl` | 當從網頁或遠端控制工作階段執行時,是否將 claude.ai 工作階段連結附加為提交上的 `Claude-Session` trailer 和拉取請求說明中的連結。預設為 `true`。設定為 `false` 以省略連結 |
500
501**預設提交歸屬:**
502
503```text theme={null}
504Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
505```
506
507模型名稱在 trailer 中反映工作階段的使用中模型。
508
509**預設拉取請求歸屬:**
510
511```text theme={null}
512🤖 Generated with [Claude Code](https://claude.com/claude-code)
513```
514
515**範例:**
516
517```json theme={null}
518{
519 "attribution": {
520 "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
521 "pr": ""
522 }
523}
524```
525 547
526<Note>548<Note>
527 `attribution` 設定優先於已棄用的 `includeCoAuthoredBy` 設定。若要隱藏所有歸屬,請將 `commit` 和 `pr` 設定為空字串,並將 `sessionUrl` 設定為 `false`。549 `/config` 是終端機介面的一部分。[VS Code](/docs/zh-TW/vs-code) 聊天面板和[桌面應用程式](/docs/zh-TW/desktop)不開啟它;通過編輯設定檔案或通過這些應用程式自己的設定在那裡變更設定。
528</Note>550</Note>
529 551
530<h3 id="file-suggestion-settings">552<h3 id="edit-a-settings-file">
531 檔案建議設定553 編輯設定檔案
532</h3>
533
534為 `@` 檔案路徑自動完成設定自訂命令。內建檔案建議使用快速檔案系統遍歷,但大型 monorepos 可能受益於專案特定的索引,例如預先建立的檔案索引或自訂工具。
535
536```json theme={null}
537{
538 "fileSuggestion": {
539 "type": "command",
540 "command": "~/.claude/file-suggestion.sh"
541 }
542}
543```
544
545該命令使用與 [hooks](/docs/zh-TW/hooks) 相同的環境變數執行,包括 `CLAUDE_PROJECT_DIR`。它透過 stdin 接收包含 `query` 欄位的 JSON:
546
547```json theme={null}
548{"query": "src/comp"}
549```
550
551將換行符分隔的檔案路徑輸出到 stdout(目前限制為 15):
552
553```text theme={null}
554src/components/Button.tsx
555src/components/Modal.tsx
556src/components/Form.tsx
557```
558
559**範例:**
560
561```bash theme={null}
562#!/bin/bash
563query=$(cat | jq -r '.query')
564# 用您自己的檔案搜尋命令替換 your-repo-file-index
565your-repo-file-index --query "$query" | head -20
566```
567
568<h3 id="footer-link-badges">
569 頁尾連結徽章
570</h3>554</h3>
571 555
572`footerLinksRegexes` 設定在輸入框下方的頁尾中渲染額外的可點擊徽章。使用它將專案 CLI 列印的 ID(例如審查工具和問題追蹤器)轉換為工作階段連結。556在您的編輯器中開啟您想要的範圍的設定檔案,並新增或變更金鑰。設定檔案是嚴格的 JSON:`//` 註解或尾部逗號是語法錯誤,Claude Code 在下次啟動時將檔案報告為[設定錯誤](#fix-a-broken-settings-file)。例如,若要讓 Claude Code 執行您的 lint 和測試命令而不詢問並停止讀取 `.env` 檔案,請將此新增到 `~/.claude/settings.json`:
573
574每個項目的 `pattern` regex 與輪次輸出相符:工具結果,包括檔案內容和擷取的頁面,以及 Claude 自己的回應。`url` 和 `label` 中的 `{name}` 佔位符從模式中的命名擷取群組填入。
575
576以下範例在問題金鑰(如 `PROJ-1234`)出現在輪次輸出中時渲染徽章。`(?<key>...)` 命名群組擷取金鑰,`{key}` 將其替換到 URL 和標籤中:
577 557
578```json ~/.claude/settings.json theme={null}558```json ~/.claude/settings.json theme={null}
579{559{
580 "footerLinksRegexes": [560 "$schema": "https://json.schemastore.org/claude-code-settings.json",
581 {561 "permissions": {
582 "type": "regex",562 "allow": [
583 "pattern": "\\b(?<key>PROJ-\\d+)\\b",563 "Bash(npm run lint)",
584 "url": "https://issues.example.com/browse/{key}",564 "Bash(npm run test *)"
585 "label": "{key}"565 ],
586 }566 "deny": [
567 "Read(./.env)",
568 "Read(./.env.*)"
587 ]569 ]
570 }
588}571}
589```572```
590 573
591設定此項後,當 `PROJ-1234` 出現在工具結果或 Claude 的回覆中時,`PROJ-1234` 晶片會出現在頁尾中,連結到 `https://issues.example.com/browse/PROJ-1234`。574`permissions` 下的每個項目都是命名工具及其可能執行的操作的規則;[設定權限](/docs/zh-TW/permissions)解釋語法。`$schema` 行指向 Claude Code 設定的[已發佈 JSON 架構](https://json.schemastore.org/claude-code-settings.json),它在 VS Code、Cursor 和任何其他支援 JSON 架構的編輯器中為您提供自動完成和內嵌驗證。架構可能滯後於最新的 CLI 版本,因此最近記錄的金鑰上的驗證警告並不意味著您的設定無效。
592
593以下限制適用於每個項目:
594 575
595| 限制 | 行為 |576儲存後,在 Claude Code 內執行 `/status` 以確認檔案已載入;[確認已載入的內容](#check-what-loaded)說明 `Setting sources` 行顯示的內容以及如何報告損壞的檔案。
596| :----- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
597| URL 來源 | 擷取的值是 URL 編碼的,構造的 URL 必須共享範本的字面來源。擷取可以填入路徑段或查詢值,但無法改變連結指向的位置 |
598| URL 長度 | 超過 2048 個字元的構造 URL 會被丟棄 |
599| URL 方案 | 必須是 `https`、`http` 或公認的編輯器或工作區深層連結方案:`vscode`、`vscode-insiders`、`cursor`、`windsurf`、`zed`、`jetbrains`、`idea`、`slack`、`linear`、`notion`、`figma` |
600| 標籤 | 預設為符合的文字,截斷為 28 個顯示欄 |
601| 徽章計數 | 最多 5 個徽章渲染。最舊的被較新的符合所取代,`/clear` 會移除它們 |
602| 設定範圍 | 僅從使用者設定、`--settings` 旗標和 managed 設定讀取。在專案 `.claude/settings.json` 和本機 `.claude/settings.local.json` 中被忽略 |
603 577
604輪次完成時,Claude Code 在主執行緒上將每個項目的 `pattern` regex 與輪次輸出相符,因此緩慢的 regex 會阻止 UI,直到完成。嵌套量詞(例如 `(a+)+$`)可能針對某些輸入花費指數級長時間並凍結工作階段,因此保持每個 `pattern` 線性並避免嵌套 `+` 或 `*`。578如需完整的個人檔案、團隊檔案和組織檔案,每個都帶有每個金鑰的註解,請參閱[範例設定檔案](/docs/zh-TW/settings-example)。
605 579
606頁尾徽章與[自訂狀態行](/docs/zh-TW/statusline)並排渲染(當設定一個時);兩者都不替換另一個。使用狀態行用於從工作階段資料計算自己內容的指令碼驅動列,使用頁尾徽章將對話中的 ID 轉換為連結,而無需指令碼。580<span id="pass-settings-for-one-session" />
607 581
608<h3 id="hook-configuration">582<h3 id="change-a-setting-for-one-session">
609 Hook 設定583 為一個工作階段變更設定
610</h3>584</h3>
611 585
612這些設定控制允許執行哪些 hooks 以及 HTTP hooks 可以存取的內容。`allowManagedHooksOnly` 設定只能在 [managed 設定](#settings-files)中設定。URL 和環境變數白名單可以在任何設定層級設定,並跨來源合併。586若要嘗試值而不儲存它,請在啟動 Claude Code 時設定它。該值適用於該工作階段,您的設定檔案保持原樣。您有三種方式執行此操作:
613
614**當 `allowManagedHooksOnly` 為 `true` 時的行為:**
615
616* 載入 Managed hooks 和 SDK hooks
617* 從在 managed 設定 `enabledPlugins` 中強制啟用的 plugins 載入 Hooks。這讓管理員透過組織 marketplace 分發經過審查的 hooks,同時阻止其他所有內容。信任由完整 `plugin@marketplace` ID 授予,因此來自不同 marketplace 的同名 plugin 保持被阻止
618* 使用者 hooks、專案 hooks 和所有其他 plugin hooks 被阻止
619 587
620**限制 HTTP hook URL:**588* **`--settings`**:將金鑰作為 JSON 傳遞,內嵌或作為檔案路徑。Claude Code 在您的使用者、專案和本機檔案上方以及受管設定下方應用它。它可以設定您的使用者設定檔案可以設定的任何金鑰;它無法設定 `Managed` 或 `Global config` 金鑰。
589* **該金鑰的旗標**:某些金鑰有自己的旗標,例如 `model` 的 `--model` 和 `effortLevel` 和 `modelSettings` 的 `--effort`。
590* **環境變數**:在執行 `claude` 之前匯出金鑰的配對變數,例如 `ANTHROPIC_MODEL` 用於 `model`。
621 591
622限制 HTTP hooks 可以針對的 URL。支援 `*` 作為匹配的萬用字元。定義陣列時,針對不匹配 URL 的 HTTP hooks 會被無聲地阻止。主機名稱匹配不區分大小寫,並忽略尾部 FQDN 點,符合 DNS 語義。592[設定參考](/docs/zh-TW/settings-reference)上的每個金鑰項目列出其每個工作階段覆蓋及其優先順序,因此檢查您想變更的金鑰的項目。
623 593
624```json theme={null}594您在工作階段內執行的命令大多儲存您的選擇:當您在 `/config` 中變更設定時,Claude Code 將其寫入您的設定檔案,而 `/model` 將值儲存為新工作階段的預設值。
625{
626 "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
627}
628```
629 595
630**限制 HTTP hook 環境變數:**596如果您在 `/model` 選擇器中按 `s`,Claude Code 會切換模型而不將其儲存為您的使用者預設值。[調整努力等級](/docs/zh-TW/model-config#adjust-effort-level)說明哪些 `/effort` 選擇 Claude Code 儲存為您使用的模型的預設值,哪些僅適用於目前工作階段。
631 597
632限制 HTTP hooks 可以插入到標頭值中的環境變數名稱。每個 hook 的有效 `allowedEnvVars` 是其自己清單與此設定的交集。598例如,若要在 Opus 上啟動一個工作階段而不變更您的預設值:
633 599
634```json theme={null}600```bash theme={null}
635{601claude --settings '{"model": "claude-opus-4-8"}'
636 "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
637}
638```602```
639 603
640<h3 id="compute-managed-settings-with-a-policy-helper">604<h3 id="when-edits-take-effect">
641 使用政策協助程式計算 managed 設定605 編輯何時生效
642</h3>606</h3>
643 607
644`policyHelper` 設定指向在啟動時計算 managed 設定的可執行檔,因此管理員可以從裝置狀態、身份或遠端服務衍生政策,而不是靜態檔案。從 MDM 或系統 `managed-settings.json` 檔案設定它。Claude Code 在任何其他範圍中出現 `policyHelper` 時會忽略它,包括使用者設定、專案設定、HKCU 登錄 hive 和[伺服器管理的設定](/docs/zh-TW/server-managed-settings)。608Claude Code 監視您的設定檔案並在它們變更時重新載入它們,因此它應用大多數編輯到執行中的工作階段而不需要重新啟動,包括對 `permissions`、`hooks` 和認證協助程式(例如 `apiKeyHelper`)的編輯。Claude Code 也在其資料夾在工作階段啟動時存在時載入您在中途建立的設定檔案。對於專案的 `.claude/` 資料夾,即使您在同一工作階段中建立資料夾,它也會載入檔案。
645 609
646該設定接受這些金鑰:610重新載入涵蓋使用者、專案、本機和受管設定,Claude Code 為它偵測到的每個設定檔案變更執行 [`ConfigChange` hook](/docs/zh-TW/hooks#configchange),而不是來自 MDM 或 claude.ai 主控台的受管設定。來自 MDM 或 claude.ai 主控台的受管設定按排程而不是保存時到達執行中的工作階段;[傳遞表](/docs/zh-TW/managed-settings#choose-a-delivery-mechanism)按來源給出它。
647 611
648| 金鑰 | 類型 | 說明 |612Claude Code 只在工作階段啟動時讀取某些金鑰一次,因此對其中一個的編輯不會到達執行中的工作階段。也等待重新啟動的管理員端金鑰(例如 `requiredMinimumVersion`)列在[政策適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)下。您最可能在中途編輯的是:
649| ------------------- | ------ | ------------------------------------------- |
650| `path` | string | 協助程式可執行檔的絕對路徑 |
651| `timeoutMs` | number | 在將執行視為失敗之前等待協助程式多長時間 |
652| `refreshIntervalMs` | number | 在背景中重新執行協助程式的頻率。設定為 `0` 以停用重新整理,或至少 `60000` |
653 613
654協助程式將 JSON 信封寫入 stdout。將設定放在 `managedSettings` 金鑰下,而不是在頂層,因為裸設定物件會以 `managedSettings` 未定義的方式解析並應用任何內容:614* [`model`](/docs/zh-TW/settings-reference#model):使用 [`/model`](/docs/zh-TW/model-config#setting-your-model) 在中途切換。每個模型都有自己的提示快取,因此切換後的第一個請求會重新讀取整個對話未快取;請參閱[切換模型](/docs/zh-TW/prompt-caching#switching-models)
615* [`effortLevel`](/docs/zh-TW/settings-reference#effortlevel) 和 [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings):使用 [`/effort`](/docs/zh-TW/model-config#adjust-effort-level) 在中途變更努力
655 616
656```json theme={null}617<span id="verify-active-settings" />
657{
658 "managedSettings": {
659 "permissions": { "deny": ["Read(//etc/secrets/**)"] }
660 },
661 "claudeMd": "# Organization context\n...",
662 "appendSystemPrompt": "Always cite the internal style guide."
663}
664```
665 618
666當協助程式發出 `managedSettings` 時,該物件會替換該執行的檔案型 managed 設定。當協助程式在啟動時以非零狀態結束時,Claude Code 會列印錯誤並拒絕啟動,因此需要中斷恢復能力的協助程式應從自己的快取提供並以 `0` 結束。619<span id="check-what-loaded" />
667 620
668<h3 id="settings-precedence">621<h3 id="confirm-what-loaded">
669 設定優先順序622 確認已載入的內容
670</h3>623</h3>
671 624
672設定按優先順序順序應用。從最高到最低:625在 Claude Code 內執行 `/status` 以查看哪些設定來源是使用中的。**Status** 標籤包含 `Setting sources` 行,列出 Claude Code 為目前工作階段載入的每個設定檔案,例如 `User settings` 或 `Project local settings`。當[受管設定](/docs/zh-TW/admin-setup#decide-how-settings-reach-devices)生效時,受管設定項目在括號中顯示它們如何到達您的機器。
673 626
6741. **Managed 設定**([伺服器管理](/docs/zh-TW/server-managed-settings)、[MDM/OS 層級政策](#configuration-scopes)或 [managed 設定](#settings-files))627該行確認 Claude Code 讀取了哪些檔案;它不顯示哪個檔案提供了每個金鑰。若要列出 Claude Code 拒絕的項目,請執行 [`claude doctor`](/docs/zh-TW/debug-your-config);對於專案或受管設定設定的模型,啟動標頭命名設定它的檔案。`/status` 和 `/config` 在不同標籤上開啟相同的對話框,**Config** 標籤不是您 `settings.json` 內容的檢視。
675 * 由 IT 透過伺服器傳遞、MDM 設定檔案、登錄政策或 managed 設定檔案部署的政策
676 * 無法被任何其他層級覆蓋,包括命令列引數
677 * 在 managed 層級內,僅使用一個 managed 來源,其他來源被忽略而不是合併。優先順序,最高優先:
678 * [`policyHelper`](#compute-managed-settings-with-a-policy-helper) 輸出:當設定時,這是唯一使用的 managed 來源
679 * 遠端(claude.ai [伺服器管理](/docs/zh-TW/server-managed-settings)或 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway)傳遞)
680 * MDM/OS 層級政策
681 * 檔案型(`managed-settings.d/*.json` 和 `managed-settings.json`,合併在一起)
682 * HKCU 登錄(僅限 Windows)
683 * 少數金鑰是例外,在任何管理員控制的 managed 來源設定它們時受尊重,而不是僅由獲勝的來源。使用者可寫的 HKCU 登錄來源被排除。例外金鑰為:
684 * sandbox 鎖定金鑰 `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`,以及其相關聯的白名單
685 * `allowAllClaudeAiMcps`
686 * sandbox 二進位路徑 `sandbox.bwrapPath` 和 `sandbox.socatPath`
687 * [`forceRemoteSettingsRefresh`](/docs/zh-TW/server-managed-settings)
688 * 嵌入主機(例如 Claude Desktop)可以透過 SDK `managedSettings` 選項提供政策。預設情況下,當任何 admin 部署的 managed 來源存在時,此會被忽略:伺服器管理的設定、MDM 或 OS 層級政策,或 managed 設定檔案。使用者可寫的 HKCU 登錄回退不計為 admin 部署的來源。管理員可以透過設定 [`parentSettingsBehavior`](#available-settings) 為 `"merge"` 來選擇加入。嵌入器的值會被篩選,以便它們可以收緊 managed 政策但不能放鬆政策。
689 628
6902. **命令列引數**629<h3 id="fix-a-broken-settings-file">
691 * 特定工作階段的臨時覆蓋。JSON 透過 `--settings <file-or-json>` 傳遞會與檔案型設定合併,使用與其他層級相同的規則:此處設定的金鑰會覆蓋本機、專案或使用者設定中的相同金鑰,省略金鑰會保留較低層級的值630 修復損壞的設定檔案
692 631</h3>
6933. **本機專案設定**(`.claude/settings.local.json`)
694 * 個人專案特定設定
695 632
6964. **共享專案設定**(`.claude/settings.json`)633如果您輸入錯誤的 JSON 或將金鑰設定為 Claude Code 不接受的值,Claude Code 在互動式工作階段啟動時會告訴您。它顯示的內容取決於檔案受影響的程度:
697 * 原始碼控制中的團隊共享專案設定
698 634
6995. **使用者設定**(`~/.claude/settings.json`)635* **設定錯誤**:使用者、專案或本機檔案有無效的 JSON 或架構拒絕的值。在互動式工作階段啟動時,Claude Code 顯示一個對話框,讓您用 Claude 的幫助修復檔案、退出或繼續而不使用損壞的設定。
700 * 個人全域設定636* **設定警告**:只有個別項目失敗,例如格式錯誤的權限規則或未知的 hook 事件名稱。Claude Code 跳過這些值並保持檔案的其餘部分生效。
637* **受管設定**:Claude Code 繼續強制執行檔案的其餘部分。[受管設定中的無效項目](/docs/zh-TW/managed-settings#invalid-entries-in-managed-settings)說明它丟棄的內容以及哪些金鑰回退到更嚴格的值,直到您修復它們。對於不是有效 JSON 的受管設定文件,請參閱[受管設定文件無法解析](/docs/zh-TW/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 在寫入檔案前儲存。
701 639
702此階層確保組織政策始終被強制執行,同時仍允許團隊和個人自訂其體驗。無論您從 CLI、[VS Code 擴充功能](/docs/zh-TW/vs-code)或 [JetBrains IDE](/docs/zh-TW/jetbrains) 執行 Claude Code,相同的優先順序都適用。640繼續後,執行 `/status` 以查看受影響的檔案,執行 `claude doctor` 以查看每個錯誤的詳細資訊。
703 641
704例如,如果您的使用者設定將 `permissions.defaultMode` 設定為 `acceptEdits`,而專案的共享設定將其設定為 `default`,則專案值適用。下面的範例涵蓋陣列值設定(如權限規則)如何組合的方式。642`-p` 執行不顯示對話框。除非[受管設定文件無法解析](/docs/zh-TW/errors#managed-settings-document-could-not-be-parsed),Claude Code 跳過損壞的檔案或值並繼續其餘部分,因此在忽略設定的 `-p` 執行後,執行 `claude doctor` 以查看它丟棄的內容。
705 643
706<Note>644<span id="how-scopes-interact" />
707 **陣列設定跨範圍合併。** 當相同的陣列值設定(例如 `sandbox.filesystem.allowWrite` 或 `permissions.allow`)出現在多個範圍中時,陣列會**連接和去重**,而不是替換。這意味著較低優先順序的範圍可以新增項目而不覆蓋由較高優先順序範圍設定的項目,反之亦然。例如,如果 managed 設定將 `allowWrite` 設定為 `["/opt/company-tools"]`,使用者新增 `["~/.kube"]`,則最終設定中包含兩個路徑。
708 645
709 兩個陣列設定不以此方式合併:646<span id="key-points-about-the-configuration-system" />
710 647
711 * [`fallbackModel`](#available-settings) 是一個有序鏈,其中位置具有意義:定義它的最高優先順序檔案提供整個值。648<span id="which-value-claude-code-uses" />
712 * [`availableModels`](#available-settings):當[最高優先順序 managed 來源](/docs/zh-TW/server-managed-settings#settings-precedence)定義它時,該清單按原樣應用,使用者、專案和本機項目無法擴展它。跨非 managed 範圍,陣列會照常合併。請參閱[合併行為](/docs/zh-TW/model-config#merge-behavior)。
713</Note>
714 649
715<h3 id="verify-active-settings">650<span id="which-value-wins" />
716 驗證使用中的設定
717</h3>
718 651
719在 Claude Code 內執行 `/status` 以查看哪些設定來源是使用中的。在功能表內,**Status** 標籤包含 `Setting sources` 行,列出 Claude Code 為目前工作階段載入的每一層,例如 `User settings` 或 `Project local settings`。當[managed 設定](/docs/zh-TW/admin-setup#decide-how-settings-reach-devices)生效時,項目會在括號中顯示傳遞頻道,例如 `Enterprise managed settings (remote)`、`(plist)`、`(HKLM)`、`(HKCU)` 或 `(file)`。`remote` 頻道涵蓋 claude.ai 伺服器管理的設定和 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway)傳遞的政策。層級僅在該來源以至少一個金鑰載入時才出現在清單中,因此空清單表示未找到任何設定來源。652<h2 id="settings-precedence">
653 設定優先順序
654</h2>
720 655
721`Setting sources` 行確認正在讀取哪些來源。它不顯示哪一層提供了每個個別金鑰。同一對話框中的 **Config** 標籤是固定切換集(例如主題和詳細輸出)的編輯器,而不是您 `settings.json` 內容的檢視。656當相同金鑰出現在多個位置時,Claude Code 使用設定它的最高層級的值。下面的堆疊顯示層級,最高在頂部;較高層級的金鑰覆蓋它在下面任何地方的相同金鑰。
722 657
723如果設定檔案包含錯誤(例如無效的 JSON 或驗證失敗的值),`/status` 會列出受影響的檔案。執行 `/doctor` 以查看每個錯誤的詳細資訊。658<SettingsPrecedence />
724 659
725<h3 id="key-points-about-the-configuration-system">660按順序,最高優先順序優先:
726 設定系統的關鍵要點
727</h3>
728 661
729* **記憶檔案(`CLAUDE.md`)**:包含 Claude 在啟動時載入的指示和內容6621. **受管設定**:您的組織部署的設定,通過 `managed-settings.json` 檔案、MDM 政策或來自 claude.ai 主控台的[伺服器管理設定](/docs/zh-TW/server-managed-settings)。沒有什麼您設定會覆蓋它們:您用 `--settings` 傳遞的金鑰不覆蓋相同的受管金鑰,而 `--model` 之類的旗標只從您的組織允許的模型中選擇。受管 `model` 設定每個工作階段啟動時的模型,您仍然可以用 `/model` 切換;鎖定是 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels),它限制 `/model`、`--model` 和您自己檔案中的 `model` 金鑰。當您的組織傳遞多個受管來源時,[受管層級內的優先順序](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)的規則說明 Claude Code 從每個讀取什麼。
730* **設定檔案(JSON)**:設定權限、環境變數和工具行為6632. **命令列引數**:您在終端機啟動 `claude` 時傳遞的旗標,用於一個工作階段;請參閱[為一個工作階段變更設定](#change-a-setting-for-one-session)。Claude Code 使用與其他層級相同的規則合併您用 `--settings <file-or-json>` 傳遞的 JSON:它在此處設定的金鑰優先於本機、專案或使用者設定中的相同金鑰,並為您省略的金鑰保留較低層級的值。
731* **Skills**:可以使用 `/skill-name` 叫用或由 Claude 自動載入的自訂提示6643. **專案本機設定**(`.claude/settings.local.json`):此專案的您的個人設定。
732* **MCP servers**:使用其他工具和整合擴展 Claude Code6654. **共享專案設定**(`.claude/settings.json`):您的團隊簽入原始碼控制的設定。
733* **優先順序**:較高層級的設定(Managed)覆蓋較低層級的設定(User/Project)6665. **使用者設定**(`~/.claude/settings.json`):每個專案的您的個人設定。
734* **繼承**:設定會合併跨範圍;較高優先順序範圍中的純量值覆蓋,陣列連接,有兩個例外如[陣列合併注意](#settings-precedence)中所述
735 667
736<h3 id="system-prompt">668環境變數不是此堆疊中的層級。當行為同時具有 shell 變數和設定金鑰時,哪一個適用是按對決定的,而不是按層級:在您的 shell 中匯出的 `ANTHROPIC_MODEL` 適用於任何檔案中的 `model` 金鑰,而 `ANTHROPIC_DEFAULT_MODEL` 僅在沒有檔案設定 `model` 時適用。[環境變數參考](/docs/zh-TW/env-vars#precedence)說明哪些金鑰有對以及 Claude Code 首先讀取哪一個。設定檔案內的 `env` 區塊是普通金鑰並遵循上面的層級。
737 系統提示
738</h3>
739 669
740Claude Code 的內部系統提示未發佈。若要新增自訂指示,請使用 `CLAUDE.md` 檔案或 `--append-system-prompt` 旗標。670對於少數安全敏感金鑰,Claude Code 尊重來自較低層級的更嚴格值優先於受管值;[受管設定優先順序的例外](#exceptions-to-managed-settings-precedence)列出它們。
741 671
742<h3 id="exclude-sensitive-files">672<h3 id="lists-merge-instead-of-overriding">
743 排除敏感檔案673 列表改為合併而不是覆蓋
744</h3>674</h3>
745 675
746若要防止 Claude Code 存取包含敏感資訊(如 API 金鑰、機密和環境檔案)的檔案,請在您的 `.claude/settings.json` 檔案中使用 `permissions.deny` 設定:676當您在多個檔案中設定相同的列表金鑰(例如 `permissions.allow`)時,Claude Code 合併列表而不是選擇一個,因此每個檔案可以新增項目而不移除另一個檔案的。四個保存模型列表或每個模型項目的金鑰遵循自己的規則:
747
748```json theme={null}
749{
750 "permissions": {
751 "deny": [
752 "Read(./.env)",
753 "Read(./.env.*)",
754 "Read(./secrets/**)",
755 "Read(./config/credentials.json)",
756 "Read(./build)"
757 ]
758 }
759}
760```
761
762這取代了已棄用的 `ignorePatterns` 設定。符合這些模式的檔案會從檔案發現和搜尋結果中排除,並拒絕對這些檔案的讀取操作。
763
764<h2 id="subagent-configuration">
765 Subagent 設定
766</h2>
767
768Claude Code 支援可在使用者和專案層級設定的自訂 AI subagents。這些 subagents 儲存為具有 YAML frontmatter 的 Markdown 檔案:
769 677
770* **使用者 subagents**:`~/.claude/agents/`,在所有專案中可用678* [`fallbackModel`](/docs/zh-TW/settings-reference#fallbackmodel) 是一個有序鏈,其中位置具有意義,因此 Claude Code 從定義它的最高優先順序檔案取整個值。
771* **專案 subagents**:`.claude/agents/`,特定於您的專案,可與您的團隊共享679* [`modelPicker`](/docs/zh-TW/settings-reference#modelpicker) 保存一個有序行列表加上替換旗標,因此 Claude Code 永遠不會合併來自兩個來源的行。它從定義它的受管設定、`--settings` 和使用者設定的最高取整個值,並忽略專案和本機設定中的金鑰。需要 Claude Code v2.1.242 或更新版本。
680* [`availableModels`](/docs/zh-TW/settings-reference#availablemodels):當 Claude Code 應用的受管設定定義它時,Claude Code 按原樣應用該列表並忽略您在使用者、專案或本機設定中新增的項目,除非嵌入 Claude Code 的應用程式提供自己的模型列表;請參閱[受管設定優先順序的例外](#exceptions-to-managed-settings-precedence)。跨受管來源列表也永遠不會合併;[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)說明哪個來源的列表適用。跨非受管範圍 Claude Code 照常合併陣列。
681* [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings):Claude Code 一次解析它一個模型,連同 [`effortLevel`](/docs/zh-TW/settings-reference#effortlevel)。`modelSettings` 項目說明哪個檔案的值適用於模型。
772 682
773Subagent 檔案定義具有自訂提示和工具權限的專門 AI 助手。在 [subagents 文件](/docs/zh-TW/sub-agents)中深入了解建立和使用 subagents。683<span id="examples" />
774 684
775<h2 id="plugin-configuration">685<h3 id="precedence-examples">
776 Plugin 配置686 優先順序範例
777</h2>
778
779Claude Code 支援 plugin 系統,可讓您使用 skills、agents、hooks 和 MCP servers 擴展功能。Plugins 透過 marketplaces 分發,可以在使用者和儲存庫層級設定。
780
781<h3 id="plugin-settings">
782 Plugin 設定
783</h3>687</h3>
784 688
785`settings.json` 中的 plugin 相關設定:689當 Claude 工作時,Claude Code 在微調器下顯示單行提示,例如「使用 /config 變更您的預設權限模式(包括 Plan Mode)」。假設您想要這些提示關閉,因此您在 `~/.claude/settings.json` 中將 [`spinnerTipsEnabled`](/docs/zh-TW/settings-reference#spinnertipsenabled) 設定為 `false`。下面的每個情景都是可以將它們打開的東西,以及您可以做什麼。
786
787```json theme={null}
788{
789 "enabledPlugins": {
790 "formatter@acme-tools": true,
791 "deployer@acme-tools": true,
792 "analyzer@security-plugins": false
793 },
794 "extraKnownMarketplaces": {
795 "acme-tools": {
796 "source": {
797 "source": "github",
798 "repo": "acme-corp/claude-plugins"
799 }
800 }
801 }
802}
803```
804 690
805<h4 id="enabledplugins">691<h4 id="team-settings-override-personal-settings">
806 `enabledPlugins`692 團隊設定覆蓋個人設定
807</h4>693</h4>
808 694
809控制啟用哪些 plugins。格式:`"plugin-name@marketplace-name": true/false`。沒有在任何範圍中有項目的 plugin 會回退到其 [`defaultEnabled`](/docs/zh-TW/plugins-reference#default-enablement) 值。695您的團隊的 `.claude/settings.json` 將其設定為 `true`。Claude Code 使用專案值,因為共享專案位於使用者上方,因此您在該專案中看到提示,而在其他地方看不到。
810 696
811**範圍**:697您可以取回您的值:在該專案中將 `"spinnerTipsEnabled": false` 新增到 `.claude/settings.local.json`。專案本機位於共享專案上方,因此您的工作階段停止顯示提示,您隊友的工作階段不變。
812 698
813* **使用者設定**(`~/.claude/settings.json`):個人 plugin 偏好設定699<h4 id="organization-settings-override-everything">
814* **專案設定**(`.claude/settings.json`):與團隊共享的專案特定 plugins700 組織設定覆蓋一切
815* **本機設定**(`.claude/settings.local.json`):每台機器的覆蓋,Claude Code 建立時會被 gitignored
816* **Managed 設定**(`managed-settings.json`):組織範圍的政策覆蓋,在所有範圍阻止安裝並從 marketplace 隱藏 plugin
817
818<Note>
819 專案設定優先於使用者設定,因此在 `~/.claude/settings.json` 中將 plugin 設定為 `false` 不會停用專案的 `.claude/settings.json` 啟用的 plugin。若要在您的機器上選擇退出專案啟用的 plugin,請改在 `.claude/settings.local.json` 中將其設定為 `false`。
820
821 由 managed 設定強制啟用的 plugins 無法以此方式停用,因為 managed 設定會覆蓋本機設定。
822
823 自 Claude Code v2.1.195 起,在專案的 `.claude/settings.json` 中啟用來自外部來源(例如 GitHub 儲存庫或 npm 套件)的 plugin 不會為其他人安裝它。每個載入 plugins 的路徑都會要求每個使用者在執行前[安裝並信任 plugin](/docs/zh-TW/discover-plugins#configure-team-marketplaces)。
824</Note>
825
826**範例**:
827
828```json theme={null}
829{
830 "enabledPlugins": {
831 "code-formatter@team-tools": true,
832 "deployment-tools@team-tools": true,
833 "experimental-features@personal": false
834 }
835}
836```
837
838<h4 id="pluginconfigs">
839 `pluginConfigs`
840</h4>701</h4>
841 702
842儲存 plugin 的 [`userConfig`](/docs/zh-TW/plugins-reference#user-configuration) 提示收集的非敏感選項值,按 plugin ID 鍵入。Claude Code 在您填入 plugin 的設定對話框時會將此鍵寫入使用者設定,因此您無需手動編輯它。敏感選項改為儲存在 macOS Keychain 中,或在沒有支援 keychain 的平台上儲存在 `~/.claude/.credentials.json` 中。703您的組織的受管設定將其設定為 `true`。您在使用者、專案或本機設定中放入的任何內容都不會關閉提示,`--settings` 也不會。受管是最高層級。
843
844此範例儲存從 `acme-tools` marketplace 安裝的 plugin 的一個選項:
845
846```json theme={null}
847{
848 "pluginConfigs": {
849 "deployer@acme-tools": {
850 "options": {
851 "api_endpoint": "https://api.example.com"
852 }
853 }
854 }
855}
856```
857 704
858`pluginConfigs` 僅從使用者設定、`--settings` 旗標和 managed 設定讀取。專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目會被忽略,因為這些值會被替換到 plugin hook、MCP 和 LSP 配置中,而複製的儲存庫不得能夠提供它們。在 v2.1.207 之前,專案和本機設定也會被讀取。705您無法取回您的值。執行 `/status` 以查看哪個受管來源適用,並詢問您的管理員政策是否應該變更。
859 706
860<h4 id="extraknownmarketplaces">707<h4 id="the-command-line-overrides-your-files-for-one-session">
861 `extraKnownMarketplaces`708 命令列覆蓋您的檔案用於一個工作階段
862</h4>709</h4>
863 710
864定義應為儲存庫提供的其他 marketplaces。通常在儲存庫層級設定中使用,以確保團隊成員有權存取所需的 plugin 來源。711您使用 `claude --settings '{"spinnerTipsEnabled": true}'` 啟動了工作階段。命令列位於除受管外的每個檔案上方,因此該工作階段顯示提示,即使您的檔案說 `false`。
865 712
866**當儲存庫包含 `extraKnownMarketplaces` 時**:713您在下一個工作階段上取回您的值;`--settings` 持續一個工作階段並不寫入任何檔案。
867 714
8681. 當團隊成員信任資料夾時,系統會提示他們安裝 marketplace715<h4 id="a-flag-or-environment-variable-sets-the-same-thing">
8692. 然後提示團隊成員從該 marketplace 安裝 plugins716 旗標或環境變數設定相同的東西
8703. 使用者可以跳過不需要的 marketplaces 或 plugins(儲存在使用者設定中)
8714. 安裝尊重信任邊界並需要明確同意
872
873**範例**:
874
875```json theme={null}
876{
877 "extraKnownMarketplaces": {
878 "acme-tools": {
879 "source": {
880 "source": "github",
881 "repo": "acme-corp/claude-plugins"
882 }
883 },
884 "security-plugins": {
885 "source": {
886 "source": "git",
887 "url": "https://git.example.com/security/plugins.git"
888 }
889 }
890 }
891}
892```
893
894**Marketplace 來源類型**:
895
896* `github`:GitHub 儲存庫(使用 `repo`)
897* `git`:任何 git URL(使用 `url`)
898* `directory`:本機檔案系統路徑(使用 `path`,僅用於開發)
899* `hostPattern`:正規表達式模式以符合 marketplace 主機(使用 `hostPattern`)
900* `settings`:直接在 settings.json 中宣告的內嵌 marketplace,無需單獨的託管儲存庫(使用 `name` 和 `plugins`)
901
902`git` 來源類型適用於任何 git 託管服務,包括自託管 GitLab 和 Bitbucket。Claude Code 使用與該機器上 `git clone` 相同的驗證來複製儲存庫:已設定的認證助手或 SSH 金鑰。提供者 token(例如 `GITHUB_TOKEN`)只有透過讀取它的認證助手才會生效。請參閱[私有儲存庫](/docs/zh-TW/plugin-marketplaces#private-repositories)以了解設定詳細資訊。
903
904對於 `github` 和 `git` 來源,在 `source` 物件內設定 `"skipLfs": true`(與 `repo` 或 `url` 並列)以在 Claude Code 複製或更新 marketplace 儲存庫時跳過 Git LFS 下載。LFS 指標檔案保持為指標而不是下載其內容。當儲存庫包含與 plugin 內容無關的大型 LFS 物件時,請使用此選項。需要 Claude Code v2.1.153 或更新版本。
905
906每個 marketplace 項目也接受選用的 `autoUpdate` 布林值。在 `source` 旁邊設定 `"autoUpdate": true`,使 Claude Code 在啟動時重新整理該 marketplace 並更新其已安裝的 plugins。省略時,官方 Anthropic marketplaces 預設為 `true`,所有其他 marketplaces 預設為 `false`。請參閱[設定自動更新](/docs/zh-TW/discover-plugins#configure-auto-updates)。
907
908使用 `source: 'settings'` 宣告一小組 plugins,無需設定託管 marketplace 儲存庫。此處列出的 Plugins 必須參考外部來源,例如 GitHub 或 npm。您仍需要在 `enabledPlugins` 中分別啟用每個 plugin。
909
910```json theme={null}
911{
912 "extraKnownMarketplaces": {
913 "team-tools": {
914 "source": {
915 "source": "settings",
916 "name": "team-tools",
917 "plugins": [
918 {
919 "name": "code-formatter",
920 "source": {
921 "source": "github",
922 "repo": "acme-corp/code-formatter"
923 }
924 }
925 ]
926 }
927 }
928 }
929}
930```
931
932<h4 id="strictknownmarketplaces">
933 `strictKnownMarketplaces`
934</h4>717</h4>
935 718
936**Managed 設定僅限**:控制使用者可以新增和安裝 plugins 的 plugin marketplaces。此設定只能在 [managed 設定](/docs/zh-TW/settings#settings-files)中設定,並為管理員提供對 marketplace 來源的嚴格控制。719某些金鑰有命令列旗標或環境變數,無論哪個檔案設定它,都覆蓋設定值:`ANTHROPIC_MODEL` 覆蓋 [`model`](/docs/zh-TW/settings-reference#model) 設定,而 `--model` 為工作階段覆蓋兩者。
937
938**Managed 設定檔案位置**:
939
940* **macOS**:`/Library/Application Support/ClaudeCode/managed-settings.json`
941* **Linux 和 WSL**:`/etc/claude-code/managed-settings.json`
942* **Windows**:`C:\Program Files\ClaudeCode\managed-settings.json`
943
944**關鍵特性**:
945 720
946* 僅在 managed 設定(`managed-settings.json`)中可用721您是否可以取回您的值取決於金鑰:取消設定變數或刪除旗標,並檢查[設定參考](/docs/zh-TW/settings-reference)上的金鑰項目和[環境變數參考](/docs/zh-TW/env-vars)上的變數行,以了解 Claude Code 使用哪一個。
947* 無法被使用者或專案設定覆蓋(最高優先順序)
948* 在網路/檔案系統操作之前強制執行(被阻止的來源永遠不會執行)
949* 對來源規格使用精確匹配(包括 git 來源的 `ref`、`path`),除了 `hostPattern` 和 `pathPattern`,它們使用正規表達式匹配
950 722
951**白名單行為**:723<span id="keys-ignored-in-a-repository-file" />
952 724
953* `undefined`(預設):無限制 - 使用者可以新增任何 marketplace725<span id="keys-only-you-or-your-organization-can-set" />
954* 空陣列 `[]`:完全鎖定 - 使用者無法新增任何新 marketplaces
955* 來源清單:使用者只能新增完全符合的 marketplaces
956
957**所有支援的來源類型**:
958
959白名單支援多種 marketplace 來源類型。大多數來源使用精確匹配,而 `hostPattern` 和 `pathPattern` 分別使用正規表達式匹配 marketplace 主機和檔案系統路徑。
960
9611. **GitHub 儲存庫**:
962
963```json theme={null}
964{ "source": "github", "repo": "acme-corp/approved-plugins" }
965{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
966{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }
967```
968
969欄位:`repo`(必需)、`ref`(選用:分支或標籤)、`path`(選用:子目錄)
970
9712. **Git 儲存庫**:
972
973```json theme={null}
974{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
975{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
976{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }
977```
978
979欄位:`url`(必需)、`ref`(選用:分支或標籤)、`path`(選用:子目錄)
980
9813. **基於 URL 的 marketplaces**:
982
983```json theme={null}
984{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
985{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }
986```
987
988欄位:`url`(必需)、`headers`(選用:用於驗證存取的 HTTP 標頭)
989
990<Note>
991 基於 URL 的 marketplaces 僅下載 `marketplace.json` 檔案。它們不從伺服器下載 plugin 檔案。基於 URL 的 marketplaces 中的 Plugins 必須使用外部來源(GitHub、npm 或 git URL),而不是相對路徑。對於具有相對路徑的 plugins,請改用基於 Git 的 marketplace。請參閱[疑難排解](/docs/zh-TW/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)以了解詳細資訊。
992</Note>
993
9944. **NPM 套件**:
995
996```json theme={null}
997{ "source": "npm", "package": "@acme-corp/claude-plugins" }
998{ "source": "npm", "package": "@acme-corp/approved-marketplace" }
999```
1000 726
1001欄位:`package`(必需,支援範圍套件)727<span id="common-cases" />
1002 728
10035. **檔案路徑**:729<span id="which-value-applies-in-common-situations" />
1004 730
1005```json theme={null}731<h3 id="troubleshoot-a-setting-that-doesn’t-apply">
1006{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }732 疑難排解不適用的設定
1007{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }733</h3>
1008```
1009
1010欄位:`path`(必需:marketplace.json 檔案的絕對路徑)
1011
10126. **目錄路徑**:
1013
1014```json theme={null}
1015{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
1016{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }
1017```
1018
1019欄位:`path`(必需:包含 `.claude-plugin/marketplace.json` 的目錄的絕對路徑)
1020
10217. **主機模式匹配**:
1022
1023```json theme={null}
1024{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
1025{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }
1026```
1027
1028欄位:`hostPattern`(必需:用於符合 marketplace 主機的正規表達式模式)
1029
1030當您想允許來自特定主機的所有 marketplaces 而不列舉每個儲存庫時,請使用主機模式匹配。這對於具有內部 GitHub Enterprise 或 GitLab 伺服器的組織很有用,開發人員可以在其中建立自己的 marketplaces。
1031
1032按來源類型的主機提取:
1033
1034* `github`:始終符合 `github.com`
1035* `git`:從 URL 提取主機名稱(支援 HTTPS 和 SSH 格式)
1036* `url`:從 URL 提取主機名稱
1037* `npm`、`file`、`directory`:不支援主機模式匹配
1038
10398. **路徑模式匹配**:
1040
1041```json theme={null}
1042{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
1043{ "source": "pathPattern", "pathPattern": ".*" }
1044```
1045
1046欄位:`pathPattern`(必需:與 `file` 和 `directory` 來源的 `path` 欄位相符的正規表達式模式)
1047
1048使用路徑模式匹配來允許檔案系統型 marketplaces 與網路來源的 `hostPattern` 限制並行。設定 `".*"` 以允許所有本機路徑,或設定更窄的模式以限制到特定目錄。
1049
1050**設定範例**:
1051
1052範例:僅允許特定 marketplaces:
1053
1054```json theme={null}
1055{
1056 "strictKnownMarketplaces": [
1057 {
1058 "source": "github",
1059 "repo": "acme-corp/approved-plugins"
1060 },
1061 {
1062 "source": "github",
1063 "repo": "acme-corp/security-tools",
1064 "ref": "v2.0"
1065 },
1066 {
1067 "source": "url",
1068 "url": "https://plugins.example.com/marketplace.json"
1069 },
1070 {
1071 "source": "npm",
1072 "package": "@acme-corp/compliance-plugins"
1073 }
1074 ]
1075}
1076```
1077
1078範例:停用所有 marketplace 新增:
1079
1080```json theme={null}
1081{
1082 "strictKnownMarketplaces": []
1083}
1084```
1085
1086範例:允許來自內部 git 伺服器的所有 marketplaces:
1087
1088```json theme={null}
1089{
1090 "strictKnownMarketplaces": [
1091 {
1092 "source": "hostPattern",
1093 "hostPattern": "^github\\.example\\.com$"
1094 }
1095 ]
1096}
1097```
1098
1099**精確匹配要求**:
1100
1101Marketplace 來源必須完全符合才能允許使用者的新增。對於基於 git 的來源(`github` 和 `git`),這包括所有選用欄位:
1102
1103* `repo` 或 `url` 必須完全符合
1104* `ref` 欄位必須完全符合(或兩者都未定義)
1105* `path` 欄位必須完全符合(或兩者都未定義)
1106
1107**不符合**的來源範例:
1108
1109```json theme={null}
1110// 這些是不同的來源:
1111{ "source": "github", "repo": "acme-corp/plugins" }
1112{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }
1113
1114// 這些也不同:
1115{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
1116{ "source": "github", "repo": "acme-corp/plugins" }
1117```
1118
1119**與 `extraKnownMarketplaces` 的比較**:
1120
1121| 方面 | `strictKnownMarketplaces` | `extraKnownMarketplaces` |
1122| ---------- | ------------------------- | ------------------------ |
1123| **目的** | 組織政策強制執行 | 團隊便利 |
1124| **設定檔案** | 僅 `managed-settings.json` | 任何設定檔案 |
1125| **行為** | 阻止非白名單新增 | 自動安裝遺失的 marketplaces |
1126| **何時強制執行** | 在網路/檔案系統操作之前 | 在使用者信任提示之後 |
1127| **可以被覆蓋** | 否(最高優先順序) | 是(由較高優先順序設定) |
1128| **來源格式** | 直接來源物件 | 具有巢狀來源的命名 marketplace |
1129| **使用案例** | 合規、安全限制 | 上線、標準化 |
1130
1131**格式差異**:
1132
1133`strictKnownMarketplaces` 使用直接來源物件:
1134
1135```json theme={null}
1136{
1137 "strictKnownMarketplaces": [
1138 { "source": "github", "repo": "acme-corp/plugins" }
1139 ]
1140}
1141```
1142 734
1143`extraKnownMarketplaces` 需要命名 marketplaces:735當您設定金鑰而 Claude Code 不表現得好像您有時,請從 `/status` 開始以查看它載入了哪些檔案,然後在下面找到您的症狀。[除錯您的設定](/docs/zh-TW/debug-your-config)涵蓋更廣泛的檢查,包括乾淨設定測試。
1144 736
1145```json theme={null}737<h4 id="a-value-you-set-is-ignored">
1146{738 您設定的值被忽略
1147 "extraKnownMarketplaces": {739</h4>
1148 "acme-tools": {
1149 "source": { "source": "github", "repo": "acme-corp/plugins" }
1150 }
1151 }
1152}
1153```
1154 740
1155**同時使用兩者**:741其他東西設定相同金鑰、檔案無法設定該值,或檔案未載入:
1156 742
1157`strictKnownMarketplaces` 是政策閘門:它控制使用者可能新增的內容,但不註冊任何 marketplaces。若要同時限制和為所有使用者預先註冊 marketplace,請在 `managed-settings.json` 中設定兩者:743* **較高層級設定它。** 另一個設定檔案、`--settings` 旗標或受管來源在您的上方設定金鑰;[堆疊](#settings-precedence)說明哪一個。旗標或環境變數也可以按自己的方式覆蓋金鑰,按金鑰決定;[設定參考](/docs/zh-TW/settings-reference)上的金鑰項目說明 Claude Code 使用哪一個,而 [`env` 項目](/docs/zh-TW/settings-reference#env)涵蓋受管 `env` 值與 shell 匯出。
744* **安全金鑰保持其嚴格值。** 對於少數金鑰,Claude Code 尊重來自任何檔案的限制值,因此專案 `true` 用於 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) 保持開啟;請參閱[受管設定優先順序的例外](#exceptions-to-managed-settings-precedence)。
745* **檔案無法設定該值。** [`permissions.defaultMode`](/docs/zh-TW/settings-reference#permissions-defaultmode) 值 `auto` 和 `bypassPermissions` 不從專案或本機設定生效;改為在使用者或受管設定中設定它們,或為一個工作階段傳遞 `--permission-mode`。在 v2.1.257 之前,`bypassPermissions` 從任何檔案生效。
746* **檔案損壞。** 無效的 JSON 或拒絕的值使 Claude Code 跳過檔案或項目;請參閱[修復損壞的設定檔案](#fix-a-broken-settings-file)。
1158 747
1159```json theme={null}748<h4 id="a-change-you-made-in-claude-code-is-lost-in-new-sessions">
1160{749 您在 Claude Code 中所做的變更在新工作階段中丟失
1161 "strictKnownMarketplaces": [750</h4>
1162 { "source": "github", "repo": "acme-corp/plugins" }
1163 ],
1164 "extraKnownMarketplaces": {
1165 "acme-tools": {
1166 "source": { "source": "github", "repo": "acme-corp/plugins" }
1167 }
1168 }
1169}
1170```
1171 751
1172僅設定 `strictKnownMarketplaces` 時,使用者仍可透過 `/plugin marketplace add` 手動新增允許的 marketplace,但它不會自動提供。752當您從 Claude Code 內儲存新工作階段的選擇時,例如使用 `/model` 的預設模型,Claude Code 將其寫入您的使用者設定檔案 `~/.claude/settings.json`。如果您無法寫入該檔案,例如因為另一個工具產生它或將其連結到唯讀副本,變更適用於目前工作階段並在下一個工作階段中消失。在產生檔案的工具中設定金鑰,或用您可以寫入的檔案替換檔案。
1173 753
1174**重要注意事項**:754如果您可以寫入檔案而變更仍然不持續,請檢查變更是否[僅用於一個工作階段](#change-a-setting-for-one-session)或[較高層級設定相同金鑰](#a-value-you-set-is-ignored)。對於 `model` 金鑰,[新工作階段在不同的模型上啟動而不是您選擇的](/docs/zh-TW/model-config#a-new-session-starts-on-a-different-model-than-you-picked)列出更多原因。
1175 755
1176* 限制在任何網路請求或檔案系統操作之前檢查756<h4 id="a-managed-change-hasn’t-reached-you">
1177* 被阻止時,使用者會看到清晰的錯誤訊息,指示來源被 managed 政策阻止757 受管變更還沒有到達您
1178* 限制在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行。在設定政策之前新增的 marketplace 一旦其來源不再符合白名單,就無法用於安裝或更新 plugins758</h4>
1179* Managed 設定具有最高優先順序,無法被覆蓋
1180 759
1181請參閱 [Managed marketplace 限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)以了解面向使用者的文件。760受管來源按[傳遞表](/docs/zh-TW/managed-settings#choose-a-delivery-mechanism)中的排程到達執行中的工作階段,因此首先重新啟動工作階段。如果 `/status` 然後命名不同的來源而不是您的管理員變更的,較高優先順序的來源適用;[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)給出順序。
1182 761
1183<h4 id="strictpluginonlycustomization">762<h4 id="a-committed-key-doesn’t-reach-teammates">
1184 `strictPluginOnlyCustomization`763 提交的金鑰不到達隊友
1185</h4>764</h4>
1186 765
1187**Managed 設定僅限**:阻止 skills、agents、hooks 和 MCP servers 來自使用者和專案來源,因此它們只能來自 plugins 或 managed 設定。將其與 `strictKnownMarketplaces` 結合以控制完整的自訂供應鏈:marketplace 白名單控制使用者可以安裝哪些 plugins,此設定阻止所有不來自 plugin 或 managed 設定的內容。766兩件事使 `.claude/settings.json` 中的金鑰無法為複製它的每個人應用:
1188
1189該值要麼是 `true` 以鎖定所有四個表面,要麼是命名要鎖定的表面的陣列:
1190 767
1191```json theme={null}768* **Claude Code 忽略儲存庫檔案中的金鑰。** 在[設定索引](/docs/zh-TW/settings-reference#settings-index)的「範圍」欄中查找 `User, local, or managed`、`User or managed`、`Managed` 或 `Global config`;這些金鑰永遠不會從共享檔案應用,除了 [`autoContinueAtUsageLimit`](/docs/zh-TW/settings-reference#autocontinueatusagelimit),儲存庫檔案仍然可以關閉:當檔案設定金鑰而沒有使用者、`--settings` 或受管值時,Claude Code 讀取設定為關閉。`Global config` 金鑰僅從 `~/.claude.json` 應用。
1192{769* **金鑰等待信任。** `permissions.allow` 規則、`permissions.additionalDirectories`、`extraKnownMarketplaces` 和大多數 [`env`](/docs/zh-TW/settings-reference#env) 值僅在每個隊友[信任資料夾](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)後應用。在那之前,他們仍然看到提示並不從檔案宣告的 marketplace 獲得 plugins。`deny` 和 `ask` 規則立即應用。
1193 "strictPluginOnlyCustomization": ["skills", "hooks"]
1194}
1195```
1196 770
1197對於每個鎖定的表面,Claude Code 會跳過使用者層級和專案層級的來源,並僅載入 plugin 提供的和 managed 來源:771<h4 id="permission-rules-combine-differently-than-you-expected">
772 權限規則組合方式與您預期不同
773</h4>
1198 774
1199| 表面 | 鎖定時被阻止 | 仍然載入 |775* **您在權限提示上選擇「是,不要再問」但仍然為相同工具獲得提示。** 該選擇將 `allow` 規則儲存到您的本機檔案,本機的 `allow` 規則不優先於專案或受管檔案的 `ask` 規則;[權限規則如何組合](/docs/zh-TW/permissions#settings-precedence)解釋順序。在 VS Code 擴充功能中,批准卡讓您選擇目標檔案,包括專案的共享檔案,這為每個人變更規則;在 CLI 中,Claude Code 僅寫入您的本機檔案。
1200| :------- | :---------------------------------------- | :------------------------------------------------------------------ |776* **您的組織的 allow 規則仍然與您的一起應用。** 這是預期的:Claude Code 跨範圍合併 [`permissions.allow`](/docs/zh-TW/settings-reference#permissions-allow),除非您的組織設定 [`allowManagedPermissionRulesOnly`](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly)。
1201| `skills` | `~/.claude/skills/`、`.claude/skills/` | Plugin skills、bundled skills、managed 政策目錄中的 skills |
1202| `agents` | `~/.claude/agents/`、`.claude/agents/` | Plugin agents、內建 agents、managed 政策目錄中的 agents |
1203| `hooks` | 使用者、專案和本機 `settings.json` 中的 Hooks | Plugin hooks、managed 設定中的 hooks |
1204| `mcp` | `~/.claude.json` 和 `.mcp.json` 中的 Servers | Plugin MCP servers、[`managed-mcp.json`](/docs/zh-TW/managed-mcp) servers |
1205 777
1206Claude Code 版本不識別的表面名稱會被忽略而不是導致設定檔案失敗,因此您可以在所有用戶端更新之前新增新的表面名稱。778<span id="security-keys-where-the-stricter-value-applies" />
1207 779
1208<h3 id="manage-plugins">780<h3 id="exceptions-to-managed-settings-precedence">
1209 管理 plugins781 受管設定優先順序的例外
1210</h3>782</h3>
1211 783
1212使用 `/plugin` 命令以互動方式管理 plugins:784對於少數值限制工作階段的金鑰,Claude Code 尊重來自否則無法覆蓋受管設定的範圍的限制值。在此表中找到金鑰以查看它尊重哪個值以及從哪裡。
1213 785
1214* 瀏覽 marketplaces 中的可用 plugins786| 金鑰 | Claude Code 尊重的值 | 注意 |
1215* 安裝/解除安裝 plugins787| :--------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
1216* 啟用/停用 plugins788| [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) | 來自任何範圍的 `true` | 即使受管來源設定 `false` 也被尊重 |
1217* 檢視 plugin 詳細資訊(提供的 skills、agents、hooks)789| [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) | 來自任何範圍的 `false`,以及來自任何範圍的 `disableArtifact: true` | 即使受管來源設定 `true` 也被尊重;沒有什麼將 [Artifact 工具](/docs/zh-TW/artifacts#disable-artifacts)打開。需要 Claude Code v2.1.242 或更新版本 |
1218* 新增/移除 marketplaces790| [`isolatePeerMachines`](/docs/zh-TW/settings-reference#isolatepeermachines) | 來自任何範圍的 `true` | 即使受管來源設定 `false` 也被尊重 |
791| [`remoteControlAtStartup`](/docs/zh-TW/settings-reference#remotecontrolatstartup) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使受管來源設定 `true` 也被尊重;專案或本機 `true` 被忽略 |
792| [`crossSessionInbound`](/docs/zh-TW/settings-reference#crosssessioninbound) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的更嚴格值,在 `accept` \< `hold` \< `refuse` 梯形上 | 在受管、`--settings` 和使用者值上被尊重;不是更嚴格的專案或本機值被忽略 |
793| [`useAutoModeDuringPlan`](/docs/zh-TW/settings-reference#useautomodeduringplan) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重;`.claude/settings.json` 中的 `false` 被忽略 |
794| [`syncClaudeAiSkills`](/docs/zh-TW/settings-reference#syncclaudeaiskills) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重;`.claude/settings.json` 中的 `false` 被忽略 |
795| [`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) | 來自任何範圍的較低上限,包括 `--settings` | 即使 Claude Code 應用的受管設定設定較高上限也被尊重;最低上限適用。需要 Claude Code v2.1.267 或更新版本 |
1219 796
1220在 [plugins 文件](/docs/zh-TW/plugins)中深入了解 plugin 系統。797在自己內部執行 Claude Code 並設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars) 的應用程式也是例外。Claude Code 將該應用程式的模型設定優先於來自每個受管來源的 `model`、`fallbackModel` 和 `modelOverrides` 金鑰,以及受管 `env` 區塊中的模型選擇變數,例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列。Claude Code 保持受管 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單生效,除非應用程式提供自己的。
1221 798
1222<h2 id="environment-variables">799<h2 id="settings-in-cloud-sessions">
1223 環境變數800 雲端工作階段中的設定
1224</h2>801</h2>
1225 802
1226環境變數可讓您控制 Claude Code 行為,而無需編輯設定檔案。任何變數也可以在 [`settings.json`](#available-settings) 中的 `env` 金鑰下設定,以將其應用於每個工作階段或推出到您的團隊。803雲端工作階段,在 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 或來自 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-web),在[雲端環境](/docs/zh-TW/cloud-environments)中執行,在您儲存庫的新複製上,而不是在您的機器上。這改變了哪些設定到達它:
1227
1228請參閱[環境變數參考](/docs/zh-TW/env-vars)以了解完整清單。
1229
1230<h2 id="tools-available-to-claude">
1231 Claude 可用的工具
1232</h2>
1233 804
1234Claude Code 可以存取一組工具,用於讀取、編輯、搜尋、執行命令和協調 subagents。工具名稱是您在權限規則和 hook 匹配器中使用的確切字串。805* **共享專案設定**(`.claude/settings.json`):讀取,因為檔案是複製的一部分。在那裡提交設定以在雲端工作階段中應用它。
806* **使用者和專案本機設定**(`~/.claude/settings.json` 和 `.claude/settings.local.json`):未讀取。兩者都保留在您的機器上,本機檔案不在複製中。
807* **受管設定**:只有[伺服器管理設定](/docs/zh-TW/server-managed-settings)到達雲端工作階段;您裝置上的 `managed-settings.json` 檔案或 MDM 設定檔不會。[自託管環境](/docs/zh-TW/self-hosted-environments)也讀取其執行器映像中的受管設定檔案。[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)說明該檔案何時適用。
808* **`/config`**:在網路上,開啟您的 claude.ai 設定的 Claude Code 部分而不是變更值。若要為雲端工作階段變更設定,請在環境上設定[環境變數](/docs/zh-TW/cloud-environments#set-environment-variables)或將金鑰提交到儲存庫的 `.claude/settings.json`。
1235 809
1236請參閱[工具參考](/docs/zh-TW/tools-reference)以了解完整清單和 Bash 工具行為詳細資訊。810[從您的設定進行的內容](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)列出其餘部分:`CLAUDE.md`、skills、MCP 伺服器、plugins 和認證。
1237 811
1238<h2 id="see-also">812<h2 id="what’s-next">
1239 另請參閱813 下一步
1240</h2>814</h2>
1241 815
1242* [Permissions](/docs/zh-TW/permissions):權限系統、規則語法、工具特定模式和 managed 政策816* [所有設定](/docs/zh-TW/settings-reference):每個金鑰,及其設定位置和範例
1243* [Authentication](/docs/zh-TW/authentication):設定使用者對 Claude Code 的存取817* [範例設定檔案](/docs/zh-TW/settings-example):個人檔案、團隊檔案和組織的受管檔案
1244* [Debug your configuration](/docs/zh-TW/debug-your-config):診斷為什麼設定、hook 或 MCP server 未生效818* [設定權限](/docs/zh-TW/permissions):allow、ask 和 deny 規則,以及 Claude Code 在不詢問的情況下執行的內容
1245* [Troubleshoot installation and login](/docs/zh-TW/troubleshoot-install):安裝、authentication 和平台問題819* [環境變數](/docs/zh-TW/env-vars):Claude Code 讀取的變數和 `env` 區塊
820* [除錯您的設定](/docs/zh-TW/debug-your-config):當設定不適用時
821* [Claude 目錄參考](/docs/zh-TW/claude-directory):Claude Code 讀取的每個檔案,包括 subagents、MCP 伺服器、plugins 和 `CLAUDE.md`