2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.
4 4
5# Claude Code 설정5# 설정 파일 및 우선순위
6 6
7> 전역 및 프로젝트 수준 설정과 환경 변수로 Claude Code를 구성합니다.7> Claude Code 설정을 변경하고, 키가 속할 범위를 선택하고, 변경을 확인하고, 키가 여러 위치에 설정되어 있을 때 Claude Code가 사용하는 값을 알아봅니다.
8 8
9Claude Code는 사용자의 필요에 맞게 동작을 구성할 수 있는 다양한 설정을 제공합니다. `/config` 명령을 실행하여 Claude Code를 구성할 수 있으며, 이는 상태 정보를 보고 구성 옵션을 수정할 수 있는 탭 형식의 설정 인터페이스를 엽니다. v2.1.181부터는 인터페이스를 열지 않고 `/config`에 `key=value`를 전달하여 단일 옵션을 변경할 수 있습니다. 예를 들어 `/config verbose=true`입니다.9export const SettingsPrecedence = () => {
10 10 const LEVELS = [{
11<h2 id="configuration-scopes">11 n: 1,
12 구성 범위12 name: 'Managed settings',
13</h2>13 file: 'managed-settings.json, MDM, or the claude.ai console',
14 14 who: 'Your organization',
15Claude Code는 범위 시스템을 사용하여 구성이 어디에 적용되고 누가 공유하는지 결정합니다. 범위를 이해하면 개인 사용, 팀 협업 또는 엔터프라이즈 배포를 위해 Claude Code를 구성하는 방법을 결정하는 데 도움이 됩니다.15 w: 390
16 16 }, {
17<h3 id="available-scopes">17 n: 2,
18 사용 가능한 범위18 name: 'Command line',
19</h3>19 file: 'claude --settings',
20 20 who: 'You, this session',
21| 범위 | 위치 | 영향을 받는 대상 | 팀과 공유? |21 w: 420
22| :---------- | :-------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :--------------- |22 }, {
23| **Managed** | 서버 관리 설정, plist / 레지스트리 또는 시스템 수준 `managed-settings.json` | 서버 관리 전달을 위한 모든 조직 구성원; plist, HKLM 레지스트리 및 파일 전달을 위한 머신의 모든 사용자; HKCU 레지스트리 전달을 위한 현재 사용자 | 예 (IT에서 배포) |23 n: 3,
24| **User** | `~/.claude/` 디렉토리 | 모든 프로젝트에서 사용자 | 아니오 |24 name: 'Project local',
25| **Project** | 저장소의 `.claude/` | 이 저장소의 모든 협업자 | 예 (git에 커밋됨) |25 file: '.claude/settings.local.json',
26| **Local** | `.claude/settings.local.json` | 이 저장소에서만 사용자 | 아니오 (gitignored) |26 who: 'You, this project',
27 27 w: 480
28<h3 id="when-to-use-each-scope">28 }, {
29 각 범위를 사용할 때29 n: 4,
30</h3>30 name: 'Shared project',
31 31 file: '.claude/settings.json',
32**Managed 범위**는 다음을 위한 것입니다:32 who: 'Everyone in the project',
33 33 w: 540
34* 조직 전체에서 적용해야 하는 보안 정책34 }, {
35* 재정의할 수 없는 규정 준수 요구 사항35 n: 5,
36* IT/DevOps에서 배포한 표준화된 구성36 name: 'User',
37 37 file: '~/.claude/settings.json',
38**User 범위**는 다음에 가장 적합합니다:38 who: 'You, every project',
39 39 w: 600
40* 모든 곳에서 원하는 개인 설정 (테마, 편집기 설정)40 }];
41* 모든 프로젝트에서 사용하는 도구 및 플러그인41 const W = 760;
42* API 키 및 인증 (안전하게 저장됨)42 const ROW = 58;
43 43 const GAP = 8;
44**Project 범위**는 다음에 가장 적합합니다:44 const TOP = 34;
45 45 const H = TOP + LEVELS.length * (ROW + GAP) + 30;
46* 팀 공유 설정 (권한, hooks, MCP servers)46 const cx = W / 2;
47* 전체 팀이 가져야 할 플러그인47 const mono = 'var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace)';
48* 협업자 간 도구 표준화48 const sans = 'var(--font-sans, system-ui, -apple-system, sans-serif)';
49 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**Local 범위**는 다음에 가장 적합합니다:50 <style>{`
51 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* 특정 프로젝트에 대한 개인 재정의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* 팀과 공유하기 전에 구성 테스트53 .sp-root svg { width: 100%; height: auto; display: block; max-width: ${W}px; margin: 0 auto; }
54* 다른 사용자에게는 작동하지 않을 머신 특정 설정54 `}</style>
55 55 <svg viewBox={`0 0 ${W} ${H}`} xmlns="http://www.w3.org/2000/svg">
56<h3 id="how-scopes-interact">56 <text x={cx} y={18} textAnchor="middle" fontFamily={sans} fontSize="12.5" fontWeight="600" fill="var(--sp-sub)">Highest precedence</text>
57 범위가 상호 작용하는 방식57 {LEVELS.map((l, i) => {
58</h3>58 const y = TOP + i * (ROW + GAP);
59 59 const x = cx - l.w / 2;
60동일한 설정이 여러 범위에서 구성되면 Claude Code는 우선순위 순서대로 적용합니다:60 const top = i === 0;
61 61 return <g key={l.n}>
621. **Managed** (최고): 아무것도 재정의할 수 없음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} />
632. **명령줄 인수**: 임시 세션 재정의63 <text x={x + 14} y={y + 24} fontFamily={sans} fontSize="14" fontWeight="600" fill="var(--sp-text)">{l.n}. {l.name}</text>
643. **Local**: 프로젝트 및 사용자 설정 재정의64 <text x={x + 14} y={y + 43} fontFamily={mono} fontSize="11.5" fill="var(--sp-sub)">{l.file}</text>
654. **Project**: 사용자 설정 재정의65 <text x={x + l.w - 14} y={y + 24} textAnchor="end" fontFamily={sans} fontSize="12" fill="var(--sp-faint)">{l.who}</text>
665. **User** (최저): 다른 것이 설정을 지정하지 않을 때 적용66 </g>;
67 67 })}
68예를 들어, 사용자 설정에서 `spinnerTipsEnabled`를 `true`로 설정하고 프로젝트 설정에서 `false`로 설정하면 프로젝트 값이 적용됩니다. 권한 규칙은 재정의하지 않고 범위 전체에서 병합되기 때문에 다르게 작동합니다. [설정 우선순위](#settings-precedence)를 참조하십시오.68 <text x={cx} y={H - 10} textAnchor="middle" fontFamily={sans} fontSize="12.5" fontWeight="600" fill="var(--sp-sub)">Lowest precedence</text>
69 69 <g stroke="var(--sp-arrow)" strokeWidth="1.5" fill="none">
70<h3 id="what-uses-scopes">70 <line x1={W - 40} y1={TOP + 10} x2={W - 40} y2={H - 38} />
71 범위를 사용하는 것71 <path d={`M ${W - 46} ${TOP + 18} L ${W - 40} ${TOP + 10} L ${W - 34} ${TOP + 18}`} />
72</h3>72 </g>
73 73 <text x={W - 40} y={H - 22} textAnchor="middle" fontFamily={sans} fontSize="10.5" fill="var(--sp-faint)">overrides</text>
74범위는 많은 Claude Code 기능에 적용됩니다:74 </svg>
75 75 </div>;
76| 기능 | 사용자 위치 | 프로젝트 위치 | Local 위치 |76};
77| :-------------- | :------------------------ | :--------------------------------- | :---------------------------- |77
78| **Settings** | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |78export const SettingsScope = ({defaultSelected = 'project'}) => {
79| **Subagents** | `~/.claude/agents/` | `.claude/agents/` | 없음 |79 const FILES = [{
80| **MCP servers** | `~/.claude.json` | `.mcp.json` | `~/.claude.json` (프로젝트별) |80 id: 'user',
81| **Plugins** | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |81 path: '~/.claude/settings.json'
82| **CLAUDE.md** | `~/.claude/CLAUDE.md` | `CLAUDE.md` 또는 `.claude/CLAUDE.md` | `CLAUDE.local.md` |82 }, {
83 83 id: 'project',
84Windows에서 `~/.claude`로 표시된 경로는 `%USERPROFILE%\.claude`로 확인됩니다.84 path: 'acme-app/.claude/settings.json'
85 85 }, {
86***86 id: 'local',
87 87 path: 'acme-app/.claude/settings.local.json'
88<h2 id="settings-files">88 }, {
89 설정 파일89 id: 'managed',
90</h2>90 path: 'Managed settings',
91 91 ring: 'managed-settings.json, MDM, or the claude.ai console'
92`settings.json` 파일은 계층적 설정을 통해 Claude Code를 구성하기 위한 공식 메커니즘입니다:92 }];
93 93 const SHORT = {
94* **사용자 설정**은 `~/.claude/settings.json`에 정의되며 모든 프로젝트에 적용됩니다.94 user: '~/.claude/settings.json',
95* **프로젝트 설정**은 프로젝트 디렉토리에 저장됩니다:95 project: 'acme-app/.claude/settings.json',
96 * 소스 제어에 체크인되고 팀과 공유되는 설정을 위한 `.claude/settings.json`96 local: 'acme-app/.claude/settings.local.json',
97 * 체크인되지 않은 설정을 위한 `.claude/settings.local.json`으로, 개인 설정 및 실험에 유용합니다. Claude Code는 `.claude/settings.local.json`이 생성될 때 git을 구성하여 이를 무시하도록 합니다. 파일을 직접 생성하는 경우 gitignore에 수동으로 추가합니다.97 managed: 'managed-settings.json, MDM, or the claude.ai console'
98 98 };
99 이 파일은 저장소가 아닌 사용자의 파일이므로 `allow` 권한 규칙이 `.claude/settings.json` 허용 규칙이 요구하는 [작업 공간 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust) 단계 없이 적용됩니다. 저장소가 파일을 제공하는 경우 (예: 커밋하여) 작업 공간 신뢰가 여전히 적용됩니다.99 const TILE_MARK = {
100* **Managed 설정**: 중앙 집중식 제어가 필요한 조직의 경우 Claude Code는 managed 설정을 위한 여러 전달 메커니즘을 지원합니다. 모두 동일한 JSON 형식을 사용하며 사용자 또는 프로젝트 설정으로 재정의할 수 없습니다:100 project: 'settings.json',
101 101 local: 'settings.local.json'
102 * **서버 관리 설정**: Anthropic의 서버에서 claude.ai 관리 콘솔을 통해 또는 자체 호스팅 [Claude apps gateway](/docs/ko/claude-apps-gateway)에서 원격으로 전달됩니다. [서버 관리 설정](/docs/ko/server-managed-settings)을 참조하세요.102 };
103 * **MDM/OS 수준 정책**: macOS 및 Windows의 기본 장치 관리를 통해 전달됩니다:103 const initial = FILES.some(f => f.id === defaultSelected) ? defaultSelected : 'project';
104 * macOS: `com.anthropic.claudecode` managed preferences domain. plist의 최상위 키는 `managed-settings.json`을 반영하며, 중첩된 설정은 딕셔너리이고 배열은 plist 배열입니다. Jamf, Iru (Kandji) 또는 유사한 MDM 도구의 구성 프로필을 통해 배포합니다.104 const [sel, setSel] = useState(initial);
105 * Windows: `HKLM\SOFTWARE\Policies\ClaudeCode` 레지스트리 키와 JSON을 포함하는 `Settings` 값 (REG\_SZ 또는 REG\_EXPAND\_SZ) (그룹 정책 또는 Intune을 통해 배포)105 const [scale, setScale] = useState(1);
106 * Windows (사용자 수준): `HKCU\SOFTWARE\Policies\ClaudeCode` (최저 정책 우선순위, 관리자 수준 소스가 없을 때만 사용)106 const [isFullscreen, setIsFullscreen] = useState(false);
107 * **파일 기반**: 시스템 디렉토리에 배포된 `managed-settings.json` 및 `managed-mcp.json`:107 const rootRef = useRef(null);
108 108 const frameRef = useRef(null);
109 * macOS: `/Library/Application Support/ClaudeCode/`109 const CANVAS_W = 862;
110 * Linux 및 WSL: `/etc/claude-code/`110 const CANVAS_H = 240;
111 * Windows: `C:\Program Files\ClaudeCode\`111 useEffect(() => {
112 112 const el = frameRef.current;
113 <Warning>113 if (!el) return;
114 레거시 Windows 경로 `C:\ProgramData\ClaudeCode\managed-settings.json`은 v2.1.75부터 더 이상 지원되지 않습니다. 해당 위치에 설정을 배포한 관리자는 파일을 `C:\Program Files\ClaudeCode\managed-settings.json`으로 마이그레이션해야 합니다.114 const measure = () => setScale(Math.min(1, el.clientWidth / CANVAS_W));
115 </Warning>115 measure();
116 116 if (typeof ResizeObserver === 'undefined') {
117 파일 기반 managed 설정은 `managed-settings.json`과 동일한 시스템 디렉토리에 `managed-settings.d/` 드롭인 디렉토리도 지원합니다. 이를 통해 별도의 팀이 단일 파일 편집을 조정하지 않고 독립적인 정책 조각을 배포할 수 있습니다.117 window.addEventListener('resize', measure);
118 118 return () => window.removeEventListener('resize', measure);
119 systemd 규칙을 따르면 `managed-settings.json`이 먼저 기본으로 병합되고, 드롭인 디렉토리의 모든 `*.json` 파일이 알파벳순으로 정렬되어 위에 병합됩니다. 스칼라 값의 경우 나중 파일이 이전 파일을 재정의합니다. 배열은 연결되고 중복 제거됩니다. 객체는 깊게 병합됩니다. `.`로 시작하는 숨겨진 파일은 무시됩니다.119 }
120 120 const ro = new ResizeObserver(measure);
121 병합 순서를 제어하려면 숫자 접두사를 사용합니다 (예: `10-telemetry.json` 및 `20-security.json`).121 ro.observe(el);
122 122 return () => ro.disconnect();
123 [managed 설정](/docs/ko/permissions#managed-only-settings) 및 [Managed MCP 구성](/docs/ko/managed-mcp)을 참조하세요.123 }, []);
124 124 useEffect(() => {
125 이 [저장소](https://github.com/anthropics/claude-code/tree/main/examples/mdm)에는 Jamf, Iru (Kandji), Intune 및 그룹 정책에 대한 시작 배포 템플릿이 포함되어 있습니다. 이를 시작점으로 사용하고 필요에 맞게 조정합니다.125 const onFsChange = () => setIsFullscreen(!!document.fullscreenElement);
126 126 document.addEventListener('fullscreenchange', onFsChange);
127 <Note>127 return () => document.removeEventListener('fullscreenchange', onFsChange);
128 Managed 배포는 `strictKnownMarketplaces`를 사용하여 **플러그인 마켓플레이스 추가**를 제한할 수도 있습니다. 자세한 내용은 [Managed 마켓플레이스 제한](/docs/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요.128 }, []);
129 </Note>129 const toggleFullscreen = () => {
130* **기타 구성**은 `~/.claude.json`에 저장됩니다. 이 파일에는 OAuth 세션, [MCP server](/docs/ko/mcp) 구성 (사용자 및 local 범위), 프로젝트별 상태 (허용된 도구, 신뢰 설정) 및 다양한 캐시가 포함됩니다. 프로젝트 범위 MCP 서버는 `.mcp.json`에 별도로 저장됩니다.130 if (!rootRef.current) return;
131 131 if (document.fullscreenElement) document.exitFullscreen(); else rootRef.current.requestFullscreen().catch(() => {});
132<Note>132 };
133 Claude Code는 자동으로 구성 파일의 타임스탐프가 지정된 백업을 생성하고 데이터 손실을 방지하기 위해 가장 최근의 5개 백업을 유지합니다.133 const COVERAGE = {
134</Note>134 user: ['website', 'api', 'yacme'],
135 135 project: ['yacme', 'tacme', 'cacme'],
136```JSON 예제 settings.json theme={null}136 local: ['yacme'],
137{137 managed: ['website', 'api', 'yacme', 'tacme', 'cacme']
138 "$schema": "https://json.schemastore.org/claude-code-settings.json",138 };
139 "permissions": {139 const RINGS = {
140 "allow": [140 local: {
141 "Bash(npm run lint)",141 l: 282,
142 "Bash(npm run test *)",142 t: 50,
143 "Read(~/.zshrc)"143 w: 142,
144 ],144 h: 124
145 "deny": [
146 "Bash(curl *)",
147 "Read(./.env)",
148 "Read(./.env.*)",
149 "Read(./secrets/**)"
150 ]
151 },145 },
152 "env": {146 project: {
153 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",147 l: 282,
154 "OTEL_METRICS_EXPORTER": "otlp"148 t: 50,
149 w: 560,
150 h: 124
155 },151 },
156 "companyAnnouncements": [152 user: {
157 "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",153 l: 2,
158 "Reminder: Code reviews required for all PRs",154 t: 34,
159 "New security policy in effect"155 w: 446,
160 ]156 h: 198
161}157 },
162```158 managed: {
163 159 l: 0,
164위의 예제에서 `$schema` 줄은 Claude Code 설정에 대한 [공식 JSON 스키마](https://json.schemastore.org/claude-code-settings.json)를 가리킵니다. 이를 `settings.json`에 추가하면 VS Code, Cursor 및 JSON 스키마 검증을 지원하는 다른 편집기에서 자동 완성 및 인라인 검증이 활성화됩니다.160 t: 32,
165 161 w: 862,
166게시된 스키마는 주기적으로 업데이트되며 가장 최근 CLI 릴리스에서 추가된 설정을 포함하지 않을 수 있으므로, 최근에 문서화된 필드에 대한 검증 경고가 반드시 구성이 유효하지 않음을 의미하지는 않습니다.162 h: 204
167 163 }
168<h3 id="when-edits-take-effect">164 };
169 편집이 적용되는 시기165 const TILES = [{
170</h3>166 id: 'website',
171 167 name: 'website/',
172Claude Code는 설정 파일을 감시하고 변경될 때 다시 로드하므로 대부분의 키에 대한 편집은 재시작 없이 실행 중인 세션에 적용됩니다. 여기에는 `permissions`, `hooks` 및 `apiKeyHelper`와 같은 자격 증명 도우미가 포함됩니다. 다시 로드는 사용자, 프로젝트, local 및 managed 설정을 포함하며, 감지된 각 변경에 대해 [`ConfigChange` hook](/docs/ko/hooks#configchange)이 실행됩니다.168 left: 30,
173 169 caption: ''
174몇 가지 키는 세션 시작 시 한 번 읽혀지고 대신 다음 재시작에 적용됩니다:170 }, {
175 171 id: 'api',
176* `model`: 세션 중에 전환하려면 [`/model`](/docs/ko/model-config#setting-your-model)을 사용합니다172 name: 'api/',
177* [`outputStyle`](/docs/ko/output-styles): 시스템 프롬프트의 일부로, `/clear` 또는 재시작 시 다시 빌드됩니다173 left: 160,
178 174 caption: ''
179<h3 id="invalid-entries-in-managed-settings">175 }, {
180 Managed 설정의 유효하지 않은 항목176 id: 'yacme',
181</h3>177 name: 'acme-app/',
182 178 left: 290,
183Managed 설정은 관대하게 파싱됩니다. Managed 구성에 스키마 검증에 실패하는 항목이 포함되어 있으면 Claude Code는 해당 항목을 제거하고 경고를 기록하며 남은 모든 유효한 정책을 적용합니다. 단일 오타가 조직의 나머지 정책을 비활성화할 수 없습니다. [`/doctor`](/docs/ko/debug-your-config#check-resolved-settings)를 실행하여 제거된 항목을 소스 파일 및 필드와 함께 나열합니다.179 caption: ''
184 180 }, {
185이 동작은 세 가지 전달 메커니즘 모두에서 일관됩니다: [서버 관리 설정](/docs/ko/server-managed-settings), MDM을 통해 배포된 plist 및 레지스트리 정책, 그리고 `managed-settings.json` 파일. Claude Code v2.1.169 이상이 필요합니다.181 id: 'tacme',
186 182 name: 'acme-app/',
187보안 적용 필드는 전체적으로 제거되는 대신 필드별로 처리됩니다:183 left: 497,
188 184 caption: sel === 'project' ? 'their clone, once you commit the file' : 'their clone'
189| 필드 | 존재하지만 유효하지 않을 때의 동작 |185 }, {
190| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |186 id: 'cacme',
191| `allowedMcpServers` | 값이 수정될 때까지 MCP 서버가 허용되지 않도록 빈 허용 목록으로 적용됩니다. 개별 유효하지 않은 항목은 제거되고 유효한 부분 집합이 적용됩니다. |187 name: 'acme-app/',
192| `allowManagedMcpServersOnly` | `true`로 처리됩니다. |188 left: 704,
193| `availableModels` | 값이 수정될 때까지 기본 모델만 사용 가능하도록 빈 허용 목록으로 적용됩니다. 개별 비문자열 항목은 제거되고 유효한 부분 집합이 적용됩니다. v2.1.175 이상에 적용됩니다. |189 caption: sel === 'project' ? 'fresh clone, once you commit the file' : sel === 'managed' ? 'server-managed only' : 'fresh clone'
194| `enforceAvailableModels` | }`true`로 처리됩니다. v2.1.175 이상에 적용됩니다. |190 }];
195| `forceLoginOrgUUID` | 값이 수정될 때까지 조직이 로그인할 수 없습니다. |191 const FILE_AT = {
196| `deniedMcpServers` | 개별 유효하지 않은 항목은 제거되고 유효한 부분 집합이 적용됩니다. 완전히 유효하지 않은 값은 경고와 함께 삭제됩니다. 모든 서버를 거부하면 정책이 명명하지 않은 서버를 차단하기 때문입니다. |192 user: {
197| `sandbox.credentials` | }`files` 또는 `envVars`의 개별 유효하지 않은 항목은 경고와 함께 제거되고 유효한 부분 집합이 적용됩니다. 완전히 유효하지 않은 `credentials` 값은 경고와 함께 삭제되지만 `sandbox`의 나머지는 여전히 적용됩니다. v2.1.191 이상에 적용됩니다. |193 machine: 'you',
198 194 tiles: []
199`requiredMinimumVersion` 및 `requiredMaximumVersion`은 설계상 실패하도록 열려 있습니다: 유효하지 않은 값은 적용되지 않고 제거되므로 잘못된 정책 푸시가 Claude Code 시작을 방지할 수 없습니다.195 },
200 196 project: {
201검증 오류는 세 곳에 표시됩니다:197 machine: null,
202 198 tiles: ['yacme', 'tacme', 'cacme']
203* 대화형 세션은 시작 시 유효하지 않은 항목을 나열하는 대화를 표시합니다.199 },
204* `-p`를 사용한 헤드리스 실행은 stderr에 요약을 인쇄합니다.200 local: {
205* [`claude doctor`](/docs/ko/debug-your-config)는 각 유효하지 않은 항목을 소스 및 필드와 함께 나열합니다.201 machine: null,
206 202 tiles: ['yacme']
207정책 변경을 검증하려면 전사 배포 전에 테스트 머신에서 `claude doctor`를 실행합니다.203 },
208 204 managed: {
209이 관대함은 managed 설정에만 적용됩니다. 사용자, 프로젝트 및 local 설정 파일은 엄격합니다: 검증에 실패하는 파일은 전체적으로 거부되고 보고됩니다.205 machine: null,
210 206 tiles: []
211<h3 id="available-settings">207 }
212 사용 가능한 설정208 };
213</h3>209 const fileAt = FILE_AT[sel];
214 210 const coverage = COVERAGE[sel];
215`settings.json`은 여러 옵션을 지원합니다:211 const ring = RINGS[sel];
216 212 const selFile = FILES.find(f => f.id === sel);
217| 키 | 설명 | 예제 |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">
218| :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |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" />
219| `advisorModel` | 서버 측 [advisor 도구](/docs/ko/advisor)를 위한 모델입니다. `"opus"`, `"sonnet"` 또는 `"fable"` (v2.1.170+)과 같은 모델 별칭 또는 전체 모델 ID를 허용합니다. `/advisor`를 실행할 때 자동으로 작성됩니다. Advisor를 비활성화하려면 설정 해제합니다 | `"opus"` |215 {open && <path d="M1.5 7.5h13" />}
220| `agent` | 메인 스레드를 명명된 subagent로 실행하고 `claude agents`에서 디스패치된 세션의 기본 에이전트를 설정합니다. 해당 subagent의 시스템 프롬프트, 도구 제한 및 모델을 적용합니다. [subagents 명시적으로 호출](/docs/ko/sub-agents#invoke-subagents-explicitly)을 참조하세요 | `"code-reviewer"` |216 </svg>;
221| `agentPushNotifEnabled` | **기본값**: `false`. [Remote Control](/docs/ko/remote-control)이 연결되어 있을 때 Claude가 장시간 작업이 완료될 때와 같이 휴대폰에 사전 예방적 푸시 알림을 보낼 수 있도록 허용합니다. `/config`에 **Claude가 결정할 때 푸시**로 표시됩니다. [모바일 푸시 알림](/docs/ko/remote-control#mobile-push-notifications)을 참조하세요. Claude Code v2.1.119 이상이 필요합니다 | `true` |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">
222| `allowAllClaudeAiMcps` | (Managed 설정만) 배포된 `managed-mcp.json`과 함께 claude.ai 커넥터를 로드합니다. 그렇지 않으면 독점적 제어를 취하고 이를 억제합니다. [Managed MCP 구성](/docs/ko/managed-mcp)을 참조하세요 | `true` |218 <path d="M4 1.5h5.5L13 5v9.5H4z" />
223| `allowedChannelPlugins` | (Managed 설정만) 메시지를 푸시할 수 있는 채널 플러그인의 허용 목록입니다. 설정되면 기본 Anthropic 허용 목록을 대체합니다. 정의되지 않음 = 기본값으로 폴백, 빈 배열 = 모든 채널 플러그인 차단. `channelsEnabled: true`가 필요합니다. [채널 플러그인 실행 제한](/docs/ko/channels#restrict-which-channel-plugins-can-run)을 참조하세요 | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |219 <path d="M9.5 1.5V5H13" />
224| `allowedHttpHookUrls` | HTTP hooks가 대상으로 할 수 있는 URL 패턴의 허용 목록입니다. `*`를 와일드카드로 지원합니다. 설정되면 일치하지 않는 URL을 가진 hooks는 차단됩니다. 정의되지 않음 = 제한 없음, 빈 배열 = 모든 HTTP hooks 차단. 배열은 설정 소스 전체에서 병합됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `["https://hooks.example.com/*"]` |220 </svg>;
225| `allowedMcpServers` | Managed 설정에서 설정되면 사용자가 구성할 수 있는 MCP 서버의 허용 목록입니다. 정의되지 않음 = 제한 없음, 빈 배열 = 잠금. 모든 범위에 적용됩니다. 거부 목록이 우선합니다. [Managed MCP 구성](/docs/ko/managed-mcp)을 참조하세요 | `[{ "serverName": "github" }]` |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">
226| `allowManagedHooksOnly` | (Managed 설정만) Managed hooks, SDK hooks 및 managed 설정 `enabledPlugins`에서 강제 활성화된 플러그인의 hooks만 로드됩니다. 사용자, 프로젝트 및 다른 모든 플러그인 hooks는 차단됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `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" />
227| `allowManagedMcpServersOnly` | (Managed 설정만) Managed 설정의 `allowedMcpServers`만 존중됩니다. `deniedMcpServers`는 여전히 모든 소스에서 병합됩니다. 사용자는 여전히 MCP 서버를 추가할 수 있지만 관리자 정의 허용 목록만 적용됩니다. [Managed MCP 구성](/docs/ko/managed-mcp)을 참조하세요 | `true` |223 </svg>;
228| `allowManagedPermissionRulesOnly` | (Managed 설정만) 사용자 및 프로젝트 설정이 `allow`, `ask` 또는 `deny` 권한 규칙을 정의하는 것을 방지합니다. Managed 설정의 규칙만 적용됩니다. [Managed 전용 설정](/docs/ko/permissions#managed-only-settings)을 참조하세요 | `true` |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">
229| `alwaysThinkingEnabled` | 모든 세션에 대해 기본적으로 [확장 사고](/docs/ko/model-config#extended-thinking)를 활성화합니다. 일반적으로 직접 편집하기보다는 `/config` 명령을 통해 구성됩니다. 사고를 강제로 끄려면 `env`에서 [`MAX_THINKING_TOKENS=0`](/docs/ko/env-vars)을 설정합니다. 이는 Anthropic API에서 사고를 비활성화합니다. Fable 5는 제외되며, 이는 사고를 끌 수 없습니다. [제3자 공급자](/docs/ko/third-party-integrations)에서 이는 `thinking` 매개변수를 생략하며, 적응형 추론 모델은 여전히 사고할 수 있습니다 | `true` |225 <rect x="2.5" y="3" width="11" height="7.5" rx="1" />
230| `apiKeyHelper` | 시스템 셸 (`/bin/sh` on macOS and Linux, `cmd` on Windows)을 통해 실행될 사용자 정의 명령으로 인증 값을 생성합니다. 이 값은 모델 요청에 대해 `X-Api-Key` 및 `Authorization: Bearer` 헤더로 전송됩니다. [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/docs/ko/env-vars)로 새로고침 간격을 설정합니다 | `/bin/generate_temp_api_key.sh` |226 <path d="M1 12.5h14" />
231| `askUserQuestionTimeout` | **기본값**: `"never"`. 답변되지 않은 [`AskUserQuestion`](/docs/ko/tools-reference) 대화가 이미 선택한 옵션으로 자동 계속되기 전의 유휴 시간입니다. `"60s"`, `"5m"`, `"10m"` 또는 `"never"`를 허용합니다. 기본값을 사용하면 질문은 답변할 때까지 기다립니다. `/config`에 **질문 자동 계속 시간 초과**로 표시됩니다. 프로젝트 또는 local 설정에서는 읽지 않습니다. Claude Code v2.1.200 이상이 필요합니다 | `"5m"` |227 </svg>;
232| `attribution` | git 커밋 및 pull request에 대한 attribution을 사용자 정의합니다. [Attribution 설정](#attribution-settings)을 참조하세요 | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |228 return <div ref={rootRef} className={'ssc-root not-prose' + (isFullscreen ? ' ssc-fs' : '')}>
233| `autoCompactEnabled` | **기본값**: `true`. 컨텍스트가 한계에 접근할 때 자동으로 대화를 압축합니다. `/config`에 **자동 압축**으로 표시됩니다. 환경 변수로 비활성화하려면 `env`에서 [`DISABLE_AUTO_COMPACT`](/docs/ko/env-vars)를 설정합니다 | `false` |229 <style>{`
234| `autoMemoryDirectory` | [자동 메모리](/docs/ko/memory#storage-location) 저장소를 위한 사용자 정의 디렉토리입니다. 절대 경로 또는 `~/` 접두사 경로를 허용합니다. 프로젝트 또는 local 설정에서 이는 작업 공간 신뢰 대화를 수락한 후에만 적용됩니다. 복제된 저장소가 이 파일을 제공할 수 있기 때문입니다 | `"~/my-memory-dir"` |230 .ssc-root {
235| `autoMemoryEnabled` | **기본값**: `true`. [자동 메모리](/docs/ko/memory#enable-or-disable-auto-memory)를 활성화합니다. `false`일 때 Claude는 자동 메모리 디렉토리에서 읽거나 쓰지 않습니다. 세션 중에 `/memory`로도 전환할 수 있습니다. 환경 변수로 비활성화하려면 `env`에서 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/docs/ko/env-vars)를 설정합니다 | `false` |231 --ssc-bg: #FFFFFF;
236| `autoMode` | [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기가 차단하고 허용하는 것을 사용자 정의합니다. `environment`, `allow`, `soft_deny` 및 `hard_deny` 배열의 산문 규칙을 포함합니다. 배열에 리터럴 문자열 `"$defaults"`를 포함하여 해당 위치에서 기본 제공 규칙을 상속합니다. [자동 모드 구성](/docs/ko/auto-mode-config)을 참조하세요. 사용자 설정, `--settings` 플래그 및 managed 설정에서만 읽습니다. 프로젝트 `.claude/settings.json` 및 local `.claude/settings.local.json`에서는 무시됩니다. v2.1.207 이전에는 `.claude/settings.local.json`도 읽혔습니다 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |232 --ssc-text: #1A1918;
237| `autoMode.classifyAllShell` | **기본값**: `false`. `true`일 때 자동 모드가 활성화되어 있는 동안 모든 Bash 및 PowerShell 허용 규칙을 일시 중단하므로 모든 셸 명령이 임의 코드 실행 패턴과 일치하는 규칙뿐만 아니라 분류기를 통해 라우팅됩니다. [분류기를 통해 모든 셸 명령 라우팅](/docs/ko/auto-mode-config#route-all-shell-commands-through-the-classifier)을 참조하세요. Claude Code v2.1.193 이상이 필요합니다 | `true` |233 --ssc-sub: #5E5D59;
238| `autoScrollEnabled` | **기본값**: `true`. [fullscreen 렌더링](/docs/ko/fullscreen)에서 새 출력을 대화의 맨 아래로 따릅니다. `/config`에 **자동 스크롤**로 표시됩니다. 이것이 꺼져 있을 때도 권한 프롬프트는 여전히 보기로 스크롤됩니다 | `false` |234 --ssc-faint: #8A8880;
239| `autoUpdatesChannel` | **기본값**: `"latest"`. 업데이트를 따를 릴리스 채널입니다. 일반적으로 약 1주일 된 버전이고 주요 회귀가 있는 버전을 건너뛰는 `"stable"`을 사용하거나 가장 최근 릴리스인 `"latest"`를 사용합니다. 자동 업데이트를 완전히 비활성화하려면 `env`에서 [`DISABLE_AUTOUPDATER`](/docs/ko/setup#disable-auto-updates)를 설정합니다 | `"stable"` |235 --ssc-border: rgba(0,0,0,0.12);
240| `availableModels` | 사용자가 메인 세션, [subagents](/docs/ko/sub-agents), [skills](/docs/ko/skills) 및 [advisor](/docs/ko/advisor)를 위해 선택할 수 있는 모델을 제한합니다. `enforceAvailableModels`도 설정되지 않으면 기본 옵션에는 영향을 주지 않습니다. [모델 선택 제한](/docs/ko/model-config#restrict-model-selection)을 참조하세요 | `["sonnet", "haiku"]` |236 --ssc-panel: #F5F4EF;
241| `awaySummaryEnabled` | 몇 분 동안 터미널에서 떨어져 있다가 돌아올 때 한 줄 세션 요약을 표시합니다. 비활성화하려면 `false`로 설정하거나 `/config`에서 세션 요약을 끕니다. [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/docs/ko/env-vars)와 동일합니다 | `true` |237 --ssc-tile: #FAFAF8;
242| `awsAuthRefresh` | `.aws` 디렉토리를 수정하는 사용자 정의 스크립트 ([고급 자격 증명 구성](/docs/ko/amazon-bedrock#advanced-credential-configuration) 참조) | `aws sso login --profile myprofile` |238 --ssc-clay: #D97757;
243| `awsCredentialExport` | AWS 자격 증명이 포함된 JSON을 출력하는 사용자 정의 스크립트 ([고급 자격 증명 구성](/docs/ko/amazon-bedrock#advanced-credential-configuration) 참조) | `/bin/generate_aws_grant.sh` |239 --ssc-clay-bg: rgba(217,119,87,0.14);
244| `axScreenReader` | 화면 판독기 친화적 출력을 렌더링합니다: 장식적 테두리나 애니메이션 없는 평면 텍스트. 화면 판독기 모드는 항상 클래식 렌더러를 사용하므로 활성화되어 있는 동안 `tui` 설정은 영향을 주지 않습니다. 연결된 [배경 세션](/docs/ko/agent-view)은 여전히 fullscreen을 렌더링합니다. [`CLAUDE_AX_SCREEN_READER`](/docs/ko/env-vars) 환경 변수 및 [`--ax-screen-reader`](/docs/ko/cli-reference#cli-flags) 플래그가 우선합니다. Claude Code v2.1.181 이상이 필요합니다 | `true` |240 --ssc-label: #B0562F;
245| `blockedMarketplaces` | (Managed 설정만) 마켓플레이스 소스의 차단 목록입니다. 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용되므로 정책이 설정되기 전에 추가된 마켓플레이스는 플러그인을 가져오는 데 사용할 수 없습니다. 차단된 소스는 다운로드 전에 확인되므로 파일 시스템에 닿지 않습니다. [Managed 마켓플레이스 제한](/docs/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요 | `[{ "source": "github", "repo": "untrusted/plugins" }]` |241 --ssc-hover: rgba(115,114,108,0.10);
246| `browserExternalPageTools` | (Managed 설정만) 데스크톱 앱의 [Browser 창](/docs/ko/desktop#browse-external-sites)에서 외부 페이지를 읽거나 작용하기 위해 Claude가 도구를 사용하는 것을 방지하려면 `"disabled"`로 설정합니다. 사용자는 여전히 외부 사이트로 직접 이동할 수 있으며 local dev 서버 미리보기는 영향을 받지 않습니다 | `"disabled"` |242 font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
247| `channelsEnabled` | (Managed 설정만) 조직을 위해 [channels](/docs/ko/channels)를 허용합니다. Claude.ai Team 및 Enterprise 플랜에서 설정되지 않거나 `false`이면 채널이 차단됩니다. [Anthropic Console](/docs/ko/authentication#claude-console-authentication) 계정이 API 키 인증을 사용하는 경우 조직이 managed 설정을 배포하지 않으면 기본적으로 채널이 허용되며, 이 경우 이 키를 `true`로 설정해야 합니다 | `true` |243 background: var(--ssc-bg);
248| `claudeMd` | (Managed 설정만) 조직 관리 메모리로 주입된 CLAUDE.md 스타일 지침입니다. Managed 또는 정책 설정에서 설정된 경우에만 적용되며 사용자, 프로젝트 및 local 설정에서는 무시됩니다. [조직 전체 CLAUDE.md](/docs/ko/memory#deploy-organization-wide-claude-md)를 참조하세요 | `"Always run make lint before committing."` |244 color: var(--ssc-text);
249| `claudeMdExcludes` | [메모리](/docs/ko/memory)를 로드할 때 건너뛸 `CLAUDE.md` 파일의 Glob 패턴 또는 절대 경로입니다. 패턴은 절대 파일 경로와 일치합니다. 사용자, 프로젝트 및 local 메모리에만 적용됩니다. managed 정책 파일은 제외할 수 없습니다 | `["**/vendor/**/CLAUDE.md"]` |245 border: 1px solid var(--ssc-border);
250| `cleanupPeriodDays` | **기본값**: `30`일, 최소 `1`. Claude Code는 이 기간보다 오래된 [세션 파일 및 기타 애플리케이션 데이터](/docs/ko/claude-directory#cleaned-up-automatically)를 시작 시 삭제합니다. `0`으로 설정하면 검증 오류가 발생합니다. 또한 시작 시 [고아 worktrees](/docs/ko/worktrees#clean-up-worktrees)의 자동 제거에 대한 나이 기준을 제어합니다. Claude Code가 설정 파일을 읽거나 파싱할 수 없으면 보존 정리 스윕을 일시 중단하고 파일을 수정할 때까지 `/status`에 경고를 표시합니다. 단, [managed 설정](/docs/ko/server-managed-settings)이 `cleanupPeriodDays`를 제공하는 경우 스윕은 managed 값에서 실행됩니다. v2.1.203 이전에는 정리가 해당 상태에서 30일 기본값으로 실행되었고 더 긴 `cleanupPeriodDays`가 유지하려던 트랜스크립트를 삭제할 수 있었습니다. 30일보다 최신인 파일은 절대 제거되지 않았습니다. 트랜스크립트 쓰기를 완전히 비활성화하려면 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/ko/env-vars) 환경 변수를 설정합니다. 비대화형 모드에서 `-p`와 함께 `--no-session-persistence`를 전달하거나 Agent SDK에서 `persistSession: false`를 설정합니다. | `20` |246 border-radius: 16px;
251| `companyAnnouncements` | 시작 시 사용자에게 표시할 공지사항입니다. 여러 공지사항이 제공되면 무작위로 순환됩니다. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |247 padding: 20px 24px 24px;
252| `defaultShell` | **기본값**: `"bash"`, 또는 Bash를 사용할 수 없을 때 Windows에서 `"powershell"`. 입력 상자 `!` 명령의 기본 셸입니다. `"bash"` 또는 `"powershell"`을 허용합니다. `"powershell"`을 설정하면 Windows에서 대화형 `!` 명령을 PowerShell을 통해 라우팅합니다. `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`이 필요합니다. [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)를 참조하세요 | `"powershell"` |248 margin: 1.5rem 0;
253| `deniedMcpServers` | Managed 설정에서 설정되면 명시적으로 차단된 MCP 서버의 거부 목록입니다. Managed 서버를 포함한 모든 범위에 적용됩니다. 거부 목록이 허용 목록보다 우선합니다. [Managed MCP 구성](/docs/ko/managed-mcp)을 참조하세요 | `[{ "serverName": "filesystem" }]` |249 box-sizing: border-box;
254| `disableAgentView` | [배경 에이전트 및 에이전트 보기](/docs/ko/agent-view)를 끄려면 `true`로 설정합니다: `claude agents`, `--bg`, `/background` 및 온디맨드 감독자. 일반적으로 [managed 설정](/docs/ko/permissions#managed-settings)에서 설정됩니다. `CLAUDE_CODE_DISABLE_AGENT_VIEW`를 `1`로 설정하는 것과 동일합니다 | `true` |250 }
255| `disableAllHooks` | 모든 [hooks](/docs/ko/hooks) 및 사용자 정의 [상태 줄](/docs/ko/statusline) 비활성화 | `true` |251 .dark .ssc-root {
256| `disableArtifact` | [Artifact](/docs/ko/artifacts) 도구를 비활성화하려면 `true`로 설정합니다. 이는 세션 출력을 claude.ai의 비공개 웹 페이지로 게시합니다. `CLAUDE_CODE_DISABLE_ARTIFACT`를 `1`로 설정하는 것과 동일합니다 | `true` |252 --ssc-bg: #1B1A18;
257| `disableAutoMode` | [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. `Shift+Tab` 순환에서 `auto`를 제거하고 시작 시 `--permission-mode auto`를 거부합니다. [managed 설정](/docs/ko/permissions#managed-settings)에서 사용자가 재정의할 수 없을 때 가장 유용합니다 | `"disable"` |253 --ssc-text: #F1EFE9;
258| `disableBrowserExternalNavigation` | (Managed 설정만) 데스크톱 앱의 [Browser 창](/docs/ko/desktop#browse-external-sites)에서 외부 탐색을 끄려면 `true`로 설정합니다. 사용자와 Claude 모두 외부 사이트로 이동할 수 없으며 localhost dev 서버 미리보기는 영향을 받지 않습니다. 값은 JSON 부울 `true`여야 합니다. 문자열 `"true"`는 무시됩니다 | `true` |254 --ssc-sub: #B8B5AD;
259| `disableBundledSkills` | [skills](/docs/ko/skills) 및 Claude Code와 함께 제공되는 워크플로우를 비활성화하려면 `true`로 설정합니다: 번들 skills 및 워크플로우는 완전히 제거되고, `/init`과 같은 기본 제공 슬래시 명령은 입력 가능하지만 모델에서 숨겨집니다. `/doctor`는 기본 제공 명령처럼 입력 가능하지만 [`DISABLE_DOCTOR_COMMAND`](/docs/ko/env-vars)로 숨깁니다. 플러그인의 skills, `.claude/skills/` 및 `.claude/commands/`는 영향을 받지 않습니다. `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS`를 `1`로 설정하는 것과 동일합니다 | `true` |255 --ssc-faint: #8A8880;
260| `disableClaudeAiConnectors` | }[claude.ai MCP 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai)를 비활성화하여 자동 가져오기 또는 연결되지 않도록 합니다. 모든 설정 범위에서 설정합니다. 모든 소스에서 `true`가 우선하므로 체크인된 프로젝트 `.claude/settings.json`이 저장소를 클라우드 커넥터에서 제외할 수 있지만 프로젝트 수준 `false`는 사용자 또는 정책 수준 `true`를 재정의할 수 없습니다. `--mcp-config`를 통해 명시적으로 전달된 서버는 영향을 받지 않습니다. 모든 커넥터를 거부하는 대신 개별 커넥터를 거부하려면 [`deniedMcpServers`](/docs/ko/managed-mcp)를 사용합니다. Claude Code v2.1.182 이상이 필요합니다 | `true` |256 --ssc-border: rgba(255,255,255,0.12);
261| `disableDeepLinkRegistration` | Claude Code가 시작 시 운영 체제에 `claude-cli://` 프로토콜 핸들러를 등록하는 것을 방지하려면 `"disable"`로 설정합니다. [Deep links](/docs/ko/deep-links)를 사용하면 외부 도구가 사전 채워진 프롬프트로 Claude Code 세션을 열 수 있습니다. 프로토콜 핸들러 등록이 제한되거나 별도로 관리되는 환경에서 유용합니다 | `"disable"` |257 --ssc-panel: #24231F;
262| `disabledMcpjsonServers` | `.mcp.json` 파일에서 거부할 특정 MCP 서버 목록 | `["filesystem"]` |258 --ssc-tile: #2A2925;
263| `disableRemoteControl` | }[Remote Control](/docs/ko/remote-control) 비활성화: `claude remote-control`, `--remote-control` 플래그, 자동 시작 및 세션 내 전환을 차단합니다. 일반적으로 장치별 MDM 적용을 위해 [managed 설정](/docs/ko/permissions#managed-settings)에 배치되지만 모든 범위에서 작동합니다. Claude Code v2.1.128 이상이 필요합니다 | `true` |259 --ssc-clay-bg: rgba(217,119,87,0.20);
264| `disableSideloadFlags` | }(Managed 설정만) 시작 시 `--plugin-dir`, `--plugin-url`, `--agents` 및 `--mcp-config` CLI 플래그를 거부합니다. 사용자는 단일 실행을 위해 [`strictKnownMarketplaces`](#strictknownmarketplaces)를 우회하기 위해 이를 전달할 수 있습니다. 또한 현재 [Cowork](/docs/ko/desktop) local 세션인 CLI를 내부적으로 생성하는 모든 표면에서 이러한 플래그를 거부합니다. 모든 서버가 in-process `type: "sdk"` 항목인 `--mcp-config`는 여전히 허용되므로 Agent SDK 및 VS Code 확장이 계속 작동합니다. `claude mcp add`, `.mcp.json` 또는 SDK `setMcpServers()`를 차단하지 않습니다. 서버별 MCP 제어를 위해 [`allowedMcpServers`](/docs/ko/managed-mcp)와 쌍을 이룹니다. Claude Code v2.1.193 이상이 필요합니다 | `true` |260 --ssc-label: #EBC9B7;
265| `disableSkillShellExecution` | [skills](/docs/ko/skills) 및 사용자, 프로젝트, 플러그인 또는 추가 디렉토리 소스의 사용자 정의 명령에서 `` !`...` `` 및 ` ```! ` 블록에 대한 인라인 셸 실행을 비활성화합니다. 명령은 실행되는 대신 `[shell command execution disabled by policy]`로 대체됩니다. 번들 및 managed skills는 영향을 받지 않습니다. [managed 설정](/ko/permissions#managed-settings)에서 사용자가 재정의할 수 없을 때 가장 유용합니다 | `true` |261 }
266| `disableWorkflows` | **기본값**: `false`. [동적 워크플로우](/docs/ko/workflows#turn-workflows-off) 및 번들 워크플로우 명령을 비활성화합니다. `CLAUDE_CODE_DISABLE_WORKFLOWS`를 `1`로 설정하는 것과 동일합니다 | `true` |262 .ssc-fs { display: flex; flex-direction: column; justify-content: center; align-items: center; margin: 0; border-radius: 0; height: 100vh; }
267| `editorMode` | **기본값**: `"normal"`. 입력 프롬프트의 키 바인딩 모드: `"normal"` 또는 `"vim"`. `/config`에 **편집기 모드**로 표시됩니다 | `"vim"` |263 .ssc-fs .ssc-head { width: 100%; max-width: ${CANVAS_W}px; }
268| `effortLevel` | [노력 수준](/docs/ko/model-config#adjust-effort-level)을 세션 간에 유지합니다. `"low"`, `"medium"`, `"high"` 또는 `"xhigh"`를 허용합니다. `/effort`를 이러한 값 중 하나로 실행할 때 자동으로 작성됩니다. `--effort` 및 [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/ko/env-vars)은 한 세션에 대해 이를 재정의합니다. [노력 수준 조정](/docs/ko/model-config#adjust-effort-level)에서 지원되는 모델을 참조하세요 | `"xhigh"` |264 .ssc-fs .ssc-frame { width: 100%; }
269| `enableAllProjectMcpServers` | 프로젝트 `.mcp.json` 파일에 정의된 모든 MCP 서버를 자동으로 승인합니다. }v2.1.196부터 `claude mcp list` 및 `claude mcp get`은 [저장소에 체크인되지 않은 설정 파일](/docs/ko/mcp#managing-your-servers)에서만 신뢰할 수 없는 폴더에서 이 키를 존중합니다 | `true` |265 .ssc-mono { font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace); }
270| `enableArtifact` | }이 사용자에 대해 [Artifact](/docs/ko/artifacts) 도구를 활성화하거나 비활성화합니다. 설정되지 않으면 기본값은 계정의 기능 [가용성](/docs/ko/artifacts#availability)을 따릅니다. `/config`의 **Artifacts** 행이 이 키를 작성합니다. Managed `disableArtifact` 및 조직의 [관리자 설정](/docs/ko/artifacts#manage-artifacts-for-your-organization)이 우선하며, 키는 프로젝트 및 local 설정 (`.claude/settings.json`, `.claude/settings.local.json`)에서 무시됩니다. 저장소가 이를 커밋할 수 있기 때문입니다. Claude Code v2.1.196 이상이 필요합니다 | `true` |266 .ssc-head { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; margin-bottom: 20px; }
271| `enabledMcpjsonServers` | `.mcp.json` 파일에서 승인할 특정 MCP 서버 목록입니다. }v2.1.196부터 `claude mcp list` 및 `claude mcp get`은 [저장소에 체크인되지 않은 설정 파일](/docs/ko/mcp#managing-your-servers)에서만 신뢰할 수 없는 폴더에서 이 키를 존중합니다 | `["memory", "github"]` |267 .ssc-files { display: flex; gap: 8px; flex-wrap: wrap; }
272| `enforceAvailableModels` | }}}Extend the `availableModels` allowlist to the Default model. When `true` in managed settings and `availableModels` is a non-empty array, the Default option falls back to the first allowlisted entry that is available, but only when the model Default would resolve to (the [organization default](/docs/ko/model-config#organization-default-model) when one applies, otherwise the account-type default) is not in the allowlist; an allowlisted default is kept as-is. Has no effect when `availableModels` is unset or empty. See [Enforce the allowlist for the Default model](/docs/ko/model-config#enforce-the-allowlist-for-the-default-model). Requires Claude Code v2.1.175 or later | `true` |268 .ssc-file {
273| `env` | 모든 세션에 적용될 환경 변수 및 Claude Code가 생성하는 하위 프로세스에 적용됩니다. 변수를 `""`로 설정하여 셸 내보내기를 빈 문자열로 재정의합니다. Claude Code는 이를 설정 해제로 처리합니다. 하위 프로세스는 여전히 빈 값을 상속합니다. `NO_COLOR` 및 `FORCE_COLOR`는 여기에 설정되면 하위 프로세스에만 도달합니다. Claude Code의 자체 인터페이스 색상을 변경하려면 Claude를 시작하기 전에 셸에서 이를 설정합니다. }v2.1.195부터 Claude Code의 호스팅 환경이 설정하는 `CLAUDE_CODE_REMOTE` 및 `CLAUDE_CODE_ACCOUNT_UUID`와 같은 ID 변수는 여기에 설정되면 무시됩니다 | `{"FOO": "bar"}` |269 font-size: 12.5px; font-weight: 430; padding: 8px 13px; border-radius: 10px; cursor: pointer;
274| `fallbackModel` | 기본 모델이 과부하이거나 사용할 수 없을 때 순서대로 시도할 폴백 모델입니다. Claude Code는 턴의 나머지 부분에 대해 체인의 다음 사용 가능한 모델로 전환하고 알림을 표시합니다. `"default"`는 기본 모델로 확장됩니다. 체인은 3개 모델로 제한되며 추가 항목은 무시됩니다. 대부분의 배열 설정과 달리 이 키는 설정 파일 전체에서 병합되지 않습니다: 이를 정의하는 최고 우선순위 파일이 전체 체인을 제공합니다. [`--fallback-model`](/docs/ko/cli-reference#cli-flags) 플래그는 한 세션에 대해 이를 재정의합니다. [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)을 참조하세요 | `["claude-sonnet-5", "claude-haiku-4-5"]` |270 border: 0.5px solid var(--ssc-border); background: var(--ssc-tile); color: var(--ssc-text);
275| `fastMode` | 사용 가능한 세션에 대해 [fast mode](/docs/ko/fast-mode)를 켭니다. `/fast`로 전환하면 사용자 설정에서 `true`를 작성하고 fast mode를 끌 때 키를 제거합니다 | `true` |271 white-space: nowrap; transition: background 0.2s, border-color 0.2s;
276| `fastModePerSessionOptIn` | `true`일 때 fast mode는 세션 간에 지속되지 않습니다. 각 세션은 fast mode가 꺼진 상태로 시작되며 사용자가 `/fast`로 활성화해야 합니다. 사용자의 fast mode 설정은 여전히 저장됩니다. [세션별 옵트인 필요](/docs/ko/fast-mode#require-per-session-opt-in)를 참조하세요 | `true` |272 }
277| `feedbackSurveyRate` | [세션 품질 설문조사](/docs/ko/data-usage#session-quality-surveys)가 적격일 때 나타날 확률 (0–1). 완전히 억제하려면 `0`으로 설정하거나 `env`에서 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/docs/ko/env-vars)를 설정합니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry를 사용할 때 유용하며 기본 샘플 레이트가 적용되지 않습니다 | `0.05` |273 .ssc-file:hover { filter: brightness(0.97); }
278| `fileCheckpointingEnabled` | }**기본값**: `true`. 각 편집 전에 파일을 스냅샷하여 [`/rewind`](/docs/ko/checkpointing)가 이를 복원할 수 있도록 합니다. `/config`에 \*\*코드 되감기 (체크포인트)\*\*로 표시됩니다. 환경 변수로 비활성화하려면 `env`에서 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/docs/ko/env-vars)를 설정합니다 | `false` |274 .ssc-file[aria-pressed="true"] { font-weight: 600; border: 1.5px solid var(--ssc-clay); background: var(--ssc-clay-bg); }
279| `fileSuggestion` | `@` 파일 자동 완성을 위한 사용자 정의 스크립트를 구성합니다. [파일 제안 설정](#file-suggestion-settings)을 참조하세요 | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |275 .ssc-fsbtn {
280| `footerLinksRegexes` | }정규식이 턴 출력과 일치할 때 바닥글에 클릭 가능한 배지를 렌더링합니다. 각 항목에는 `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}"}]` |276 display: flex; align-items: center; justify-content: center; width: 28px; height: 28px; flex-shrink: 0;
281| `forceLoginMethod` | `claudeai`를 사용하여 Claude.ai 계정으로만 로그인을 제한하거나, `console`을 사용하여 Claude Console 계정으로만 제한하거나, `gateway`를 사용하여 클라우드 게이트웨이로만 제한합니다. [Claude apps gateway](/docs/ko/claude-apps-gateway)를 참조하세요. Managed 설정에서 설정되면 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`로 인증된 세션은 시작 시 차단됩니다. 어느 값도 먼저 자사 OAuth 없이 만족할 수 없기 때문입니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry와 같은 제3자 공급자 세션은 차단되지 않습니다: 이들은 Anthropic이 아닌 클라우드 공급자에 대해 인증합니다 | `claudeai` |277 border: none; background: none; border-radius: 6px; cursor: pointer; color: var(--ssc-faint); font-size: 15px;
282| `forceLoginGatewayUrl` | `/login` 클라우드 게이트웨이 화면에서 게이트웨이 URL을 사전 채우고 잠급니다. 이 키 또는 `forceLoginMethod: "gateway"` 중 하나가 해당 화면을 표시합니다. URL이 채워지도록 둘 다 설정합니다. Managed 정책 계층에서만 적용됩니다. 사용자 및 프로젝트 설정에서는 무시됩니다. [Claude apps gateway](/docs/ko/claude-apps-gateway#set-the-gateway-url)를 참조하세요 | `"https://claude-gateway.example.com"` |278 }
283| `forceLoginOrgUUID` | 로그인이 특정 Anthropic 조직에 속하도록 요구합니다. 단일 UUID 문자열을 허용하며, 이는 로그인 중에 해당 조직을 사전 선택하거나, 나열된 조직이 사전 선택 없이 허용되는 UUID 배열을 허용합니다. Managed 설정에서 설정되면 인증된 계정이 나열된 조직에 속하지 않으면 로그인이 실패합니다. `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`로 인증된 세션은 시작 시 차단됩니다. 조직 멤버십을 확인할 수 없기 때문입니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry와 같은 제3자 공급자 세션은 차단되지 않습니다: 클라우드 IAM을 사용하여 사용할 수 있는 클라우드 계정을 제한합니다. 빈 배열은 실패하고 잘못된 구성 메시지로 로그인을 차단합니다 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 또는 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |279 .ssc-fsbtn:hover { background: var(--ssc-hover); }
284| `forceRemoteSettingsRefresh` | (Managed 설정만) 원격 managed 설정이 서버에서 새로 가져올 때까지 CLI 시작을 차단합니다. 가져오기가 실패하면 캐시된 또는 설정 없이 계속하는 대신 CLI가 종료됩니다. 설정되지 않으면 시작이 원격 설정을 기다리지 않고 계속됩니다. [실패 폐쇄 적용](/docs/ko/server-managed-settings#enforce-fail-closed-startup)을 참조하세요 | `true` |280 .ssc-frame { width: 100%; max-width: ${CANVAS_W}px; margin: 0 auto; }
285| `gcpAuthRefresh` | GCP Application Default Credentials가 만료되거나 로드할 수 없을 때 새로고침하는 사용자 정의 스크립트입니다. [고급 자격 증명 구성](/docs/ko/google-vertex-ai#advanced-credential-configuration)을 참조하세요 | `gcloud auth application-default login` |281 .ssc-canvas { position: relative; width: ${CANVAS_W}px; height: ${CANVAS_H}px; transform-origin: top left; }
286| `hooks` | 라이프사이클 이벤트에서 실행할 사용자 정의 명령을 구성합니다. 형식은 [hooks 문서](/docs/ko/hooks)를 참조하세요 | [hooks](/docs/ko/hooks) 참조 |282 .ssc-machine { position: absolute; top: 42px; height: 182px; background: var(--ssc-panel); border-radius: 16px; }
287| `httpHookAllowedEnvVars` | HTTP hooks가 헤더에 보간할 수 있는 환경 변수 이름의 허용 목록입니다. 설정되면 각 hook의 유효한 `allowedEnvVars`는 이 설정과의 교집합입니다. 정의되지 않음 = 제한 없음. 배열은 설정 소스 전체에서 병합됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `["MY_TOKEN", "HOOK_SECRET"]` |283 .ssc-machine-label { position: absolute; top: 192px; display: flex; align-items: center; gap: 8px; font-size: 13.5px; font-weight: 600; }
288| `includeGitInstructions` | **기본값**: `true`. Claude의 시스템 프롬프트에 기본 제공 커밋 및 PR 워크플로우 지침 및 git 상태 스냅샷을 포함합니다. 예를 들어 자신의 git 워크플로우 skills을 사용할 때 이를 `false`로 설정하여 둘 다 제거합니다. `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 환경 변수가 설정되면 이 설정보다 우선합니다 | `false` |284 .ssc-tile {
289| `inputNeededNotifEnabled` | }**기본값**: `false`. [Remote Control](/docs/ko/remote-control)이 연결되어 있을 때 권한 프롬프트 또는 질문이 입력을 기다리고 있을 때 휴대폰에 푸시 알림을 보냅니다. `/config`에 **작업이 필요할 때 푸시**로 표시됩니다. [모바일 푸시 알림](/docs/ko/remote-control#mobile-push-notifications)을 참조하세요. Claude Code v2.1.119 이상이 필요합니다 | `true` |285 position: absolute; top: 58px; width: 126px; height: 108px; border-radius: 12px; padding: 11px 12px; box-sizing: border-box;
290| `language` | Claude의 선호 응답 언어를 구성합니다 (예: `"japanese"`, `"spanish"`, `"french"`). Claude는 기본적으로 이 언어로 응답합니다. 또한 [음성 받아쓰기](/docs/ko/voice-dictation#change-the-dictation-language) 언어를 설정합니다. }v2.1.176부터 설정되지 않으면 세션 제목이 대화의 언어와 일치합니다 | `"japanese"` |286 background: var(--ssc-tile); border: 0.5px solid var(--ssc-border); opacity: 0.6;
291| `minimumVersion` | 배경 자동 업데이트 및 `claude update`가 이 버전 아래로 설치되는 것을 방지하는 하한입니다. `"latest"` 채널에서 `"stable"`로 전환할 때 `/config`를 통해 현재 버전에 머물기 또는 다운그레이드를 허용하라는 메시지가 표시됩니다. 머물기를 선택하면 이 값이 설정됩니다. 또한 [managed 설정](/docs/ko/permissions#managed-settings)에서 조직 전체 최소값을 고정하는 데 유용합니다. 시작을 완전히 차단하는 하드 플로어는 `requiredMinimumVersion`을 참조하세요 | `"2.1.100"` |287 transition: background 0.25s, border-color 0.25s, opacity 0.25s;
292| `model` | Claude Code에 사용할 기본 모델을 재정의합니다. `--model` 및 [`ANTHROPIC_MODEL`](/docs/ko/model-config#environment-variables)은 한 세션에 대해 이를 재정의합니다 | `"claude-sonnet-5"` |288 }
293| `modelOverrides` | Anthropic 모델 ID를 Amazon Bedrock 추론 프로필 ARN과 같은 공급자 특정 모델 ID로 매핑합니다. 각 모델 선택기 항목은 공급자 API를 호출할 때 매핑된 값을 사용합니다. [버전별 모델 ID 재정의](/docs/ko/model-config#override-model-ids-per-version)를 참조하세요 | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |289 .ssc-tile.ssc-on { background: var(--ssc-clay-bg); border: 1px solid var(--ssc-clay); opacity: 1; }
294| `otelHeadersHelper` | 동적 OpenTelemetry 헤더를 생성하는 스크립트입니다. 시작 시 및 주기적으로 실행됩니다. [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/docs/ko/env-vars)로 새로고침 간격을 설정합니다. [동적 헤더](/docs/ko/monitoring-usage#dynamic-headers)를 참조하세요 | `/bin/generate_otel_headers.sh` |290 .ssc-tile-name { display: flex; align-items: center; gap: 6px; color: var(--ssc-faint); }
295| `outputStyle` | 시스템 프롬프트를 조정하기 위한 출력 스타일을 구성합니다. [출력 스타일 문서](/docs/ko/output-styles)를 참조하세요 | `"Explanatory"` |291 .ssc-tile.ssc-on .ssc-tile-name { color: var(--ssc-clay); }
296| `parentSettingsBehavior` | }(Managed 설정만) **기본값**: `"first-wins"`. Agent SDK 또는 IDE 확장과 같은 embedding host 프로세스에 의해 프로그래밍 방식으로 제공되는 managed 설정이 관리자 배포 managed 계층도 있을 때 적용되는지 여부를 제어합니다. `"first-wins"`: 부모 제공 설정이 삭제되고 관리자 계층만 적용됩니다. `"merge"`: 부모 제공 설정이 관리자 계층 아래에 적용되며, 정책을 강화할 수 있지만 완화할 수 없도록 필터링됩니다. 관리자 계층이 배포되지 않으면 영향을 주지 않습니다. Claude Code v2.1.133 이상이 필요합니다 | `"merge"` |292 .ssc-tile-name span { font-size: 12px; font-weight: 430; white-space: nowrap; color: var(--ssc-text); }
297| `permissions` | 권한의 구조는 아래 표를 참조하세요. | |293 .ssc-tile.ssc-on .ssc-tile-name span { font-weight: 600; }
298| `plansDirectory` | **기본값**: `~/.claude/plans`. 계획 파일이 저장되는 위치를 사용자 정의합니다. 경로는 프로젝트 루트에 상대적입니다. | `"./plans"` |294 .ssc-tile-caption { font-size: 10.5px; color: var(--ssc-sub); margin-top: 5px; line-height: 1.35; }
299| `pluginSuggestionMarketplaces` | (Managed 설정만) 플러그인이 상황별 설치 제안으로 나타날 수 있는 마켓플레이스 이름입니다. 제안은 각 플러그인의 마켓플레이스 항목의 `relevance` 선언에서 나옵니다. 이름은 마켓플레이스가 머신에 등록되고 등록된 소스가 managed 설정에서도 선언될 때만 적용됩니다. 해당 이름에 대한 `extraKnownMarketplaces` 항목으로 또는 `strictKnownMarketplaces`의 항목으로 선언됩니다. 허용 목록 이름 아래에 다른 소스에서 등록된 마켓플레이스는 무시됩니다. 공식 마켓플레이스는 소스 요구 사항에서 제외됩니다: 이름만 허용 목록에 있으면 충분합니다. 이름은 공식 Anthropic 소스에서만 등록될 수 있기 때문입니다. | `["acme-corp-plugins"]` |295 .ssc-filemark {
300| `pluginTrustMessage` | (Managed 설정만) 설치 전에 표시되는 플러그인 신뢰 경고에 추가될 사용자 정의 메시지입니다. 이를 사용하여 조직 특정 컨텍스트를 추가합니다. 예를 들어 내부 마켓플레이스의 플러그인이 검증되었음을 확인합니다. | `"All plugins from our marketplace are approved by IT"` |296 position: absolute; left: 5px; right: 5px; bottom: 8px; display: inline-flex; align-items: center; justify-content: center; gap: 2px;
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"}` |297 font-size: 8.5px; color: var(--ssc-label); background: var(--ssc-bg); border: 1px solid var(--ssc-clay);
302| `preferredNotifChannel` | **기본값**: `"auto"`. 작업 완료 및 권한 프롬프트 알림 방법입니다. `"auto"`, `"terminal_bell"`, `"iterm2"`, `"iterm2_with_bell"`, `"kitty"`, `"ghostty"` 또는 `"notifications_disabled"`를 허용합니다. `"auto"`는 iTerm2, Ghostty 및 Kitty에서 데스크톱 알림을 보내고 다른 터미널에서는 아무것도 하지 않습니다. 모든 터미널에서 벨 문자를 울리려면 `"terminal_bell"`을 설정합니다. `/config`에 **알림**으로 표시됩니다. [터미널 벨 또는 알림 받기](/docs/ko/terminal-config#get-a-terminal-bell-or-notification)를 참조하세요 | `"terminal_bell"` |298 border-radius: 6px; padding: 2px 3px; white-space: nowrap; overflow: hidden;
303| `prefersReducedMotion` | 접근성을 위해 UI 애니메이션 (스피너, shimmer, flash 효과) 감소 또는 비활성화 | `true` |299 }
304| `prUrlTemplate` | PR 배지에 대한 URL 템플릿으로 바닥글 및 도구 결과 요약에 표시됩니다. `gh`에서 보고한 PR URL에서 `{host}`, `{owner}`, `{repo}`, `{number}` 및 `{url}`을 대체합니다. `github.com` 대신 내부 코드 검토 도구를 가리키도록 사용합니다. Claude의 산문에서 `#123` 자동 링크에는 영향을 주지 않습니다 | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |300 .ssc-filemark svg { flex-shrink: 0; }
305| `remoteControlAtStartup` | }각 대화형 세션이 시작될 때 [Remote Control](/docs/ko/remote-control)을 자동으로 연결합니다. `/remote-control`을 기다리는 대신 `true`로 설정하여 항상 자동 연결하거나, `false`로 설정하여 절대 자동 연결하지 않거나, 조직의 기본값을 따르려면 설정 해제합니다. `/config`에 **모든 세션에 대해 Remote Control 활성화**로 표시됩니다. [모든 세션에 대해 Remote Control 활성화](/docs/ko/remote-control#enable-remote-control-for-all-sessions)를 참조하세요 | `false` |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); }
306| `requiredMaximumVersion` | Managed 설정만. 시작할 수 있는 최대 Claude Code 버전입니다. 실행 중인 버전이 더 최신이면 Claude Code는 시작 시 종료되고 사용자에게 조직의 승인된 방법을 통해 승인된 버전을 설치하도록 지시합니다. `claude install <version>`도 작동할 수 있습니다. 배경 자동 업데이트 및 `claude update`는 천장 위의 버전을 건너뜁니다. 범위 내 설치는 범위 내로 유지됩니다. `claude update`, `claude install` 및 `claude doctor`는 사용자가 복구할 수 있도록 천장 위에서 계속 작동합니다. 이 설정보다 먼저 나온 버전은 무시합니다 | `"2.1.150"` |302 .ssc-ring {
307| `requiredMinimumVersion` | Managed 설정만. 시작하는 데 필요한 최소 Claude Code 버전입니다. 실행 중인 버전이 더 오래되면 Claude Code는 시작 시 종료되고 사용자에게 조직의 승인된 방법을 통해 업데이트하도록 지시합니다. `claude update`, `claude install` 및 `claude doctor`는 사용자가 복구할 수 있도록 바닥 아래에서 계속 작동합니다. 시작을 차단하지 않지만 다운그레이드를 방지하는 `minimumVersion`과 다릅니다. 이 설정보다 먼저 나온 버전은 무시합니다 | `"2.1.150"` |303 position: absolute; border: 2px solid var(--ssc-clay); border-radius: 18px; pointer-events: none;
308| `respectGitignore` | **기본값**: `true`. `@` 파일 선택기가 `.gitignore` 패턴을 존중할지 여부를 제어합니다. `true`일 때 `.gitignore` 패턴과 일치하는 파일은 제안에서 제외됩니다 | `false` |304 transition: left 0.35s ease, top 0.35s ease, width 0.35s ease, height 0.35s ease;
309| `respondToBashCommands` | }**기본값**: `true`. 입력 상자 `!` 셸 명령이 실행된 후 Claude가 응답할지 여부입니다. 응답 없이 명령 출력을 컨텍스트에 추가하려면 `false`로 설정합니다. [접두사 `!`를 사용한 셸 모드](/docs/ko/interactive-mode#shell-mode-with-prefix)를 참조하세요. Claude Code v2.1.186 이상이 필요합니다 | `false` |305 }
310| `showClearContextOnPlanAccept` | **기본값**: `false`. 계획 수락 화면에서 "컨텍스트 지우기" 옵션을 표시합니다. 옵션을 복원하려면 `true`로 설정합니다 | `true` |306 .ssc-ring-label {
311| `showThinkingSummaries` | **기본값**: `false`. 대화형 세션에서 [확장 사고](/docs/ko/model-config#extended-thinking) 요약을 표시합니다. 설정되지 않거나 `false`일 때 사고 블록은 API에 의해 편집되고 축소된 스텁으로 표시됩니다. 편집은 표시되는 내용만 변경하고 모델이 생성하는 내용은 변경하지 않습니다. 사고 지출을 줄이려면 [예산을 낮추거나 사고를 비활성화](/docs/ko/model-config#extended-thinking)하세요. 이 설정은 비대화형 모드 (`-p`), Agent SDK 또는 VS Code와 같은 IDE 확장에서는 영향을 주지 않습니다 | `true` |307 position: absolute; font-size: 12px; font-weight: 600; color: var(--ssc-label); white-space: nowrap; pointer-events: none;
312| `showTurnDuration` | **기본값**: `true`. 응답 후 턴 지속 시간 메시지를 표시합니다 (예: "Cooked for 1m 6s"). `/config`에 **턴 지속 시간 표시**로 표시됩니다 | `false` |308 transition: left 0.35s ease, top 0.35s ease;
313| `skillListingBudgetFraction` | **기본값**: `0.01`. Claude가 각 턴에 보는 [skill 목록](/docs/ko/skills#skill-descriptions-are-cut-short)을 위해 예약된 모델의 컨텍스트 윈도우의 분수입니다. 목록이 예산을 초과하면 가장 적게 사용되는 skills의 설명이 베어 이름으로 축소되어 Claude가 여전히 호출할 수 있지만 이유를 보지 못합니다. 더 많은 설명을 보이려면 높이고 턴당 더 많은 컨텍스트를 사용합니다. 더 많은 skills을 [`skillListingMaxDescChars`](#available-settings) 아래에 맞추려면 낮춥니다 | `0.02` |309 }
314| `skillListingMaxDescChars` | **기본값**: `1536`. Claude가 각 턴에 보는 [skill 목록](/docs/ko/skills#skill-descriptions-are-cut-short)의 결합된 `description` 및 `when_to_use` 텍스트에 대한 skill별 문자 제한입니다. 이 길이보다 긴 텍스트는 잘립니다. 더 긴 설명을 유지하려면 높이고 턴당 더 많은 컨텍스트를 사용합니다. 더 많은 skills을 [`skillListingBudgetFraction`](#available-settings)에 맞추려면 낮춥니다 | `2048` |310 `}</style>
315| `skillOverrides` | }skill 이름으로 키가 지정된 skill별 가시성 재정의입니다. 값은 `"on"`, `"name-only"`, `"user-invocable-only"` 또는 `"off"`입니다. SKILL.md를 편집하지 않고 skill을 숨기거나 축소할 수 있습니다. 플러그인 skills에는 적용되지 않으며, 이는 `/plugin`을 통해 관리됩니다. `/skills` 메뉴는 이를 `.claude/settings.local.json`에 작성합니다. [설정에서 skill 가시성 재정의](/docs/ko/skills#override-skill-visibility-from-settings)를 참조하세요. Claude Code v2.1.129 이상이 필요합니다 | `{"legacy-context": "name-only", "deploy": "off"}` |311
316| `skipWebFetchPreflight` | [WebFetch 도메인 안전 검사](/docs/ko/data-usage#webfetch-domain-safety-check)를 건너뜁니다. 이 검사는 각 요청된 호스트명을 가져오기 전에 `api.anthropic.com`으로 전송합니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry 배포와 같이 Anthropic으로의 트래픽을 차단하는 환경에서 `true`로 설정합니다. 건너뛰면 WebFetch는 차단 목록을 참조하지 않고 모든 URL을 시도합니다 | `true` |312 <div className="ssc-head">
317| `spinnerTipsEnabled` | **기본값**: `true`. Claude가 작업 중일 때 스피너에 팁을 표시합니다. 팁을 비활성화하려면 `false`로 설정합니다 | `false` |313 <div className="ssc-files" role="group" aria-label="Settings file">
318| `spinnerTipsOverride` | 사용자 정의 문자열로 스피너 팁을 재정의합니다. `tips`: 팁 문자열 배열. `excludeDefault`: `true`이면 사용자 정의 팁만 표시하고, `false`이거나 없으면 사용자 정의 팁이 기본 제공 팁과 병합됩니다 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |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>)}
319| `spinnerVerbs` | 스피너에 표시되는 작업 동사를 사용자 정의합니다. `mode`를 `"replace"`로 설정하여 동사만 사용하거나 `"append"`로 설정하여 기본값에 추가합니다 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |315 </div>
320| `sshConfigs` | [Desktop](/docs/ko/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"}]` |316 <button type="button" className="ssc-fsbtn" onClick={toggleFullscreen} aria-label={isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'} title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}>{isFullscreen ? '⤡' : '⛶'}</button>
321| `statusLine` | 컨텍스트를 표시하기 위한 사용자 정의 상태 줄을 구성합니다. 객체의 선택적 `padding`, `refreshInterval` 및 `hideVimModeIndicator` 필드는 간격, 주기적 재실행 및 프롬프트 아래의 기본 제공 vim 모드 표시기 숨김 여부를 제어합니다. [`statusLine` 문서](/docs/ko/statusline#manually-configure-a-status-line)를 참조하세요 | `{"type": "command", "command": "~/.claude/statusline.sh"}` |317 </div>
322| `strictKnownMarketplaces` | (Managed 설정만) 플러그인 마켓플레이스 소스의 허용 목록입니다. 정의되지 않음 = 제한 없음, 빈 배열 = 잠금. 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용되므로 정책이 설정되기 전에 추가된 마켓플레이스는 플러그인을 가져오는 데 사용할 수 없습니다. [Managed 마켓플레이스 제한](/docs/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요 | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |318
323| `strictPluginOnlyCustomization` | (Managed 설정만) 플러그인 또는 managed 설정에서만 올 수 있도록 사용자 및 프로젝트 소스에서 skills, agents, hooks 및 MCP 서버를 차단합니다. `true`는 네 가지 모두를 잠그고, 배열은 명명된 것만 잠급니다. [`strictPluginOnlyCustomization`](#strictpluginonlycustomization)을 참조하세요 | `["skills", "hooks"]` |319 <div ref={frameRef} className="ssc-frame" style={{
324| `syntaxHighlightingDisabled` | diffs, 코드 블록 및 파일 미리보기에서 구문 강조 비활성화 | `true` |320 height: CANVAS_H * scale + 'px'
325| `teammateMode` | **기본값**: `in-process`. [에이전트 팀](/docs/ko/agent-teams) 팀원이 표시되는 방식입니다. `in-process`, `auto` (tmux 또는 iTerm2에서 분할 창 선택, 그 외에는 in-process), `tmux` (tmux 또는 iTerm2를 사용하여 분할 창 선택, 터미널에서 감지됨) 또는 }`iterm2` (iTerm2 기본 분할 창 via `it2` CLI, v2.1.186에서 추가됨)를 허용합니다. 기본값은 v2.1.179에서 `auto`에서 변경되었습니다. `--teammate-mode`은 한 세션에 대해 이를 재정의합니다. [디스플레이 모드 선택](/docs/ko/agent-teams#choose-a-display-mode)을 참조하세요 | `"auto"` |321 }}>
326| `terminalProgressBarEnabled` | **기본값**: `true`. 지원되는 터미널에서 터미널 진행률 표시줄을 표시합니다: ConEmu, Ghostty 1.2.0+ 및 iTerm2 3.6.6+. `/config`에 **터미널 진행률 표시줄**로 표시됩니다 | `false` |322 <div className="ssc-canvas" style={{
327| `theme` | }**기본값**: `"dark"`. 인터페이스의 색상 테마입니다. `"auto"`, `"dark"`, `"light"`, `"dark-daltonized"`, `"light-daltonized"`, `"dark-ansi"`, `"light-ansi"` 또는 `"custom:<slug>"` 또는 `"custom:<plugin-name>:<slug>"`과 같은 사용자 정의 테마 참조를 허용합니다. [사용자 정의 테마 만들기](/docs/ko/terminal-config#create-a-custom-theme)를 참조하세요. `/config`에 **테마**로 표시됩니다 | `"dark"` |323 transform: 'scale(' + scale + ')'
328| `tui` | 터미널 UI 렌더러입니다. 깜박임 없는 [alt-screen 렌더러](/docs/ko/fullscreen)가 있는 가상화된 스크롤백을 위해 `"fullscreen"`을 사용합니다. 클래식 메인 화면 렌더러를 위해 `"default"`를 사용합니다. `/tui`를 통해 설정합니다. [`CLAUDE_CODE_NO_FLICKER`](/docs/ko/env-vars) 환경 변수도 설정할 수 있습니다. [에이전트 보기](/docs/ko/agent-view)에서 열린 배경 세션은 이 설정과 관계없이 항상 fullscreen 렌더러를 사용합니다 | `"fullscreen"` |324 }}>
329| `ultracode` | 세션에 대해 [ultracode](/docs/ko/workflows#let-claude-decide-with-ultracode)를 켭니다. 세션 전용이며 `settings.json`에서 읽지 않습니다. `/effort ultracode`, `--settings` 또는 Agent SDK 제어 요청을 통해 설정합니다. }ultracode를 이미 켜진 상태로 세션을 시작하려면 `claude --effort ultracode`로 시작합니다. Claude Code v2.1.203 이상이 필요합니다 | `true` |325 <div className="ssc-machine" style={{
330| `useAutoModeDuringPlan` | **기본값**: `true`. 자동 모드를 사용할 수 있을 때 계획 모드가 자동 모드 의미론을 사용할지 여부입니다. 공유 프로젝트 설정에서는 읽지 않음. `/config`에 "계획 중 자동 모드 사용"으로 표시됨 | `false` |326 left: '10px',
331| `verbose` | }**기본값**: `false`. 잘린 요약 대신 전체 도구 출력을 표시합니다. `/config`에 **상세 출력**으로 표시됩니다. `--verbose` 플래그는 한 세션에 대해 이를 재정의합니다 | `true` |327 width: '430px'
332| `viewMode` | 시작 시 기본 트랜스크립트 보기 모드입니다. `"default"`, `"verbose"` 또는 `"focus"`를 허용합니다. 설정되면 sticky `/focus` 선택을 재정의합니다. `--verbose` 플래그는 한 세션에 대해 이를 재정의합니다 | `"verbose"` |328 }} />
333| `vimInsertModeRemaps` | }[vim 편집기 모드](/docs/ko/interactive-mode#vim-editor-mode)에서 Escape로 두 키 INSERT 모드 시퀀스를 매핑합니다. 각 키는 정확히 두 개의 인쇄 가능한 문자이며 순서대로 입력되고 `"<Esc>"`는 유일하게 지원되는 대상입니다. 다른 항목은 무시됩니다. 사용자, `--settings` 플래그 및 managed 설정에서만 읽습니다. 저장소의 체크인된 설정이 키 입력을 다시 매핑할 수 없습니다. `editorMode`가 `"vim"`이 아니면 영향을 주지 않습니다. [INSERT 모드 키 시퀀스 다시 매핑](/docs/ko/interactive-mode#remap-insert-mode-key-sequences)을 참조하세요. Claude Code v2.1.208 이상이 필요합니다 | `{"jj": "<Esc>"}` |329 <span className="ssc-machine-label" style={{
334| `voice` | [음성 받아쓰기](/docs/ko/voice-dictation) 설정입니다. `enabled`는 받아쓰기를 켜고, `mode`는 `"hold"` 또는 `"tap"`을 선택하고, `autoSubmit`은 hold 모드에서 키 릴리스 시 프롬프트를 전송합니다. `/voice`를 실행할 때 자동으로 작성됩니다. Claude.ai 계정이 필요합니다 | `{ "enabled": true, "mode": "tap" }` |330 left: '30px'
335| `voiceEnabled` | `voice.enabled`에 대한 레거시 별칭입니다. `voice` 객체를 선호합니다 | `true` |331 }}><LaptopIcon />Your machine{fileAt.machine === 'you' && <span className="ssc-machine-filemark ssc-mono"><FileIcon />{selFile.path}</span>}</span>
336| `wheelScrollAccelerationEnabled` | }**기본값**: `true`. [fullscreen 렌더링](/docs/ko/fullscreen#mouse-wheel-scrolling)에서 빠른 스크롤 중에 마우스 휠 스크롤 속도를 가속화합니다. 휠 노치당 일정한 스크롤 속도를 원하면 `false`로 설정합니다. Claude Code v2.1.174 이상이 필요합니다 | `false` |332 <div className="ssc-machine" style={{
337| `workflowKeywordTriggerEnabled` | }**기본값**: `true`. 프롬프트의 단어 `ultracode`이 [동적 워크플로우](/docs/ko/workflows#ask-for-a-workflow-in-your-prompt)를 트리거할지 여부입니다. 하나를 트리거하지 않고 단어를 입력하려면 `false`로 설정합니다. `ultracode` 노력 설정, `/workflows` 및 저장된 워크플로우 명령은 영향을 받지 않습니다. `/config`에 **Ultracode 키워드 트리거**로 표시됩니다. v2.1.157에서 추가됨; v2.1.160 이전에 트리거 키워드는 `workflow`였습니다 | `false` |333 left: '460px',
338| `wslInheritsWindowsSettings` | (Windows managed 설정만) `true`일 때 WSL의 Claude Code는 `/etc/claude-code`에 추가하여 Windows 정책 체인에서 managed 설정을 읽으며 Windows 소스가 우선합니다. Windows 관리자가 작성해야 하는 HKLM 레지스트리 키 또는 `C:\Program Files\ClaudeCode\managed-settings.json`에서 설정된 경우에만 적용됩니다. HKCU 정책도 WSL에 적용되려면 플래그를 HKCU 자체에도 설정해야 합니다. 기본 Windows에는 영향을 주지 않습니다 | `true` |334 width: '200px'
339 335 }} />
340<h3 id="global-config-settings">336 <span className="ssc-machine-label" style={{
341 전역 구성 설정337 left: '470px'
342</h3>338 }}><LaptopIcon />A teammate’s machine</span>
343 339 <div className="ssc-machine" style={{
344이러한 설정은 `settings.json`이 아닌 `~/.claude.json`에 저장됩니다. 이들을 `settings.json`에 추가하면 스키마 검증 오류가 발생합니다.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/ko/settings-reference)으로 이동하세요. 여기에는 설정한 파일, 기본값, 예제가 있는 모든 키가 나열됩니다.
377</Tip>
378
379Claude Code는 `~/.claude/settings.json`과 같은 JSON 설정 파일에서 설정을 읽습니다. 여러 위치에서 찾으며, [읽는 파일이 설정이 누구에게 적용되는지 결정합니다](#settings-files-and-who-they-affect). 이 페이지에서는 이러한 파일을 다룹니다: 설정을 어느 파일에 넣을지, 설정을 변경하고 적용되었는지 확인하는 방법, 동일한 키가 여러 파일에 설정되어 있을 때 Claude Code가 사용하는 값입니다. [권한 구성](/docs/ko/permissions)에서는 Claude Code가 묻지 않고 실행할 수 있는 것과 `allow`, `ask`, `deny` 규칙을 작성하는 방법을 다룹니다.
345 380
346<Note>381<Note>
347 v2.1.119 이전 버전은 `theme`, `verbose`, `editorMode`, `autoCompactEnabled` 및 `preferredNotifChannel`을 포함한 여러 `/config` 설정 키를 `settings.json` 대신 여기에 저장합니다.382 이 페이지는 머신에서 실행되는 Claude Code를 다룹니다: 터미널, [VS Code](/docs/ko/vs-code) 및 [JetBrains](/docs/ko/jetbrains) 확장, [데스크톱 앱](/docs/ko/desktop)은 모두 동일한 설정 파일을 읽습니다. [Claude Code on the web](/docs/ko/claude-code-on-the-web)의 클라우드 세션은 다른 머신에서 실행되며 일부만 읽습니다. [클라우드 세션의 설정](#settings-in-cloud-sessions)을 참조하세요.
348</Note>383</Note>
349 384
350| 키 | 설명 | 예제 |385<span id="settings-files" />
351| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------- |
352| `autoConnectIde` | **기본값**: `false`. Claude Code가 외부 터미널에서 시작될 때 실행 중인 IDE에 자동으로 연결합니다. VS Code 또는 JetBrains 터미널 외부에서 실행할 때 `/config`에 \*\*IDE에 자동 연결 (외부 터미널)\*\*로 표시됩니다. [`CLAUDE_CODE_AUTO_CONNECT_IDE`](/docs/ko/env-vars) 환경 변수가 설정되면 이를 재정의합니다 | `true` |
353| `autoInstallIdeExtension` | **기본값**: `true`. VS Code 터미널에서 실행할 때 Claude Code IDE 확장을 자동으로 설치합니다. VS Code 또는 JetBrains 터미널 내에서 실행할 때 `/config`에 **IDE 확장 자동 설치**로 표시됩니다. [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/docs/ko/env-vars) 환경 변수도 설정할 수 있습니다 | `false` |
354| `externalEditorContext` | **기본값**: `false`. `Ctrl+G`로 외부 편집기를 열 때 Claude의 이전 응답을 `#` 주석 처리된 컨텍스트로 앞에 붙입니다. `/config`에 **외부 편집기에 마지막 응답 표시**로 표시됩니다 | `true` |
355| `permissionExplainerEnabled` | **기본값**: `true`. Bash 또는 PowerShell 권한 프롬프트에서 `Ctrl+E`를 누를 때 모델 생성 [명령 설명](/docs/ko/permissions#permission-system)을 표시합니다. 바로 가기를 끄려면 `false`로 설정합니다 | `false` |
356| `teammateDefaultModel` | [에이전트 팀](/docs/ko/agent-teams) 팀원을 위한 기본 모델로 spawn 프롬프트가 하나를 지정하지 않을 때 사용됩니다. `"sonnet"`과 같은 모델 별칭으로 설정하거나 lead의 현재 `/model` 선택을 상속하려면 `null`로 설정합니다. `/config`에 **기본 팀원 모델**로 표시됩니다 | `"sonnet"` |
357| `workflowSizeGuideline` | }**기본값**: `unrestricted`, 이는 지침을 보내지 않습니다. 동적 워크플로우가 작성하는 [에이전트 수를 목표로 설정](/docs/ko/workflows#set-a-size-guideline)합니다. Claude Code는 값을 Claude에 조언으로 보내며 적용된 상한이 아닙니다. `unrestricted`, `small`, `medium` 또는 `large`를 허용합니다. `/config`에 **동적 워크플로우 크기**로 표시됩니다. `/config workflowSizeGuideline=small`으로 직접 설정할 수도 있습니다. Claude Code v2.1.202 이상이 필요합니다. }지침의 에이전트 수는 [`Large workflow` 경고](/docs/ko/workflows#cost)의 기본 임계값도 대체합니다. 이 동작은 Claude Code v2.1.203 이상이 필요합니다 | `"small"` |
358
359<h3 id="worktree-settings">
360 Worktree 설정
361</h3>
362 386
363`--worktree`가 git worktrees를 생성하고 관리하는 방식을 구성합니다.387<span id="configuration-scopes" />
364 388
365| 키 | 설명 | 예제 |389<span id="available-scopes" />
366| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |
367| `worktree.baseRef` | 새 worktrees가 분기하는 ref입니다. `"fresh"` (기본값)은 깨끗한 트리와 일치하는 원격에 대해 `origin/<default-branch>`에서 분기합니다. `"head"`는 현재 local `HEAD`에서 분기하므로 푸시되지 않은 커밋 및 feature-branch 상태가 worktree에 있습니다. 연결된 worktree 내에서 `"head"`는 해당 worktree의 `HEAD`로 해석되며 메인 체크아웃의 것이 아닙니다. `--worktree`, `EnterWorktree` 도구 및 subagent 격리에 적용됩니다 | `"head"` |
368| `worktree.symlinkDirectories` | 각 worktree에서 중복을 피하기 위해 메인 저장소에서 symlink할 디렉토리입니다. 기본적으로 디렉토리는 symlink되지 않습니다 | `["node_modules", ".cache"]` |
369| `worktree.sparsePaths` | git sparse-checkout을 통해 각 worktree에서 체크아웃할 디렉토리입니다. 나열된 경로만 디스크에 작성되므로 대규모 monorepos에서 더 빠릅니다. sparse worktree가 존재하는 동안 git은 저장소의 공유 `.git/config`에서 `extensions.worktreeConfig`를 활성화합니다. [필요한 디렉토리만 체크아웃](/docs/ko/large-codebases#check-out-only-the-directories-you-need)을 참조하세요 | `["packages/my-app", "shared/utils"]` |
370| `worktree.bgIsolation` | }[배경 세션](/docs/ko/agent-view#how-file-edits-are-isolated)의 격리 모드입니다. `"worktree"` (기본값)은 `EnterWorktree`가 호출될 때까지 메인 체크아웃에서 `Edit`/`Write`를 차단합니다. }git 저장소 외부에서 실패하는 [`WorktreeCreate` hook](/docs/ko/worktrees#non-git-version-control)이 블록을 해제하여 세션이 작업 디렉토리를 제자리에서 편집할 수 있도록 합니다. Claude Code v2.1.203 이상이 필요합니다. `"none"`은 배경 작업이 작업 복사본을 직접 편집하도록 허용합니다. Claude Code v2.1.143 이상이 필요합니다 | `"none"` |
371 390
372worktrees에 `.env`와 같은 gitignored 파일을 복사하려면 설정 대신 프로젝트 루트의 [`.worktreeinclude` 파일](/docs/ko/worktrees#copy-gitignored-files-into-worktrees)을 사용합니다.391<span id="when-to-use-each-scope" />
373 392
374<h3 id="permission-settings">393<span id="what-uses-scopes" />
375 권한 설정
376</h3>
377 394
378| 키 | 설명 | 예제 |395<span id="subagent-configuration" />
379| :---------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |
380| `allow` | 도구 사용을 허용하는 권한 규칙 배열입니다. 도구 이름 globs는 `mcp__<server>__get_*`과 같이 리터럴 `mcp__<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/ko/permissions#tool-specific-permission-rules)을 참조하세요 | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |
383| `additionalDirectories` | Claude가 액세스할 수 있는 추가 [작업 디렉토리](/docs/ko/permissions#working-directories)입니다. 대부분의 `.claude/` 구성은 이러한 디렉토리에서 [발견되지 않습니다](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |
384| `defaultMode` | Claude Code를 열 때 기본 [권한 모드](/docs/ko/permission-modes)입니다. 유효한 값: `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`, 그리고 }`manual` (CLI 및 VS Code와 JetBrains 확장에서 Manual로 표시되는 모드의 별칭). `manual` 별칭은 Claude Code v2.1.200 이상이 필요합니다. }v2.1.142부터 프로젝트 또는 local 설정 (`.claude/settings.json`, `.claude/settings.local.json`)에서 설정되면 `auto`가 무시되므로 저장소가 자신에게 자동 모드를 부여할 수 없습니다. 대신 `~/.claude/settings.json`에서 설정합니다. `--permission-mode` CLI 플래그는 단일 세션에 대해 이 설정을 재정의합니다 | `"acceptEdits"` |
385| `disableBypassPermissionsMode` | `bypassPermissions` 모드가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. 이는 `--dangerously-skip-permissions` 명령줄 플래그를 비활성화합니다. 일반적으로 [managed 설정](/docs/ko/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>
391 396
392권한 규칙은 `Tool` 또는 `Tool(specifier)` 형식을 따릅니다. 규칙은 순서대로 평가됩니다: 먼저 거부 규칙, 그 다음 요청, 그 다음 허용. 첫 번째 일치 규칙이 우승합니다. 규칙 특이성과 관계없이 결과를 결정합니다. [권한 규칙 평가 순서](/docs/ko/permissions#manage-permissions)를 참조하세요.397<span id="where-settings-live" />
393 398
394빠른 예제:399<h2 id="settings-files-and-who-they-affect">
400 설정 파일 및 영향을 받는 대상
401</h2>
395 402
396| 규칙 | 효과 |403Claude Code는 네 개의 파일에서 설정을 읽으며, 조직은 claude.ai 콘솔에서 관리되는 설정을 제공할 수도 있습니다. 각 소스는 범위를 가지고 있습니다. 즉, 설정이 적용되는 사람과 프로젝트의 집합으로, 개인, 프로젝트의 모든 사람, 또는 조직의 모든 사람일 수 있습니다.
397| :----------------------------- | :--------------------------- |
398| `Bash` | 모든 Bash 명령과 일치 |
399| `Bash(npm run *)` | `npm run`으로 시작하는 명령과 일치 |
400| `Read(./.env)` | `.env` 파일 읽기와 일치 |
401| `WebFetch(domain:example.com)` | example.com에 대한 fetch 요청과 일치 |
402 404
403Read, Edit, WebFetch, MCP 및 Agent 규칙에 대한 와일드카드 동작, 도구 특정 패턴 및 Bash 패턴의 보안 제한을 포함한 완전한 규칙 구문 참조는 [권한 규칙 구문](/docs/ko/permissions#permission-rule-syntax)을 참조하세요.405| 범위 | 파일 | 영향을 받는 대상 | 용도 |
406| :------ | :------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- | :------------------------------------ |
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/ko/managed-settings#delivery-mechanisms) | 조직이 배포하는 모든 대상. 몇 가지 [보안 관련 예외](#exceptions-to-managed-settings-precedence)를 제외하고 설정한 것이 이를 재정의하지 않음 | 보안 정책 및 규정 준수 요구사항 |
404 411
405<h3 id="sandbox-settings">412파일 열에서 `~/.claude`는 홈 디렉토리의 `.claude` 폴더이고, 단순 `.claude`는 프로젝트 내부의 `.claude` 폴더입니다.
406 Sandbox 설정
407</h3>
408 413
409고급 샌드박싱 동작을 구성합니다. 샌드박싱은 bash 명령을 파일 시스템 및 네트워크에서 격리합니다. 자세한 내용은 [Sandboxing](/docs/ko/sandboxing)을 참조하세요.414<span id="where-each-file-applies" />
410
411| 키 | 설명 | 예제 |
412| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
413| `enabled` | bash 샌드박싱 활성화 (macOS, Linux 및 WSL2). 기본값: false | `true` |
414| `failIfUnavailable` | `sandbox.enabled`가 true이지만 샌드박스를 시작할 수 없는 경우 (종속성 누락, 지원되지 않는 플랫폼) 시작 시 오류로 종료합니다. false (기본값)일 때 경고가 표시되고 명령이 샌드박싱되지 않은 상태로 실행됩니다. Managed 설정 배포에서 샌드박싱을 하드 게이트로 요구하는 경우를 위한 것입니다 | `true` |
415| `autoAllowBashIfSandboxed` | 샌드박싱되면 bash 명령 자동 승인. 기본값: true | `true` |
416| `excludedCommands` | 샌드박스 외부에서 실행해야 하는 명령 | `["docker *"]` |
417| `allowUnsandboxedCommands` | `dangerouslyDisableSandbox` 매개변수를 통해 샌드박스 외부에서 명령을 실행하도록 허용합니다. `false`로 설정되면 `dangerouslyDisableSandbox` 이스케이프 해치가 완전히 비활성화되고 모든 명령은 샌드박싱되거나 `excludedCommands`에 있어야 합니다. 엄격한 샌드박싱이 필요한 엔터프라이즈 정책에 유용합니다. 기본값: true | `false` |
418| `filesystem.allowWrite` | 샌드박싱된 명령이 쓸 수 있는 추가 경로입니다. 배열은 모든 설정 범위에서 병합됩니다: 사용자, 프로젝트 및 managed 경로가 결합되고 대체되지 않습니다. `Edit(...)` 허용 권한 규칙의 경로와도 병합됩니다. [경로 접두사](#sandbox-path-prefixes)를 참조하세요. | `["/tmp/build", "~/.kube"]` |
419| `filesystem.denyWrite` | 샌드박싱된 명령이 쓸 수 없는 경로입니다. 배열은 모든 설정 범위에서 병합됩니다. `Edit(...)` 거부 권한 규칙의 경로와도 병합됩니다. | `["/etc", "/usr/local/bin"]` |
420| `filesystem.denyRead` | 샌드박싱된 명령이 읽을 수 없는 경로입니다. 배열은 모든 설정 범위에서 병합됩니다. `Read(...)` 거부 권한 규칙의 경로와도 병합됩니다. | `["~/.aws/credentials"]` |
421| `filesystem.allowRead` | `denyRead` 영역 내에서 읽기를 다시 허용할 경로입니다. `denyRead`보다 우선합니다. 배열은 모든 설정 범위에서 병합됩니다. 이를 사용하여 작업 공간 전용 읽기 액세스 패턴을 만듭니다. | `["."]` |
422| `filesystem.allowManagedReadPathsOnly` | (Managed 설정만) Managed 설정의 `filesystem.allowRead` 경로만 존중됩니다. `denyRead`는 여전히 모든 소스에서 병합됩니다. 기본값: false | `true` |
423| `credentials.files` | }샌드박싱된 명령이 읽을 수 없는 자격 증명 파일 또는 디렉토리입니다. `filesystem.denyRead`와 동일한 읽기 블록을 적용합니다. 별도의 키는 자격 증명 경로를 `credentials.envVars`와 함께 그룹화하고 일반 파일 시스템 규칙과 분리합니다. 각 항목은 `{ "path": "...", "mode": "deny" }`입니다. 경로는 `filesystem.*` 설정과 동일한 [접두사](#sandbox-path-prefixes)를 사용합니다. 배열은 모든 설정 범위에서 병합됩니다. `deny`만 지원됩니다. Claude Code v2.1.187 이상이 필요합니다. | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |
424| `credentials.envVars` | }[샌드박싱된 명령에서 보호](/docs/ko/sandboxing#protect-credentials)할 환경 변수입니다. 각 항목에는 `name` 및 `mode`가 있습니다. 이름은 문자 또는 밑줄로 시작하고 문자, 숫자 및 밑줄만 포함해야 합니다. `deny`는 샌드박싱된 명령의 환경에서 변수를 제거합니다. Claude Code v2.1.187 이상이 필요합니다. }`mask`는 샌드박스 내에서 변수를 세션별 sentinel 값으로 바꾸고 샌드박스 프록시는 해당 항목의 `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` | 샌드박스 프록시가 `mask` 항목의 실제 값을 대체할 호스트입니다. 각 호스트는 `network.allowedDomains`에서도 정확히 또는 와일드카드로 포함되어야 합니다. 설정되지 않으면 프록시가 `network.allowedDomains`의 모든 호스트에 대해 값을 대체합니다. `mode`가 `deny`일 때 허용되지만 무시됩니다. Claude Code v2.1.199 이상이 필요합니다. } | `["api.github.com"]` |
426| `credentials.allowPlaintextInject` | 일반 HTTP 요청뿐만 아니라 TLS 종료 HTTPS에서 `mask` 대체를 허용합니다. 일반 HTTP에서 업스트림 ID는 확인되지 않고 자격 증명은 평문으로 이동하므로 신뢰할 수 있는 테스트 네트워크 외부에서는 이를 끕니다. 사용자, managed 또는 CLI `--settings` 설정에서만 적용되며 `.claude/settings.json` 또는 `.claude/settings.local.json`에서는 적용되지 않습니다. 기본값: false. Claude Code v2.1.199 이상이 필요합니다. } | `true` |
427| `network.allowUnixSockets` | (macOS만) Unix 소켓 경로 샌드박스에서 액세스 가능. Linux 및 WSL2에서는 무시되며, seccomp 필터가 소켓 경로를 검사할 수 없습니다. 대신 `allowAllUnixSockets`를 사용합니다. | `["~/.ssh/agent-socket"]` |
428| `network.allowAllUnixSockets` | 샌드박스에서 모든 Unix 소켓 연결을 허용합니다. Linux 및 WSL2에서 이는 `socket(AF_UNIX, ...)` 호출을 차단하는 seccomp 필터를 건너뛰므로 Unix 소켓을 허용하는 유일한 방법입니다. 기본값: false | `true` |
429| `network.allowLocalBinding` | localhost 포트에 바인딩 허용 (macOS만). 기본값: false | `true` |
430| `network.allowMachLookup` | 샌드박스가 조회할 수 있는 추가 XPC/Mach 서비스 이름 (macOS만). 접두사 일치를 위해 단일 후행 `*`를 지원합니다. iOS Simulator 또는 Playwright와 같이 XPC를 통해 통신하는 도구에 필요합니다. | `["com.apple.coresimulator.*"]` |
431| `network.allowedDomains` | 아웃바운드 네트워크 트래픽을 허용할 도메인 배열입니다. 와일드카드를 지원합니다 (예: `*.example.com`). | `["github.com", "*.npmjs.org"]` |
432| `network.deniedDomains` | 아웃바운드 네트워크 트래픽을 차단할 도메인 배열입니다. `allowedDomains`와 동일한 와일드카드 구문을 지원합니다. 둘 다 일치할 때 `allowedDomains`보다 우선합니다. 모든 설정 소스와 관계없이 병합됩니다 | `["sensitive.cloud.example.com"]` |
433| `network.allowManagedDomainsOnly` | (Managed 설정만) Managed 설정의 `allowedDomains` 및 `WebFetch(domain:...)` 허용 규칙만 존중됩니다. 사용자, 프로젝트 및 local 설정의 도메인은 무시됩니다. 허용되지 않은 도메인은 사용자에게 메시지를 표시하지 않고 자동으로 차단됩니다. 거부된 도메인은 여전히 모든 소스에서 존중됩니다. 기본값: false | `true` |
434| `network.httpProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 HTTP 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8080` |
435| `network.socksProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 SOCKS5 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8081` |
436| `network.tlsTerminate` | }실험적입니다. 샌드박스 프록시 내에서 TLS를 종료하여 HTTPS 요청의 내용을 읽을 수 있습니다. `mask` [자격 증명 대체](/docs/ko/sandboxing#protect-credentials)에 필요합니다. 세션에 대한 임시 인증 기관을 생성하려면 `{}`로 설정하거나 자신의 것을 사용하려면 `caCertPath` 및 `caKeyPath`로 설정합니다. 사용자, managed 또는 CLI `--settings` 설정에서만 적용되며 `.claude/settings.json` 또는 `.claude/settings.local.json`에서는 적용되지 않습니다. Claude Code v2.1.199 이상이 필요합니다. } | `{}` |
437| `enableWeakerNestedSandbox` | 권한이 없는 Docker 환경에서 더 약한 샌드박스를 활성화합니다 (Linux 및 WSL2만). **보안을 감소시킵니다.** 기본값: false | `true` |
438| `enableWeakerNetworkIsolation` | (macOS만) 샌드박스에서 시스템 TLS 신뢰 서비스 (`com.apple.trustd.agent`)에 대한 액세스를 허용합니다. MITM 프록시 및 사용자 정의 CA를 사용하는 `httpProxyPort`를 사용할 때 `gh`, `gcloud` 및 `terraform`과 같은 Go 기반 도구가 TLS 인증서를 확인하는 데 필요합니다. **보안을 감소시킵니다** 잠재적 데이터 유출 경로를 열어서. 기본값: false | `true` |
439| `allowAppleEvents` | (macOS만) 샌드박싱된 명령이 Apple Events를 보낼 수 있도록 허용합니다. `open`, `osascript` 및 URL을 브라우저에서 열 수 있는 도구에 필요하며, 그렇지 않으면 오류 `-600`으로 실패합니다. **코드 실행 격리를 제거합니다.** 샌드박싱된 명령은 사용자 프롬프트 없이 다른 애플리케이션을 샌드박싱되지 않은 상태로 시작할 수 있습니다. 또한 Terminal과 같은 실행 중인 애플리케이션에 AppleScript 명령을 보낼 수 있으며, 이는 앱별 macOS 자동화 동의 프롬프트 (TCC)의 대상입니다. 사용자, managed 또는 CLI 설정에서만 적용되며 프로젝트 설정에서는 적용되지 않습니다. 기본값: false | `true` |
440| `bwrapPath` | (Managed 설정만, Linux/WSL2) bubblewrap (`bwrap`) 바이너리의 절대 경로입니다. `PATH`를 통한 자동 감지를 재정의합니다. [managed 설정](/docs/ko/settings#settings-files)에서만 적용되며 사용자 또는 프로젝트 설정에서는 적용되지 않습니다. `bwrap`이 managed 환경에서 비표준 위치에 설치된 경우 유용합니다. | `/opt/admin/bwrap` |
441| `socatPath` | (Managed 설정만, Linux/WSL2) 샌드박스 네트워크 프록시에 사용되는 `socat` 바이너리의 절대 경로입니다. `PATH`를 통한 자동 감지를 재정의합니다. Managed 설정에서만 적용됩니다. | `/opt/admin/socat` |
442
443<h4 id="sandbox-path-prefixes">
444 Sandbox 경로 접두사
445</h4>
446 415
447`filesystem.allowWrite`, `filesystem.denyWrite`, `filesystem.denyRead`, `filesystem.allowRead` 및 `credentials.files`의 경로는 다음 접두사를 지원합니다:416<span id="compare-what-each-file-reaches" />
448 417
449| 접두사 | 의미 | 예제 |418<h3 id="compare-the-scope-of-each-settings-file">
450| :------------- | :------------------------------------------------------ | :------------------------------------------------------------------ |419 각 설정 파일의 범위 비교
451| `/` | 파일 시스템 루트의 절대 경로 | `/tmp/build`는 `/tmp/build`로 유지됨 |420</h3>
452| `~/` | 홈 디렉토리에 상대적 | `~/.kube`는 `$HOME/.kube`가 됨 |
453| `./` 또는 접두사 없음 | 프로젝트 설정의 경우 프로젝트 루트에 상대적이거나 사용자 설정의 경우 `~/.claude`에 상대적 | `./output`은 `.claude/settings.json`에서 `<project-root>/output`으로 해결됨 |
454 421
455이전 `//path` 접두사는 절대 경로에 대해 여전히 작동합니다. 이전에 프로젝트 상대 해결을 기대하면서 단일 슬래시 `/path`를 사용한 경우 `./path`로 전환합니다. 이 구문은 `/path`를 프로젝트 상대로 사용하는 [Read 및 Edit 권한 규칙](/docs/ko/permissions#read-and-edit)과 다릅니다. Sandbox 파일 시스템 경로는 표준 규칙을 사용합니다: `/tmp/build`는 절대 경로입니다.422머신에 `website/`, `api/`, `acme-app/` 세 개의 프로젝트가 있고, 팀원이 `acme-app/`의 자신의 클론을 가지고 있으며, `acme-app/`에서 [클라우드 세션](#settings-in-cloud-sessions)을 시작한다고 가정합니다.
456 423
457**구성 예제:**424아래 그래픽은 이들 폴더에서 Claude Code를 시작할 때 설정이 적용되는 폴더를 보여줍니다. 설정 파일을 클릭하여 도달하는 폴더를 확인합니다.
458 425
459```json theme={null}426<SettingsScope />
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 427
481**파일 시스템 및 네트워크 제한**은 함께 병합되는 두 가지 방식으로 구성할 수 있습니다:428* **`~/.claude/settings.json`**: 머신의 모든 프로젝트, 팀원의 것이나 클라우드 세션의 것은 제외
429* **`acme-app/.claude/settings.json`**: 사용자의 `acme-app/`. 파일을 버전 제어에 커밋한 경우에만 팀원의 클론과 클라우드 세션에 도달합니다. 그 전까지는 다른 파일처럼 디스크의 파일이며 다른 사람은 가지고 있지 않습니다
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/ko/server-managed-settings)인지 여부: 조직이 배포하는 모든 머신의 모든 프로젝트, 또는 조직 계정으로 로그인하는 모든 머신. 서버 관리 설정만 클라우드 세션에 도달합니다
482 432
483* **`sandbox.filesystem` 설정** (위에 표시됨): OS 수준 샌드박스 경계에서 경로를 제어합니다. 이러한 제한은 Claude의 파일 도구뿐만 아니라 모든 하위 프로세스 명령 (예: `kubectl`, `terraform`, `npm`)에 적용됩니다.433<span id="which-files-you-have" />
484* **권한 규칙**: `Edit` 허용/거부 규칙을 사용하여 Claude의 파일 도구 액세스를 제어하고, `Read` 거부 규칙을 사용하여 읽기를 차단하고, `WebFetch` 허용/거부 규칙을 사용하여 네트워크 도메인을 제어합니다. 이러한 규칙의 경로도 샌드박스 구성에 병합됩니다.
485 434
486<h3 id="attribution-settings">435<h3 id="find-or-create-your-settings-files">
487 Attribution 설정436 설정 파일 찾기 또는 생성
488</h3>437</h3>
489 438
490Claude Code는 git 커밋 및 pull request에 attribution을 추가합니다. 이들은 별도로 구성됩니다:439Claude Code를 설치해도 설정 파일이 생성되지 않습니다. 머신이나 프로젝트에 이미 파일이 있다면 다음 중 하나에서 온 것입니다:
491
492* 커밋은 기본적으로 [git trailers](https://git-scm.com/docs/git-interpret-trailers) (예: `Co-Authored-By`)를 사용하며 사용자 정의하거나 비활성화할 수 있습니다
493* Pull request 설명은 일반 텍스트입니다
494
495| 키 | 설명 |
496| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
497| `commit` | git 커밋에 대한 attribution으로 모든 trailers를 포함합니다. 빈 문자열은 커밋 attribution을 숨깁니다 |
498| `pr` | Pull request 설명에 대한 attribution입니다. 빈 문자열은 pull request attribution을 숨깁니다 |
499| `sessionUrl` | 웹 또는 Remote Control 세션에서 실행할 때 커밋에 `Claude-Session` trailer로 claude.ai 세션 링크를 추가할지 여부 및 pull request 설명의 링크. 기본값: `true`. 링크를 생략하려면 `false`로 설정합니다 |
500
501**기본 커밋 attribution:**
502
503```text theme={null}
504Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
505```
506
507세션의 활성 모델을 반영하는 trailer의 모델 이름입니다.
508 440
509**기본 pull request attribution:**441* **관리됨**: 조직이 배포합니다. 생성하거나 편집하지 않습니다.
442* **공유 프로젝트**: Claude Code를 이미 사용하는 프로젝트에 커밋된 파일이 있을 수 있습니다. 없으면 프로젝트 폴더에 `.claude/settings.json`을 생성합니다.
443* **사용자** 및 **프로젝트 로컬**: 직접 생성하거나 Claude Code가 생성하도록 합니다. 테마와 같이 사용자 설정에 저장하는 `/config` 메뉴의 옵션을 처음 변경할 때 `~/.claude/settings.json`을 쓰고, Bash 명령에 대해 "Yes, and don't ask again"과 같은 권한 프롬프트에서 처음 승인을 할 때 `.claude/settings.local.json`을 씁니다. **Show tips**를 포함한 몇 가지 `/config` 옵션은 사용자 파일 대신 `.claude/settings.local.json`에 저장됩니다.
510 444
511```text theme={null}445<Info>
512🤖 Generated with [Claude Code](https://claude.com/claude-code)446 Windows에서 `~/.claude`는 `%USERPROFILE%\.claude`를 의미합니다. 홈 디렉토리 파일을 다른 곳에 보관하려면 [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)을 설정합니다. Claude Code는 설정, 세션 기록, plugins을 대신 저장합니다.
513```447</Info>
514 448
515**예제:**449Claude Code는 또한 다섯 번째 파일인 [`~/.claude.json`](/docs/ko/claude-directory#ce-claude-json)을 유지합니다. 이는 자신을 위해 쓰는 파일이므로 편집할 필요가 없습니다. 로그인 세션, [MCP server](/docs/ko/mcp) 구성, 신뢰 결정과 같은 프로젝트별 상태, 그리고 `/config`가 사용자를 위해 쓰는 [전역 구성 키](/docs/ko/settings-reference#global-config-settings)를 보유합니다.
516 450
517```json theme={null}451<h3 id="share-settings-with-your-team">
518{452 팀과 설정 공유
519 "attribution": {
520 "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
521 "pr": ""
522 }
523}
524```
525
526<Note>
527 `attribution` 설정은 더 이상 사용되지 않는 `includeCoAuthoredBy` 설정보다 우선합니다. 모든 attribution을 숨기려면 `commit` 및 `pr`을 빈 문자열로 설정하고 `sessionUrl`을 `false`로 설정합니다.
528</Note>
529
530<h3 id="file-suggestion-settings">
531 파일 제안 설정
532</h3>453</h3>
533 454
534`@` 파일 경로 자동 완성을 위한 사용자 정의 명령을 구성합니다. 기본 제공 파일 제안은 빠른 파일 시스템 순회를 사용하지만 대규모 monorepos는 사전 구축된 파일 인덱스 또는 사용자 정의 도구와 같은 프로젝트 특정 인덱싱의 이점을 얻을 수 있습니다.455`.claude/settings.json`을 커밋하여 저장소를 클론하는 모든 사람이 동일한 권한, hooks, 원격 측정, plugins을 받도록 합니다. 각 팀원은 자신의 `.claude/settings.local.json`에서 자신을 위해 재정의할 수 있으므로 개인 예외는 커밋이 필요하지 않습니다. 완전한 팀 파일은 [팀의 공유 설정](/docs/ko/settings-example#a-teams-shared-settings)을 참조합니다.
535
536```json theme={null}
537{
538 "fileSuggestion": {
539 "type": "command",
540 "command": "~/.claude/file-suggestion.sh"
541 }
542}
543```
544
545명령은 `CLAUDE_PROJECT_DIR`을 포함한 [hooks](/docs/ko/hooks)와 동일한 환경 변수로 실행됩니다. stdin을 통해 `query` 필드가 있는 JSON을 받습니다:
546 456
547```json theme={null}457커밋하는 것 중 일부는 각 팀원이 [폴더를 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)할 때까지 기다리며, 몇 가지 키는 저장소 파일에서 적용되지 않습니다. [적용되지 않는 설정 문제 해결](#common-cases)은 둘 다 다룹니다.
548{"query": "src/comp"}
549```
550 458
551stdout에 줄 바꿈으로 구분된 파일 경로를 출력합니다 (현재 15개로 제한됨):459<span id="local-settings-file" />
552 460
553```text theme={null}461<span id="where-claude-code-saves-the-project-local-file" />
554src/components/Button.tsx
555src/components/Modal.tsx
556src/components/Form.tsx
557```
558 462
559**예제:**463<span id="the-project-local-file" />
560 464
561```bash theme={null}465<span id="keep-personal-settings-out-of-the-repository" />
562#!/bin/bash
563query=$(cat | jq -r '.query')
564# your-repo-file-index를 자신의 파일 검색 명령으로 바꿉니다
565your-repo-file-index --query "$query" | head -20
566```
567 466
568<h3 id="footer-link-badges">467<h3 id="keep-personal-settings-out-of-a-repository">
569 바닥글 링크 배지468 저장소에서 개인 설정 제외
570</h3>469</h3>
571 470
572`footerLinksRegexes` 설정은 입력 상자 아래 바닥글에 클릭 가능한 배지를 렌더링합니다. 이를 사용하여 검토 도구 및 이슈 추적기와 같은 프로젝트 CLI에서 인쇄한 ID를 세션 링크로 변환합니다.471팀원을 위해 변경하지 않고 한 프로젝트에서 자신을 위해 설정을 변경하려면 프로젝트 내부의 `.claude/settings.local.json`에 저장합니다. Claude Code는 커밋된 `.claude/settings.json` 위에 해당 파일을 적용하므로, 팀의 파일이 `"model": "claude-sonnet-5"`를 설정하고 Opus를 원하면 로컬 파일에 `"model": "claude-opus-4-8"`을 넣으면 세션만 변경됩니다.
573
574각 항목의 `pattern` 정규식은 턴 출력과 일치합니다: 도구 결과 (파일 내용 및 가져온 페이지 포함) 및 Claude의 자체 응답. `url` 및 `label`의 `{name}` 자리 표시자는 패턴의 명명된 캡처 그룹에서 채워집니다.
575
576다음 예제는 `PROJ-1234`와 같은 이슈 키가 턴 출력에 나타날 때마다 배지를 렌더링합니다. `(?<key>...)` 명명된 그룹이 키를 캡처하고 `{key}`가 URL 및 레이블로 대체됩니다:
577 472
578```json ~/.claude/settings.json theme={null}473로컬 파일에 대해 알아야 할 세 가지:
579{
580 "footerLinksRegexes": [
581 {
582 "type": "regex",
583 "pattern": "\\b(?<key>PROJ-\\d+)\\b",
584 "url": "https://issues.example.com/browse/{key}",
585 "label": "{key}"
586 }
587 ]
588}
589```
590 474
591이렇게 구성하면 `PROJ-1234`가 도구 결과 또는 Claude의 응답에 나타날 때 `PROJ-1234` 칩이 바닥글에 나타나 `https://issues.example.com/browse/PROJ-1234`로 연결됩니다.475* **Claude Code도 이를 씁니다.** Claude가 Bash 명령을 실행할 권한을 요청하고 "Yes, and don't ask again"을 선택하면, Claude Code는 해당 [권한 승인](/docs/ko/permissions#permission-system)을 `allow` 규칙으로 여기에 저장합니다.
476* **직접 생성한 경우가 아니면 gitignore할 필요가 없습니다.** Claude Code가 이미 무시하지 않는 git 저장소에서 파일을 처음 쓸 때, 전역 git 제외 파일에 `**/.claude/settings.local.json`을 추가하므로 모든 저장소의 커밋에서 파일이 제외됩니다. 해당 파일은 전역 git 구성이 절대 경로 또는 `~` 접두사 경로로 설정할 때 `core.excludesFile`입니다. 그렇지 않으면 `$XDG_CONFIG_HOME/git/ignore` 또는 `XDG_CONFIG_HOME`이 설정되지 않을 때 `~/.config/git/ignore`입니다. 파일을 직접 생성했고 Claude Code가 아직 쓰지 않았다면 `.gitignore`에 직접 추가합니다.
477* **파일이 추적되지 않는 동안 allow 규칙은 신뢰를 기다리지 않습니다.** 파일이 저장소의 것이 아니라 사용자의 것이므로, Claude Code는 커밋된 파일에 필요한 [workspace trust](/docs/ko/permissions#project-allow-rules-and-workspace-trust) 단계 없이 `allow` 규칙을 적용합니다. 파일이 git으로 추적되면 신뢰 단계도 적용됩니다. [로컬 설정 파일이 신뢰가 필요한 경우](/docs/ko/permissions#when-your-local-settings-file-needs-trust)를 참조합니다.
592 478
593다음 제약이 각 항목에 적용됩니다:479<span id="where-claude-code-looks-for-each-file" />
594 480
595| 제약 | 동작 |481<span id="how-claude-code-keeps-the-local-file-out-of-git" />
596| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
597| URL origin | 캡처된 값은 URL 인코딩되고 구성된 URL은 템플릿의 리터럴 origin을 공유해야 합니다. 캡처는 경로 세그먼트 또는 쿼리 값을 채울 수 있지만 링크가 가리키는 위치를 변경할 수 없습니다 |
598| URL 길이 | 2048자보다 긴 구성된 URL은 삭제됩니다 |
599| URL 스키마 | `https`, `http` 또는 인식된 편집기 또는 작업 공간 deep-link 스키마여야 합니다: `vscode`, `vscode-insiders`, `cursor`, `windsurf`, `zed`, `jetbrains`, `idea`, `slack`, `linear`, `notion`, `figma` |
600| 레이블 | 기본값은 일치한 텍스트이며 28개 표시 열로 잘립니다 |
601| 배지 수 | 최대 5개 배지가 렌더링됩니다. 가장 오래된 것이 새로운 일치로 대체되고 `/clear`가 이를 제거합니다 |
602| 설정 범위 | 사용자 설정, `--settings` 플래그 및 managed 설정에서만 읽습니다. 프로젝트 `.claude/settings.json` 및 local `.claude/settings.local.json`에서는 무시됩니다 |
603 482
604턴이 완료되면 Claude Code는 메인 스레드에서 각 항목의 `pattern` 정규식을 턴 출력과 일치시키므로 느린 정규식은 완료될 때까지 UI를 차단합니다. `(a+)+$`와 같은 중첩된 수량자는 특정 입력에 대해 지수적으로 오래 걸릴 수 있고 세션을 고정시킬 수 있으므로 각 `pattern`을 선형으로 유지하고 `+` 또는 `*` 중첩을 피합니다.483<span id="local-allow-rules-dont-wait-for-workspace-trust" />
605 484
606바닥글 배지는 구성된 [사용자 정의 상태 줄](/docs/ko/statusline)과 함께 렌더링됩니다. 어느 것도 다른 것을 대체하지 않습니다. 세션 데이터에서 자신의 콘텐츠를 계산하는 스크립트 기반 행에 상태 줄을 사용하고 스크립트 없이 대화에서 ID를 링크로 변환하려면 바닥글 배지를 사용합니다.485<h4 id="where-claude-code-keeps-the-local-file-in-a-git-repository">
486 Claude Code가 git 저장소에서 로컬 파일을 보관하는 위치
487</h4>
607 488
608<h3 id="hook-configuration">489Claude가 Bash 명령을 실행할 권한을 요청하고 "Yes, and don't ask again"을 선택하면, Claude Code는 해당 승인을 `.claude/settings.local.json`의 `allow` 규칙으로 저장합니다. git 저장소의 하위 디렉토리에서 Claude Code를 시작하면 저장소 루트에서 해당 파일을 읽고 쓰며 전체 저장소에 승인을 적용합니다. [worktree](/docs/ko/worktrees)에서는 주 체크아웃의 루트에서 파일을 사용합니다.
609 Hook 구성
610</h3>
611 490
612이러한 설정은 어떤 hooks가 실행될 수 있는지와 HTTP hooks가 액세스할 수 있는 것을 제어합니다. `allowManagedHooksOnly` 설정은 [managed 설정](#settings-files)에서만 구성할 수 있습니다. URL 및 env var 허용 목록은 모든 설정 수준에서 설정할 수 있으며 소스 전체에서 병합됩니다.491두 가지 규칙이 루트 위치를 한정합니다:
613 492
614**`allowManagedHooksOnly`가 `true`일 때의 동작:**493* **파일이 `.claude/settings.json` 대신 유지되는 경우**: git 저장소 외부, 저장소 루트가 홈 디렉토리인 경우, Windows에서, 또는 저장소 루트나 `.git` 또는 `.claude` 항목이 사용자가 소유하지 않은 경우.
494* **파일의 경로는 저장소 루트에 고정되지 않습니다**: `/`로 시작하거나 상대 sandbox 경로인 권한 규칙은 [세션의 주 작업 디렉토리](/docs/ko/permissions#read-and-edit)에 고정됩니다.
615 495
616* Managed hooks 및 SDK hooks가 로드됨496v2.1.211 이전에는 Claude Code가 시작 디렉토리에 파일을 보관했습니다. 이전 버전이 루트 파일 옆에 남긴 파일을 여전히 읽습니다. 둘 다 동일한 키를 설정하면 루트의 값이 적용되고, 두 파일의 권한 규칙이 적용됩니다. Agent SDK의 [`resolveSettings()`](/docs/ko/agent-sdk/typescript#resolvesettings) 헬퍼는 항상 시작 디렉토리에서 파일을 읽습니다.
617* Managed 설정 `enabledPlugins`에서 강제 활성화된 플러그인의 hooks가 로드됩니다. 이를 통해 관리자는 조직 마켓플레이스를 통해 검증된 hooks를 배포하면서 다른 모든 것을 차단할 수 있습니다. 신뢰는 전체 `plugin@marketplace` ID로 부여되므로 다른 마켓플레이스의 동일한 이름의 플러그인은 차단된 상태로 유지됩니다
618* 사용자 hooks, 프로젝트 hooks 및 다른 모든 플러그인 hooks는 차단됩니다
619 497
620**HTTP hook URL 제한:**498Claude Code는 세션의 [주 작업 디렉토리](/docs/ko/permissions#working-directories)에서 공유 `.claude/settings.json`을 읽으므로, 저장소 루트에 커밋된 파일을 사용하려면 거기서 Claude Code를 시작합니다. [`/cd`로 세션을 이동](/docs/ko/permissions#move-the-session-to-another-directory)한 후, Claude Code는 대신 새 디렉토리에서 두 프로젝트 파일을 읽으며, 동일한 규칙으로 로컬 파일을 배치합니다. 이동한 디렉토리에서 읽으려면 Claude Code v2.1.246 이상이 필요합니다.
621 499
622HTTP hooks가 대상으로 할 수 있는 URL을 제한합니다. 일치를 위해 `*`를 와일드카드로 지원합니다. 배열이 정의되면 일치하지 않는 URL을 대상으로 하는 HTTP hooks는 자동으로 차단됩니다. 호스트명 일치는 대소문자를 구분하지 않으며 후행 FQDN 점을 무시하여 DNS 의미론과 일치합니다.500<span id="managed-settings-delivery" />
623 501
624```json theme={null}502<span id="precedence-within-the-managed-tier" />
625{
626 "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
627}
628```
629 503
630**HTTP hook 환경 변수 제한:**504<span id="parent-settings-from-embedding-hosts" />
631 505
632HTTP hooks가 헤더 값에 보간할 수 있는 환경 변수 이름을 제한합니다. 각 hook의 유효한 `allowedEnvVars`는 이 설정과의 교집합입니다.506<span id="enforce-settings-for-an-organization" />
633 507
634```json theme={null}508<span id="settings-your-organization-manages" />
635{
636 "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
637}
638```
639 509
640<h3 id="compute-managed-settings-with-a-policy-helper">510<h3 id="check-what-your-organization-enforces">
641 정책 도우미로 managed 설정 계산511 조직이 적용하는 항목 확인
642</h3>512</h3>
643 513
644`policyHelper` 설정은 시작 시 managed 설정을 동적으로 계산하는 실행 파일을 가리키므로 관리자는 장치 상태, ID 또는 원격 서비스에서 정책을 파생시킬 수 있습니다. MDM 또는 시스템 `managed-settings.json` 파일에서 구성합니다. Claude Code는 사용자 설정, 프로젝트 설정, HKCU 레지스트리 하이브 및 [서버 관리 설정](/docs/ko/server-managed-settings)을 포함한 다른 범위에 나타나는 `policyHelper`를 무시합니다.514조직이 Claude Code를 관리하면 일부 설정이 결정되며 자신의 파일에 넣은 것이 변경하지 않습니다. 어떤 것인지 확인하려면 `/status`를 실행합니다. `Setting sources` 줄은 사용자에게 적용되는 관리되는 소스의 이름을 지정합니다. 관리되는 설정은 이 머신에서 Claude Code가 실행되는 모든 곳에 적용됩니다. [개발자가 변경할 수 있는 것](/docs/ko/managed-settings#what-a-developer-can-change)은 로컬 관리자 권한 및 Claude Code 이외의 도구를 다룹니다.
645
646설정은 다음 키를 허용합니다:
647 515
648| 키 | 유형 | 설명 |516관리되는 설정은 관리되는 설정 페이지의 [전달 메커니즘](/docs/ko/managed-settings#delivery-mechanisms)을 통해 사용자에게 도달합니다. 가장 일반적으로:
649| ------------------- | ------ | -------------------------------------------------------------------- |
650| `path` | string | 도우미 실행 파일의 절대 경로 |
651| `timeoutMs` | number | 도우미가 실패한 것으로 처리하기 전에 대기할 시간 |
652| `refreshIntervalMs` | number | 백그라운드에서 도우미를 다시 실행할 빈도. 새로고침을 비활성화하려면 `0`으로 설정하거나 최소 `60000`으로 설정합니다 |
653 517
654도우미는 stdout에 JSON 봉투를 작성합니다. 설정을 최상위 수준이 아닌 `managedSettings` 키 아래에 배치합니다. 왜냐하면 베어 설정 객체는 `managedSettings` undefined로 파싱되고 아무것도 적용하지 않기 때문입니다:518* [서버 관리 설정](/docs/ko/server-managed-settings), Claude Code가 claude.ai 관리 콘솔 또는 자체 호스팅 [Claude apps gateway](/docs/ko/claude-apps-gateway)에서 가져옴
655 519* MDM 또는 OS 수준 정책, 및 시스템 디렉토리의 `managed-settings.json` 파일
656```json theme={null}520* Claude Desktop과 같은 embedding host, SDK `managedSettings` 옵션을 통해. [embedding host에서 정책 제어](/docs/ko/managed-settings#parent-settings-from-embedding-hosts)를 참조합니다
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 521
666도우미가 `managedSettings`를 내보낼 때 해당 객체는 실행을 위해 파일 기반 managed 설정을 대체합니다. 도우미가 시작 시 0이 아닌 값으로 종료되면 Claude Code는 오류를 인쇄하고 시작을 거부하므로 중단 복원력이 필요한 도우미는 자신의 캐시에서 제공하고 `0`으로 종료해야 합니다.522Claude Desktop 앱에서 머신에서 실행되는 [Cowork](https://claude.com/docs/cowork/overview) 세션에서 Claude Code는 claude.ai 관리 콘솔에서 서버 관리 설정을 가져오지 않으며, 조직의 Claude Desktop 구성이 `requireCoworkFullVmSandbox`를 설정하지 않으면 디바이스에 배포된 정책을 읽습니다. [정책이 적용되는 위치 및 시기](/docs/ko/managed-settings#where-and-when-a-policy-applies)는 Cowork 및 클라우드 세션을 다룹니다.
667 523
668<h3 id="settings-precedence">524관리자인 경우 [조직을 위해 Claude Code 설정](/docs/ko/admin-setup)은 적용할 항목 선택을 안내하고, [관리되는 설정 배포](/docs/ko/managed-settings)는 전달 및 정책이 적용 중인지 확인하는 방법을 다룹니다.
669 설정 우선순위
670</h3>
671 525
672설정은 우선순위 순서대로 적용됩니다. 가장 높음에서 가장 낮음:526<h2 id="change-a-setting">
527 설정 변경
528</h2>
673 529
6741. **Managed 설정** ([서버 관리](/docs/ko/server-managed-settings), [MDM/OS 수준 정책](#configuration-scopes) 또는 [managed 설정](#settings-files))530`/config` 메뉴, 설정 파일 편집, 또는 한 세션에 대해 명령줄에서 설정을 변경할 수 있습니다.
675 * IT에서 서버 전달, MDM 구성 프로필, 레지스트리 정책 또는 managed 설정 파일을 통해 배포한 정책
676 * 명령줄 인수를 포함한 다른 수준으로 재정의할 수 없음
677 * Managed 계층 내에서 우선순위는: [`policyHelper`](#compute-managed-settings-with-a-policy-helper) 출력 (구성된 경우 유일한 managed 소스 사용) > 원격 (claude.ai [서버 관리](/docs/ko/server-managed-settings) 또는 [Claude apps gateway](/docs/ko/claude-apps-gateway) 전달) > MDM/OS 수준 정책 > 파일 기반 (`managed-settings.d/*.json` + `managed-settings.json`) > HKCU 레지스트리 (Windows만). 하나의 managed 소스만 사용되며 소스는 병합되지 않습니다. 파일 기반 계층 내에서 드롭인 파일과 기본 파일이 함께 병합됩니다.
678 * Agent SDK 또는 IDE 확장과 같은 embedding host는 SDK `managedSettings` 옵션을 통해 정책을 제공할 수 있습니다. 기본적으로 이는 관리자 배포 managed 계층이 있을 때 무시됩니다: 서버 관리 설정, MDM 또는 OS 수준 정책, 또는 managed 설정 파일. 사용자 쓰기 가능 HKCU 레지스트리 폴백은 관리자 배포 소스로 계산되지 않습니다. 관리자는 [`parentSettingsBehavior`](#available-settings)를 `"merge"`로 설정하여 옵트인할 수 있습니다. embedder의 값은 필터링되므로 managed 정책을 강화할 수 있지만 완화할 수 없습니다.
679 531
6802. **명령줄 인수**532<span id="system-prompt" />
681 * 특정 세션에 대한 임시 재정의. `--settings <file-or-json>`을 통해 전달된 JSON은 파일 기반 설정과 동일한 규칙을 사용하여 병합됩니다: 여기에 설정된 키는 local, project 또는 user 설정의 동일한 키를 재정의하고, 키를 생략하면 낮은 계층 값이 유지됩니다
682 533
6833. **Local 프로젝트 설정** (`.claude/settings.local.json`)534Claude Code의 시스템 프롬프트는 게시되지 않습니다. Claude에 지속적인 지침을 제공하려면 [`CLAUDE.md` 파일](/docs/ko/memory) 또는 `--append-system-prompt` 플래그를 사용합니다.
684 * 개인 프로젝트 특정 설정
685 535
6864. **공유 프로젝트 설정** (`.claude/settings.json`)536<h3 id="use-the-/config-menu">
687 * 소스 제어의 팀 공유 프로젝트 설정537 /config 메뉴 사용
538</h3>
688 539
6895. **사용자 설정** (`~/.claude/settings.json`)540Claude Code 내에서 `/config`를 실행하고 **Config** 탭을 엽니다. 테마, 편집기 모드, 상세 출력과 같은 짧은 개인 옵션 집합을 나열하며, 모든 설정 키는 아닙니다. 옵션을 선택하여 변경합니다. Claude Code가 저장합니다:
690 * 개인 전역 설정
691 541
692이 계층 구조는 조직 정책이 항상 적용되면서도 팀과 개인이 자신의 경험을 사용자 정의할 수 있도록 보장합니다. CLI, [VS Code 확장](/docs/ko/vs-code) 또는 [JetBrains IDE](/docs/ko/jetbrains)에서 Claude Code를 실행하든 동일한 우선순위가 적용됩니다.542* **대부분의 옵션**: `~/.claude/settings.json`
543* **팁 표시와 같은 몇 가지 옵션**: `.claude/settings.local.json`
544* **[전역 구성 옵션](/docs/ko/settings-reference#global-config-settings)**: `~/.claude.json`
693 545
694예를 들어 사용자 설정이 `permissions.defaultMode`를 `acceptEdits`로 설정하지만 프로젝트의 공유 설정이 이를 `default`로 설정하면 프로젝트 값이 적용됩니다. 아래 예제는 배열 값 설정 (예: 권한 규칙)이 대신 어떻게 결합되는지를 다룹니다.546메뉴 없이 한 옵션을 설정하려면 `/config verbose=true`와 같이 `key=value`를 전달합니다.
695 547
696<Note>548<Note>
697 **배열 설정은 범위 전체에서 병합됩니다.** 동일한 배열 값 설정 (예: `sandbox.filesystem.allowWrite` 또는 `permissions.allow`)이 여러 범위에 나타나면 배열은 **연결되고 중복 제거되며** 대체되지 않습니다. 이는 낮은 우선순위 범위가 높은 우선순위 범위에서 설정한 항목을 재정의하지 않고 항목을 추가할 수 있음을 의미하며 그 반대도 마찬가지입니다. 예를 들어 managed 설정이 `allowWrite`를 `["/opt/company-tools"]`로 설정하고 사용자가 `["~/.kube"]`를 추가하면 두 경로 모두 최종 구성에 포함됩니다. 두 가지 예외가 있습니다: [`fallbackModel`](#available-settings)은 위치가 의미를 가지는 순서가 지정된 체인입니다: 이를 정의하는 최고 우선순위 파일이 전체 값을 제공합니다. [`availableModels`](#available-settings): }[최고 우선순위 managed 소스](/docs/ko/server-managed-settings#settings-precedence)가 이를 정의할 때 해당 목록이 그대로 적용되고 사용자, 프로젝트 및 local 항목은 이를 확장할 수 없습니다. 비 managed 범위 전체에서 배열은 평소대로 병합됩니다. [병합 동작](/docs/ko/model-config#merge-behavior)을 참조하세요.549 `/config`는 터미널 인터페이스의 일부입니다. [VS Code](/docs/ko/vs-code) 채팅 패널 및 [데스크톱 앱](/docs/ko/desktop)은 열지 않습니다. 설정 파일을 편집하거나 해당 앱의 자체 설정을 통해 변경합니다.
698</Note>550</Note>
699 551
700<h3 id="verify-active-settings">552<h3 id="edit-a-settings-file">
701 활성 설정 확인553 설정 파일 편집
702</h3>554</h3>
703 555
704Claude Code 내에서 `/status`를 실행하여 활성 설정 소스를 확인합니다. 메뉴 내에서 **Status** 탭에는 이 세션에 대해 Claude Code가 로드한 각 계층을 나열하는 `Setting sources` 줄이 포함됩니다 (예: `User settings` 또는 `Project local settings`). [managed 설정](/docs/ko/admin-setup#decide-how-settings-reach-devices)이 적용되면 항목은 전달 채널을 괄호로 표시합니다 (예: `Enterprise managed settings (remote)`, `(plist)`, `(HKLM)`, `(HKCU)` 또는 `(file)`). 계층은 해당 소스가 최소 하나의 키로 로드될 때만 목록에 나타나므로 빈 목록은 설정 소스를 찾을 수 없음을 의미합니다.556원하는 범위의 설정 파일을 편집기에서 열고 키를 추가하거나 변경합니다. 설정 파일은 엄격한 JSON입니다: `//` 주석이나 후행 쉼표는 구문 오류이며, Claude Code는 다음 시작에서 파일을 [설정 오류](#fix-a-broken-settings-file)로 보고합니다. 예를 들어 Claude Code가 lint 및 테스트 명령을 묻지 않고 실행하고 `.env` 파일 읽기를 중지하도록 하려면 `~/.claude/settings.json`에 다음을 추가합니다:
705
706`Setting sources` 줄은 어떤 소스가 읽혀지는지 확인합니다. 각 개별 키를 제공한 계층을 표시하지는 않습니다. **Config** 탭은 동일한 대화에서 테마 및 verbose 출력과 같은 고정된 토글 집합의 편집기입니다. `settings.json` 내용의 보기가 아닙니다.
707
708설정 파일에 유효하지 않은 JSON 또는 검증에 실패한 값이 포함되어 있으면 Claude Code는 시작 시 설정 문제 알림을 표시하고 `/status`는 영향을 받는 파일을 나열합니다. 각 오류의 세부 사항을 보려면 `/doctor`를 실행합니다.
709
710<h3 id="key-points-about-the-configuration-system">
711 구성 시스템의 핵심 포인트
712</h3>
713 557
714* **메모리 파일 (`CLAUDE.md`)**: Claude가 시작 시 로드하는 지침 및 컨텍스트를 포함합니다558```json ~/.claude/settings.json theme={null}
715* **설정 파일 (JSON)**: 권한, 환경 변수 및 도구 동작을 구성합니다
716* **Skills**: `/skill-name`으로 호출하거나 Claude가 자동으로 로드할 수 있는 사용자 정의 프롬프트
717* **MCP servers**: 추가 도구 및 통합으로 Claude Code를 확장합니다
718* **우선순위**: 높은 수준 구성 (Managed)이 낮은 수준 (User/Project)을 재정의합니다
719* **상속**: 설정은 범위 전체에서 병합됩니다. 스칼라 값은 높은 우선순위 범위에서 재정의되고, 배열은 연결됩니다 (예외: `fallbackModel`은 최고 우선순위 범위가 전체 체인을 제공합니다. v2.1.175부터 `availableModels`도 managed 또는 정책 값이 낮은 우선순위 항목을 완전히 대체합니다)
720
721<h3 id="system-prompt">
722 시스템 프롬프트
723</h3>
724
725Claude Code의 내부 시스템 프롬프트는 게시되지 않습니다. 사용자 정의 지침을 추가하려면 `CLAUDE.md` 파일 또는 `--append-system-prompt` 플래그를 사용합니다.
726
727<h3 id="exclude-sensitive-files">
728 민감한 파일 제외
729</h3>
730
731API 키, 비밀 및 환경 파일과 같은 민감한 정보가 포함된 파일에서 Claude Code가 액세스하는 것을 방지하려면 `.claude/settings.json` 파일에서 `permissions.deny` 설정을 사용합니다:
732
733```json theme={null}
734{559{
560 "$schema": "https://json.schemastore.org/claude-code-settings.json",
735 "permissions": {561 "permissions": {
562 "allow": [
563 "Bash(npm run lint)",
564 "Bash(npm run test *)"
565 ],
736 "deny": [566 "deny": [
737 "Read(./.env)",567 "Read(./.env)",
738 "Read(./.env.*)",568 "Read(./.env.*)"
739 "Read(./secrets/**)",
740 "Read(./config/credentials.json)",
741 "Read(./build)"
742 ]569 ]
743 }570 }
744}571}
745```572```
746 573
747이는 더 이상 사용되지 않는 `ignorePatterns` 구성을 대체합니다. 이러한 패턴과 일치하는 파일은 파일 검색 및 검색 결과에서 제외되며 이러한 파일에 대한 읽기 작업이 거부됩니다.574`permissions` 아래의 각 항목은 도구와 수행할 수 있는 것을 명명하는 규칙입니다. [권한 구성](/docs/ko/permissions)은 구문을 설명합니다. `$schema` 줄은 Claude Code 설정에 대한 [게시된 JSON 스키마](https://json.schemastore.org/claude-code-settings.json)를 가리키며, VS Code, Cursor 및 JSON 스키마를 지원하는 다른 편집기에서 자동 완성 및 인라인 검증을 제공합니다. 스키마는 최신 CLI 릴리스보다 뒤떨어질 수 있으므로 최근에 문서화된 키에 대한 검증 경고는 구성이 유효하지 않음을 의미하지 않습니다.
748 575
749<h2 id="subagent-configuration">576저장한 후 Claude Code 내에서 `/status`를 실행하여 파일이 로드되었는지 확인합니다. [로드된 것 확인](#check-what-loaded)은 `Setting sources` 줄이 표시하는 것과 손상된 파일이 보고되는 방식을 설명합니다.
750 Subagent 구성
751</h2>
752 577
753Claude Code는 사용자 및 프로젝트 수준 모두에서 구성할 수 있는 사용자 정의 AI subagents를 지원합니다. 이러한 subagents는 YAML frontmatter가 있는 Markdown 파일로 저장됩니다:578완전한 개인 파일, 팀 파일, 조직 파일은 각각 설정하는 모든 키에 대한 주석과 함께 [예제 설정 파일](/docs/ko/settings-example)을 참조하세요.
754 579
755* **사용자 subagents**: `~/.claude/agents/` - 모든 프로젝트에서 사용 가능580<span id="pass-settings-for-one-session" />
756* **프로젝트 subagents**: `.claude/agents/` - 프로젝트에 특정이며 팀과 공유할 수 있음
757 581
758Subagent 파일은 사용자 정의 프롬프트 및 도구 권한이 있는 특화된 AI 어시스턴트를 정의합니다. [subagents 문서](/docs/ko/sub-agents)에서 subagents 생성 및 사용에 대해 자세히 알아보세요.582<h3 id="change-a-setting-for-one-session">
759 583 한 세션에 대해 설정 변경
760<h2 id="plugin-configuration">
761 플러그인 구성
762</h2>
763
764Claude Code는 skills, agents, hooks 및 MCP servers로 기능을 확장할 수 있는 플러그인 시스템을 지원합니다. 플러그인은 마켓플레이스를 통해 배포되며 사용자 및 저장소 수준 모두에서 구성할 수 있습니다.
765
766<h3 id="plugin-settings">
767 플러그인 설정
768</h3>584</h3>
769 585
770`settings.json`의 플러그인 관련 설정:586값을 저장하지 않고 시도하려면 Claude Code를 시작할 때 설정합니다. 값은 해당 세션에 적용되고 설정 파일은 그대로 유지됩니다. 3가지 방법이 있습니다:
771
772```json theme={null}
773{
774 "enabledPlugins": {
775 "formatter@acme-tools": true,
776 "deployer@acme-tools": true,
777 "analyzer@security-plugins": false
778 },
779 "extraKnownMarketplaces": {
780 "acme-tools": {
781 "source": {
782 "source": "github",
783 "repo": "acme-corp/claude-plugins"
784 }
785 }
786 }
787}
788```
789
790<h4 id="enabledplugins">
791 `enabledPlugins`
792</h4>
793
794어떤 플러그인이 활성화되는지 제어합니다. 형식: `"plugin-name@marketplace-name": true/false`. 어떤 범위에서도 항목이 없는 플러그인은 해당 [`defaultEnabled`](/docs/ko/plugins-reference#default-enablement) 값으로 폴백됩니다.
795 587
796**범위**:588* **`--settings`**: JSON으로 키를 전달하거나 파일 경로로. Claude Code는 사용자, 프로젝트, 로컬 파일 위에 적용하고 관리되는 설정 아래에 적용합니다. 사용자 설정 파일이 설정할 수 있는 모든 키를 설정할 수 있습니다. `Managed` 또는 `Global config` 키는 설정할 수 없습니다.
589* **해당 키에 대한 플래그**: 일부 키에는 `model`에 대한 `--model`, `effortLevel` 및 `modelSettings`에 대한 `--effort`와 같은 자체 플래그가 있습니다.
590* **환경 변수**: `model`에 대해 `ANTHROPIC_MODEL`과 같이 `claude`를 실행하기 전에 키의 쌍을 이루는 변수를 내보냅니다.
797 591
798* **사용자 설정** (`~/.claude/settings.json`): 개인 플러그인 설정592각 키의 [설정 참조](/docs/ko/settings-reference) 항목은 세션별 재정의 및 우선순위를 나열하므로 변경하려는 키의 항목을 확인합니다.
799* **프로젝트 설정** (`.claude/settings.json`): 팀과 공유되는 프로젝트 특정 플러그인
800* **Local 설정** (`.claude/settings.local.json`): 머신별 재정의, Claude Code가 생성할 때 gitignored됨
801* **Managed 설정** (`managed-settings.json`): 모든 범위에서 설치를 차단하고 마켓플레이스에서 플러그인을 숨기는 조직 전체 정책 재정의
802
803<Note>
804 프로젝트 설정은 사용자 설정보다 우선순위가 높으므로 `~/.claude/settings.json`에서 플러그인을 `false`로 설정해도 프로젝트의 `.claude/settings.json`이 활성화하는 플러그인은 비활성화되지 않습니다. 머신에서 프로젝트 활성화 플러그인을 거부하려면 대신 `.claude/settings.local.json`에서 `false`로 설정합니다.
805 593
806 Managed 설정으로 강제 활성화된 플러그인은 managed 설정이 local 설정을 재정의하므로 이 방식으로 비활성화할 수 없습니다.594세션 내에서 실행하는 명령은 대부분 선택을 저장합니다: `/config`에서 설정을 변경하면 Claude Code가 설정 파일에 작성하고, `/model`은 새 세션의 기본값으로 값을 저장합니다.
807 595
808 Claude Code v2.1.195부터 GitHub 저장소 또는 npm 패키지와 같은 외부 소스의 플러그인을 프로젝트의 `.claude/settings.json`에서 활성화해도 다른 사람을 위해 설치되지 않습니다. 플러그인을 로드하는 모든 경로는 각 사용자에게 실행되기 전에 [플러그인을 설치하고 신뢰](/docs/ko/discover-plugins#configure-team-marketplaces)하도록 요청합니다.596`/model` 선택기에서 `s`를 누르면 Claude Code는 기본값으로 저장하지 않고 모델을 전환합니다. [노력 수준 조정](/docs/ko/model-config#adjust-effort-level)은 `/effort`가 사용 중인 모델의 기본값으로 저장하는 것과 현재 세션에만 적용하는 것을 설명합니다.
809</Note>
810 597
811**예제**:598예를 들어 기본값을 변경하지 않고 한 세션을 Opus에서 시작하려면:
812 599
813```json theme={null}600```bash theme={null}
814{601claude --settings '{"model": "claude-opus-4-8"}'
815 "enabledPlugins": {
816 "code-formatter@team-tools": true,
817 "deployment-tools@team-tools": true,
818 "experimental-features@personal": false
819 }
820}
821```
822
823<h4 id="pluginconfigs">
824 `pluginConfigs`
825</h4>
826
827플러그인의 [`userConfig`](/docs/ko/plugins-reference#user-configuration) 프롬프트가 수집하는 민감하지 않은 옵션 값을 저장하며, 플러그인 ID로 키가 지정됩니다. Claude Code는 플러그인의 구성 대화 상자를 작성할 때 이 키를 사용자 설정에 기록하므로 수동으로 편집할 필요가 없습니다. 민감한 옵션은 macOS Keychain에 저장되거나 지원되는 keychain이 없는 플랫폼에서는 `~/.claude/.credentials.json`에 저장됩니다.
828
829이 예제는 `acme-tools` 마켓플레이스에서 설치된 플러그인의 한 가지 옵션을 저장합니다:
830
831```json theme={null}
832{
833 "pluginConfigs": {
834 "deployer@acme-tools": {
835 "options": {
836 "api_endpoint": "https://api.example.com"
837 }
838 }
839 }
840}
841```
842
843`pluginConfigs`는 사용자 설정, `--settings` 플래그 및 managed 설정에서만 읽습니다. 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`의 항목은 무시됩니다. 이러한 값이 플러그인 hook, MCP 및 LSP 구성에 대체되기 때문이며, 복제된 저장소는 이들을 제공할 수 없어야 합니다. v2.1.207 이전에는 프로젝트 및 local 설정도 읽혔습니다.
844
845<h4 id="extraknownmarketplaces">
846 `extraKnownMarketplaces`
847</h4>
848
849저장소에서 사용 가능하게 해야 할 추가 마켓플레이스를 정의합니다. 일반적으로 팀 멤버가 필요한 플러그인 소스에 액세스할 수 있도록 저장소 수준 설정에서 사용됩니다.
850
851**저장소에 `extraKnownMarketplaces`가 포함되면**:
852
8531. 팀 멤버는 폴더를 신뢰할 때 마켓플레이스를 설치하라는 메시지를 받습니다
8542. 그 다음 팀 멤버는 해당 마켓플레이스에서 플러그인을 설치하라는 메시지를 받습니다
8553. 사용자는 원하지 않는 마켓플레이스 또는 플러그인을 건너뛸 수 있습니다 (사용자 설정에 저장됨)
8564. 설치는 신뢰 경계를 존중하고 명시적 동의가 필요합니다
857
858**예제**:
859
860```json theme={null}
861{
862 "extraKnownMarketplaces": {
863 "acme-tools": {
864 "source": {
865 "source": "github",
866 "repo": "acme-corp/claude-plugins"
867 }
868 },
869 "security-plugins": {
870 "source": {
871 "source": "git",
872 "url": "https://git.example.com/security/plugins.git"
873 }
874 }
875 }
876}
877```
878
879**마켓플레이스 소스 유형**:
880
881* `github`: GitHub 저장소 (`repo` 사용)
882* `git`: 모든 git URL (`url` 사용)
883* `directory`: 로컬 파일 시스템 경로 (`path` 사용, 개발 전용)
884* `hostPattern`: 마켓플레이스 호스트와 일치하는 정규식 패턴 (`hostPattern` 사용)
885* `settings`: 별도의 호스팅 저장소 없이 settings.json에 직접 선언된 인라인 마켓플레이스 (`name` 및 `plugins` 사용)
886
887`git` 소스 유형은 자체 호스팅 GitLab 및 Bitbucket을 포함한 모든 git 호스팅 서비스에서 작동합니다. Claude Code는 해당 머신에서 `git clone`이 사용할 것과 동일한 인증으로 저장소를 복제합니다: 구성된 credential helpers 또는 SSH 키. `GITHUB_TOKEN`과 같은 공급자 토큰은 이를 읽는 credential helper를 통해서만 적용됩니다. 설정 세부 정보는 [Private repositories](/docs/ko/plugin-marketplaces#private-repositories)를 참조하세요.
888
889`github` 및 `git` 소스의 경우 `source` 객체 내부 (`repo` 또는 `url`과 함께)에 `"skipLfs": true`를 설정하여 Claude Code가 마켓플레이스 저장소를 복제하거나 업데이트할 때 Git LFS 다운로드를 건너뜁니다. LFS 포인터 파일은 해당 콘텐츠를 다운로드하는 대신 포인터로 유지됩니다. 저장소에 플러그인 콘텐츠와 무관한 대용량 LFS 객체가 포함되어 있을 때 이를 사용합니다. Claude Code v2.1.153 이상이 필요합니다.
890
891각 마켓플레이스 항목은 선택적 `autoUpdate` Boolean도 허용합니다. `source`와 함께 `"autoUpdate": true`를 설정하여 Claude Code가 해당 마켓플레이스를 새로고침하고 시작 시 설치된 플러그인을 업데이트하도록 합니다. 생략하면 공식 Anthropic 마켓플레이스는 기본값이 `true`이고 다른 모든 마켓플레이스는 기본값이 `false`입니다. [자동 업데이트 구성](/docs/ko/discover-plugins#configure-auto-updates)을 참조하세요.
892
893`source: 'settings'`를 사용하여 호스팅된 마켓플레이스 저장소를 설정하지 않고 작은 플러그인 세트를 인라인으로 선언합니다. 여기에 나열된 플러그인은 GitHub 또는 npm과 같은 외부 소스를 참조해야 합니다. 여전히 `enabledPlugins`에서 각 플러그인을 별도로 활성화해야 합니다.
894
895```json theme={null}
896{
897 "extraKnownMarketplaces": {
898 "team-tools": {
899 "source": {
900 "source": "settings",
901 "name": "team-tools",
902 "plugins": [
903 {
904 "name": "code-formatter",
905 "source": {
906 "source": "github",
907 "repo": "acme-corp/code-formatter"
908 }
909 }
910 ]
911 }
912 }
913 }
914}
915```602```
916 603
917<h4 id="strictknownmarketplaces">604<h3 id="when-edits-take-effect">
918 `strictKnownMarketplaces`605 편집이 적용되는 시기
919</h4>606</h3>
920
921**Managed 설정만**: 사용자가 추가할 수 있는 플러그인 마켓플레이스를 제어합니다. 이 설정은 [managed 설정](/docs/ko/settings#settings-files)에서만 구성할 수 있으며 관리자에게 마켓플레이스 소스에 대한 엄격한 제어를 제공합니다.
922
923**Managed 설정 파일 위치**:
924
925* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`
926* **Linux 및 WSL**: `/etc/claude-code/managed-settings.json`
927* **Windows**: `C:\Program Files\ClaudeCode\managed-settings.json`
928
929**주요 특성**:
930
931* Managed 설정 (`managed-settings.json`)에서만 사용 가능
932* 사용자 또는 프로젝트 설정으로 재정의할 수 없음 (최고 우선순위)
933* 네트워크/파일 시스템 작업 전에 적용됨 (차단된 소스는 실행되지 않음)
934* `hostPattern` 및 `pathPattern`을 제외한 소스 사양에 대해 정확한 일치를 사용합니다. `hostPattern` 및 `pathPattern`은 정규식 일치를 사용합니다
935
936**허용 목록 동작**:
937
938* `undefined` (기본값): 제한 없음 - 사용자는 모든 마켓플레이스를 추가할 수 있습니다
939* 빈 배열 `[]`: 완전 잠금 - 사용자는 새 마켓플레이스를 추가할 수 없습니다
940* 소스 목록: 사용자는 정확히 일치하는 마켓플레이스만 추가할 수 있습니다
941
942**지원되는 모든 소스 유형**:
943
944허용 목록은 여러 마켓플레이스 소스 유형을 지원합니다. 대부분의 소스는 정확한 일치를 사용하는 반면 `hostPattern` 및 `pathPattern`은 마켓플레이스 호스트 및 파일 시스템 경로에 대한 정규식 일치를 각각 사용합니다.
945 607
9461. **GitHub 저장소**:608Claude Code는 설정 파일을 감시하고 변경될 때 다시 로드하므로 대부분의 편집이 재시작 없이 실행 중인 세션에 적용됩니다. 여기에는 `permissions`, `hooks`, `apiKeyHelper`와 같은 자격 증명 도우미에 대한 편집이 포함됩니다. 다시 로드는 사용자, 프로젝트, 로컬, 관리되는 설정을 다룹니다. Claude Code는 감지된 각 설정 파일 변경에 대해 [`ConfigChange` hook](/docs/ko/hooks#configchange)을 실행하며, MDM 또는 claude.ai 콘솔에서 도착하는 관리되는 설정에 대해서는 실행하지 않습니다. MDM 또는 claude.ai 콘솔에서 도착하는 관리되는 설정은 일정에 따라 실행 중인 세션에 도달합니다. [전달 테이블](/docs/ko/managed-settings#choose-a-delivery-mechanism)은 소스별로 제공합니다.
947 609
948```json theme={null}610Claude Code는 일부 키를 세션 시작 시에만 한 번 읽으므로 편집이 실행 중인 세션에 도달하지 않습니다. 관리자 측 키도 `requiredMinimumVersion`과 같이 재시작을 기다립니다. [정책이 적용되는 위치와 시기](/docs/ko/managed-settings#where-and-when-a-policy-applies)에 나열됩니다. 세션 중에 편집할 가능성이 가장 높은 것:
949{ "source": "github", "repo": "acme-corp/approved-plugins" }
950{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
951{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }
952```
953 611
954필드: `repo` (필수), `ref` (선택: 분기 또는 태그), `path` (선택: 하위 디렉토리)612* [`model`](/docs/ko/settings-reference#model): 세션 중에 전환하려면 [`/model`](/docs/ko/model-config#setting-your-model)을 사용합니다. 각 모델에는 자체 프롬프트 캐시가 있으므로 전환 후 첫 요청은 전체 대화를 캐시되지 않은 상태로 다시 읽습니다. [모델 전환](/docs/ko/prompt-caching#switching-models)을 참조하세요
613* [`effortLevel`](/docs/ko/settings-reference#effortlevel) 및 [`modelSettings`](/docs/ko/settings-reference#modelsettings): 세션 중에 변경하려면 [`/effort`](/docs/ko/model-config#adjust-effort-level)를 사용합니다
955 614
9562. **Git 저장소**:615<span id="verify-active-settings" />
957 616
958```json theme={null}617<span id="check-what-loaded" />
959{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
960{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
961{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }
962```
963 618
964필드: `url` (필수), `ref` (선택: 분기 또는 태그), `path` (선택: 하위 디렉토리)619<h3 id="confirm-what-loaded">
620 로드된 것 확인
621</h3>
965 622
9663. **URL 기반 마켓플레이스**:623Claude Code 내에서 `/status`를 실행하여 활성 설정 소스를 확인합니다. **Status** 탭에는 Claude Code가 현재 세션에 로드한 각 설정 파일을 나열하는 `Setting sources` 줄이 포함됩니다. 예: `User settings` 또는 `Project local settings`. [관리되는 설정](/docs/ko/admin-setup#decide-how-settings-reach-devices)이 적용되면 관리되는 설정 항목은 괄호에 도달 방식을 표시합니다.
967 624
968```json theme={null}625줄은 Claude Code가 읽은 파일을 확인합니다. 각 키를 제공한 파일은 표시하지 않습니다. Claude Code가 거부한 항목을 나열하려면 [`claude doctor`](/docs/ko/debug-your-config)를 실행합니다. 프로젝트 또는 관리되는 설정이 설정한 모델의 경우 시작 헤더가 설정한 파일의 이름을 지정합니다. `/status`와 `/config`는 다른 탭에서 동일한 대화를 엽니다. **Config** 탭은 `settings.json` 내용의 보기가 아닙니다.
969{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
970{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }
971```
972 626
973필드: `url` (필수), `headers` (선택: 인증된 액세스를 위한 HTTP 헤더)627<h3 id="fix-a-broken-settings-file">
628 손상된 설정 파일 수정
629</h3>
974 630
975<Note>631JSON을 잘못 입력하거나 Claude Code가 수락하지 않는 값으로 키를 설정하면 Claude Code는 대화형 세션 시작 시 알려줍니다. 표시되는 것은 파일의 얼마나 많은 부분이 영향을 받는지에 따라 다릅니다:
976 URL 기반 마켓플레이스는 `marketplace.json` 파일만 다운로드합니다. 서버에서 플러그인 파일을 다운로드하지 않습니다. URL 기반 마켓플레이스의 플러그인은 상대 경로가 아닌 외부 소스 (GitHub, npm 또는 git URL)를 사용해야 합니다. 상대 경로가 있는 플러그인의 경우 대신 Git 기반 마켓플레이스를 사용합니다. [문제 해결](/docs/ko/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)을 참조하세요.
977</Note>
978 632
9794. **NPM 패키지**:633* **설정 오류**: 사용자, 프로젝트 또는 로컬 파일에 유효하지 않은 JSON 또는 스키마가 거부하는 값이 있습니다. 대화형 세션 시작 시 Claude Code는 Claude의 도움으로 파일을 수정하거나, 종료하거나, 손상된 설정 없이 계속할 수 있는 대화를 표시합니다.
634* **설정 경고**: 개별 항목만 실패합니다. 예: 잘못된 형식의 권한 규칙 또는 알 수 없는 hook 이벤트 이름. Claude Code는 해당 값을 건너뛰고 파일의 나머지를 유지합니다.
635* **관리되는 설정**: Claude Code는 파일의 나머지를 적용합니다. [관리되는 설정의 유효하지 않은 항목](/docs/ko/managed-settings#invalid-entries-in-managed-settings)은 삭제되는 것과 유효하지 않은 항목을 수정할 때까지 폴백하는 키를 설명합니다. 유효한 JSON이 아닌 관리되는 설정 문서는 [관리되는 설정 문서를 파싱할 수 없음](/docs/ko/errors#managed-settings-document-could-not-be-parsed)을 참조하세요.
636* **구성 오류**: `~/.claude.json`을 파싱할 수 없습니다. Claude Code는 손상된 파일을 `~/.claude/backups/.claude.json.corrupted.<timestamp>`에 복사하고 종료하고 직접 수정하거나 기본 구성으로 재설정할지 묻습니다. `-p` 실행은 오류를 인쇄하고 종료합니다. 이전 상태를 복구하려면 `~/.claude/backups/`의 5개 가장 최근 `.claude.json.backup.<timestamp>` 파일 중 하나를 다시 복사합니다. Claude Code는 파일을 쓰기 전에 저장합니다.
980 637
981```json theme={null}638계속한 후 `/status`를 실행하여 영향을 받는 파일을 확인하고 각 오류의 세부 사항을 보려면 `claude doctor`를 실행합니다.
982{ "source": "npm", "package": "@acme-corp/claude-plugins" }
983{ "source": "npm", "package": "@acme-corp/approved-marketplace" }
984```
985 639
986필드: `package` (필수, 범위가 지정된 패키지 지원)640`-p` 실행은 대화를 표시하지 않습니다. [관리되는 설정 문서를 파싱할 수 없음](/docs/ko/errors#managed-settings-document-could-not-be-parsed)이 아니면 Claude Code는 손상된 파일이나 값을 건너뛰고 나머지로 계속합니다. 따라서 설정을 무시한 `-p` 실행 후 `claude doctor`를 실행하여 삭제된 것을 확인합니다.
987 641
9885. **파일 경로**:642<span id="how-scopes-interact" />
989 643
990```json theme={null}644<span id="key-points-about-the-configuration-system" />
991{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
992{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }
993```
994 645
995필드: `path` (필수: marketplace.json 파일의 절대 경로)646<span id="which-value-claude-code-uses" />
996 647
9976. **디렉토리 경로**:648<span id="which-value-wins" />
998 649
999```json theme={null}650<h2 id="settings-precedence">
1000{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }651 설정 우선순위
1001{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }652</h2>
1002```
1003 653
1004필드: `path` (필수: `.claude-plugin/marketplace.json`을 포함하는 디렉토리의 절대 경로)654동일한 키가 여러 위치에 나타나면 Claude Code는 가장 높은 수준에서 값을 사용합니다. 아래 스택은 수준을 보여줍니다. 맨 위가 가장 높습니다. 높은 수준의 키는 아래 어디든 동일한 키를 재정의합니다.
1005 655
10067. **호스트 패턴 일치**:656<SettingsPrecedence />
1007 657
1008```json theme={null}658순서대로, 가장 높은 우선순위 먼저:
1009{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
1010{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }
1011```
1012 659
1013필드: `hostPattern` (필수: 마켓플레이스 호스트와 일치하는 정규식 패턴)6601. **관리되는 설정**: 조직이 배포하는 설정. `managed-settings.json` 파일, MDM 정책, 또는 claude.ai 콘솔의 [서버 관리 설정](/docs/ko/server-managed-settings). 아무것도 재정의하지 않습니다: `--settings`로 전달하는 키는 동일한 관리되는 키를 재정의하지 않으며, `--model`과 같은 플래그는 조직이 허용하는 모델에서만 선택합니다. 관리되는 `model`은 각 세션이 시작하는 모델을 설정하고, 여전히 `/model`로 전환할 수 있습니다. 잠금은 [`availableModels`](/docs/ko/settings-reference#availablemodels)이며, `/model`, `--model`, 자신의 파일의 `model` 키를 제한합니다. 조직이 여러 관리되는 소스를 전달하면 [관리되는 계층 내 우선순위](/docs/ko/managed-settings#precedence-within-the-managed-tier)의 규칙이 Claude Code가 각각에서 읽는 것을 설명합니다.
6612. **명령줄 인수**: 터미널에서 `claude`를 시작할 때 전달하는 플래그. 한 세션용입니다. [한 세션에 대해 설정 변경](#change-a-setting-for-one-session)을 참조하세요. Claude Code는 `--settings <file-or-json>`으로 전달하는 JSON을 다른 수준과 동일한 규칙으로 병합합니다: 여기에 설정하는 키는 로컬, 프로젝트 또는 사용자 설정의 동일한 키를 가져가고, 생략하는 키는 낮은 수준 값을 유지합니다.
6623. **프로젝트 로컬 설정** (`.claude/settings.local.json`): 이 프로젝트에 대한 개인 설정.
6634. **공유 프로젝트 설정** (`.claude/settings.json`): 팀이 소스 제어에 체크인하는 설정.
6645. **사용자 설정** (`~/.claude/settings.json`): 모든 프로젝트에 대한 개인 설정.
1014 665
1015각 저장소를 열거하지 않고 특정 호스트의 모든 마켓플레이스를 허용하려면 호스트 패턴 일치를 사용합니다. 이는 개발자가 자신의 마켓플레이스를 만드는 내부 GitHub Enterprise 또는 GitLab 서버가 있는 조직에 유용합니다.666환경 변수는 이 스택의 수준이 아닙니다. 동작에 셸 변수와 설정 키가 모두 있으면 어느 것이 적용되는지는 수준별이 아니라 쌍별로 결정됩니다: `ANTHROPIC_MODEL`을 셸에서 내보내면 모든 파일의 `model` 키 위에 적용되는 반면, `ANTHROPIC_DEFAULT_MODEL`은 파일이 `model`을 설정하지 않을 때만 적용됩니다. [환경 변수 참조](/docs/ko/env-vars#precedence)는 어떤 키에 쌍이 있고 Claude Code가 먼저 읽는 것을 설명합니다. 설정 파일 내부의 `env` 블록은 일반 키이며 위의 수준을 따릅니다.
1016 667
1017소스 유형별 호스트 추출:668몇 가지 보안 민감 키의 경우 Claude Code는 낮은 수준의 더 엄격한 값을 관리되는 값보다 우선합니다. [관리되는 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)가 나열합니다.
1018 669
1019* `github`: 항상 `github.com`에 대해 일치670<h3 id="lists-merge-instead-of-overriding">
1020* `git`: URL에서 호스트 이름 추출 (HTTPS 및 SSH 형식 지원)671 목록은 재정의하지 않고 병합합니다
1021* `url`: URL에서 호스트 이름 추출672</h3>
1022* `npm`, `file`, `directory`: 호스트 패턴 일치에 지원되지 않음
1023 673
10248. **경로 패턴 일치**:674동일한 목록 키 (예: `permissions.allow`)를 여러 파일에 설정하면 Claude Code는 하나를 선택하지 않고 목록을 결합합니다. 따라서 각 파일은 다른 파일을 제거하지 않고 항목을 추가할 수 있습니다. 4개 키는 모델 목록 또는 모델별 항목을 보유하며 자체 규칙을 따릅니다:
1025 675
1026```json theme={null}676* [`fallbackModel`](/docs/ko/settings-reference#fallbackmodel)은 위치가 의미를 가지는 순서가 지정된 체인이므로 Claude Code는 이를 정의하는 가장 높은 우선순위 파일에서 전체 값을 가져갑니다.
1027{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }677* [`modelPicker`](/docs/ko/settings-reference#modelpicker)는 행의 하나의 순서가 지정된 목록과 바꾸기 플래그를 보유하므로 Claude Code는 두 소스의 행을 병합하지 않습니다. 관리되는 설정, `--settings`, 사용자 설정 중 가장 높은 것에서 전체 값을 가져가고 프로젝트 및 로컬 설정의 키를 무시합니다. Claude Code v2.1.242 이상이 필요합니다.
1028{ "source": "pathPattern", "pathPattern": ".*" }678* [`availableModels`](/docs/ko/settings-reference#availablemodels): Claude Code가 적용하는 관리되는 설정이 이를 정의할 때 Claude Code는 해당 목록을 그대로 적용하고 사용자, 프로젝트 또는 로컬 설정에 추가하는 항목을 무시합니다. embedding host가 자체 모델 목록을 제공하지 않으면 [관리되는 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)를 참조하세요. 관리되는 소스 전체에서 목록도 병합되지 않습니다. [Claude Code가 관리되는 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 어느 소스의 목록이 적용되는지 설명합니다. 비 관리되는 범위 전체에서 Claude Code는 평소대로 배열을 병합합니다.
1029```679* [`modelSettings`](/docs/ko/settings-reference#modelsettings): Claude Code는 [`effortLevel`](/docs/ko/settings-reference#effortlevel)과 함께 한 번에 하나의 모델로 해결합니다. `modelSettings` 항목은 어느 파일의 값이 모델에 적용되는지 설명합니다.
1030 680
1031필드: `pathPattern` (필수: `file` 및 `directory` 소스의 `path` 필드와 일치하는 정규식 패턴)681<span id="examples" />
1032 682
1033네트워크 소스에 대한 `hostPattern` 제한과 함께 파일 시스템 기반 마켓플레이스를 허용하려면 경로 패턴 일치를 사용합니다. 모든 로컬 경로를 허용하려면 `".*"`를 설정하거나 특정 디렉토리로 제한하려면 더 좁은 패턴을 설정합니다.683<h3 id="precedence-examples">
684 우선순위 예제
685</h3>
1034 686
1035**구성 예제**:687Claude가 작업하는 동안 Claude Code는 스피너 아래에 한 줄 팁을 표시합니다. 예: "권한 모드 기본값을 변경하려면 /config를 사용합니다 (Plan Mode 포함)". 팁을 끄고 싶어서 `~/.claude/settings.json`에서 [`spinnerTipsEnabled`](/docs/ko/settings-reference#spinnertipsenabled)를 `false`로 설정한다고 가정합니다. 아래의 각 시나리오는 팁을 다시 켤 수 있는 것과 할 수 있는 것입니다.
1036 688
1037예제: 특정 마켓플레이스만 허용:689<h4 id="team-settings-override-personal-settings">
690 팀 설정이 개인 설정을 재정의합니다
691</h4>
1038 692
1039```json theme={null}693팀의 `.claude/settings.json`이 이를 `true`로 설정합니다. Claude Code는 공유 프로젝트가 사용자 위에 있으므로 프로젝트 값을 사용합니다. 해당 프로젝트에서 팁을 보고 다른 곳에서는 보지 않습니다.
1040{
1041 "strictKnownMarketplaces": [
1042 {
1043 "source": "github",
1044 "repo": "acme-corp/approved-plugins"
1045 },
1046 {
1047 "source": "github",
1048 "repo": "acme-corp/security-tools",
1049 "ref": "v2.0"
1050 },
1051 {
1052 "source": "url",
1053 "url": "https://plugins.example.com/marketplace.json"
1054 },
1055 {
1056 "source": "npm",
1057 "package": "@acme-corp/compliance-plugins"
1058 }
1059 ]
1060}
1061```
1062 694
1063예제: 모든 마켓플레이스 추가 비활성화:695값을 다시 얻을 수 있습니다: 해당 프로젝트의 `.claude/settings.local.json`에 `"spinnerTipsEnabled": false`를 추가합니다. 프로젝트 로컬이 공유 프로젝트 위에 있으므로 세션이 팁을 표시하지 않고 팀원의 세션은 변경되지 않습니다.
1064 696
1065```json theme={null}697<h4 id="organization-settings-override-everything">
1066{698 조직 설정이 모든 것을 재정의합니다
1067 "strictKnownMarketplaces": []699</h4>
1068}
1069```
1070 700
1071예제: 내부 git 서버의 모든 마켓플레이스 허용:701조직의 관리되는 설정이 이를 `true`로 설정합니다. 사용자, 프로젝트 또는 로컬 설정에 넣은 것도 팁을 끄지 않으며, `--settings`도 끄지 않습니다. 관리됨이 최고 수준입니다.
1072 702
1073```json theme={null}703값을 다시 얻을 수 없습니다. `/status`를 실행하여 어느 관리되는 소스가 적용되는지 확인하고 정책이 변경되어야 하는지 관리자에게 문의합니다.
1074{
1075 "strictKnownMarketplaces": [
1076 {
1077 "source": "hostPattern",
1078 "hostPattern": "^github\\.example\\.com$"
1079 }
1080 ]
1081}
1082```
1083 704
1084**정확한 일치 요구 사항**:705<h4 id="the-command-line-overrides-your-files-for-one-session">
706 명령줄이 한 세션에 대해 파일을 재정의합니다
707</h4>
1085 708
1086마켓플레이스 소스는 사용자의 추가가 허용되려면 정확히 일치해야 합니다. git 기반 소스 (`github` 및 `git`)의 경우 이는 모든 선택적 필드를 포함합니다:709`claude --settings '{"spinnerTipsEnabled": true}'`로 세션을 시작했습니다. 명령줄이 관리됨을 제외한 모든 파일 위에 있으므로 해당 세션은 파일이 `false`라고 말해도 팁을 표시합니다.
1087 710
1088* `repo` 또는 `url`이 정확히 일치해야 합니다711다음 세션에서 값을 다시 얻습니다. `--settings`는 한 세션 동안 지속되고 파일에 작성하지 않습니다.
1089* `ref` 필드가 정확히 일치해야 합니다 (또는 둘 다 정의되지 않음)
1090* `path` 필드가 정확히 일치해야 합니다 (또는 둘 다 정의되지 않음)
1091 712
1092일치하지 않는 소스의 예:713<h4 id="a-flag-or-environment-variable-sets-the-same-thing">
714 플래그 또는 환경 변수가 동일한 것을 설정합니다
715</h4>
1093 716
1094```json theme={null}717일부 키에는 설정 값이 어느 파일에서 왔든 재정의하는 명령줄 플래그 또는 환경 변수가 있습니다: `ANTHROPIC_MODEL`은 [`model`](/docs/ko/settings-reference#model) 설정을 재정의하고, `--model`은 한 세션에 대해 둘 다 재정의합니다.
1095// 이들은 다른 소스입니다:
1096{ "source": "github", "repo": "acme-corp/plugins" }
1097{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }
1098 718
1099// 이것도 다릅니다:719값을 다시 얻을 수 있는지는 키에 따라 다릅니다: 변수를 설정 해제하거나 플래그를 제거하고, [설정 참조](/docs/ko/settings-reference)의 키 항목과 [환경 변수 참조](/docs/ko/env-vars)의 변수 행을 확인하여 Claude Code가 어느 것을 사용하는지 확인합니다.
1100{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
1101{ "source": "github", "repo": "acme-corp/plugins" }
1102```
1103 720
1104**`extraKnownMarketplaces`와의 비교**:721<span id="keys-ignored-in-a-repository-file" />
1105 722
1106| 측면 | `strictKnownMarketplaces` | `extraKnownMarketplaces` |723<span id="keys-only-you-or-your-organization-can-set" />
1107| ---------- | ------------------------- | ------------------------ |
1108| **목적** | 조직 정책 적용 | 팀 편의 |
1109| **설정 파일** | `managed-settings.json`만 | 모든 설정 파일 |
1110| **동작** | 허용 목록에 없는 추가 차단 | 누락된 마켓플레이스 자동 설치 |
1111| **적용 시기** | 네트워크/파일 시스템 작업 전 | 사용자 신뢰 프롬프트 후 |
1112| **재정의 가능** | 아니오 (최고 우선순위) | 예 (높은 우선순위 설정으로) |
1113| **소스 형식** | 직접 소스 객체 | 중첩된 소스가 있는 명명된 마켓플레이스 |
1114| **사용 사례** | 규정 준수, 보안 제한 | 온보딩, 표준화 |
1115 724
1116**형식 차이**:725<span id="common-cases" />
1117 726
1118`strictKnownMarketplaces`는 직접 소스 객체를 사용합니다:727<span id="which-value-applies-in-common-situations" />
1119 728
1120```json theme={null}729<h3 id="troubleshoot-a-setting-that-doesn’t-apply">
1121{730 적용되지 않는 설정 문제 해결
1122 "strictKnownMarketplaces": [731</h3>
1123 { "source": "github", "repo": "acme-corp/plugins" }
1124 ]
1125}
1126```
1127 732
1128`extraKnownMarketplaces`는 명명된 마켓플레이스가 필요합니다:733설정을 설정했는데 Claude Code가 설정한 것처럼 동작하지 않으면 `/status`로 시작하여 로드된 파일을 확인한 다음 아래에서 증상을 찾습니다. [구성 디버깅](/docs/ko/debug-your-config)은 깨끗한 구성 테스트를 포함한 더 넓은 검사를 다룹니다.
1129 734
1130```json theme={null}735<h4 id="a-value-you-set-is-ignored">
1131{736 설정한 값이 무시됩니다
1132 "extraKnownMarketplaces": {737</h4>
1133 "acme-tools": {
1134 "source": { "source": "github", "repo": "acme-corp/plugins" }
1135 }
1136 }
1137}
1138```
1139 738
1140**함께 사용**:739다른 것이 동일한 키를 설정하거나, 파일이 해당 값을 설정할 수 없거나, 파일이 로드되지 않았습니다:
1141 740
1142`strictKnownMarketplaces`는 정책 게이트입니다: 사용자가 추가할 수 있는 것을 제어하지만 마켓플레이스를 등록하지 않습니다. 모든 사용자를 위해 마켓플레이스를 제한하고 사전 등록하려면 `managed-settings.json`에서 둘 다 설정합니다:741* **더 높은 수준이 설정합니다.** 다른 설정 파일, `--settings` 플래그, 또는 관리되는 소스가 당신의 위에 키를 설정합니다. [스택](#settings-precedence)은 어느 것을 설명합니다. 플래그 또는 환경 변수도 자체적으로 키를 재정의할 수 있습니다. 쌍별로 결정됩니다. [설정 참조](/docs/ko/settings-reference)의 키 항목은 Claude Code가 어느 것을 사용하는지 설명하고, [`env` 항목](/docs/ko/settings-reference#env)은 관리되는 `env` 값 대 셸 내보내기를 다룹니다.
742* **보안 키가 엄격한 값을 유지합니다.** 몇 가지 키의 경우 Claude Code는 모든 파일에서 제한적 값을 우선합니다. 예: 프로젝트 `true`는 [`disableClaudeAiConnectors`](/docs/ko/settings-reference#disableclaudeaiconnectors)에 대해 유지됩니다. [관리되는 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)를 참조하세요.
743* **파일이 해당 값을 설정할 수 없습니다.** [`permissions.defaultMode`](/docs/ko/settings-reference#permissions-defaultmode) 값 `auto` 및 `bypassPermissions`은 프로젝트 또는 로컬 설정에서 적용되지 않습니다. 대신 사용자 또는 관리되는 설정에서 설정하거나 한 세션에 대해 `--permission-mode`를 전달합니다. v2.1.257 이전에 `bypassPermissions`은 모든 파일에서 적용되었습니다.
744* **파일이 손상되었습니다.** 유효하지 않은 JSON 또는 거부된 값은 Claude Code가 파일이나 항목을 건너뛰게 합니다. [손상된 설정 파일 수정](#fix-a-broken-settings-file)을 참조하세요.
1143 745
1144```json theme={null}746<h4 id="a-change-you-made-in-claude-code-is-lost-in-new-sessions">
1145{747 Claude Code에서 만든 변경이 새 세션에서 손실됩니다
1146 "strictKnownMarketplaces": [748</h4>
1147 { "source": "github", "repo": "acme-corp/plugins" }
1148 ],
1149 "extraKnownMarketplaces": {
1150 "acme-tools": {
1151 "source": { "source": "github", "repo": "acme-corp/plugins" }
1152 }
1153 }
1154}
1155```
1156 749
1157`strictKnownMarketplaces`만 설정되면 사용자는 여전히 `/plugin marketplace add`를 통해 허용된 마켓플레이스를 수동으로 추가할 수 있지만 자동으로 사용 가능하지 않습니다.750Claude Code 내에서 `/model`로 기본 모델을 설정하는 것과 같이 새 세션에 대한 선택을 저장하면 Claude Code가 사용자 설정 파일 `~/.claude/settings.json`에 작성합니다. 해당 파일에 쓸 수 없으면 (예: 다른 도구가 생성하거나 읽기 전용 복사본에 연결), 변경이 현재 세션에 적용되고 다음 세션에서 사라집니다. 파일을 생성하는 도구에서 키를 설정하거나 파일을 쓸 수 있는 것으로 바꿉니다.
1158 751
1159**중요 참고 사항**:752파일에 쓸 수 있고 변경이 여전히 지속되지 않으면 변경이 [한 세션만](#change-a-setting-for-one-session) 또는 [더 높은 수준이 동일한 키를 설정](#a-value-you-set-is-ignored)하는지 확인합니다. `model` 키의 경우 [새 세션이 선택한 것과 다른 모델에서 시작합니다](/docs/ko/model-config#a-new-session-starts-on-a-different-model-than-you-picked)가 더 많은 원인을 나열합니다.
1160 753
1161* 제한은 네트워크 요청 또는 파일 시스템 작업 전에 확인됩니다754<h4 id="a-managed-change-hasn’t-reached-you">
1162* 차단되면 사용자는 소스가 managed 정책으로 차단되었음을 나타내는 명확한 오류 메시지를 봅니다755 관리되는 변경이 당신에게 도달하지 않았습니다
1163* 제한은 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용됩니다. 정책이 설정되기 전에 추가된 마켓플레이스는 해당 소스가 더 이상 허용 목록과 일치하지 않으면 플러그인을 설치하거나 업데이트하는 데 사용할 수 없습니다756</h4>
1164* Managed 설정은 최고 우선순위를 가지며 재정의할 수 없습니다
1165 757
1166사용자 대면 문서는 [Managed 마켓플레이스 제한](/docs/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요.758관리되는 소스는 [전달 테이블](/docs/ko/managed-settings#choose-a-delivery-mechanism)의 일정에 따라 실행 중인 세션에 도달하므로 먼저 세션을 다시 시작합니다. `/status`가 관리자가 변경한 것과 다른 소스의 이름을 지정하면 더 높은 우선순위 소스가 적용됩니다. [Claude Code가 관리되는 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 순서를 제공합니다.
1167 759
1168<h4 id="strictpluginonlycustomization">760<h4 id="a-committed-key-doesn’t-reach-teammates">
1169 `strictPluginOnlyCustomization`761 커밋된 키가 팀원에게 도달하지 않습니다
1170</h4>762</h4>
1171 763
1172**Managed 설정만**: skills, agents, hooks 및 MCP servers가 사용자 및 프로젝트 소스에서 로드되는 것을 차단하므로 플러그인 또는 managed 설정에서만 가져올 수 있습니다. `strictKnownMarketplaces`와 결합하여 전체 사용자 정의 공급 체인을 제어합니다: 마켓플레이스 허용 목록은 사용자가 설치할 수 있는 플러그인을 제어하고 이 설정은 플러그인 또는 managed 설정에서 오지 않는 모든 것을 차단합니다.7642가지가 `.claude/settings.json`의 키가 복제하는 모든 사람에게 적용되는 것을 방지합니다:
1173
1174값은 모든 4개 표면을 잠그려면 `true`이거나 잠글 표면을 명명하는 배열입니다:
1175 765
1176```json theme={null}766* **Claude Code가 저장소 파일의 키를 무시합니다.** [설정 인덱스](/docs/ko/settings-reference#settings-index)의 범위 열에서 `User, local, or managed`, `User or managed`, `Managed`, 또는 `Global config`를 찾습니다. 해당 키는 공유 파일에서 적용되지 않습니다. [`autoContinueAtUsageLimit`](/docs/ko/settings-reference#autocontinueatusagelimit) 제외. 저장소 파일은 여전히 키를 끌 수 있습니다: 파일이 키를 설정하고 사용자, `--settings`, 또는 관리되는 값이 하지 않으면 Claude Code는 설정을 끈 것으로 읽습니다. `Global config` 키는 `~/.claude.json`에서만 적용됩니다.
1177{767* **키가 신뢰를 기다립니다.** `permissions.allow` 규칙, `permissions.additionalDirectories`, `extraKnownMarketplaces`, 대부분의 [`env`](/docs/ko/settings-reference#env) 값은 각 팀원이 [폴더를 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)한 후에만 적용됩니다. 그때까지 여전히 프롬프트를 보고 파일이 선언하는 마켓플레이스에서 플러그인을 받지 않습니다. `deny` 및 `ask` 규칙은 즉시 적용됩니다.
1178 "strictPluginOnlyCustomization": ["skills", "hooks"]
1179}
1180```
1181 768
1182각 잠긴 표면에 대해 Claude Code는 사용자 수준 및 프로젝트 수준 소스를 건너뛰고 플러그인 제공 및 managed 소스만 로드합니다:769<h4 id="permission-rules-combine-differently-than-you-expected">
770 권한 규칙이 예상과 다르게 결합됩니다
771</h4>
1183 772
1184| 표면 | 잠금 시 차단됨 | 여전히 로드됨 |773* **권한 프롬프트에서 "예, 다시 묻지 마세요"를 선택했지만 여전히 동일한 도구에 대해 프롬프트를 받습니다.** 해당 선택이 로컬 파일에 `allow` 규칙을 저장했고, `allow` 규칙은 프로젝트 또는 관리되는 파일의 `ask` 규칙을 능가하지 않습니다. [권한 규칙이 결합되는 방식](/docs/ko/permissions#settings-precedence)은 순서를 설명합니다. VS Code 확장에서 승인 카드는 프로젝트의 공유 파일을 포함한 대상 파일을 선택할 수 있으므로 모든 사람의 규칙을 변경합니다. CLI에서 Claude Code는 로컬 파일에만 작성합니다.
1185| :------- | :--------------------------------------- | :-------------------------------------------------------------- |774* **조직의 allow 규칙이 당신의 것과 함께 적용됩니다.** 예상됩니다: Claude Code는 [`permissions.allow`](/docs/ko/settings-reference#permissions-allow)를 범위 전체에서 병합합니다. [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly)를 설정하지 않으면.
1186| `skills` | `~/.claude/skills/`, `.claude/skills/` | 플러그인 skills, 번들된 skills, managed 정책 디렉토리의 skills |
1187| `agents` | `~/.claude/agents/`, `.claude/agents/` | 플러그인 agents, 기본 제공 agents, managed 정책 디렉토리의 agents |
1188| `hooks` | 사용자, 프로젝트 및 local `settings.json`의 hooks | 플러그인 hooks, managed 설정의 hooks |
1189| `mcp` | `~/.claude.json` 및 `.mcp.json`의 서버 | 플러그인 MCP servers, [`managed-mcp.json`](/docs/ko/managed-mcp) servers |
1190 775
1191Claude Code 버전이 인식하지 못하는 표면 이름은 설정 파일을 실패시키지 않고 무시되므로 모든 클라이언트가 업데이트되기 전에 새 표면 이름을 추가할 수 있습니다.776<span id="security-keys-where-the-stricter-value-applies" />
1192 777
1193<h3 id="manage-plugins">778<h3 id="exceptions-to-managed-settings-precedence">
1194 플러그인 관리779 관리되는 설정 우선순위의 예외
1195</h3>780</h3>
1196 781
1197`/plugin` 명령을 사용하여 플러그인을 대화형으로 관리합니다:782몇 가지 보안 민감 키의 경우 Claude Code는 다른 경우 관리되는 설정을 재정의할 수 없는 범위에서 제한적 값을 우선합니다. 이 테이블에서 키를 찾아 우선하는 값과 어디서 오는지 확인합니다.
1198 783
1199* 마켓플레이스에서 사용 가능한 플러그인 찾아보기784| 키 | Claude Code가 우선하는 값 | 참고 |
1200* 플러그인 설치/제거785| :------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
1201* 플러그인 활성화/비활성화786| [`disableClaudeAiConnectors`](/docs/ko/settings-reference#disableclaudeaiconnectors) | 모든 범위의 `true` | 관리되는 소스가 `false`를 설정해도 우선합니다 |
1202* 플러그인 세부 정보 보기 (제공되는 skills, agents, hooks)787| [`enableArtifact`](/docs/ko/settings-reference#enableartifact) | 모든 범위의 `false`, 모든 범위의 `disableArtifact: true` | 관리되는 소스가 `true`를 설정해도 우선합니다. 아무것도 [Artifact 도구](/docs/ko/artifacts#disable-artifacts)를 다시 켜지 않습니다. Claude Code v2.1.242 이상이 필요합니다 |
1203* 마켓플레이스 추가/제거788| [`isolatePeerMachines`](/docs/ko/settings-reference#isolatepeermachines) | 모든 범위의 `true` | 관리되는 소스가 `false`를 설정해도 우선합니다 |
789| [`remoteControlAtStartup`](/docs/ko/settings-reference#remotecontrolatstartup) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 `false` | 관리되는 소스가 `true`를 설정해도 우선합니다. 프로젝트 또는 로컬 `true`는 무시됩니다 |
790| [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 더 엄격한 값. `accept` \< `hold` \< `refuse` 사다리 | 관리되는, `--settings`, 사용자 값보다 우선합니다. 프로젝트 또는 로컬 값이 더 엄격하지 않으면 무시됩니다 |
791| [`useAutoModeDuringPlan`](/docs/ko/settings-reference#useautomodeduringplan) | 모든 관리되는 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 우승 관리되는 소스가 `true`를 설정해도 우선합니다. `.claude/settings.json`의 `false`는 무시됩니다 |
792| [`syncClaudeAiSkills`](/docs/ko/settings-reference#syncclaudeaiskills) | 모든 관리되는 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 우승 관리되는 소스가 `true`를 설정해도 우선합니다. `.claude/settings.json`의 `false`는 무시됩니다 |
1204 793
1205[플러그인 문서](/docs/ko/plugins)에서 플러그인 시스템에 대해 자세히 알아보세요.794Claude Code를 자체 내부에서 실행하고 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ko/env-vars)를 설정하는 앱도 예외입니다. Claude Code는 모든 관리되는 소스의 `model`, `fallbackModel`, `modelOverrides` 키 위에 해당 앱의 모델 구성을 가져가고, 관리되는 `env` 블록의 `ANTHROPIC_MODEL` 및 `ANTHROPIC_DEFAULT_*_MODEL` 패밀리와 같은 모델 선택 변수를 가져갑니다. Claude Code는 앱이 자체를 제공하지 않으면 관리되는 [`availableModels`](/docs/ko/settings-reference#availablemodels) 허용 목록을 적용합니다.
1206 795
1207<h2 id="environment-variables">796<h2 id="settings-in-cloud-sessions">
1208 환경 변수797 클라우드 세션의 설정
1209</h2>798</h2>
1210 799
1211환경 변수를 사용하면 설정 파일을 편집하지 않고 Claude Code 동작을 제어할 수 있습니다. 모든 변수는 [`settings.json`](#available-settings)의 `env` 키 아래에서 구성하여 모든 세션에 적용하거나 팀에 배포할 수 있습니다.800클라우드 세션은 [Claude Code on the web](/docs/ko/claude-code-on-the-web) 또는 [`claude --cloud`](/docs/ko/claude-code-on-the-web#from-terminal-to-web)에서 [클라우드 환경](/docs/ko/cloud-environments)에서 저장소의 신선한 복제본에서 실행되며, 머신에서 실행되지 않습니다. 이는 어느 설정이 도달하는지 변경합니다:
1212
1213전체 목록은 [환경 변수 참조](/docs/ko/env-vars)를 참조하세요.
1214
1215<h2 id="tools-available-to-claude">
1216 Claude가 사용할 수 있는 도구
1217</h2>
1218 801
1219Claude Code는 파일 읽기, 편집, 검색, 명령 실행 및 subagents 조율을 위한 도구 세트에 액세스할 수 있습니다. 도구 이름은 권한 규칙 및 hook 매처에서 사용하는 정확한 문자열입니다.802* **공유 프로젝트 설정** (`.claude/settings.json`): 읽습니다. 파일이 복제본의 일부이기 때문입니다. 클라우드 세션에 적용하려면 설정을 거기에 커밋합니다.
803* **사용자 및 프로젝트 로컬 설정** (`~/.claude/settings.json` 및 `.claude/settings.local.json`): 읽지 않습니다. 둘 다 머신에 유지되고 로컬 파일은 복제본에 없습니다.
804* **관리되는 설정**: [서버 관리 설정](/docs/ko/server-managed-settings)만 클라우드 세션에 도달합니다. 장치의 `managed-settings.json` 파일이나 MDM 프로필은 도달하지 않습니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)도 실행기 이미지의 관리되는 설정 파일을 읽습니다. [Claude Code가 관리되는 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 해당 파일이 적용되는 시기를 설명합니다.
805* **`/config`**: 웹에서 설정 파일을 변경하는 대신 claude.ai 설정의 Claude Code 섹션을 엽니다. 클라우드 세션에 대해 설정을 변경하려면 환경에서 [환경 변수](/docs/ko/cloud-environments#set-environment-variables)를 설정하거나 저장소의 `.claude/settings.json`에 키를 커밋합니다.
1220 806
1221전체 목록 및 Bash 도구 동작 세부 사항은 [도구 참조](/docs/ko/tools-reference)를 참조하세요.807[설정에서 수행되는 것](/docs/ko/cloud-environments#what-carries-over-from-your-setup)은 나머지를 나열합니다: `CLAUDE.md`, skills, MCP 서버, 플러그인, 자격 증명.
1222 808
1223<h2 id="see-also">809<h2 id="what’s-next">
1224 참고 항목810 다음 단계
1225</h2>811</h2>
1226 812
1227* [권한](/docs/ko/permissions): 권한 시스템, 규칙 구문, 도구 특정 패턴 및 관리형 정책813* [모든 설정](/docs/ko/settings-reference): 모든 키, 설정 위치, 기본값, 예제
1228* [인증](/docs/ko/authentication): Claude Code에 대한 사용자 액세스 설정814* [예제 설정 파일](/docs/ko/settings-example): 개인 파일, 팀 파일, 조직의 관리되는 파일
1229* [구성 디버깅](/docs/ko/debug-your-config): 설정, 훅 또는 MCP 서버가 적용되지 않는 이유를 진단합니다815* [권한 구성](/docs/ko/permissions): allow, ask, deny 규칙, Claude Code가 묻지 않고 실행하는 것
1230* [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install): 설치, 인증 및 플랫폼 문제816* [환경 변수](/docs/ko/env-vars): Claude Code가 읽는 변수 및 `env` 블록
817* [구성 디버깅](/docs/ko/debug-your-config): 설정이 적용되지 않을 때
818* [Claude 디렉토리 참조](/docs/ko/claude-directory): Claude Code가 읽는 모든 파일. subagents, MCP 서버, 플러그인, `CLAUDE.md` 포함