Documentation — Spybara

agent-sdk/agent-loop.md +2 −2

Details

291| :- | :- | :- |291| :- | :- | :- |

294| **도구 정의** | 모든 요청; MCP 스키마는 기본적으로 지연됨 | 기본 제공 도구 스키마는 모든 요청에서 로드됩니다. [도구 검색](/docs/ko/agent-sdk/mcp#mcp-tool-search)은 기본적으로 MCP 도구 스키마를 지연시키며, 지원되지 않는 모델 및 특정 플랫폼에서 사전 로드로 폴백합니다. 전체 매트릭스는 [도구 검색 구성](/docs/ko/agent-sdk/tool-search#configure-tool-search)을 참조하세요 |294| **도구 정의** | Bash, Read, Edit 같은 핵심 기본 제공 도구는 모든 요청; MCP 도구 및 기타 기본 제공 도구는 필요 시([도구 검색](/docs/ko/agent-sdk/mcp#mcp-tool-search)이 기본적으로 지연시킴) | [도구 검색 구성](/docs/ko/agent-sdk/tool-search#configure-tool-search)에 설명된 경우에는 모든 스키마가 사전에 로드됩니다 |

297 297

331 331

332장기 실행 에이전트를 위한 몇 가지 전략:332장기 실행 에이전트를 위한 몇 가지 전략:

333 333

334* **서브작업에 서브에이전트 사용.** 각 서브에이전트는 새로운 대화로 시작합니다(이전 메시지 기록 없음, 자신의 시스템 프롬프트 및 CLAUDE.md 같은 프로젝트 수준 컨텍스트는 로드함). 부모의 턴을 보지 않으며, 최종 응답만 부모에게 반환됩니다. 주 에이전트의 컨텍스트는 전체 서브작업 트랜스크립트가 아니라 해당 요약으로 증가합니다. 자세한 내용은 [서브에이전트가 상속하는 것](/docs/ko/agent-sdk/subagents#what-subagents-inherit)을 참조하세요.334* **서브작업에 서브에이전트 사용.** 서브에이전트는 최종 응답만 반환하므로 주 에이전트의 컨텍스트는 서브작업의 트랜스크립트가 아니라 요약만큼만 증가합니다.

335* **도구를 선택적으로 사용합니다.** 모든 도구 정의는 컨텍스트 공간을 차지합니다. [`AgentDefinition`](/docs/ko/agent-sdk/subagents#agentdefinition-configuration)의 `tools` 필드를 사용하여 서브에이전트를 필요한 최소 세트로 범위를 지정합니다.335* **도구를 선택적으로 사용합니다.** 모든 도구 정의는 컨텍스트 공간을 차지합니다. [`AgentDefinition`](/docs/ko/agent-sdk/subagents#agentdefinition-configuration)의 `tools` 필드를 사용하여 서브에이전트를 필요한 최소 세트로 범위를 지정합니다.

336* **MCP 서버 비용을 주시합니다.** [MCP 도구 검색](/docs/ko/agent-sdk/mcp#mcp-tool-search)은 기본적으로 MCP 도구 스키마를 지연시키고 필요에 따라 로드합니다. 도구 검색이 꺼져 있거나 사전 로드로 폴백된 경우 각 MCP 서버는 모든 도구 스키마를 모든 요청에 추가하므로 많은 도구가 있는 몇 개의 서버는 에이전트가 작업을 수행하기 전에 상당한 컨텍스트를 소비할 수 있습니다. 폴백이 적용되는 구성에 대해서는 [도구 검색 구성](/docs/ko/agent-sdk/tool-search#configure-tool-search)을 참조하세요.336* **MCP 서버 비용을 주시합니다.** [MCP 도구 검색](/docs/ko/agent-sdk/mcp#mcp-tool-search)은 기본적으로 MCP 도구 스키마를 지연시키고 필요에 따라 로드합니다. 도구 검색이 꺼져 있거나 사전 로드로 폴백된 경우 각 MCP 서버는 모든 도구 스키마를 모든 요청에 추가하므로 많은 도구가 있는 몇 개의 서버는 에이전트가 작업을 수행하기 전에 상당한 컨텍스트를 소비할 수 있습니다. 폴백이 적용되는 구성에 대해서는 [도구 검색 구성](/docs/ko/agent-sdk/tool-search#configure-tool-search)을 참조하세요.

337* **일상적인 작업에 낮은 effort를 사용합니다.** 파일을 읽거나 디렉토리를 나열하기만 하면 되는 에이전트의 경우 [effort](#effort-level)를 `"low"`로 설정합니다. 이는 토큰 사용량과 비용을 줄입니다.337* **일상적인 작업에 낮은 effort를 사용합니다.** 파일을 읽거나 디렉토리를 나열하기만 하면 되는 에이전트의 경우 [effort](#effort-level)를 `"low"`로 설정합니다. 이는 토큰 사용량과 비용을 줄입니다.

agent-sdk/permissions.md +1 −8

Details

123 123

124권한 모드는 Claude가 도구를 사용하는 방식을 전역적으로 제어합니다. `query()`를 호출할 때 권한 모드를 설정하거나 스트리밍 세션 중에 동적으로 변경할 수 있습니다.124권한 모드는 Claude가 도구를 사용하는 방식을 전역적으로 제어합니다. `query()`를 호출할 때 권한 모드를 설정하거나 스트리밍 세션 중에 동적으로 변경할 수 있습니다.

125 125

126권한 모드를 설정하지 않으면 Claude Code는 [세션이 시작되는 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)의 규칙에 따라 시작 권한 모드를 선택합니다.126Claude Code v2.1.302 이상에서는 권한 모드를 설정하지 않거나 앱이 설정 파일의 [`permissions.defaultMode`](/docs/ko/settings-reference#permissions-defaultmode)에서 권한 모드를 가져오지 않는 한 앱이 `default` 모드에서 시작합니다. `default` 모드에서 Claude Code는 승인이 필요한 도구 호출을 허용 규칙, 훅, `canUseTool` 콜백 또는 권한 프롬프트 도구를 통해 승인하지 않으면 거부합니다. 도구 호출이 거부되는 경우 [`claude -p` 및 Agent SDK 실행에서 거부되는 도구 호출](/docs/ko/permission-modes#which-mode-a-non-interactive-run-starts-in)을 참조하세요.

~~127~~

128* 적용되는 세션의 [설정 파일](/docs/ko/settings#where-settings-live)의 `permissions.defaultMode`

129* 그렇지 않으면 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)일 수 있는 기본 제공 기본값

~~130~~

131자동 모드에서 시작하는 세션은 `Bash` 항목과 같은 광범위한 허용 규칙을 삭제합니다. [자동 모드가 작업을 평가하는 방식](/docs/ko/permission-modes#how-auto-mode-evaluates-actions)에서 설명합니다. 애플리케이션이 `default` 모드 또는 이러한 규칙에 의존하는 경우 `default`를 명시적으로 전달하세요.

~~132~~

133TypeScript Agent SDK v0.3.286 이전에는 `permissionMode`를 생략하는 것이 `default`를 전달하는 것과 동일했습니다.

134 127

135<h3 id="available-modes">128<h3 id="available-modes">

136 사용 가능한 모드129 사용 가능한 모드

agent-sdk/python.md +1 −1

Details

1035)1035)

1036```1036```

1037 1037

1038* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청당 타임아웃 (밀리초). 기본값 `600000`. 주 루프 및 모든 서브에이전트에 적용됩니다.1038* [`API_TIMEOUT_MS`](/docs/ko/env-vars): 각 요청 시도가 응답 헤더를 기다릴 수 있는 시간 (밀리초). 헤더가 도착한 후 스트리밍 응답이 실행되는 시간은 제한하지 않습니다. 기본값 `600000`. 주 루프 및 모든 서브에이전트에 적용됩니다.

1039* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도. 기본값 `10`, 최대 `15`로 제한됨. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가집니다.1039* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도. 기본값 `10`, 최대 `15`로 제한됨. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가집니다.

1040 1040

1041 더 긴 중단을 기다려야 하는 무인 실행의 경우, [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/ko/errors#tune-retry-behavior)을 설정합니다. 이 설정은 일시적 용량 오류를 무한정 재시도하며, Claude Code v2.1.199 이상에서는 다른 일시적 오류의 기본값을 `300`으로 올리고 이 변수의 상한을 제거합니다.1041 더 긴 중단을 기다려야 하는 무인 실행의 경우, [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/ko/errors#tune-retry-behavior)을 설정합니다. 이 설정은 일시적 용량 오류를 무한정 재시도하며, Claude Code v2.1.199 이상에서는 다른 일시적 오류의 기본값을 `300`으로 올리고 이 변수의 상한을 제거합니다.

agent-sdk/subagents.md +33 −2

Details

172 172

173Python SDK에서 `disallowedTools` 및 `mcpServers`와 같은 다중 단어 필드 이름은 Python의 snake\_case 규칙을 따르지 않고 와이어 형식과 일치하도록 camelCase 철자를 유지합니다. 자세한 내용은 [`AgentDefinition` 참조](/docs/ko/agent-sdk/python#agentdefinition)를 참조하십시오.173Python SDK에서 `disallowedTools` 및 `mcpServers`와 같은 다중 단어 필드 이름은 Python의 snake\_case 규칙을 따르지 않고 와이어 형식과 일치하도록 camelCase 철자를 유지합니다. 자세한 내용은 [`AgentDefinition` 참조](/docs/ko/agent-sdk/python#agentdefinition)를 참조하십시오.

174 174

175서브에이전트는 기본적으로 백그라운드에서 실행됩니다. [`run_in_background`](/docs/ko/sub-agents#run-subagents-in-foreground-or-background) 입력을 생략하는 Agent 도구 호출은 백그라운드 서브에이전트를 시작하며, Claude는 계속하기 전에 결과가 필요할 때 `run_in_background: false`를 설정합니다. 특정 에이전트에 대해 `background` 필드를 `true`로 설정하여 Claude가 요청하는 것과 관계없이 백그라운드 실행을 강제합니다. Claude Code v2.1.198 이전에는 백그라운드 기본값이 점진적으로 출시되었으며, `run_in_background`를 생략하는 Agent 도구 호출은 서브에이전트를 동기적으로 실행할 수 있었습니다.175<h4 id="choose-whether-claude-waits-for-subagents">

176 Claude가 서브에이전트를 기다릴지 선택하기

177</h4>

176 178

177서브에이전트는 자신의 서브에이전트를 생성할 수도 있습니다. 해당 중첩이 얼마나 깊은지, 한 번에 몇 개의 서브에이전트가 실행되는지, 쿼리가 얼마나 많이 소비하는지를 제한하려면 [서브에이전트 깊이, 동시성 및 지출 제한](#cap-subagent-depth-concurrency-and-spend)을 참조하십시오.179기본적으로 주 에이전트가 생성하는 서브에이전트는 [백그라운드에서 실행됩니다](/docs/ko/sub-agents#run-subagents-in-foreground-or-background). Agent 도구 결과에는 `status: "async_launched"`가 포함되며, 보고서는 이후 턴에 도착합니다.

180

181Claude는 다음 작업에 보고서가 필요할 때 기다립니다. 이 경우 호출이 차단되고 `status: "completed"`를 반환합니다. 이 선택을 직접 하려면 다음과 같이 합니다.

182

183* **프롬프트에서**: "test-runner 에이전트를 실행하고 완료될 때까지 기다려"와 같이 Claude에게 기다리도록 요청합니다

184* **정의에서**: 해당 에이전트를 백그라운드에 유지하려면 `background`를 `true`로 설정합니다

178 185

179<h3 id="filesystem-based-definition-alternative">186<h3 id="filesystem-based-definition-alternative">

180 파일 시스템 기반 정의 (대안)187 파일 시스템 기반 정의 (대안)

242 249

243이는 자동 일치를 우회하고 명명된 서브에이전트를 직접 호출합니다.250이는 자동 일치를 우회하고 명명된 서브에이전트를 직접 호출합니다.

244 251

252<h3 id="forked-subagents">

253 포크된 서브에이전트

254</h3>

255

256[포크](/docs/ko/sub-agents#fork-the-current-conversation)는 새로 시작하는 대신 지금까지의 대화를 복사하는 서브에이전트입니다. Claude Code v2.1.302부터 Claude는 별도의 구성 없이 `subagent_type: "fork"`로 Agent 도구를 호출하여 애플리케이션에서 포크를 시작할 수 있습니다.

257

258Claude가 포크를 시작하지 못하도록 하려면 [`Agent(fork)` 거부 규칙](/docs/ko/agent-sdk/permissions#allow-and-deny-rules)을 추가하십시오:

259

260<CodeGroup>

261 ```python Python theme={null}

262 options = ClaudeAgentOptions(

263 # Deny only the fork subagent type; other subagents still run

264 disallowed_tools=["Agent(fork)"],

265 )

266 ```

267

268 ```typescript TypeScript theme={null}

269 const options = {

270 // Deny only the fork subagent type; other subagents still run

271 disallowedTools: ["Agent(fork)"]

272 };

273 ```

274</CodeGroup>

275

245<h3 id="dynamic-agent-configuration">276<h3 id="dynamic-agent-configuration">

246 동적 에이전트 구성277 동적 에이전트 구성

247</h3>278</h3>

agent-sdk/typescript.md +2 −2

Details

610| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 에이전트 결과의 출력 형식을 정의합니다. 자세한 내용은 [구조화된 출력](/docs/ko/agent-sdk/structured-outputs)을 참조하세요 |610| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 에이전트 결과의 출력 형식을 정의합니다. 자세한 내용은 [구조화된 출력](/docs/ko/agent-sdk/structured-outputs)을 참조하세요 |

611| `outputStyle` | `string` | `undefined` | `Options` 필드가 아닙니다. 대신 인라인 [`settings`](/docs/ko/settings) 객체나 설정 파일에서 `outputStyle`을 설정하세요. [출력 스타일 활성화](/docs/ko/agent-sdk/modifying-system-prompts#activate-an-output-style)를 참조하세요 |611| `outputStyle` | `string` | `undefined` | `Options` 필드가 아닙니다. 대신 인라인 [`settings`](/docs/ko/settings) 객체나 설정 파일에서 `outputStyle`을 설정하세요. [출력 스타일 활성화](/docs/ko/agent-sdk/modifying-system-prompts#activate-an-output-style)를 참조하세요 |

613| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | 세션의 권한 모드입니다. 생략하면 세션이 자동 모드로 시작될 수 있습니다. Claude Code가 시작 권한 모드를 선택하는 방식은 [권한 모드](/docs/ko/agent-sdk/permissions#permission-modes)를 참조하세요 |613| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | 세션의 권한 모드입니다. 이 옵션을 생략하고 [`permissions.defaultMode`](/docs/ko/settings-reference#permissions-defaultmode) 설정처럼 권한 모드를 설정하는 다른 요소가 없으면 세션은 `default`로 시작합니다. [권한 모드](/docs/ko/agent-sdk/permissions#permission-modes)를 참조하세요 |

615| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 권한 프롬프트에 응답하는 주체입니다. `'host'`는 프롬프트를 [`canUseTool`](#canusetool) 콜백 또는 `permissionPromptToolName` 도구로 라우팅하고, `'none'`은 [프롬프트를 표시했을 호출을 거부합니다](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated). Claude Code v2.1.259 이상이 필요합니다 |615| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 권한 프롬프트에 응답하는 주체입니다. `'host'`는 프롬프트를 [`canUseTool`](#canusetool) 콜백 또는 `permissionPromptToolName` 도구로 라우팅하고, `'none'`은 [프롬프트를 표시했을 호출을 거부합니다](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated). Claude Code v2.1.259 이상이 필요합니다 |

662});662});

663```663```

664 664

665* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청별 타임아웃(밀리초)입니다. 기본값은 `600000`입니다. 메인 루프와 모든 서브에이전트에 적용됩니다.665* [`API_TIMEOUT_MS`](/docs/ko/env-vars): 각 요청 시도가 응답 헤더를 기다릴 수 있는 시간(밀리초)입니다. 헤더가 도착한 후 스트리밍 응답이 실행되는 시간은 제한하지 않습니다. 기본값은 `600000`입니다. 메인 루프와 모든 서브에이전트에 적용됩니다.

666* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도 횟수입니다. 기본값은 `10`이며 상한은 `15`입니다. 각 재시도는 자체 `API_TIMEOUT_MS` 시간 범위를 가집니다.666* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도 횟수입니다. 기본값은 `10`이며 상한은 `15`입니다. 각 재시도는 자체 `API_TIMEOUT_MS` 시간 범위를 가집니다.

667 667

668 더 긴 장애를 기다려야 하는 무인 실행의 경우 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/ko/errors#tune-retry-behavior)을 설정하세요. 이 설정은 일시적인 용량 오류를 무기한 재시도하며, Claude Code v2.1.199 이상에서는 다른 일시적 오류에 대한 기본값을 `300`으로 올리고 이 변수의 상한을 제거합니다.668 더 긴 장애를 기다려야 하는 무인 실행의 경우 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/ko/errors#tune-retry-behavior)을 설정하세요. 이 설정은 일시적인 용량 오류를 무기한 재시도하며, Claude Code v2.1.199 이상에서는 다른 일시적 오류에 대한 기본값을 `300`으로 올리고 이 변수의 상한을 제거합니다.

agent-teams.md +1 −1

Details

557* **종료가 느릴 수 있음**: 팀원들은 현재 요청이나 도구 호출을 마친 후 종료되어 시간이 걸릴 수 있습니다.557* **종료가 느릴 수 있음**: 팀원들은 현재 요청이나 도구 호출을 마친 후 종료되어 시간이 걸릴 수 있습니다.

558* **세션당 한 팀**: 세션은 정확히 하나의 팀을 가지며, 해당 세션으로 범위가 지정됩니다. 추가 명명된 팀을 만들거나 세션 간에 팀을 공유할 수 없습니다.558* **세션당 한 팀**: 세션은 정확히 하나의 팀을 가지며, 해당 세션으로 범위가 지정됩니다. 추가 명명된 팀을 만들거나 세션 간에 팀을 공유할 수 없습니다.

559* **중첩된 팀 없음**: 팀원들은 자신의 팀원을 생성할 수 없습니다. 리더만 팀을 관리할 수 있습니다.559* **중첩된 팀 없음**: 팀원들은 자신의 팀원을 생성할 수 없습니다. 리더만 팀을 관리할 수 있습니다.

560* **In-process 팀원의 백그라운드 서브에이전트 없음**: in-process 팀원의 자체 서브에이전트는 포그라운드에서 실행됩니다. 팀원의 백그라운드 작업은 리더의 프로세스보다 오래 지속될 수 없기 때문입니다. Claude Code는 팀원이 `background: true`를 설정하는 서브에이전트 정의를 생성할 때 오류를 반환합니다. 팀원의 `run_in_background: true` 요청도 실패하며, [Claude Code가 포그라운드 또는 백그라운드를 선택하는 방법](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에 설명된 대로 오류가 발생하거나 포그라운드에서 자동으로 실행됩니다. 주 대화에서 시작된 서브에이전트는 [백그라운드 기본값](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)을 따릅니다.560* **In-process 팀원의 백그라운드 서브에이전트 없음**: in-process 팀원의 자체 서브에이전트는 포그라운드에서 실행됩니다. 팀원의 백그라운드 작업은 리더의 프로세스보다 오래 지속될 수 없기 때문입니다. Claude Code는 팀원이 정의에 `background: true`가 설정된 서브에이전트를 생성할 때 오류를 반환합니다. 팀원의 `run_in_background: true` 요청도 실패하며, 오류가 발생하거나 포그라운드에서 자동으로 실행됩니다. 주 대화에서 시작된 서브에이전트는 [백그라운드 기본값](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)을 따릅니다.

561* **리더가 고정됨**: 주 세션은 수명 동안 리더입니다. 팀원을 리더로 승격하거나 리더십을 이전할 수 없습니다.561* **리더가 고정됨**: 주 세션은 수명 동안 리더입니다. 팀원을 리더로 승격하거나 리더십을 이전할 수 없습니다.

562* **생성 시 권한 설정**: 팀원들은 [권한](#permissions) 아래에 설명된 권한 모드로 시작합니다. 생성 후 개별 팀원의 권한 모드를 변경할 수 있지만, 생성 시 팀원별 권한 모드를 설정할 수 없습니다.562* **생성 시 권한 설정**: 팀원들은 [권한](#permissions) 아래에 설명된 권한 모드로 시작합니다. 생성 후 개별 팀원의 권한 모드를 변경할 수 있지만, 생성 시 팀원별 권한 모드를 설정할 수 없습니다.

563* **분할 창은 tmux 또는 iTerm2 필요**: 기본 in-process 모드는 모든 터미널에서 작동합니다. 분할 창 모드는 VS Code의 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않습니다.563* **분할 창은 tmux 또는 iTerm2 필요**: 기본 in-process 모드는 모든 터미널에서 작동합니다. 분할 창 모드는 VS Code의 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않습니다.

agent-view.md +10 −2

Details

479 479

480분기 후 두 대화는 독립적입니다. 복사본이 하는 일은 자동으로 원본 대화에 들어가지 않습니다. 다만 [교차 세션 메시징](/docs/ko/cross-session-messaging)이 활성화된 세션에서는 어느 세션의 Claude든 명시적으로 다른 세션에 메시지를 보낼 수 있습니다.480분기 후 두 대화는 독립적입니다. 복사본이 하는 일은 자동으로 원본 대화에 들어가지 않습니다. 다만 [교차 세션 메시징](/docs/ko/cross-session-messaging)이 활성화된 세션에서는 어느 세션의 Claude든 명시적으로 다른 세션에 메시지를 보낼 수 있습니다.

481 481

482세션 복사에는 Claude Code v2.1.212 이상이 필요합니다. v2.1.161부터 v2.1.211까지는 `/fork`가 대신 [분기된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 시작하며, 이 기능은 이제 `/subtask`입니다. [에이전트 뷰가 꺼져 있으면](#turn-off-agent-view), `/fork`는 분기된 서브에이전트 동작을 유지하고 `/subtask`는 사용할 수 없습니다.482[에이전트 뷰가 꺼져 있으면](#turn-off-agent-view), `/fork`는 세션을 복사하는 대신 [분기된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 시작합니다.

483 483

484`/fork open a draft pull request with the work so far`와 같은 프롬프트를 전달하면 복사본이 즉시 작업을 시작합니다. 프롬프트가 없으면 복사본은 첫 번째 지시사항을 기다립니다. `claude agents`에서 해당 행을 선택하고 `Space`를 눌러 지시사항을 보내거나, `claude attach <id>`를 실행합니다. 기다리는 동안 선택한 행에는 `space to send it a prompt`가 표시됩니다.484`/fork open a draft pull request with the work so far`와 같은 프롬프트를 전달하면 복사본이 즉시 작업을 시작합니다. 프롬프트가 없으면 복사본은 첫 번째 지시사항을 기다립니다. `claude agents`에서 해당 행을 선택하고 `Space`를 눌러 지시사항을 보내거나, `claude attach <id>`를 실행합니다. 기다리는 동안 선택한 행에는 `space to send it a prompt`가 표시됩니다.

485 485

955* **실행 중인 서브에이전트가 있는 워크플로**: [동적 워크플로](/docs/ko/workflows)에 여전히 실행 중인 서브에이전트가 있습니다. 워크플로 자체는 이동되지만, 실행 중인 서브에이전트는 처음부터 다시 시작되며, 대화 상자는 개수를 표시합니다.955* **실행 중인 서브에이전트가 있는 워크플로**: [동적 워크플로](/docs/ko/workflows)에 여전히 실행 중인 서브에이전트가 있습니다. 워크플로 자체는 이동되지만, 실행 중인 서브에이전트는 처음부터 다시 시작되며, 대화 상자는 개수를 표시합니다.

956* **자동 아티팩트 답변**: Claude가 [아티팩트의 댓글에 자동으로 답변](/docs/ko/artifacts#let-claude-reply-to-comments-on-its-own)하고 있습니다. 이러한 답변은 백그라운드 세션에서 계속되며, 대화 상자는 이를 표시합니다.956* **자동 아티팩트 답변**: Claude가 [아티팩트의 댓글에 자동으로 답변](/docs/ko/artifacts#let-claude-reply-to-comments-on-its-own)하고 있습니다. 이러한 답변은 백그라운드 세션에서 계속되며, 대화 상자는 이를 표시합니다.

957 957

958`/tasks`를 실행하여 실행 중인 모든 작업을 확인한 후 어쨌든 백그라운드로 이동하도록 확인하거나 `Stay`를 선택하여 작업이 먼저 완료되도록 합니다. [세션을 백그라운드로 이동할 때 이동되는 것](#what-carries-over-when-you-background)을 참조하여 어떤 종류의 작업이 이동되고 어떤 작업이 Claude Code에 의해 중지되는지 확인합니다.958`/tasks`를 실행하여 실행 중인 모든 작업을 확인한 후 어쨌든 백그라운드로 이동하도록 확인하거나 `Stay`를 선택하여 작업이 먼저 완료되도록 합니다. [백그라운드로 이동할 때 이어지는 것](#what-carries-over-when-you-background)을 참조하여 어떤 종류의 작업이 이어지고 어떤 작업이 Claude Code에 의해 중지되는지 확인합니다.

959

960<h3 id="carried-into-this-session-and-not-resumed">

961 대화에 백그라운드 에이전트가 `was carried into this session and not resumed`라고 표시됨

962</h3>

963

964이 알림은 이 세션에서 실행되고 있지 않은 백그라운드 [서브에이전트](/docs/ko/sub-agents)를 가리킵니다.

965

966Claude가 알림을 확인하고 스스로 답변하므로 별도로 요청할 필요가 없습니다. Claude의 답변을 읽은 후에도 해당 서브에이전트의 작업이 여전히 필요하면 Claude에게 요청합니다.

959 967

960<h3 id="prompt-rejected-as-too-short">968<h3 id="prompt-rejected-as-too-short">

961 프롬프트가 너무 짧아서 거부됨969 프롬프트가 너무 짧아서 거부됨

amazon-bedrock.md +1 −1

Details

182export AWS_PROFILE=your-profile-name182export AWS_PROFILE=your-profile-name

183```183```

184 184

185Claude Code는 프로필의 `sso_region`으로 명명된 IAM Identity Center 영역에서 역할 자격 증명을 요청합니다. 이는 Amazon Bedrock을 실행하는 영역과 일치할 필요가 없습니다. v2.1.207에서는 Amazon Bedrock 영역이 `sso_region`을 재정의했으므로 IAM Identity Center 인스턴스가 다른 영역에 있는 프로필은 `Session token not found or invalid` 오류로 인증에 실패했습니다.185Claude Code는 프로필의 `sso_region`으로 명명된 IAM Identity Center 영역에서 역할 자격 증명을 요청합니다. 이는 Amazon Bedrock을 실행하는 영역과 일치할 필요가 없습니다.

186 186

187<h4 id="use-aws-management-console-credentials">187<h4 id="use-aws-management-console-credentials">

188 AWS Management Console 자격 증명 사용188 AWS Management Console 자격 증명 사용

artifacts.md +1 −1

Details

105 아티팩트 다시 찾기105 아티팩트 다시 찾기

106</h2>106</h2>

107 107

108Claude Code에서 `/artifacts`를 실행하여 소유한 아티팩트와 공유받은 아티팩트를 나열합니다. 현재 세션의 아티팩트가 **This session** 아래에 먼저 표시됩니다. Claude Code v2.1.208 이상이 필요합니다.108Claude Code에서 `/artifacts`를 실행하여 소유한 아티팩트와 공유받은 아티팩트를 나열합니다. 현재 세션의 아티팩트가 **This session** 아래에 먼저 표시됩니다.

109 109

110아티팩트를 선택한 다음 다음 키 중 하나를 누릅니다.110아티팩트를 선택한 다음 다음 키 중 하나를 누릅니다.

111 111

auto-mode-config.md +2 −2

Details

321claude auto-mode defaults321claude auto-mode defaults

322```322```

323 323

324`jq`를 통해 파이핑하지 않고 한 규칙의 전체 표현을 읽으려면 `--label`을 규칙 레이블의 시작 부분(예: `claude auto-mode defaults --label 'Git Destructive'`)과 함께 전달합니다. 일치는 각 규칙의 레이블에 대한 대소문자를 구분하지 않는 접두사이며, 일치하는 항목이 없는 섹션은 빈 목록으로 출력됩니다. Claude Code v2.1.208 이상이 필요합니다.324`jq`를 통해 파이핑하지 않고 한 규칙의 전체 표현을 읽으려면 `--label`을 규칙 레이블의 시작 부분(예: `claude auto-mode defaults --label 'Git Destructive'`)과 함께 전달합니다. 일치는 각 규칙의 레이블에 대한 대소문자를 구분하지 않는 접두사이며, 일치하는 항목이 없는 섹션은 빈 목록으로 출력됩니다.

325 325

326분류기가 실제로 사용하는 것을 JSON으로 출력합니다. 설정된 곳에서는 설정을 적용하고 그 외에는 기본값을 사용합니다:326분류기가 실제로 사용하는 것을 JSON으로 출력합니다. 설정된 곳에서는 설정을 적용하고 그 외에는 기본값을 사용합니다:

327 327

359 359

360사용자 정의 규칙을 작성한 경우 `claude auto-mode critique`는 이를 검토하고 모호하거나, 중복되거나, 거짓 양성을 유발할 가능성이 있는 항목에 플래그를 지정합니다.360사용자 정의 규칙을 작성한 경우 `claude auto-mode critique`는 이를 검토하고 모호하거나, 중복되거나, 거짓 양성을 유발할 가능성이 있는 항목에 플래그를 지정합니다.

361 361

362사용자 정의를 버리고 기본 제공 기본값으로 돌아가려면 reset 하위 명령어를 실행합니다. Claude Code v2.1.212 이상이 필요하며 사용자 설정 파일에서 `autoMode` 섹션을 제거합니다:362사용자 정의를 버리고 기본 제공 기본값으로 돌아가려면 reset 하위 명령을 실행합니다. 이 명령은 사용자 설정 파일에서 `autoMode` 섹션을 제거합니다:

363 363

364```bash theme={null}364```bash theme={null}

365claude auto-mode reset365claude auto-mode reset

chrome.md +3 −3

Details

113 113

114이 설정이 켜져 있고 Claude Code v2.1.287 이상을 사용하면 각 VS Code 세션이 시작될 때 브라우저에 연결되므로, 사용자가 `@browser`를 입력하기 전에도 Claude가 브라우저를 사용할 수 있습니다. 이전 버전이거나 설정이 꺼져 있으면 VS Code 세션은 `@browser`를 입력할 때 연결됩니다.114이 설정이 켜져 있고 Claude Code v2.1.287 이상을 사용하면 각 VS Code 세션이 시작될 때 브라우저에 연결되므로, 사용자가 `@browser`를 입력하기 전에도 Claude가 브라우저를 사용할 수 있습니다. 이전 버전이거나 설정이 꺼져 있으면 VS Code 세션은 `@browser`를 입력할 때 연결됩니다.

115 115

116Chrome이 실행 중이 아니어도 Claude Code는 정상적으로 시작됩니다. v2.1.211 이전에는 Chrome 통합이 활성화되어 있지만 Chrome이 실행 중이 아닐 때 시작 과정이 멈출 수 있었습니다.116Chrome이 실행 중이 아니어도 Claude Code는 정상적으로 시작됩니다.

117 117

118<Note>118<Note>

119 기본으로 Chrome을 활성화하면 브라우저 도구와 해당 지침이 항상 로드되므로 컨텍스트 사용량이 증가합니다. 컨텍스트 소비가 늘어난 것을 발견하면 설정을 끄고 필요할 때만 연결하십시오. CLI에서는 `--chrome`을 사용하고, VS Code에서는 프롬프트 상자에 [`@browser`](/docs/ko/vs-code#automate-browser-tasks-with-chrome)를 입력합니다.119 기본으로 Chrome을 활성화하면 브라우저 도구와 해당 지침이 항상 로드되므로 컨텍스트 사용량이 증가합니다. 컨텍스트 소비가 늘어난 것을 발견하면 설정을 끄고 필요할 때만 연결하십시오. CLI에서는 `--chrome`을 사용하고, VS Code에서는 프롬프트 상자에 [`@browser`](/docs/ko/vs-code#automate-browser-tasks-with-chrome)를 입력합니다.

192 웹 페이지에 파일 업로드192 웹 페이지에 파일 업로드

193</h3>193</h3>

194 194

195Claude는 사용자 컴퓨터의 파일을 페이지의 업로드 필드에 첨부할 수 있습니다. Claude Code가 파일을 읽어 그 내용을 브라우저로 전송하므로, 업로드는 로컬 세션과 원격 세션 모두에서 작동합니다. Claude Code v2.1.211 이상이 필요합니다.195Claude는 사용자 컴퓨터의 파일을 페이지의 업로드 필드에 첨부할 수 있습니다. Claude Code가 파일을 읽어 그 내용을 브라우저로 전송하므로, 업로드는 로컬 세션과 원격 세션 모두에서 작동합니다.

196 196

197다음 예제는 로그 파일을 양식에 첨부합니다.197다음 예제는 로그 파일을 양식에 첨부합니다.

198 198

271체크아웃 페이지의 스크린샷을 찍어 디스크에 저장해 주세요271체크아웃 페이지의 스크린샷을 찍어 디스크에 저장해 주세요

272```272```

273 273

274Claude는 이미지를 디스크에 저장하고 파일 경로를 알려줍니다. v2.1.211 이전에는 스크린샷 도구의 `save_to_disk` 옵션이 파일을 기록하지 않았습니다.274Claude는 이미지를 디스크에 저장하고 파일 경로를 알려줍니다.

275 275

276<h2 id="troubleshooting">276<h2 id="troubleshooting">

277 문제 해결277 문제 해결

claude-apps-gateway.md +1 −1

Details

502 CI 파이프라인 및 원격 머신502 CI 파이프라인 및 원격 머신

503</h3>503</h3>

504 504

505무인 파이프라인을 위한 서비스 토큰 흐름은 없습니다. 게이트웨이 로그인은 항상 브라우저 디바이스 흐름을 실행하므로, 로그인을 승인할 개발자가 없는 CI 작업은 인증할 수 없습니다. 이러한 작업은 제공자에 직접 연결하도록 구성하세요.505무인 파이프라인을 위한 서비스 토큰 흐름은 없습니다. 게이트웨이 로그인은 항상 브라우저 디바이스 흐름을 실행하므로, 로그인을 승인할 개발자가 없는 CI 작업은 인증할 수 없습니다. 이러한 작업은 제공자에 직접 연결하도록 구성하세요. `forceLoginMethod`와 `forceLoginGatewayUrl`은 개발자 머신에 배포하고 CI 러너에는 배포하지 마세요. 관리형 설정에서 이 키를 설정한 머신에서는 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`로 인증하는 세션이 [시작 시 종료됩니다](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in).

506 506

507개발자가 로그인하면 해당 머신의 각 Claude Code 세션은 비대화형 `claude -p` 실행과 Agent SDK에서 시작된 세션을 포함하여 게이트웨이 세션을 사용합니다. Claude Code는 각 세션에 [게이트웨이 정책](/docs/ko/claude-apps-gateway-config#managed)을 적용합니다.507개발자가 로그인하면 해당 머신의 각 Claude Code 세션은 비대화형 `claude -p` 실행과 Agent SDK에서 시작된 세션을 포함하여 게이트웨이 세션을 사용합니다. Claude Code는 각 세션에 [게이트웨이 정책](/docs/ko/claude-apps-gateway-config#managed)을 적용합니다.

508 508

claude-apps-gateway-config.md +18 −1

Details

340 340

341`forward_user_identity`를 `base_url`이 운영하는 프록시인 업스트림에만 설정합니다. 게이트웨이는 개발자 이메일을 해당 `base_url`이 이름을 지정하는 모든 서버에 보냅니다. `base_url`이 기본값인 Anthropic API인 경우 게이트웨이는 시작을 거부합니다.341`forward_user_identity`를 `base_url`이 운영하는 프록시인 업스트림에만 설정합니다. 게이트웨이는 개발자 이메일을 해당 `base_url`이 이름을 지정하는 모든 서버에 보냅니다. `base_url`이 기본값인 Anthropic API인 경우 게이트웨이는 시작을 거부합니다.

342 342

343<Note>

344 Amazon Bedrock 업스트림에 `forward_user_identity`를 설정하면 게이트웨이는 시작 시 `Unrecognized key(s) in object: 'forward_user_identity'`와 함께 종료됩니다. 프록시가 Bedrock 앞에 있는 경우 대신 `provider: anthropic` 업스트림으로 나열합니다. 게이트웨이는 해당 업스트림에 Anthropic Messages 형식을 보내므로 프록시가 [Bedrock용으로 요청을 변환](/docs/ko/llm-gateway-protocol#format-mismatch-with-the-upstream)해야 합니다. 대신 AWS에 각 개발자를 식별하려면 [개발자별 AWS 비용 기인](#per-developer-aws-cost-attribution)을 참조하세요.

345</Note>

346

343<h4 id="amazon-bedrock">347<h4 id="amazon-bedrock">

344 Amazon Bedrock348 Amazon Bedrock

345</h4>349</h4>

1133 1137

1134* 모델 목록은 `availableModels`에서 도출합니다. 각 모델의 1M 컨텍스트 옵션은 [Claude Desktop의 확장 컨텍스트](#extended-context-in-claude-desktop)에서 다룹니다1138* 모델 목록은 `availableModels`에서 도출합니다. 각 모델의 1M 컨텍스트 옵션은 [Claude Desktop의 확장 컨텍스트](#extended-context-in-claude-desktop)에서 다룹니다

1135* 비활성화된 도구는 도구 이름만 있는 `permissions.deny` 항목에서 도출합니다. 정책의 `desktop` 블록에서 `disabledBuiltinTools`를 설정하면 게이트웨이는 해당 값과 도출된 목록의 합집합을 제공하므로, 이 방식으로 도구를 더 비활성화할 수는 있지만 `permissions.deny`로 비활성화한 도구를 다시 활성화할 수는 없습니다1139* 비활성화된 도구는 도구 이름만 있는 `permissions.deny` 항목에서 도출합니다. 정책의 `desktop` 블록에서 `disabledBuiltinTools`를 설정하면 게이트웨이는 해당 값과 도출된 목록의 합집합을 제공하므로, 이 방식으로 도구를 더 비활성화할 수는 있지만 `permissions.deny`로 비활성화한 도구를 다시 활성화할 수는 없습니다

1136* 송신 허용 목록은 `sandbox.network.allowedDomains`에서 도출합니다. 정책의 `desktop` 블록에서 `coworkEgressAllowedHosts`를 설정하면 게이트웨이는 도출된 목록 대신 해당 값을 사용합니다1140* `sandbox.network.allowedDomains`에서 도출한 이그레스 허용 목록. 정책의 `desktop` 블록에 `coworkEgressAllowedHosts`를 설정하면 게이트웨이는 도출된 목록 대신 해당 값을 사용합니다. 게이트웨이가 제공하는 허용 목록에 `*`가 포함되어 있고 게이트웨이가 Claude Desktop의 [`allowedWorkspaceFolders`](https://claude.com/docs/third-party/claude-desktop/code#applied-as-managed-policy)를 함께 제공하지 않으면, Claude Desktop은 Code 탭에서 [Bash 샌드박스](/docs/ko/sandboxing)를 켜지 않습니다

1137* 게이트웨이 자신을 가리키는 OTLP 엔드포인트와 로그인한 사용자의 ID 속성. 게이트웨이는 해당 엔드포인트에서 받은 내보내기를 `forward_to` 대상으로 중계합니다. [`telemetry.forward_to`](#telemetry)와 `listen.public_url`을 모두 설정한 경우 엔드포인트와 속성을 포함합니다.1141* 게이트웨이 자신을 가리키는 OTLP 엔드포인트와 로그인한 사용자의 ID 속성. 게이트웨이는 해당 엔드포인트에서 받은 내보내기를 `forward_to` 대상으로 중계합니다. [`telemetry.forward_to`](#telemetry)와 `listen.public_url`을 모두 설정한 경우 엔드포인트와 속성을 포함합니다.

1138 1142

1139 Claude Desktop은 모든 신호를 하나의 인코딩으로 내보냅니다. 기본은 `http/protobuf`이며, 정책의 `env`에서 `OTEL_EXPORTER_OTLP_PROTOCOL` 또는 신호별 변형 중 하나를 `http/json`으로 설정하면 `http/json`입니다. 게이트웨이 서버의 Claude Code v2.1.261 이전에는 응답이 항상 `http/json`을 설정했으므로, protobuf만 허용하는 수집기는 Claude Desktop의 내보내기를 거부했습니다1143 Claude Desktop은 모든 신호를 하나의 인코딩으로 내보냅니다. 기본은 `http/protobuf`이며, 정책의 `env`에서 `OTEL_EXPORTER_OTLP_PROTOCOL` 또는 신호별 변형 중 하나를 `http/json`으로 설정하면 `http/json`입니다. 게이트웨이 서버의 Claude Code v2.1.261 이전에는 응답이 항상 `http/json`을 설정했으므로, protobuf만 허용하는 수집기는 Claude Desktop의 내보내기를 거부했습니다

1374 1378

1375protobuf와 JSON OTLP 인코딩 모두 중계되며, OpenTelemetry 호환 백엔드라면 모두 대상으로 사용할 수 있습니다.1379protobuf와 JSON OTLP 인코딩 모두 중계되며, OpenTelemetry 호환 백엔드라면 모두 대상으로 사용할 수 있습니다.

1376 1380

1381<h4 id="send-cumulative-metrics">

1382 누적 메트릭 전송

1383</h4>

1384

1385컬렉터가 누적 메트릭만 받는 경우 [`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`](/docs/ko/monitoring-usage#common-configuration-variables)를 `cumulative`로 설정하십시오. Claude Code는 기본적으로 델타 메트릭을 보내며, 게이트웨이는 이를 변환하지 않고 전달합니다. 각 세션 유형이 읽는 위치에 변수를 설정하십시오.

1386

1387* **터미널 세션**: 정책의 [`cli` 또는 `code` 키](#choose-cli-or-code) 아래 `env` 블록

1388* **[사용자 머신에서 실행되는](/docs/ko/managed-settings#where-and-when-a-policy-applies) Cowork 세션**: 해당 머신의 [클라이언트 측 관리형 설정](#client-side-managed-settings)의 `env` 블록

1389* **`code` 정책의 Code 탭 세션**: [`code` 설정이 적용되는 조건](#apply-code-settings-in-the-code-tab)을 충족한 후 정책의 `env` 블록

1390* **`cli` 정책의 Code 탭 세션**: 세션을 실행하는 머신의 클라이언트 측 관리형 설정의 `env` 블록. SSH의 경우 원격 호스트입니다.

1391

1392머신의 관리형 설정에 변수를 추가하는 경우, 해당 머신에서 우선순위가 가장 높은 소스에 [`parentSettingsBehavior: "merge"`](/docs/ko/claude-apps-gateway#set-the-opt-in)도 설정하십시오. 이 설정이 없으면 Cowork 세션과 `cli` 정책의 Code 탭 세션은 Claude Desktop이 상위 설정으로 전달하는 이그레스 허용 목록 및 기타 정책 없이 실행됩니다.

1393

1377<h4 id="add-your-own-labels">1394<h4 id="add-your-own-labels">

1378 자체 레이블 추가1395 자체 레이블 추가

1379</h4>1396</h4>

claude-directory.md +6 −3

Details

1706claude purge ~/work/my-repo --yes1706claude purge ~/work/my-repo --yes

1707```1707```

1708 1708

1709경로 대신 `--all`을 전달하여 한 번에 모든 프로젝트의 상태를 purge합니다. 이는 `history.jsonl`을 필터링하는 대신 완전히 삭제합니다. `-i`를 전달하여 삭제 계획을 한 번에 하나씩 단계별로 진행합니다.1709기타 옵션:

1710

1711* 경로 대신 `--all`을 전달하면 한 번에 모든 프로젝트의 상태를 purge합니다. 이 경우 `history.jsonl`을 필터링하는 대신 완전히 삭제합니다.

1712* `-i`를 전달하면 삭제 계획을 한 번에 한 항목씩 단계별로 진행합니다.

1710 1713

1711명령은 `shell-snapshots/` 및 `backups/`를 그대로 두는데, 이는 프로젝트 범위가 아니기 때문이며 계획 출력에서 이에 대해 경고합니다. 누군가 해당 머신에서 [`/heapdump`](/docs/ko/troubleshooting#high-cpu-or-memory-usage)를 실행했다면 그것이 작성한 `.heapsnapshot` 파일도 삭제하세요. 힙 스냅샷에는 전체 대화와 프로세스가 보유했던 모든 자격 증명이 포함되며, 보존 스윕과 purge 모두 이를 건드리지 않습니다.1714명령은 `shell-snapshots/` 및 `backups/`를 그대로 두는데, 이는 프로젝트 범위가 아니기 때문이며 계획 출력에서 이에 대해 경고합니다. 누군가 해당 머신에서 [`/heapdump`](/docs/ko/troubleshooting#high-cpu-or-memory-usage)를 실행했다면 그것이 작성한 `.heapsnapshot` 파일도 삭제하세요. 힙 스냅샷에는 전체 대화와 프로세스가 보유했던 모든 자격 증명이 포함되며, 보존 스윕과 purge 모두 이를 건드리지 않습니다.

1712 1715

1713위의 [애플리케이션 데이터 경로](#state-files-to-keep)를 제외한 모든 경로를 직접 삭제할 수도 있습니다. 새 세션은 영향을 받지 않습니다. 아래 표는 과거 세션에서 손실되는 것을 보여줍니다.1716[유지해야 할 상태 파일](#state-files-to-keep)을 제외하면 위의 애플리케이션 데이터 경로를 직접 삭제할 수도 있습니다.

1714 1717

1715| 삭제 | 손실되는 것 |1718| 삭제 | 손실되는 것 |

1716| - | - |1719| - | - |

1730| `~/.claude/skills/.trash/`, `~/.claude/plugins/.trash/` | [동기화된 skills](/docs/ko/skills#how-synced-skills-behave) 및 [동기화된 plugins](/docs/ko/plugins/loading#synced-plugins)를 복구할 기회. Claude Code가 제거한 것 |1733| `~/.claude/skills/.trash/`, `~/.claude/plugins/.trash/` | [동기화된 skills](/docs/ko/skills#how-synced-skills-behave) 및 [동기화된 plugins](/docs/ko/plugins/loading#synced-plugins)를 복구할 기회. Claude Code가 제거한 것 |

1731| `~/.claude/plugins/installed_plugins.set-aside.<date>.<hash>.json`, `~/.claude/plugins/installed_plugins.unreadable.<date>.<hash>.kept` | Claude Code가 삭제했거나 읽을 수 없는 plugin 설치 기록의 복사본. 아무것도 이를 다시 읽지 않습니다 |1734| `~/.claude/plugins/installed_plugins.set-aside.<date>.<hash>.json`, `~/.claude/plugins/installed_plugins.unreadable.<date>.<hash>.kept` | Claude Code가 삭제했거나 읽을 수 없는 plugin 설치 기록의 복사본. 아무것도 이를 다시 읽지 않습니다 |

1732| `~/.claude/debug/`, `~/.claude/plans/`, `~/.claude/session-env/`, `~/.claude/shell-snapshots/`, `~/.claude/backups/` | 사용자 대면 없음 |1735| `~/.claude/debug/`, `~/.claude/plans/`, `~/.claude/session-env/`, `~/.claude/shell-snapshots/`, `~/.claude/backups/` | 사용자 대면 없음 |

claude-projects.md +1 −1

Details

417* MCP 서버: 클라우드 스레드는 claude.ai 계정의 커넥터에서 MCP 도구를 가져옵니다. 커넥터는 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 한 번 연결하는 MCP 서버입니다. 모든 클라우드 스레드는 프로젝트별 설정 없이 모두 사용할 수 있습니다. 프로젝트 대화 자체는 커넥터가 없으므로 커넥터가 필요한 작업을 클라우드 스레드의 작업으로 보냅니다. 한 저장소가 있는 프로젝트에서, 클라우드 스레드는 또한 해당 저장소의 [`.mcp.json`](/docs/ko/cloud-environments#what-carries-over-from-your-setup)에서 MCP 서버를 로드합니다. [커넥터가 Claude Code에 도달하는 방법](/docs/ko/mcp#how-connectors-reach-claude-code)은 클라우드 세션의 규칙과 커넥터를 끄는 설정을 나열합니다.417* MCP 서버: 클라우드 스레드는 claude.ai 계정의 커넥터에서 MCP 도구를 가져옵니다. 커넥터는 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 한 번 연결하는 MCP 서버입니다. 모든 클라우드 스레드는 프로젝트별 설정 없이 모두 사용할 수 있습니다. 프로젝트 대화 자체는 커넥터가 없으므로 커넥터가 필요한 작업을 클라우드 스레드의 작업으로 보냅니다. 한 저장소가 있는 프로젝트에서, 클라우드 스레드는 또한 해당 저장소의 [`.mcp.json`](/docs/ko/cloud-environments#what-carries-over-from-your-setup)에서 MCP 서버를 로드합니다. [커넥터가 Claude Code에 도달하는 방법](/docs/ko/mcp#how-connectors-reach-claude-code)은 클라우드 세션의 규칙과 커넥터를 끄는 설정을 나열합니다.

418* 명령줄 도구 및 패키지: 환경의 [설정 스크립트](/docs/ko/cloud-environments#setup-scripts)에 설치합니다.418* 명령줄 도구 및 패키지: 환경의 [설정 스크립트](/docs/ko/cloud-environments#setup-scripts)에 설치합니다.

419 419

420실행 중인 클라우드 스레드가 claude.ai/code에서 가진 커넥터를 보려면, 스레드를 열고 메시지 상자 옆의 **+** 메뉴에서 **커넥터**를 선택합니다. 거기서 커넥터를 끄면 해당 스레드에서 제거되고 계정 기본값으로 저장되므로, 다시 켤 때까지 새로운 스레드와 claude.ai 채팅이 해당 커넥터 없이 시작합니다. 클라우드 스레드는 다음 메시지를 보낸 후 추가하거나 다시 연결한 커넥터를 가져옵니다.420실행 중인 클라우드 스레드가 claude.ai/code에서 가진 커넥터를 보려면, 스레드를 열고 메시지 상자 옆의 **+** 메뉴에서 **커넥터**를 선택합니다. 거기서 커넥터를 끄면 해당 스레드에서 제거되고 계정 기본값으로 저장되므로, 다시 켤 때까지 새로운 스레드와 claude.ai 채팅이 해당 커넥터 없이 시작합니다. 클라우드 스레드는 추가하거나 다시 연결한 커넥터를 다음에 해당 스레드로 메시지를 보낸 후에 가져옵니다.

421 421

422<h2 id="project-settings-reference">422<h2 id="project-settings-reference">

423 프로젝트 설정 참조423 프로젝트 설정 참조

cli-reference.md +1 −1

Details

115| `--no-session-persistence` | 세션 지속성을 비활성화하므로 세션이 디스크에 저장되지 않고 재개할 수 없습니다. 인쇄 모드만 해당입니다. [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/ko/env-vars) 환경 변수는 모든 모드에서 동일한 작업을 수행합니다 | `claude -p --no-session-persistence "query"` |115| `--no-session-persistence` | 세션 지속성을 비활성화하므로 세션이 디스크에 저장되지 않고 재개할 수 없습니다. 인쇄 모드만 해당입니다. [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/ko/env-vars) 환경 변수는 모든 모드에서 동일한 작업을 수행합니다 | `claude -p --no-session-persistence "query"` |

117| `--permission-mode` | 지정된 [권한 모드](/docs/ko/permission-modes)에서 시작합니다. `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions` 또는 `manual`을 `default`의 별칭으로 허용합니다. `manual` 별칭은 UI가 Manual로 레이블 지정하는 권한 모드를 선택하며 Claude Code v2.1.200 이상이 필요합니다. `claude --help`는 `default` 대신 이를 나열하고 두 값 모두 작동합니다. 설정 파일의 `defaultMode`를 재정의합니다. 이 플래그 또는 `--dangerously-skip-permissions` 없이 새 세션은 [세션이 시작되는 권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)에 설명된 권한 모드에서 시작됩니다. 해당 섹션에서는 `-p` 실행이 어떤 모드에서 시작되는지도 다룹니다 | `claude --permission-mode plan` |117| `--permission-mode` | 지정된 [권한 모드](/docs/ko/permission-modes)에서 시작합니다. `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions` 또는 `manual`을 `default`의 별칭으로 허용합니다. `manual` 별칭은 UI가 Manual로 레이블 지정하는 권한 모드를 선택하며 Claude Code v2.1.200 이상이 필요합니다. `claude --help`는 `default` 대신 이를 나열하고 두 값 모두 작동합니다. 설정 파일의 `defaultMode`를 재정의합니다. 이 플래그 또는 `--dangerously-skip-permissions` 없이 새 세션은 [세션이 시작되는 권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)에 설명된 권한 모드에서 시작됩니다. 해당 섹션에서는 `-p` 실행이 어떤 모드에서 시작되는지도 다룹니다 | `claude --permission-mode plan` |

118| `--permission-prompt-tool` | 비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구를 지정합니다. Claude Code는 첫 번째 턴을 실행하기 전에 해당 도구의 MCP 서버가 연결될 때까지 기다립니다. [`MCP_TIMEOUT`](/docs/ko/env-vars) 시작 시간 초과(기본값 30초)까지입니다. <br /><br />프롬프트 도구는 [사용자 상호 작용이 필요한 것으로 표시된](/docs/ko/mcp#require-approval-for-a-specific-tool) MCP 도구를 승인할 수 없습니다. Claude Code는 하나에 대한 `allow` 결과를 거부로 변환합니다. 이 제한에는 Claude Code v2.1.199 이상이 필요합니다 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |118| `--permission-prompt-tool` | 비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구를 지정합니다. 실행에서 로드하는 MCP 서버에 있는 도구의 전체 이름(예: `mcp__<server>__<tool>`)을 전달합니다. Claude Code는 첫 번째 턴을 실행하기 전에 해당 도구의 MCP 서버가 연결될 때까지 기다립니다. [`MCP_TIMEOUT`](/docs/ko/env-vars) 시작 타임아웃(기본값 30초)까지입니다. <br /><br />프롬프트 도구는 [사용자 상호 작용이 필요한 것으로 표시된](/docs/ko/mcp#require-approval-for-a-specific-tool) MCP 도구를 승인할 수 없습니다. Claude Code는 이러한 도구에 대한 `allow` 결과를 거부로 변환합니다. 이 제한에는 Claude Code v2.1.199 이상이 필요합니다 | `claude -p --mcp-config ./mcp.json --permission-prompt-tool mcp__permissions__approve "query"` |

119| `--permission-prompts` | 인쇄 모드에서 권한 프롬프트에 응답하는 사람을 설정합니다. 기본 `host`를 사용하면 Claude Code는 Agent SDK 호스트 또는 `--permission-prompt-tool` 도구로 보냅니다. 아무도 응답할 수 없을 때 `none`을 전달하면 Claude Code는 대신 거부합니다. [무인 실행에서 권한 프롬프트 끄기](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)를 참조하세요. Claude Code v2.1.259 이상이 필요합니다 | `claude -p --permission-prompts none "query"` |119| `--permission-prompts` | 인쇄 모드에서 권한 프롬프트에 응답하는 사람을 설정합니다. 기본 `host`를 사용하면 Claude Code는 Agent SDK 호스트 또는 `--permission-prompt-tool` 도구로 보냅니다. 아무도 응답할 수 없을 때 `none`을 전달하면 Claude Code는 대신 거부합니다. [무인 실행에서 권한 프롬프트 끄기](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)를 참조하세요. Claude Code v2.1.259 이상이 필요합니다 | `claude -p --permission-prompts none "query"` |

120| `--plugin-dir` | 이 세션에만 디렉터리 또는 `.zip` 아카이브에서 플러그인을 로드하거나 [플러그인 폴더](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session)에서 여러 개를 로드합니다. 각 플래그는 하나의 경로를 사용합니다. 더 많은 경로에 대해 플래그를 반복합니다: `--plugin-dir A --plugin-dir B.zip`. 플러그인 폴더를 전달하려면 Claude Code v2.1.265 이상이 필요합니다 | `claude --plugin-dir ./my-plugin` |120| `--plugin-dir` | 이 세션에만 디렉터리 또는 `.zip` 아카이브에서 플러그인을 로드하거나 [플러그인 폴더](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session)에서 여러 개를 로드합니다. 각 플래그는 하나의 경로를 사용합니다. 더 많은 경로에 대해 플래그를 반복합니다: `--plugin-dir A --plugin-dir B.zip`. 플러그인 폴더를 전달하려면 Claude Code v2.1.265 이상이 필요합니다 | `claude --plugin-dir ./my-plugin` |

code-review-setup.md +1 −1

Details

117 117

118* **저장소가 Manual로 설정된 경우**: 댓글로 리뷰를 요청하는 방법118* **저장소가 Manual로 설정된 경우**: 댓글로 리뷰를 요청하는 방법

119* **풀 리퀘스트가 포크에서 온 경우**: 메인테이너가 리뷰를 요청할 수 있다는 점119* **풀 리퀘스트가 포크에서 온 경우**: 메인테이너가 리뷰를 요청할 수 있다는 점

120* **봇 또는 쓰기 권한이 없는 사람이 `@claude review` 댓글을 단 경우**: 리뷰가 시작되지 않았다는 점과 리뷰를 요청할 수 있는 사람120* **봇 또는 풀 리퀘스트 작성자가 아니면서 쓰기 권한이 없는 사람이 `@claude review` 댓글을 단 경우**: 리뷰가 시작되지 않았다는 점과 리뷰를 요청할 수 있는 사람

121* **GitHub 조직이 Claude 조직에 연결되지 않은 경우**: 리뷰가 일시 중지되었다는 점과 연결하는 방법121* **GitHub 조직이 Claude 조직에 연결되지 않은 경우**: 리뷰가 일시 중지되었다는 점과 연결하는 방법

122 122

123이러한 댓글을 중지하려면 설정을 끕니다.123이러한 댓글을 중지하려면 설정을 끕니다.

code-review-troubleshooting.md +1 −1

Details

38 38

39* **이 저장소에 Code Review가 켜져 있지 않음**: Claude가 명령에 대한 응답으로 댓글이나 체크 실행을 게시하지 않습니다. Owner에게 [저장소 추가](/docs/ko/code-review-setup#add-more-repositories)를 요청합니다.39* **이 저장소에 Code Review가 켜져 있지 않음**: Claude가 명령에 대한 응답으로 댓글이나 체크 실행을 게시하지 않습니다. Owner에게 [저장소 추가](/docs/ko/code-review-setup#add-more-repositories)를 요청합니다.

40* **댓글이 조건을 충족하지 않음**: 새 최상위 댓글이 아니라 인라인 댓글이나 리뷰 본문이었거나, 명령이 댓글의 시작 부분에 있지 않았습니다. 새 댓글을 게시하지 않고 이전 댓글을 편집한 경우도 인정되지 않으며, 풀 리퀘스트가 열려 있어야 합니다. [댓글 명령의 조건](/docs/ko/code-review-pull-requests#comment-commands)을 확인하고 이를 충족하는 새 댓글을 게시합니다.40* **댓글이 조건을 충족하지 않음**: 새 최상위 댓글이 아니라 인라인 댓글이나 리뷰 본문이었거나, 명령이 댓글의 시작 부분에 있지 않았습니다. 새 댓글을 게시하지 않고 이전 댓글을 편집한 경우도 인정되지 않으며, 풀 리퀘스트가 열려 있어야 합니다. [댓글 명령의 조건](/docs/ko/code-review-pull-requests#comment-commands)을 확인하고 이를 충족하는 새 댓글을 게시합니다.

41* **쓰기 권한이 없음**: 저장소에 대한 write, maintain 또는 admin 권한이 필요하며, 포크에서 생성된 풀 리퀘스트의 경우 기본 저장소에 대한 권한이 기준이 됩니다. 조직에서 팁을 켜 둔 경우 Claude가 "No review was started: manual reviews can only be requested by someone with write access to this repository."라고 답장합니다. 쓰기 권한이 있는 사람에게 대신 댓글을 작성해 달라고 요청합니다.41* **쓰기 권한이 없음**: 저장소에 대한 write, maintain 또는 admin 권한이 필요하며, 포크에서 생성된 풀 리퀘스트의 경우 기본 저장소에 대한 권한이 기준이 됩니다. 본인이 작성한 풀 리퀘스트가 아니면 Claude가 [팁](/docs/ko/code-review-setup#turn-tip-comments-on-or-off)으로 "No review was started: manual reviews can only be requested by someone with write access to this repository."라고 답장할 수 있습니다. 쓰기 권한이 있는 사람에게 대신 댓글을 작성해 달라고 요청합니다.

42* **예산 소진**: Claude가 "⚠️ Code review skipped"로 시작하는 댓글을 게시합니다. [리뷰가 실행되지 않고 PR에 예산 메시지가 표시되는 경우](#review-didn’t-run-and-the-pr-shows-a-budget-message)를 참조하세요.42* **예산 소진**: Claude가 "⚠️ Code review skipped"로 시작하는 댓글을 게시합니다. [리뷰가 실행되지 않고 PR에 예산 메시지가 표시되는 경우](#review-didn’t-run-and-the-pr-shows-a-budget-message)를 참조하세요.

43 43

44<h3 id="review-didn’t-run-and-the-pr-shows-a-budget-message">44<h3 id="review-didn’t-run-and-the-pr-shows-a-budget-message">

commands.md +5 −5

Details

65| `/background [prompt]` | 현재 세션을 분리하여 [백그라운드 에이전트](/docs/ko/agent-view)로 실행하고 이 터미널을 비웁니다. 분리하기 전에 지침을 하나 더 보내려면 프롬프트를 전달합니다. `claude agents`로 세션을 모니터링합니다. 이 세션을 계속 실행하면서 대화를 새 백그라운드 세션에 복사하려면 `/fork`를 사용합니다. 별칭: `/bg` |65| `/background [prompt]` | 현재 세션을 분리하여 [백그라운드 에이전트](/docs/ko/agent-view)로 실행하고 이 터미널을 비웁니다. 분리하기 전에 지침을 하나 더 보내려면 프롬프트를 전달합니다. `claude agents`로 세션을 모니터링합니다. 이 세션을 계속 실행하면서 대화를 새 백그라운드 세션에 복사하려면 `/fork`를 사용합니다. 별칭: `/bg` |

66| `/batch <instruction>` | **[스킬](/docs/ko/skills#bundled-skills).** 코드베이스 전반의 대규모 변경을 병렬로 조율합니다. 코드베이스를 조사하고, 작업을 5\~30개의 독립적인 단위로 분해한 후 계획을 제시합니다. 승인되면 격리된 [worktree](/docs/ko/worktrees)에서 단위당 하나의 [백그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)를 생성합니다. 각 서브에이전트는 자신의 단위를 구현하고, 테스트를 실행하고, 변경 사항을 게시합니다. git 저장소 또는 worktree를 생성하는 [`WorktreeCreate` 훅](/docs/ko/worktrees#non-git-version-control)이 필요합니다. git 저장소 외부에서 `/batch`를 사용하려면 Claude Code v2.1.281 이상이 필요합니다. 예: `/batch migrate src/ from JavaScript to TypeScript` |66| `/batch <instruction>` | **[스킬](/docs/ko/skills#bundled-skills).** 코드베이스 전반의 대규모 변경을 병렬로 조율합니다. 코드베이스를 조사하고, 작업을 5\~30개의 독립적인 단위로 분해한 후 계획을 제시합니다. 승인되면 격리된 [worktree](/docs/ko/worktrees)에서 단위당 하나의 [백그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)를 생성합니다. 각 서브에이전트는 자신의 단위를 구현하고, 테스트를 실행하고, 변경 사항을 게시합니다. git 저장소 또는 worktree를 생성하는 [`WorktreeCreate` 훅](/docs/ko/worktrees#non-git-version-control)이 필요합니다. git 저장소 외부에서 `/batch`를 사용하려면 Claude Code v2.1.281 이상이 필요합니다. 예: `/batch migrate src/ from JavaScript to TypeScript` |

67| `/branch [name]` | 현재 시점에서 현재 대화의 분기를 생성하여, 지금 상태의 대화를 잃지 않고 다른 방향을 시도할 수 있도록 합니다. 분기로 전환되며 원본은 보존되고, `/resume`으로 원본으로 돌아갈 수 있습니다. 전환하지 않고 복사본을 별도의 [백그라운드 세션](/docs/ko/agent-view)으로 실행하려면 `/fork`를 사용하고, 이 대화로 결과를 보고하는 [서브에이전트](/docs/ko/sub-agents)에 부수 작업을 넘기려면 `/subtask`를 사용합니다 |67| `/branch [name]` | 현재 시점에서 현재 대화의 분기를 생성하여, 지금 상태의 대화를 잃지 않고 다른 방향을 시도할 수 있도록 합니다. 분기로 전환되며 원본은 보존되고, `/resume`으로 원본으로 돌아갈 수 있습니다. 전환하지 않고 복사본을 별도의 [백그라운드 세션](/docs/ko/agent-view)으로 실행하려면 `/fork`를 사용하고, 이 대화로 결과를 보고하는 [서브에이전트](/docs/ko/sub-agents)에 부수 작업을 넘기려면 `/subtask`를 사용합니다 |

68| `/btw [question]` | 대화에 추가하지 않고 현재 세션에 대한 [부수 질문](/docs/ko/interactive-mode#side-questions-with-%2Fbtw)을 합니다. 질문 없이 `/btw`를 실행하면 Claude Code가 가장 최근의 부수 질문을 표시하여 이전 답변을 살펴볼 수 있으며, 아직 질문한 적이 없으면 사용법 안내를 출력합니다. v2.1.212 이전에는 `/btw`에 질문이 필요했습니다 |68| `/btw [question]` | 대화에 추가하지 않고 현재 세션에 대한 [부수 질문](/docs/ko/interactive-mode#side-questions-with-%2Fbtw)을 합니다. 질문 없이 `/btw`를 실행하면 Claude Code가 가장 최근의 부수 질문을 표시하여 이전 답변을 살펴볼 수 있으며, 아직 질문한 적이 없으면 사용법 안내를 출력합니다 |

69| `/bug [report]` | 버그를 보고하거나 대화를 공유합니다. 포함할 세션 기록의 양을 선택하고, 전송 전에 동의 화면에서 확인합니다. 퍼스트 파티 연결에서 Anthropic에 로그인한 경우 보고서는 Anthropic으로 전송됩니다. 서드 파티 제공업체를 사용하거나 Anthropic 자격 증명이 없는 경우, Claude Code는 사용자가 직접 전달할 수 있도록 보고서를 [`~/.claude/feedback-bundles/` 아래의 로컬 아카이브](/docs/ko/data-usage#telemetry-services)에 기록합니다. [VS Code 확장 프로그램](/docs/ko/vs-code#use-the-prompt-box)에서는 `/bug`가 대신 확장 프로그램 자체의 피드백 대화 상자를 엽니다. Claude Code v2.1.229 이상이 필요합니다. Claude가 응답하는 중에 실행하면 Claude Code가 즉시 대화 상자를 엽니다. v2.1.232 이전에는 Claude Code가 턴이 끝날 때까지 명령을 대기열에 두었습니다. 별칭: `/share`. v2.1.212 이전에는 `/bug`와 `/share`가 `/feedback`의 별칭이었습니다 |69| `/bug [report]` | 버그를 보고하거나 대화를 공유합니다. 포함할 세션 기록의 양을 선택하고, 전송 전에 동의 화면에서 확인합니다. 퍼스트 파티 연결에서 Anthropic에 로그인한 경우 보고서는 Anthropic으로 전송됩니다. 서드 파티 제공업체를 사용하거나 Anthropic 자격 증명이 없는 경우, Claude Code는 사용자가 직접 전달할 수 있도록 보고서를 [`~/.claude/feedback-bundles/` 아래의 로컬 아카이브](/docs/ko/data-usage#telemetry-services)에 기록합니다. [VS Code 확장 프로그램](/docs/ko/vs-code#use-the-prompt-box)에서는 `/bug`가 대신 확장 프로그램 자체의 피드백 대화 상자를 엽니다. Claude Code v2.1.229 이상이 필요합니다. Claude가 응답하는 중에 실행하면 Claude Code가 즉시 대화 상자를 엽니다. v2.1.232 이전에는 Claude Code가 턴이 끝날 때까지 명령을 대기열에 두었습니다. 별칭: `/share`. v2.1.212 이전에는 `/bug`와 `/share`가 `/feedback`의 별칭이었습니다 |

70| `/cd <path>` | 대화를 유지한 채 이 세션을 새 작업 디렉터리로 이동합니다. 경로의 일부를 입력하면 일치하는 디렉터리 제안이 표시되며, `Tab`을 눌러 제안을 수락합니다. 이동 즉시 Claude Code가 새 디렉터리에서 적용하는 항목과 `/cd`가 `/add-dir`와 어떻게 다른지는 [세션을 다른 디렉터리로 이동](/docs/ko/permissions#move-the-session-to-another-directory)을 참조하세요 |70| `/cd <path>` | 대화를 유지한 채 이 세션을 새 작업 디렉터리로 이동합니다. 경로의 일부를 입력하면 일치하는 디렉터리 제안이 표시되며, `Tab`을 눌러 제안을 수락합니다. 이동 즉시 Claude Code가 새 디렉터리에서 적용하는 항목과 `/cd`가 `/add-dir`와 어떻게 다른지는 [세션을 다른 디렉터리로 이동](/docs/ko/permissions#move-the-session-to-another-directory)을 참조하세요 |

71| `/chrome` | [Claude in Chrome](/docs/ko/chrome) 설정을 구성합니다 |71| `/chrome` | [Claude in Chrome](/docs/ko/chrome) 설정을 구성합니다 |

95| `/feedback [report]` | Claude Code에 대한 제품 피드백을 보냅니다. [`/bug`](#all-commands)와 동일한 대화 상자를 열며, 동의 단계, 전송 규칙, 턴 도중 동작도 동일합니다. [Claude가 초안을 작성한 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior)이 있는 세션에서는 인수 없이 `/feedback`을 실행하면 대신 초안 대기열이 열리며, Claude가 대기열에 넣은 초안을 검토, 편집, 전송 또는 폐기할 수 있습니다. 대기열에는 대화 상자에서 새 보고서를 작성하는 옵션도 포함됩니다. 인수를 전달한 경우와 `/bug`의 경우에는 항상 대화 상자가 바로 열립니다 |95| `/feedback [report]` | Claude Code에 대한 제품 피드백을 보냅니다. [`/bug`](#all-commands)와 동일한 대화 상자를 열며, 동의 단계, 전송 규칙, 턴 도중 동작도 동일합니다. [Claude가 초안을 작성한 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior)이 있는 세션에서는 인수 없이 `/feedback`을 실행하면 대신 초안 대기열이 열리며, Claude가 대기열에 넣은 초안을 검토, 편집, 전송 또는 폐기할 수 있습니다. 대기열에는 대화 상자에서 새 보고서를 작성하는 옵션도 포함됩니다. 인수를 전달한 경우와 `/bug`의 경우에는 항상 대화 상자가 바로 열립니다 |

96| `/fewer-permission-prompts` | **[스킬](/docs/ko/skills#bundled-skills).** 트랜스크립트에서 자주 사용되는 읽기 전용 Bash 및 MCP 도구 호출을 검색한 다음, 우선순위가 지정된 허용 목록을 프로젝트 `.claude/settings.json`에 추가하여 권한 프롬프트를 줄입니다 |96| `/fewer-permission-prompts` | **[스킬](/docs/ko/skills#bundled-skills).** 트랜스크립트에서 자주 사용되는 읽기 전용 Bash 및 MCP 도구 호출을 검색한 다음, 우선순위가 지정된 허용 목록을 프로젝트 `.claude/settings.json`에 추가하여 권한 프롬프트를 줄입니다 |

97| `/focus` | 마지막 프롬프트, 편집 diffstat이 포함된 한 줄 도구 호출 요약, 최종 응답만 표시하는 포커스 보기를 전환합니다. 도구 호출 요약은 해당 턴에서 시작된 서브에이전트 수도 집계하며, 완료된 백그라운드 작업 알림을 하나의 개수로 접습니다. 선택 사항은 세션 간에 유지되며, 이를 재정의하려면 설정에서 [`viewMode`](/docs/ko/settings-reference#viewmode)를 지정합니다. [전체 화면 렌더링](/docs/ko/fullscreen)에서만 사용할 수 있습니다. [Remote Control](/docs/ko/remote-control) 클라이언트에서 `/focus [on\|off]`를 실행하면 저장된 선택 사항을 변경하지 않고 현재 세션에 대해서만 포커스 보기를 켜거나 끌 수 있으며, 이 기능은 Claude Code v2.1.281 이상이 필요합니다. [VS Code 확장 프로그램](/docs/ko/vs-code#use-the-prompt-box)은 `viewMode`와 별개로 확장 프로그램 설정으로 저장되는 자체 Focus 보기를 명령 메뉴 토글로 제공합니다 |97| `/focus` | 마지막 프롬프트, 편집 diffstat이 포함된 한 줄 도구 호출 요약, 최종 응답만 표시하는 포커스 보기를 전환합니다. 도구 호출 요약은 해당 턴에서 시작된 서브에이전트 수도 집계하며, 완료된 백그라운드 작업 알림을 하나의 개수로 접습니다. 선택 사항은 세션 간에 유지되며, 이를 재정의하려면 설정에서 [`viewMode`](/docs/ko/settings-reference#viewmode)를 지정합니다. [전체 화면 렌더링](/docs/ko/fullscreen)에서만 사용할 수 있습니다. [Remote Control](/docs/ko/remote-control) 클라이언트에서 `/focus [on\|off]`를 실행하면 저장된 선택 사항을 변경하지 않고 현재 세션에 대해서만 포커스 보기를 켜거나 끌 수 있으며, 이 기능은 Claude Code v2.1.281 이상이 필요합니다. [VS Code 확장 프로그램](/docs/ko/vs-code#use-the-prompt-box)은 `viewMode`와 별개로 확장 프로그램 설정으로 저장되는 자체 Focus 보기를 명령 메뉴 토글로 제공합니다 |

98| `/fork [prompt]` | [현재 대화를 새 백그라운드 세션으로 복사](/docs/ko/agent-view#copy-the-session-with-%2Ffork)하고 여기서 계속 작업합니다. 프롬프트를 전달하면 복사본이 즉시 해당 작업을 시작하며, 전달하지 않으면 에이전트 보기에서 첫 프롬프트를 기다립니다. 복사본이 [제자리에서 편집](/docs/ko/agent-view#how-file-edits-are-isolated)하는 경우를 제외하고, Claude Code는 복사본이 코드를 변경하기 전에 자체 worktree를 생성하도록 지시합니다. 이 격리 지시는 Claude Code v2.1.221 이상이 필요합니다. 결과가 이 대화로 돌아오는 서브에이전트에 부수 작업을 넘기려면 `/subtask`를 사용하고, 복사본으로 직접 전환하려면 `/branch`를 사용합니다. Claude Code v2.1.212 이상이 필요하며, v2.1.161부터 v2.1.211까지와 [에이전트 보기가 꺼진](/docs/ko/agent-view#turn-off-agent-view) 경우에는 `/fork`가 대신 [분기된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 시작합니다 |98| `/fork [prompt]` | [현재 대화를 새 백그라운드 세션으로 복사](/docs/ko/agent-view#copy-the-session-with-%2Ffork)하고 여기서 계속 작업합니다. 프롬프트를 전달하면 복사본이 즉시 해당 작업을 시작하며, 전달하지 않으면 에이전트 보기에서 첫 프롬프트를 기다립니다. 복사본이 [제자리에서 편집](/docs/ko/agent-view#how-file-edits-are-isolated)하는 경우를 제외하고, Claude Code는 복사본이 코드를 변경하기 전에 자체 worktree를 생성하도록 지시합니다. 이 격리 지시는 Claude Code v2.1.221 이상이 필요합니다. 결과가 이 대화로 돌아오는 서브에이전트에 부수 작업을 넘기려면 `/subtask`를 사용하고, 복사본으로 직접 전환하려면 `/branch`를 사용합니다. [에이전트 보기가 꺼진](/docs/ko/agent-view#turn-off-agent-view) 경우에는 `/fork`가 대신 [분기된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 시작합니다 |

99| `/goal [condition\|clear]` | [목표](/docs/ko/goal)를 설정합니다. Claude는 조건이 충족되거나 목표가 [다른 이유로 해제될](/docs/ko/goal#how-evaluation-works) 때까지 여러 턴에 걸쳐 계속 작업합니다. 인수 없이 실행하면 현재 목표 또는 가장 최근에 달성한 목표를 표시합니다. `clear`, `stop`, `off`, `reset`, `none` 또는 `cancel`은 활성 목표를 조기에 제거합니다 |99| `/goal [condition\|clear]` | [목표](/docs/ko/goal)를 설정합니다. Claude는 조건이 충족되거나 목표가 [다른 이유로 해제될](/docs/ko/goal#how-evaluation-works) 때까지 여러 턴에 걸쳐 계속 작업합니다. 인수 없이 실행하면 현재 목표 또는 가장 최근에 달성한 목표를 표시합니다. `clear`, `stop`, `off`, `reset`, `none` 또는 `cancel`은 활성 목표를 조기에 제거합니다 |

100| `/heapdump` | 높은 메모리 사용량을 진단하기 위해 JavaScript 힙 스냅샷과 메모리 세부 내역을 `~/Desktop`에 기록하며, Desktop 폴더가 없는 Linux에서는 홈 디렉터리에 기록합니다. 메모리 문제를 보고할 때는 `-diagnostics.json` 파일만 첨부하세요. `.heapsnapshot`에는 전체 대화와 자격 증명이 포함되어 있으므로 공유하지 마세요. [명령 메뉴에서 숨겨져 있으므로](#how-the-command-menu-matches-what-you-type) 전체를 입력해야 합니다. [출력 결과 처리 방법](/docs/ko/troubleshooting#high-cpu-or-memory-usage)을 참조하세요 |100| `/heapdump` | 높은 메모리 사용량을 진단하기 위해 JavaScript 힙 스냅샷과 메모리 세부 내역을 `~/Desktop`에 기록하며, Desktop 폴더가 없는 Linux에서는 홈 디렉터리에 기록합니다. 메모리 문제를 보고할 때는 `-diagnostics.json` 파일만 첨부하세요. `.heapsnapshot`에는 전체 대화와 자격 증명이 포함되어 있으므로 공유하지 마세요. [명령 메뉴에서 숨겨져 있으므로](#how-the-command-menu-matches-what-you-type) 전체를 입력해야 합니다. [출력 결과 처리 방법](/docs/ko/troubleshooting#high-cpu-or-memory-usage)을 참조하세요 |

103| `/ide` | IDE 통합을 관리하고 상태를 표시합니다 |103| `/ide` | IDE 통합을 관리하고 상태를 표시합니다 |

104| `/import [codex\|gemini\|cursor] [--dry-run] [--yes]` | 사용자 컴퓨터에 있는 OpenAI Codex, Google Gemini CLI 또는 Cursor의 구성(지침 파일, MCP 서버, 명령, 서브에이전트, 스킬 포함)을 Claude Code로 가져옵니다. `-p`를 사용한 [비대화형 모드](/docs/ko/headless)에서는 `/import`가 찾은 항목을 나열하고 가져오기를 확정하는 명령을 알려줍니다. 아무것도 기록하지 않고 미리 보려면 `--dry-run`을, 대화형 선택기를 건너뛰려면 `--yes`를 추가합니다. Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude Platform on AWS에서나 [Claude apps 게이트웨이](/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해서는 사용할 수 없습니다. [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)를 끈 경우에도 사용할 수 없습니다. Claude Code v2.1.213 이상이 필요합니다. Cursor에서 가져오려면 v2.1.265 이상이 필요합니다 |104| `/import [codex\|gemini\|cursor] [--dry-run] [--yes]` | 사용자 컴퓨터에 있는 OpenAI Codex, Google Gemini CLI 또는 Cursor의 구성(지침 파일, MCP 서버, 명령, 서브에이전트, 스킬 포함)을 Claude Code로 가져옵니다. `-p`를 사용한 [비대화형 모드](/docs/ko/headless)에서는 `/import`가 찾은 항목을 나열하고 가져오기를 확정하는 명령을 알려줍니다. 아무것도 기록하지 않고 미리 보려면 `--dry-run`을, 대화형 선택기를 건너뛰려면 `--yes`를 추가합니다. Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude Platform on AWS에서나 [Claude apps 게이트웨이](/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해서는 사용할 수 없습니다. [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)를 끈 경우에도 사용할 수 없습니다. Cursor에서 가져오려면 v2.1.265 이상이 필요합니다 |

105| `/init` | `CLAUDE.md` 가이드로 프로젝트를 초기화합니다. 스킬, 훅, 개인 메모리 파일까지 안내하는 대화형 흐름을 사용하려면 `CLAUDE_CODE_NEW_INIT=1`을 설정합니다. `/init`이 OpenAI Codex 또는 Google Gemini CLI 구성을 발견하면 `/import`로 가져오도록 제안합니다 |105| `/init` | `CLAUDE.md` 가이드로 프로젝트를 초기화합니다. 스킬, 훅, 개인 메모리 파일까지 안내하는 대화형 흐름을 사용하려면 `CLAUDE_CODE_NEW_INIT=1`을 설정합니다. `/init`이 OpenAI Codex 또는 Google Gemini CLI 구성을 발견하면 `/import`로 가져오도록 제안합니다 |

106| `/insights` | 이 컴퓨터의 최근 세션을 분석하는 HTML 보고서를 생성합니다. 작업하는 프로젝트, Claude Code 사용 방식, 문제가 발생하는 지점, 시도해 볼 만한 기능을 다룹니다. [클라우드 세션](/docs/ko/claude-code-on-the-web)에서는 사용할 수 없습니다. 보고서 위치, 보존 기간, 비용은 [사용 패턴 분석](/docs/ko/costs#analyze-your-usage-patterns)을 참조하세요 |106| `/insights` | 이 컴퓨터의 최근 세션을 분석하는 HTML 보고서를 생성합니다. 작업하는 프로젝트, Claude Code 사용 방식, 문제가 발생하는 지점, 시도해 볼 만한 기능을 다룹니다. [클라우드 세션](/docs/ko/claude-code-on-the-web)에서는 사용할 수 없습니다. 보고서 위치, 보존 기간, 비용은 [사용 패턴 분석](/docs/ko/costs#analyze-your-usage-patterns)을 참조하세요 |

107| `/install-github-app` | 저장소에 Claude GitHub App을 설치하며, 선택적으로 [GitHub Actions](/docs/ko/github-actions) 워크플로와 시크릿을 설정하는 단계가 포함됩니다. 저장소 선택과 통합 구성 과정을 안내합니다. github.com 저장소에서만 작동합니다. 저장소의 git 원격이 gitlab.com 또는 bitbucket.org에 있으면 명령이 설정을 시작하지 않고 안내를 출력한 후 종료됩니다. GitLab 파이프라인에서 Claude Code를 실행하려면 [GitLab CI/CD](/docs/ko/gitlab-ci-cd)를 참조하세요 |107| `/install-github-app` | 저장소에 Claude GitHub App을 설치하며, 선택적으로 [GitHub Actions](/docs/ko/github-actions) 워크플로와 시크릿을 설정하는 단계가 포함됩니다. 저장소 선택과 통합 구성 과정을 안내합니다. github.com 저장소에서만 작동합니다. 저장소의 git 원격이 gitlab.com 또는 bitbucket.org에 있으면 명령이 설정을 시작하지 않고 안내를 출력한 후 종료됩니다. GitLab 파이프라인에서 Claude Code를 실행하려면 [GitLab CI/CD](/docs/ko/gitlab-ci-cd)를 참조하세요 |

155| `/stop` | 연결된 [백그라운드 세션](/docs/ko/agent-view) 또는 [엿보기 답장](/docs/ko/agent-view#peek-and-reply)으로 이 명령을 보낸 세션을 중지합니다. 트랜스크립트와 worktree는 유지됩니다. 중지하지 않고 분리하려면 `/exit`를 사용하거나 `←`를 누릅니다 |155| `/stop` | 연결된 [백그라운드 세션](/docs/ko/agent-view) 또는 [엿보기 답장](/docs/ko/agent-view#peek-and-reply)으로 이 명령을 보낸 세션을 중지합니다. 트랜스크립트와 worktree는 유지됩니다. 중지하지 않고 분리하려면 `/exit`를 사용하거나 `←`를 누릅니다 |

156| `/subtask <task>` | [분기된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 생성합니다. 이는 전체 대화를 상속받아 사용자가 계속 작업하는 동안 해당 작업을 수행하는 백그라운드 서브에이전트입니다. 완료되면 결과가 이 대화로 돌아옵니다. 대신 대화를 별도의 백그라운드 세션으로 복사하려면 `/fork`를 사용합니다. Claude Code v2.1.212 이상이 필요하며, v2.1.161부터 v2.1.211까지는 이 명령이 `/fork`입니다. [에이전트 보기가 꺼져 있으면](/docs/ko/agent-view#turn-off-agent-view) `/subtask`를 사용할 수 없으며 `/fork`가 분기된 서브에이전트 동작을 유지합니다 |156| `/subtask <task>` | [분기된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 생성합니다. 이는 전체 대화를 상속받아 사용자가 계속 작업하는 동안 해당 작업을 수행하는 백그라운드 서브에이전트입니다. 완료되면 결과가 이 대화로 돌아옵니다. 대신 대화를 별도의 백그라운드 세션으로 복사하려면 `/fork`를 사용합니다. [에이전트 보기가 꺼져 있으면](/docs/ko/agent-view#turn-off-agent-view) `/subtask`를 사용할 수 없으며 대신 `/fork`가 분기된 서브에이전트를 생성합니다 |

158| `/team-onboarding` | Claude Code 사용 기록으로 팀 온보딩 가이드를 생성합니다. Claude는 지난 30일간의 세션, 명령, MCP 서버 사용량을 분석하고, 팀원이 빠르게 설정할 수 있도록 첫 메시지로 붙여넣을 수 있는 markdown 가이드를 생성합니다. Pro, Max, Team, Enterprise 플랜의 claude.ai 구독자에게는 팀원이 Claude Code에서 바로 열 수 있는 공유 링크도 제공됩니다 |158| `/team-onboarding` | Claude Code 사용 기록으로 팀 온보딩 가이드를 생성합니다. Claude는 지난 30일간의 세션, 명령, MCP 서버 사용량을 분석하고, 팀원이 빠르게 설정할 수 있도록 첫 메시지로 붙여넣을 수 있는 markdown 가이드를 생성합니다. Team 및 Enterprise 플랜의 claude.ai 구독자에게는 팀원이 Claude Code에서 바로 열 수 있는 공유 링크도 제공됩니다 |

159| `/teleport` | [클라우드 세션](/docs/ko/claude-code-on-the-web#from-cloud-to-terminal)을 이 터미널로 가져옵니다. 선택기를 연 다음 브랜치와 대화를 가져옵니다. `/tp`로도 사용할 수 있습니다. claude.ai 구독이 필요합니다 |159| `/teleport` | [클라우드 세션](/docs/ko/claude-code-on-the-web#from-cloud-to-terminal)을 이 터미널로 가져옵니다. 선택기를 연 다음 브랜치와 대화를 가져옵니다. `/tp`로도 사용할 수 있습니다. claude.ai 구독이 필요합니다 |

160| `/terminal-setup` | VS Code, Cursor, Devin Desktop, Alacritty 또는 Zed에서 [줄 바꿈을 위한 Shift+Enter 키보드 단축키를 설치](/docs/ko/terminal-config#enter-multiline-prompts)합니다. Apple Terminal에서는 대신 [줄 바꿈을 위한 Option+Enter를 활성화하고 경고음을 끕니다](/docs/ko/terminal-config#enable-option-key-shortcuts-on-macos). iTerm2에서는 [`/copy`가 작동하도록 클립보드 액세스를 켭니다](/docs/ko/terminal-config#enable-option-key-shortcuts-on-macos) |160| `/terminal-setup` | VS Code, Cursor, Devin Desktop, Alacritty 또는 Zed에서 [줄 바꿈을 위한 Shift+Enter 키보드 단축키를 설치](/docs/ko/terminal-config#enter-multiline-prompts)합니다. Apple Terminal에서는 대신 [줄 바꿈을 위한 Option+Enter를 활성화하고 경고음을 끕니다](/docs/ko/terminal-config#enable-option-key-shortcuts-on-macos). iTerm2에서는 [`/copy`가 작동하도록 클립보드 액세스를 켭니다](/docs/ko/terminal-config#enable-option-key-shortcuts-on-macos) |

161| `/theme` | 색상 테마를 변경합니다. 터미널의 밝은 배경 또는 어두운 배경에 맞추는 `auto` 옵션, 밝은 변형과 어두운 변형, 색맹 접근성(daltonized) 테마, 터미널의 색상 팔레트를 사용하는 ANSI 테마, `~/.claude/themes/` 또는 플러그인의 [사용자 지정 테마](/docs/ko/terminal-config#create-a-custom-theme)가 포함됩니다. 새로 만들려면 \*\*New custom theme…\*\*을 선택합니다 |161| `/theme` | 색상 테마를 변경합니다. 터미널의 밝은 배경 또는 어두운 배경에 맞추는 `auto` 옵션, 밝은 변형과 어두운 변형, 색맹 접근성(daltonized) 테마, 터미널의 색상 팔레트를 사용하는 ANSI 테마, `~/.claude/themes/` 또는 플러그인의 [사용자 지정 테마](/docs/ko/terminal-config#create-a-custom-theme)가 포함됩니다. 새로 만들려면 \*\*New custom theme…\*\*을 선택합니다 |

corporate-launcher.md +26 −4

Details

120런처가 실행될 수 없으면 Claude Code는 래핑되지 않은 상태로 시작하는 대신 프로세스 시작을 거부합니다. Windows에서는 [변수가 무시되며](#what-the-launcher-covers) 프로세스가 래핑되지 않은 상태로 시작됩니다. Claude Code는 스크립트를 다음 규칙에 따릅니다:120런처가 실행될 수 없으면 Claude Code는 래핑되지 않은 상태로 시작하는 대신 프로세스 시작을 거부합니다. Windows에서는 [변수가 무시되며](#what-the-launcher-covers) 프로세스가 래핑되지 않은 상태로 시작됩니다. Claude Code는 스크립트를 다음 규칙에 따릅니다:

121 121

122* **`exec "$@"`로 끝냅니다.** 자식을 포크하고 종료하는 런처는 백그라운드 서비스가 추적할 수 없는 고아 Claude Code 프로세스를 남깁니다. 에이전트 뷰는 런처 이름을 지정하는 메시지와 함께 이러한 세션을 실패로 표시하며, 서비스는 런처가 남긴 것을 수거합니다.122* **`exec "$@"`로 끝냅니다.** 자식을 포크하고 종료하는 런처는 백그라운드 서비스가 추적할 수 없는 고아 Claude Code 프로세스를 남깁니다. 에이전트 뷰는 런처 이름을 지정하는 메시지와 함께 이러한 세션을 실패로 표시하며, 서비스는 런처가 남긴 것을 수거합니다.

123* **인수를 재정렬, 흡수 또는 앞에 추가하지 마십시오.** 첫 번째 인수는 Claude Code 바이너리이고 그 이후의 모든 것은 해당 argv입니다.123* **Claude Code의 인수를 재정렬, 흡수하거나 추가하지 마십시오.** 맨 앞에 오는 런처 [자체 인수](#pass-arguments-to-the-launcher)를 제거하고, 나머지는 전달받은 그대로 `exec`에 전달합니다.

124* **상속된 모든 환경 변수를 `exec`를 통해 전달합니다.** 주입된 자격 증명과 같은 변수를 추가하는 것은 괜찮습니다. 상속된 변수를 삭제하는 것은 아닙니다.124* **상속된 모든 환경 변수를 `exec`를 통해 전달합니다.** 주입된 자격 증명과 같은 변수를 추가하는 것은 괜찮습니다. 상속된 변수를 삭제하는 것은 아닙니다.

125 * 세션별 인증 토큰, 모델 및 공급자 선택, 그리고 `CLAUDE_CODE_PROCESS_WRAPPER` 자체는 모두 상속된 환경에서 이동하므로 허용 목록에서 재구성하는 런처는 시작하는 세션을 중단하며, `/status`는 런처 불일치를 보고합니다.125 * 세션별 인증 토큰, 모델 및 공급자 선택, 그리고 `CLAUDE_CODE_PROCESS_WRAPPER` 자체는 모두 상속된 환경에서 이동하므로 허용 목록에서 재구성하는 런처는 시작하는 세션을 중단하며, `/status`는 런처 불일치를 보고합니다.

126 * 런처가 환경을 재설정하는 네임스페이스 또는 샌드박스에 들어가야 하는 경우, 상속된 환경을 그 안에서 그대로 다시 내보냅니다.126 * 런처가 환경을 재설정하는 네임스페이스 또는 샌드박스에 들어가야 하는 경우, 상속된 환경을 그 안에서 그대로 다시 내보냅니다.

127* **런처가 실행될 때마다 약 3초 이내에 `exec`에 도달합니다.** 콜드 백그라운드 디스패치는 첫 번째 출력 바이트 전에 런처를 두 번 연속으로 실행하므로 단일 사인온 교환과 같은 느린 작업을 게으르게 또는 캐시에서 수행합니다.127* **런처가 실행될 때마다 약 3초 이내에 `exec`에 도달합니다.** 백그라운드 세션은 첫 번째 출력 전에 런처를 세 번 연속으로 실행할 수 있습니다. 단일 사인온 교환과 같은 느린 작업은 지연 방식으로 또는 캐시에서 수행하고, 네트워크를 기다리는 모든 단계에는 자체 시간 제한을 지정합니다.

128* **자신 내부에서 호출되는 것을 허용합니다.** Claude Code는 모든 중첩된 자체 생성에 런처를 적용하므로 배타적 리소스를 획득하는 런처는 이미 보유하고 있음을 감지해야 합니다.128* **자신 내부에서 호출되는 것을 허용합니다.** Claude Code는 모든 중첩된 자체 생성에 런처를 적용하므로 배타적 리소스를 획득하는 런처는 이미 보유하고 있음을 감지해야 합니다.

129* **Claude Code가 시작되기 전에 터미널에 쓰지 마십시오.** `exec` 전에 인쇄된 모든 것은 세션이 초기화 전에 종료되면 충돌 원인으로 보고됩니다.129* **Claude Code가 시작되기 전에 터미널이나 표준 출력에 쓰지 마십시오.** `exec` 전에 인쇄된 모든 것은 세션이 초기화 전에 종료되면 충돌 원인으로 보고됩니다. 표준 출력의 텍스트는 `claude -p` 결과를 구문 분석하는 스크립트처럼 Claude Code의 출력을 읽는 프로그램에도 전달됩니다.

130* **인수의 표기 방식에 의존하지 마십시오.** 플래그의 값은 `--flag value`처럼 별도의 인수로 전달되거나, `--flag=value`처럼 플래그에 결합되어 전달될 수 있습니다. 플래그가 어떤 형식을 사용하는지는 버전에 따라 달라질 수 있습니다.130* **인수의 표기 방식에 의존하지 마십시오.** 플래그의 값은 `--flag value`처럼 별도의 인수로 전달되거나, `--flag=value`처럼 플래그에 결합되어 전달될 수 있습니다. 플래그가 어떤 형식을 사용하는지는 버전에 따라 달라질 수 있습니다.

131* **런처가 시작된 디렉터리에서 `exec`를 실행합니다.** Claude Code는 시작된 디렉터리에서 작업하므로 디렉터리를 변경하는 런처는 잘못된 프로젝트에서 세션을 시작할 수 있습니다. 런처가 작업 디렉터리를 재설정하는 네임스페이스 또는 샌드박스에 들어가야 하는 경우, `exec` 전에 그 안에서 시작 디렉터리로 다시 변경합니다.131* **런처가 시작된 디렉터리에서 `exec`를 실행합니다.** Claude Code는 시작된 디렉터리에서 작업하므로 디렉터리를 변경하는 런처는 잘못된 프로젝트에서 세션을 시작할 수 있습니다. 런처가 작업 디렉터리를 재설정하는 네임스페이스 또는 샌드박스에 들어가야 하는 경우, `exec` 전에 그 안에서 시작 디렉터리로 다시 변경합니다.

132* **표준 입력을 읽지 마십시오.** 비밀번호를 묻는 명령처럼 `exec` 전에 표준 입력을 읽는 명령은 오지 않는 입력을 기다리며 세션을 멈춘 상태로 둘 수 있습니다. 또한 Claude Code를 위한 입력을 가져갈 수도 있으며, 그러면 세션은 해당 입력 없이 실행되고 오류를 보고하지 않습니다. 이러한 명령의 입력은 `/dev/null`에서 리디렉션합니다.

133* **다른 프로그램은 절대 경로로 호출합니다.** 런처는 셸 프로필이 추가하는 디렉터리가 없는 `PATH`로 시작될 수 있습니다.

132 134

133<h3 id="format-of-the-launcher-value">135<h3 id="format-of-the-launcher-value">

134 런처 값의 형식136 런처 값의 형식

138 140

139런처에 자신의 인수를 전달하려면 경로 뒤에 작성합니다. Claude Code는 값을 셸 명령이 아닌 인수 목록으로 구문 분석합니다:141런처에 자신의 인수를 전달하려면 경로 뒤에 작성합니다. Claude Code는 값을 셸 명령이 아닌 인수 목록으로 구문 분석합니다:

140 142

141* 공백은 토큰을 분리하고 큰따옴표는 공백을 포함하는 토큰을 그룹화합니다.143* 공백은 토큰을 분리하고 큰따옴표는 공백을 포함하는 토큰을 그룹화합니다. 작은따옴표는 일반 문자이므로 `'a b'`는 두 개의 토큰입니다.

142* `[`로 시작하는 값은 `["/opt/corp/launcher", "--profile", "cc"]`와 같은 JSON 문자열 배열로 읽혀집니다.144* `[`로 시작하는 값은 `["/opt/corp/launcher", "--profile", "cc"]`와 같은 JSON 문자열 배열로 읽혀집니다.

143* 셸 구문은 작동하지 않습니다: 변수 확장이나 글로빙이 없으며, `;`, `|`, `&` 또는 `$(`와 같은 인용되지 않은 연산자는 재해석되지 않고 구성 오류로 거부됩니다.145* 셸 구문은 작동하지 않습니다: 변수 확장이나 글로빙이 없으며, `;`, `|`, `&` 또는 `$(`와 같은 인용되지 않은 연산자는 재해석되지 않고 구성 오류로 거부됩니다.

144 146

145값을 사용할 수 없으면 Claude Code는 영향을 받는 프로세스 시작을 거부하고 [이유를 보고합니다](/docs/ko/errors#claude_code_process_wrapper-launcher-errors).147값을 사용할 수 없으면 Claude Code는 영향을 받는 프로세스 시작을 거부하고 [이유를 보고합니다](/docs/ko/errors#claude_code_process_wrapper-launcher-errors).

146 148

149설정 파일에서는 배열 형식을 JSON 문자열 안에 작성하고 따옴표를 이스케이프합니다: `"[\"/opt/corp/launcher\", \"--profile\", \"cc\"]"`.

150

151<h3 id="pass-arguments-to-the-launcher">

152 런처에 인수 전달

153</h3>

154

155런처 자체 인수는 [값](#format-of-the-launcher-value)에서 경로 뒤에 작성하고, 스크립트에서 `exec` 호출 전에 제거합니다. 이 인수는 Claude Code 명령보다 앞서 스크립트에 먼저 전달됩니다. 다음 스크립트는 `/opt/corp/launcher --profile cc` 값에 맞게 작성된 것으로, 프로필 이름을 저장한 다음 `shift`로 두 인수를 모두 제거합니다:

156

157```bash theme={null}

158#!/bin/sh

159if [ "$1" = "--profile" ]; then

160 profile="$2"

161 shift 2

162fi

163# Your organization's setup for "$profile".

164exec "$@"

165```

166

167[확인 단계](#set-up-the-launcher)를 사용하여 Claude Code가 값에서 확인한 실행 명령을 볼 수 있습니다.

168

147<h2 id="relationship-to-claude_code_shell_prefix">169<h2 id="relationship-to-claude_code_shell_prefix">

148 `CLAUDE_CODE_SHELL_PREFIX`와의 관계170 `CLAUDE_CODE_SHELL_PREFIX`와의 관계

149</h2>171</h2>

desktop.md +332 −70

Details

44 세션 시작하기44 세션 시작하기

45</h2>45</h2>

46 46

~~47첫 번째 메시지를 보내기 전에 프롬프트 영역에서 네 가지를 구성하세요:~~47첫 번째 메시지를 보내기 전에 프롬프트 상자 아래 행에서 환경, 프로젝트 폴더, 권한 모드, 모델을 선택합니다:

48 48

49* **환경**: Claude가 실행되는 위치를 선택합니다. 자신의 머신의 경우 **Local**, 앱을 닫은 후에도 계속되는 [클라우드 세션](#cloud-sessions)의 경우 **Cloud**, 관리하는 원격 머신의 경우 [**SSH 연결**](#ssh-sessions), 또는 Windows의 경우 [**WSL 배포판**](/docs/ko/desktop-wsl)을 선택합니다. SSH 세션의 작업은 [Desktop 연결이 끊긴 동안에도 계속 실행](#keep-a-task-running-while-desktop-is-disconnected)될 수 있지만, Claude 계정을 사용하는 경우 로그인이 만료되면 중지될 수 있습니다. [환경 구성](#environment-configuration)을 참조하세요.49* **환경**: 행의 첫 번째 컨트롤인 환경 선택기를 사용하여 Claude가 실행되는 위치를 선택합니다. [환경 구성](#environment-configuration)을 참조하세요.

50* **프로젝트 폴더**: Claude가 작업할 폴더 또는 저장소를 선택합니다. 클라우드 세션의 경우 [여러 저장소](#run-long-running-tasks-in-the-cloud)를 추가할 수 있습니다.50 * 새 세션의 프롬프트 상자 아래에 환경 선택기가 없다면 [이전 레이아웃의 단계](#check-which-layout-you-have)를 따르세요.

~~51* **모델**: 전송 버튼 옆의 드롭다운에서 [모델](/docs/ko/model-config#available-models)을 선택합니다. 세션 중에 이를 변경할 수 있습니다.~~51* **프로젝트 폴더**: 환경 선택기 옆에 있는 프로젝트 폴더 컨트롤을 클릭하여 Claude가 작업할 폴더를 선택합니다.

~~52* **권한 모드**: [모드 선택기](#choose-a-permission-mode)에서 Claude가 가질 자율성을 선택합니다. 세션 중에 이를 변경할 수 있습니다.~~52 * **클라우드 세션**: 폴더 대신 [저장소](#run-long-running-tasks-in-the-cloud)를 선택합니다

53 * **[저장된 로컬 또는 SSH 환경](#create-a-saved-environment)**: 환경에 이미 폴더가 포함되어 있으므로 행에 프로젝트 폴더 컨트롤이 표시되지 않습니다. 폴더를 변경하려면 [환경을 편집](#use-edit-or-remove-a-saved-environment)합니다.

54* **권한 모드**: [모드 선택기](#choose-a-permission-mode)를 사용하여 Claude가 가질 자율성을 선택합니다. 세션 중에 권한 모드를 변경할 수 있습니다.

55* **모델**: 행의 오른쪽 끝 부분에 있는 모델 선택기에서 [모델](/docs/ko/model-config#available-models)을 선택합니다. 세션 중에 모델을 변경할 수 있습니다.

53 56

54작업을 입력하고 **Enter**를 눌러 시작합니다. 각 세션은 자신의 컨텍스트와 변경 사항을 독립적으로 추적합니다.57작업을 입력하고 **Enter**를 눌러 시작합니다. 각 세션은 자신의 컨텍스트와 변경 사항을 독립적으로 추적합니다.

55 58

82 프롬프트에 파일 및 컨텍스트 추가하기85 프롬프트에 파일 및 컨텍스트 추가하기

83</h3>86</h3>

84 87

~~85프롬프트 상자는 외부 컨텍스트를 가져오는 두 가지 방법을 지원합니다:~~88Claude에게 파일을 제공하려면 프롬프트 상자에서 파일을 @mention하거나 첨부합니다:

86 89

87* **@mention 파일**: `@` 다음에 파일 이름을 입력하여 파일을 대화 컨텍스트에 추가합니다. Claude는 그 파일을 읽고 참조할 수 있습니다. @mention은 클라우드 또는 WSL 세션에서 사용할 수 없습니다.90* **@mention 파일**: `@` 다음에 파일 이름을 입력하여 파일을 대화 컨텍스트에 추가합니다.

88* **파일 첨부**: 첨부 버튼을 사용하여 이미지, PDF 및 기타 파일을 프롬프트에 첨부하거나, 파일을 프롬프트에 직접 드래그 앤 드롭합니다. 이는 버그 스크린샷, 디자인 목업 또는 참고 문서를 공유하는 데 유용합니다.91 * **클라우드 세션에서**: `@`는 첫 번째 메시지를 보낸 후에만 파일을 나열할 수 있습니다. `@`가 아무 파일도 나열하지 않으면 파일 없이 첫 번째 메시지를 보낸 다음, 다음 메시지에서 파일을 @mention합니다.

92* **파일 첨부**: 프롬프트 상자 옆의 **+** 버튼에서 이미지, PDF 및 기타 파일을 프롬프트에 첨부하거나, 파일을 프롬프트에 직접 드래그 앤 드롭합니다. 이는 버그 스크린샷, 디자인 목업 또는 참고 문서를 공유하는 데 유용합니다.

93 * **[WSL 세션](/docs/ko/desktop-wsl)에서**: **+** 메뉴에 **Add files or photos** 대신 **Add image**가 표시되면 이미지만 첨부할 수 있습니다. 세션 폴더의 다른 파일을 Claude에게 제공하려면 해당 파일을 @mention합니다.

89 94

90<h3 id="choose-a-permission-mode">95<h3 id="choose-a-permission-mode">

91 권한 모드 선택하기96 권한 모드 선택하기

92</h3>97</h3>

93 98

94권한 모드는 세션 중에 Claude가 가질 자율성을 제어합니다: 파일 편집, 명령 실행 또는 둘 다 전에 묻는지 여부입니다. 전송 버튼 옆의 모드 선택기를 사용하여 언제든지 모드를 전환할 수 있습니다. 각 변경 사항을 승인하거나 거부하려면 Manual로 전환합니다.99권한 모드는 세션 중에 Claude가 가질 자율성을 제어합니다: 파일 편집, 명령 실행 또는 둘 다 전에 묻는지 여부입니다. 프롬프트 상자 아래 줄의 모드 선택기를 사용하여 언제든지 권한 모드를 전환할 수 있습니다. 각 변경 사항을 직접 승인하려면 Manual로 전환합니다.

95 100

96새 로컬 세션의 기본 모드를 설정하려면 [설정 파일](/docs/ko/settings#where-settings-live)에 `permissions.defaultMode`를 추가합니다. 데스크톱 앱은 CLI와 동일한 설정 파일을 읽습니다. 선택기에서 선택한 모드는 폴더별로 기억되며 해당 폴더의 `defaultMode`보다 우선하지만, Plan은 현재 세션에만 적용됩니다.101새 로컬 세션의 기본 모드를 설정하려면 [설정 파일](/docs/ko/settings#where-settings-live)에 `permissions.defaultMode`를 추가합니다. 데스크톱 앱은 CLI와 동일한 설정 파일을 읽습니다. 선택기에서 선택한 모드는 폴더별로 기억되며 해당 폴더의 `defaultMode`보다 우선하지만, Plan은 현재 세션에만 적용됩니다.

97 102

129 134

130Claude는 개발 서버를 시작하고 Browser 패널에서 열어 변경 사항을 확인할 수 있습니다. 이는 프론트엔드 웹 앱뿐만 아니라 백엔드 서버에도 작동합니다: Claude는 API 엔드포인트를 테스트하고, 서버 로그를 보고, 발견한 문제를 반복할 수 있습니다. 대부분의 경우 Claude는 프로젝트 파일을 편집한 후 자동으로 서버를 시작합니다. 언제든지 Claude에게 미리보기를 요청할 수도 있습니다. 기본적으로 Claude는 모든 편집 후 [자동으로 변경 사항을 확인](#auto-verify-changes)합니다.135Claude는 개발 서버를 시작하고 Browser 패널에서 열어 변경 사항을 확인할 수 있습니다. 이는 프론트엔드 웹 앱뿐만 아니라 백엔드 서버에도 작동합니다: Claude는 API 엔드포인트를 테스트하고, 서버 로그를 보고, 발견한 문제를 반복할 수 있습니다. 대부분의 경우 Claude는 프로젝트 파일을 편집한 후 자동으로 서버를 시작합니다. 언제든지 Claude에게 미리보기를 요청할 수도 있습니다. 기본적으로 Claude는 모든 편집 후 [자동으로 변경 사항을 확인](#auto-verify-changes)합니다.

131 136

132Browser 패널은 프로젝트의 정적 HTML 파일, PDF, 이미지 및 비디오도 열 수 있습니다. 채팅에서 HTML, PDF, 이미지 또는 비디오 경로를 클릭하여 Browser 패널에서 엽니다.137로컬 세션에서는 채팅에서 HTML, PDF 또는 비디오 경로를 클릭하여 Browser 패널에서 엽니다.

133 138

134<Note>139<Note>

135 [SSH 세션](#ssh-sessions)에서는 Claude가 Browser 패널의 도구를 사용할 수 없으므로 Browser 패널에서 앱을 열 수 없습니다. 앱을 직접 확인하려면 [앱의 포트를 컴퓨터로 포워딩](#reach-a-port-on-the-remote-machine)합니다.140 [SSH 세션](#ssh-sessions)에서는 Claude가 Browser 패널의 도구를 사용할 수 없으므로 Browser 패널에서 앱을 열 수 없습니다. 앱을 직접 확인하려면 [앱의 포트를 컴퓨터로 포워딩](#reach-a-port-on-the-remote-machine)합니다.

136</Note>141</Note>

137 142

143로컬 세션에서 Claude가 서버를 시작한 후 Browser 패널이 열려 있지 않으면 채팅에서 서버 카드의 **Open**을 클릭합니다.

144

138Browser 패널에서 다음을 수행할 수 있습니다:145Browser 패널에서 다음을 수행할 수 있습니다:

139 146

140* Browser 패널에서 실행 중인 앱과 직접 상호작용합니다147* Browser 패널에서 실행 중인 앱과 직접 상호작용합니다

185 diff 보기로 변경 사항 검토하기192 diff 보기로 변경 사항 검토하기

186</h3>193</h3>

187 194

188Claude가 코드를 변경한 후 diff 보기를 사용하면 풀 리퀘스트를 만들기 전에 파일별로 수정 사항을 검토할 수 있습니다.195Claude가 코드를 변경한 후 diff 보기를 사용하면 풀 리퀘스트를 만들기 전에 파일별로 수정 사항을 검토할 수 있습니다. diff 보기를 열려면 [세션 세부 정보 패널](#see-session-details)의 **Changes** 카드에서 `+12 -1`과 같은 줄 수를 클릭합니다. 세션 제목 표시줄에서 **Changes**를 클릭할 수도 있습니다.

~~189~~

190Claude가 파일을 변경하면 `+12 -1`과 같이 추가 및 제거된 줄 수를 표시하는 diff 통계 표시기가 나타납니다. 이 표시기를 클릭하여 diff 뷰어를 열면 왼쪽에 파일 목록이 표시되고 오른쪽에 각 파일의 변경 사항이 표시됩니다.

191 196

192특정 줄에 댓글을 달려면 diff의 모든 줄을 클릭하여 댓글 상자를 엽니다. 피드백을 입력하고 **Enter**를 눌러 댓글을 추가합니다. 여러 줄에 댓글을 추가한 후 모든 댓글을 한 번에 제출합니다:197특정 줄에 댓글을 달려면 diff의 모든 줄을 클릭하여 댓글 상자를 엽니다. 피드백을 입력하고 **Enter**를 눌러 댓글을 추가합니다. 여러 줄에 댓글을 추가한 후 모든 댓글을 한 번에 제출합니다:

193 198

213 풀 리퀘스트 상태 모니터링하기218 풀 리퀘스트 상태 모니터링하기

214</h3>219</h3>

215 220

216풀 리퀘스트를 연 후 CI 상태 표시줄이 세션에 나타납니다. Claude Code는 GitHub CLI를 사용하여 확인 결과를 폴링하고 실패를 표시합니다.221Claude가 실패한 확인을 수정하도록 하거나 GitHub가 풀 리퀘스트를 병합하도록 하려면 **Auto-fix** 또는 **Merge when ready**를 켭니다. 풀 리퀘스트를 열면 [세션 세부 정보 패널](#see-session-details)의 **Changes** 카드에 CI 확인 상태와 함께 표시됩니다. 제목 옆의 **⋮** 메뉴를 엽니다:

217 222

218* **Auto-fix CI & address comments**: 활성화되면 Claude는 실패 출력을 읽고 반복하여 실패한 CI 확인을 자동으로 수정하려고 시도합니다. 로컬 세션에서는 작성자가 저장소 소유자, 조직 구성원, 협업자 또는 GitHub App인 경우 사용자 이외의 사람이 남긴 새 리뷰 댓글에도 Claude가 대응합니다.223* **Auto-fix**: 로컬 세션에서는 사용자 이외의 사람이 남긴 새 리뷰 댓글에도 Claude가 대응합니다. 댓글 작성자는 저장소 소유자, 조직 구성원, 협업자 또는 GitHub App이어야 합니다.

219* **Auto-merge when ready**: 활성화되면 모든 확인이 통과하면 Claude가 PR을 병합합니다. 병합 방법은 squash입니다. 먼저 [GitHub 저장소 설정](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)에서 auto-merge를 활성화해야 합니다. 이를 활성화하지 않으면 Claude가 PR을 병합할 수 없습니다.224* **Merge when ready**: PR에 대해 GitHub의 auto-merge를 켭니다. 로컬 세션에서는 기본 브랜치가 병합 큐를 사용하지 않는 한 Desktop이 squash 병합을 요청합니다.

225 * **SSH 및 WSL 세션에서**: **Merge when ready**가 비활성화되어 있으므로 GitHub에서 풀 리퀘스트의 auto-merge를 켭니다

226 * **저장소가 auto-merge를 허용하지 않는 경우**: **Merge when ready**가 켜지지 않으므로 먼저 [GitHub 저장소 설정](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)에서 auto-merge를 활성화합니다

227* **[이전 레이아웃](#check-which-layout-you-have)**: 세션에 풀 리퀘스트가 생기면 상태 표시줄에서 **CI**를 클릭합니다.

220 228

221이 옵션을 켜려면 상태 표시줄에서 **CI**를 클릭합니다. PR이 병합되거나 닫히면 세션을 자동으로 아카이브하려면 **Settings > Claude Code**에서 [auto-archive](#work-in-parallel-with-sessions)를 켭니다.229PR이 병합되거나 닫히면 세션을 자동으로 아카이브하려면 **Settings > Claude Code**에서 [auto-archive](#archive-a-session)를 켭니다.

222 230

223<Note>231<Note>

224 PR 모니터링에는 [GitHub CLI (`gh`)](https://cli.github.com/)가 머신에 설치되고 인증되어야 합니다. `gh`가 설치되지 않은 경우 Desktop은 처음으로 PR을 만들려고 할 때 설치하도록 요청합니다.232 PR 모니터링에는 [GitHub CLI (`gh`)](https://cli.github.com/)가 머신에 설치되고 인증되어야 합니다. `gh`가 설치되지 않은 경우 Desktop은 처음으로 PR을 만들려고 할 때 설치하도록 요청합니다.

235화면 전체에서 작업하려면 diff 또는 터미널과 같은 패널을 자신의 창으로 팝업하고 완료되면 다시 도킹합니다. Claude는 주 창에서 계속 작동합니다.243화면 전체에서 작업하려면 diff 또는 터미널과 같은 패널을 자신의 창으로 팝업하고 완료되면 다시 도킹합니다. Claude는 주 창에서 계속 작동합니다.

236 244

237<Note>245<Note>

238 이 섹션의 패널 레이아웃, 터미널, 파일 편집기, 보기 모드는 Claude Desktop v1.2581.0 이상이 필요합니다. macOS에서 **Claude → Check for Updates**를 열거나 Windows에서 **Help → Check for Updates**를 열어 업데이트합니다.246 이 섹션의 패널 레이아웃, 터미널, 파일 편집기, 보기 모드는 Claude Desktop v1.2581.0 이상이 필요합니다. macOS에서 \*\*Claude > Check for Updates…\*\*를 열거나 Windows에서 \*\*Help > Check for Updates…\*\*를 열어 업데이트합니다.

239</Note>247</Note>

240 248

249<h3 id="see-session-details">

250 세션 세부 정보 보기

251</h3>

252

253세션 세부 정보 패널은 채팅 옆에 표시되는 카드 모음으로, 세션이 실행되는 위치, 세션이 변경한 내용, 현재 실행 중인 항목을 보여줍니다. 이 패널은 세션을 시작한 후 채팅 영역이 충분히 넓을 때 나타납니다.

254

255<h4 id="hide-or-show-the-session-details-panel">

256 세션 세부 정보 패널 숨기기 또는 표시하기

257</h4>

258

259패널을 숨기거나 표시하려면 세션 제목 표시줄에서 **Hide session rail** 또는 **Show session rail**을 클릭하거나, 창이 좁을 때는 표시줄의 **⋮** 메뉴에서 클릭합니다. 그래도 패널이 보이지 않으면 [사용 중인 Code 탭 레이아웃을 확인합니다](#check-which-layout-you-have).

260

241<h3 id="run-commands-in-the-terminal">261<h3 id="run-commands-in-the-terminal">

242 터미널에서 명령 실행하기262 터미널에서 명령 실행하기

243</h3>263</h3>

244 264

245통합 터미널을 사용하면 다른 앱으로 전환하지 않고 세션과 함께 명령을 실행할 수 있습니다. 세션 제목 표시줄에서 **Terminal**을 클릭하거나 macOS 또는 Windows에서 \*\*Ctrl+\`\*\*를 누릅니다. 터미널은 세션의 작업 디렉터리에서 열리고 Claude와 동일한 환경을 공유하므로 `npm test` 또는 `git status`와 같은 명령은 Claude가 편집하는 것과 동일한 파일을 봅니다. 두 번째 터미널 탭을 열려면 터미널 패널 헤더의 \*\*+\*\*를 클릭하거나 채팅의 폴더를 마우스 오른쪽 버튼으로 클릭하여 **Open in terminal**을 선택합니다.265통합 터미널을 사용하면 다른 앱으로 전환하지 않고 세션과 함께 명령을 실행할 수 있습니다. 세션 제목 표시줄에서 **Terminal**을 클릭하거나 macOS 또는 Windows에서 \*\*Ctrl+\`\*\*를 누릅니다. 터미널은 세션의 작업 디렉터리에서 열리고 Claude와 동일한 환경을 공유하므로 `npm test` 또는 `git status`와 같은 명령은 Claude가 편집하는 것과 동일한 파일을 봅니다. 두 번째 터미널 탭을 열려면 터미널 패널 헤더의 \*\*+\*\*를 클릭하거나 채팅의 폴더를 마우스 오른쪽 버튼으로 클릭하여 **Open in terminal**을 선택합니다.

246 266

247터미널은 로컬 및 [SSH](#ssh-sessions) 세션에서 사용 가능하며, [Windows 원격 머신](#windows-remote-machines)에서는 제한이 있습니다.267WSL 세션에 터미널이 없으면 [터미널 또는 커넥터를 사용할 수 없는 경우](/docs/ko/desktop-wsl#check-for-the-terminal-and-connectors)를 참조하세요. 터미널은 로컬 및 [SSH](#ssh-sessions) 세션에서 사용 가능하며, [Windows 원격 머신](#windows-remote-machines)에서는 제한이 있습니다.

248 268

249<h3 id="open-and-edit-files">269<h3 id="open-and-edit-files">

250 파일 열기 및 편집하기270 파일 열기 및 편집하기

251</h3>271</h3>

252 272

253채팅 또는 diff 뷰어의 파일 경로를 클릭하여 파일 패널에서 엽니다. HTML, PDF, 이미지, 비디오 경로는 대신 [브라우저 패널](#preview-your-app)에서 열립니다. 스팟 편집을 하고 **Save**를 클릭하여 다시 작성합니다. 파일이 열린 이후 디스크에서 변경되었으면 패널이 경고하고 재정의하거나 버립니다. **Discard**를 클릭하여 편집을 되돌리거나 패널 헤더의 경로를 클릭하여 절대 경로를 복사합니다.273Claude가 언급한 파일을 열려면 채팅에서 해당 경로를 클릭합니다.

254 274

255파일 패널은 로컬 및 SSH 세션에서 사용 가능합니다. 클라우드 세션의 경우 Claude에게 변경을 요청합니다.275파일을 직접 편집하려면 [파일 패널](#arrange-your-workspace)을 사용합니다:

276

277* **로컬 세션**: 세션의 작업 디렉터리 안에 있는 파일을 편집할 수 있지만, `.mcp.json` 및 `.claude/settings.json`과 같은 일부 보기 전용 파일은 예외입니다. 이러한 파일을 변경하려면 [다른 앱에서 엽니다](#open-files-in-other-apps).

278* **클라우드, SSH, WSL 세션**: 파일 패널은 보기 전용이므로 Claude에게 편집을 요청합니다.

279

280<h4 id="save-edits-in-the-file-pane">

281 파일 패널에서 편집 내용 저장하기

282</h4>

283

284기본적으로 파일 패널의 편집 내용은 자동으로 저장되므로 패널에 **Save** 버튼이 표시되지 않습니다. 편집 내용을 직접 저장하려면 패널의 **⋮** 메뉴에서 **Auto save**를 선택 해제합니다. **Auto save**가 꺼져 있으면 파일을 변경한 후 **Save**를 클릭하여 편집 내용을 기록하거나 **Cancel**을 클릭하여 되돌립니다.

285

286파일이 디스크에서 변경되었다는 경고가 패널에 표시되면 **Override**를 클릭하여 디스크의 버전을 편집 내용으로 덮어쓰거나 **Discard**를 클릭하여 편집 내용을 버립니다.

256 287

257<h3 id="open-files-in-other-apps">288<h3 id="open-files-in-other-apps">

258 다른 앱에서 파일 열기289 다른 앱에서 파일 열기

283 키보드 단축키314 키보드 단축키

284</h3>315</h3>

285 316

286macOS에서 \*\*Cmd+/\*\*를 누르거나 Windows에서 \*\*Ctrl+/\*\*를 눌러 Code 탭에서 사용 가능한 모든 단축키를 봅니다. Windows에서는 아래 단축키에 대해 **Cmd** 대신 **Ctrl**을 사용합니다. 세션 순환, 터미널 토글, 보기 모드 토글은 모든 플랫폼에서 **Ctrl**을 사용합니다.317macOS에서 \*\*Cmd+/\*\*를 누르거나 Windows에서 \*\*Ctrl+/\*\*를 눌러 Code 탭에서 사용 가능한 모든 단축키를 봅니다. 이 섹션의 표는 macOS 키를 보여줍니다. Windows 및 Linux에서는 다음 키를 바꿔 사용합니다:

318

319* **Cmd+Option**: **Alt**를 누릅니다

320* **Cmd**: **Ctrl**을 누릅니다

321

322세션 순환, 터미널 토글, 보기 모드 토글은 모든 플랫폼에서 **Ctrl**을 사용합니다.

287 323

288| 단축키 | 작업 |324| 단축키 | 작업 |

289| - | - |325| - | - |

290| `Cmd` `/` | 키보드 단축키 표시 |326| `Cmd` `/` | 키보드 단축키 표시 |

291| `Cmd` `N` | 새 세션 |327| `Cmd` `N` | 새 세션 |

328| `Cmd` `Option` `1`–`9` | [현재 레이아웃](#check-which-layout-you-have)의 새 세션 화면에서 환경 선택 |

329| `Cmd` `Option` `0` | 현재 레이아웃의 새 세션 화면에서 [**New environment** 대화 상자](#create-a-saved-environment) 열기 |

404 세션으로 병렬 작업하기442 세션으로 병렬 작업하기

405</h3>443</h3>

406 444

407사이드바에서 **+ New session**을 클릭하거나 macOS에서 **Cmd+N**을 누르거나 Windows에서 **Ctrl+N**을 눌러 여러 작업을 병렬로 작업합니다. **Ctrl+Tab** 및 **Ctrl+Shift+Tab**을 눌러 사이드바의 세션을 순환합니다. Git 저장소의 경우 브랜치 이름 옆의 **worktree** 옵션을 선택하면 [Git worktrees](/docs/ko/worktrees)를 사용하여 세션이 프로젝트의 자체 격리된 복사본을 가지게 됩니다.445사이드바에서 **+ New**를 클릭하거나 macOS에서 **Cmd+N**을 누르거나 Windows에서 **Ctrl+N**을 눌러 여러 작업을 병렬로 작업합니다. **Ctrl+Tab** 및 **Ctrl+Shift+Tab**을 눌러 사이드바의 세션을 순환합니다.

408 446

409두 세션을 동시에 보려면 macOS에서 **Cmd**를 누르거나 Windows에서 **Ctrl**을 누르고 사이드바의 세션을 클릭합니다. 세션이 이미 열려 있는 창 옆에 두 번째 창에서 열립니다. 분할이 활성화되어 있는 동안 다른 사이드바 세션을 클릭하면 포커스가 있는 창을 바꿉니다. macOS에서 \*\*Cmd+\\\*\*를 누르거나 Windows에서 \*\*Ctrl+\\\*\*를 눌러 포커스된 창을 닫고 단일 세션으로 돌아갑니다.447두 세션을 동시에 보려면 macOS에서 **Cmd**를 누르거나 Windows에서 **Ctrl**을 누르고 사이드바의 세션을 클릭합니다. 세션이 이미 열려 있는 창 옆에 두 번째 창에서 열립니다. 분할이 활성화되어 있는 동안 다른 사이드바 세션을 클릭하면 포커스가 있는 창을 바꿉니다. macOS에서 \*\*Cmd+\\\*\*를 누르거나 Windows에서 \*\*Ctrl+\\\*\*를 눌러 포커스된 창을 닫고 단일 세션으로 돌아갑니다.

410 448

411Worktrees는 기본적으로 `<project-root>/.claude/worktrees/`에 저장됩니다. 이를 사용자 정의 디렉토리로 변경할 수 있습니다:449<h4 id="run-a-session-in-its-own-worktree">

450 자체 worktree에서 세션 실행하기

451</h4>

452

453Git 저장소인 프로젝트에서 세션을 시작하기 전에 **Worktree**를 켜면 프로젝트의 격리된 복사본인 자체 [Git worktree](/docs/ko/worktrees)에서 세션을 실행합니다. 기본적으로 **Worktree**는 꺼져 있으며 Claude는 프로젝트 폴더 자체에서 작업합니다. [프롬프트 상자 아래 행](#start-a-session)에서 프로젝트 폴더 컨트롤을 클릭하고 **Worktree**를 켭니다.

454

455* **[저장된 환경](#create-a-saved-environment)을 사용하는 경우**: 환경을 만들거나 편집할 때 **Worktree**를 설정합니다

456* **[이전 레이아웃](#check-which-layout-you-have)**: 프롬프트 상자 위의 브랜치 이름 옆에 있는 **worktree** 체크박스를 선택합니다

457

458Worktrees는 기본적으로 `<project-root>/.claude/worktrees/`에 저장됩니다. 대신 사용자 정의 디렉토리에 저장하려면:

412 459

413* **로컬 세션**: **Settings > Claude Code**에서 **Worktree location**을 설정합니다460* **로컬 세션**: **Settings > Claude Code**에서 **Worktree location**을 설정합니다

414* **SSH 세션**: [SSH 연결](#choose-where-ssh-session-worktrees-go)에서 **Worktree folder**를 설정합니다461* **SSH 세션**: [SSH 연결](#choose-where-ssh-session-worktrees-go)에서 **Worktree folder**를 설정합니다

415 462

416**Settings > Claude Code**에서 **Branch prefix**를 설정할 수도 있습니다. Desktop은 이 접두사를 모든 worktree 브랜치 이름 앞에 추가하며, 이는 Claude가 만든 브랜치를 정리하는 데 유용합니다.463**Settings > Claude Code**에서 **Branch prefix**를 설정할 수도 있습니다. Desktop은 이 접두사를 모든 worktree 브랜치 이름 앞에 추가하며, 이는 Claude가 만든 브랜치를 정리하는 데 유용합니다.

417 464

418완료되면 사이드바의 세션 위에 마우스를 올리고 아카이브 아이콘을 클릭하여 worktree를 제거합니다. 풀 리퀘스트가 병합되거나 닫힐 때 세션이 자동으로 아카이브되도록 하려면 **Settings > Claude Code**에서 **Auto-archive after PR merge or close**를 켭니다. 자동 아카이브는 실행을 완료한 로컬 세션에만 적용됩니다.

~~419~~

420gitignored 파일 (예: `.env`)을 새 worktrees에 포함하려면 프로젝트 루트에 [`.worktreeinclude` 파일](/docs/ko/worktrees#copy-gitignored-files-into-worktrees)을 만듭니다. worktree 세션이 프로젝트 설정, 훅, 스킬을 어디에서 읽는지는 [worktree가 메인 체크아웃과 공유하는 항목](/docs/ko/worktrees#what-worktrees-share-with-the-main-checkout)을 참조하세요.465gitignored 파일 (예: `.env`)을 새 worktrees에 포함하려면 프로젝트 루트에 [`.worktreeinclude` 파일](/docs/ko/worktrees#copy-gitignored-files-into-worktrees)을 만듭니다. worktree 세션이 프로젝트 설정, 훅, 스킬을 어디에서 읽는지는 [worktree가 메인 체크아웃과 공유하는 항목](/docs/ko/worktrees#what-worktrees-share-with-the-main-checkout)을 참조하세요.

421 466

422<Note>467<Note>

423 세션 격리에는 [Git](https://git-scm.com/downloads)이 필요합니다. 대부분의 Mac에는 기본적으로 Git이 포함되어 있습니다. Terminal에서 `git --version`을 실행하여 확인합니다. 버전 번호가 출력되면 Git이 설치된 것입니다. Git 오류가 발생하면 [Cowork 탭](https://claude.com/product/cowork)에서 Claude에게 설정을 문제 해결하도록 요청하세요.468 세션 격리에는 [Git](https://git-scm.com/downloads)이 필요합니다. 대부분의 Mac에는 기본적으로 Git이 포함되어 있습니다. Terminal에서 `git --version`을 실행하여 확인합니다. 버전 번호가 출력되면 Git이 설치된 것입니다. Git 오류가 발생하면 [Cowork 탭](https://claude.com/product/cowork)에서 Claude에게 설정을 문제 해결하도록 요청하세요.

424</Note>469</Note>

425 470

426사이드바 상단의 컨트롤을 사용하여 상태, 프로젝트 또는 환경별로 세션을 필터링하고 프로젝트별로 세션을 그룹화합니다. 세션 이름을 바꾸려면 활성 세션 상단의 도구 모음에서 세션 제목을 클릭합니다.471<h3 id="add-folders-to-a-session">

472 세션에 폴더 추가하기

473</h3>

474

475세션이 시작되기 전이나 실행 중에 폴더를 추가합니다:

476

477* **로컬 세션이 시작되기 전**: [저장된 환경을 만들거나](#create-a-saved-environment) 편집할 때 **Folders** 아래에 폴더를 추가한 다음 [해당 저장된 환경에서 세션을 시작](#use-edit-or-remove-a-saved-environment)합니다.

478* **로컬 또는 [SSH](#ssh-sessions) 세션이 실행되는 동안**: 프롬프트 상자 옆의 \*\*+\*\*를 클릭하고 **Add folder**를 선택합니다. Claude는 [worktree](#run-a-session-in-its-own-worktree) 없이 해당 폴더 자체에서 작업합니다.

479

480<h3 id="archive-a-session">

481 세션 아카이브하기

482</h3>

483

484worktree에 커밋되지 않은 변경 사항이 있는 세션을 아카이브하기 전에 [세션이 아카이브될 때 커밋되지 않은 변경 사항 유지하기](#keep-uncommitted-changes-when-a-session-is-archived)를 참조하세요. 세션을 아카이브하려면 사이드바에서 세션 위에 마우스를 올리고 메뉴를 연 다음 **Archive**를 선택합니다. 세션은 [아카이브된 세션](#organize-and-find-sessions)으로 이동합니다.

485

486풀 리퀘스트가 병합되거나 닫힐 때 세션이 자동으로 아카이브되도록 하려면 **Settings > Claude Code**에서 **Auto-archive after PR merge or close**를 켭니다. 클라우드 세션과 아직 실행 중인 세션은 자동으로 아카이브되지 않습니다.

487

488<h4 id="keep-uncommitted-changes-when-a-session-is-archived">

489 세션이 아카이브될 때 커밋되지 않은 변경 사항 유지하기

490</h4>

491

492세션이 아카이브될 때 세션 worktree의 커밋되지 않은 변경 사항이 손실될 수 있으므로 유지하려는 내용을 먼저 커밋하세요:

493

494* **Desktop이 변경 사항에 대해 묻는 경우**: **Archive anyway**를 선택하여 변경 사항을 삭제하거나, 취소하고 커밋합니다

495* **변경 사항이 추적되지 않는 파일뿐인 경우**: 세션에서 Claude가 연 풀 리퀘스트가 병합되기 전에 유지하려는 파일을 커밋합니다. 병합되면 Desktop이 묻지 않고 해당 파일을 삭제할 수 있기 때문입니다

496* **그 외의 경우**: worktree는 변경 사항과 함께 디스크에 남아 있습니다. 로컬 세션의 경우 Desktop은 세션이 아카이브된 시점 또는 마지막으로 연 시점 중 더 늦은 시점으로부터 약 30일 후에 둘 다 제거합니다. 변경 사항을 유지하려면 [**Archived** 탭](#organize-and-find-sessions)에서 세션을 열고 **Unarchive**를 선택합니다

497

498<h3 id="organize-and-find-sessions">

499 세션 정리 및 찾기

500</h3>

501

502사이드바의 세션 목록에 있는 아이콘에서 세션을 그룹화하고, 정렬하고, 찾습니다:

503

504* **현재 레이아웃**: 세션 목록의 제목 위에 마우스를 올리면 **Group and sort** 아이콘이 표시되며, 이를 클릭합니다. 아카이브된 세션을 찾으려면 메뉴의 마지막 행인 **View all**을 선택한 다음 **Archived** 탭을 엽니다.

505* **[이전 레이아웃](#check-which-layout-you-have)**: **Filter** 아이콘이 마우스를 올리지 않아도 표시됩니다. 이를 클릭하여 **Group by** 또는 **Sort by**로 목록을 정렬합니다. 아카이브된 세션을 표시하려면 **Status**를 선택한 다음 **Archived**를 선택합니다.

506

507세션 이름을 바꾸려면 세션을 열고 제목 표시줄에서 세션 제목을 클릭합니다.

508

509<h3 id="check-and-free-up-context">

510 컨텍스트 확인 및 확보하기

511</h3>

427 512

428컨텍스트 사용량을 확인하려면 [사용량 확인](#check-usage)을 참조하세요. 컨텍스트가 가득 차면 Claude는 자동으로 대화를 요약하고 계속 작업합니다. `/compact`를 입력하여 요약을 더 일찍 트리거하고 컨텍스트 공간을 확보할 수도 있습니다. [컨텍스트 윈도우](/docs/ko/how-claude-code-works#the-context-window)에서 압축이 작동하는 방식에 대한 자세한 내용을 참조하세요.513컨텍스트 사용량을 확인하려면 [사용량 확인](#check-usage)을 참조하세요. 컨텍스트가 가득 차면 Claude는 자동으로 대화를 요약하고 계속 작업합니다. `/compact`를 입력하여 요약을 더 일찍 트리거하고 컨텍스트 공간을 확보할 수도 있습니다. [컨텍스트 윈도우](/docs/ko/how-claude-code-works#the-context-window)에서 압축이 작동하는 방식에 대한 자세한 내용을 참조하세요.

429 514

515<h3 id="get-notified-when-a-session-finishes">

516 세션이 완료되면 알림 받기

517</h3>

518

430데스크톱 앱은 Code 세션이 작업을 완료하고 현재 해당 세션을 보고 있지 않을 때 OS 알림을 보냅니다. [프로젝트](/docs/ko/claude-projects#see-what-needs-you-in-overview)에 속하는 세션의 경우 대신 프로젝트의 알림을 받습니다.519데스크톱 앱은 Code 세션이 작업을 완료하고 현재 해당 세션을 보고 있지 않을 때 OS 알림을 보냅니다. [프로젝트](/docs/ko/claude-projects#see-what-needs-you-in-overview)에 속하는 세션의 경우 대신 프로젝트의 알림을 받습니다.

431 520

432<h3 id="ask-a-side-question-without-derailing-the-session">521<h3 id="ask-a-side-question-without-derailing-the-session">

451 세션 간에 작업하기540 세션 간에 작업하기

452</h3>541</h3>

453 542

454Claude는 다른 Code 탭 세션을 나열하고, 각 세션이 수행한 작업을 읽고, 세션 간에 메시지를 보낼 수 있습니다. 일반 언어로 요청합니다: "어느 세션이 auth 리팩토링을 건드렸나?", "API 세션은 무엇을 결론지었나?", 또는 "payments 세션에 스키마가 변경되었다고 알려주세요". Claude에게 세션 이름을 바꾸거나 아카이브하도록 요청할 수도 있습니다. Claude는 사이드바의 아카이브 아이콘과 동일한 방식으로 세션을 아카이브하므로 PR이 병합된 세션을 정리하도록 요청합니다.543Claude는 다른 Code 탭 세션을 나열하고, 각 세션이 수행한 작업을 읽고, 세션 간에 메시지를 보낼 수 있습니다. 일반 언어로 요청합니다: "어느 세션이 auth 리팩토링을 건드렸나?", "API 세션은 무엇을 결론지었나?", 또는 "payments 세션에 스키마가 변경되었다고 알려주세요".

544

545Claude에게 세션 이름을 바꾸거나 아카이브하도록 요청할 수도 있습니다. 예를 들어 PR이 병합된 세션을 아카이브하도록 요청합니다.

455 546

456이 사용 환경을 통해 Claude는 데스크톱 앱이 자체적으로 실행하는 세션만 봅니다: Code 탭의 로컬, [SSH](#ssh-sessions), [WSL](/docs/ko/desktop-wsl) 세션. Claude는 클라우드 세션이나 터미널 CLI 또는 VS Code 확장에서 시작한 세션을 같은 프로젝트의 worktrees에 있더라도 보지 못합니다. 따라서 9개의 터미널 worktrees와 2개의 데스크톱 세션이 열려 있으면 그 중 한 데스크톱 세션에서 답변하는 Claude는 나머지 하나의 데스크톱 세션만 보고합니다. Claude는 요청하는 세션을 나열하지 않습니다. 기본적으로 가장 최근에 활성화된 20개 세션을 보며, 요청하지 않는 한 아카이브된 세션은 건너뜁니다. [교차 세션 메시징](/docs/ko/cross-session-messaging)은 이와 별도로 Claude가 터미널 세션을 포함한 [다른 Claude Code 세션](/docs/ko/cross-session-messaging#see-which-sessions-claude-can-reach)에 메시지를 보낼 수 있게 합니다.547이 사용 환경을 통해 Claude는 데스크톱 앱이 자체적으로 실행하는 세션만 봅니다: Code 탭의 로컬, [SSH](#ssh-sessions), [WSL](/docs/ko/desktop-wsl) 세션. Claude는 클라우드 세션이나 터미널 CLI 또는 VS Code 확장에서 시작한 세션을 같은 프로젝트의 worktrees에 있더라도 보지 못합니다. 따라서 9개의 터미널 worktrees와 2개의 데스크톱 세션이 열려 있으면 그 중 한 데스크톱 세션에서 답변하는 Claude는 나머지 하나의 데스크톱 세션만 보고합니다. Claude는 요청하는 세션을 나열하지 않습니다. 기본적으로 가장 최근에 활성화된 20개 세션을 보며, 요청하지 않는 한 아카이브된 세션은 건너뜁니다. [교차 세션 메시징](/docs/ko/cross-session-messaging)은 이와 별도로 Claude가 터미널 세션을 포함한 [다른 Claude Code 세션](/docs/ko/cross-session-messaging#see-which-sessions-claude-can-reach)에 메시지를 보낼 수 있게 합니다.

457 548

470 클라우드에서 장기 실행 작업 실행하기561 클라우드에서 장기 실행 작업 실행하기

471</h3>562</h3>

472 563

473대규모 리팩토링, 테스트 스위트, 마이그레이션 또는 기타 장기 실행 작업의 경우 세션을 시작할 때 **Local** 대신 **Cloud**를 선택합니다. 클라우드 세션은 기본적으로 Anthropic 관리 인프라에서 실행되며 앱을 닫거나 컴퓨터를 종료해도 계속됩니다. 언제든지 돌아와서 진행 상황을 보거나 Claude를 다른 방향으로 조종할 수 있습니다. [claude.ai/code](https://claude.ai/code)에서 또는 [Claude 모바일 앱](/docs/ko/mobile)에서 클라우드 세션을 모니터링할 수도 있습니다.564대규모 리팩토링, 테스트 스위트, 마이그레이션 또는 기타 장기 실행 작업의 경우 세션을 시작할 때 [환경 선택기](#start-a-session)의 **Cloud** 아래에서 환경을 선택합니다. 클라우드 세션은 기본적으로 Anthropic 관리 인프라에서 실행되며 앱을 닫거나 컴퓨터를 종료해도 계속됩니다. 언제든지 돌아와서 진행 상황을 보거나 Claude를 다른 방향으로 조종할 수 있습니다. [claude.ai/code](https://claude.ai/code)에서 또는 [Claude 모바일 앱](/docs/ko/mobile)에서 클라우드 세션을 모니터링할 수도 있습니다.

565

566클라우드 세션은 또한 여러 저장소를 지원합니다. 저장소를 선택하는 위치는 다음과 같습니다:

474 567

475클라우드 세션은 또한 여러 저장소를 지원합니다. 클라우드 환경을 선택한 후 선택된 저장소 옆의 **+** 버튼을 클릭하여 세션에 추가 저장소를 추가합니다. 각 저장소는 자신의 브랜치 선택기를 가집니다. 이는 공유 라이브러리와 그 소비자를 업데이트하는 것과 같이 여러 코드베이스에 걸친 작업에 유용합니다.568* **현재 레이아웃**: 클라우드 환경을 선택하면 프롬프트 상자 아래 행에서 선택합니다.

569* **[이전 레이아웃](#check-which-layout-you-have)**: 프롬프트 상자 위에서 선택합니다. 다른 저장소를 추가하려면 선택된 저장소 옆의 \*\*+\*\*를 클릭합니다.

476 570

477클라우드 세션이 작동하는 방식에 대한 자세한 내용은 [클라우드에서 Claude Code 사용하기](/docs/ko/claude-code-on-the-web)를 참조하세요. 한 가지 작업이 많은 클라우드 세션이 필요할 때 사이드바에서 **Projects**를 선택하여 [프로젝트](/docs/ko/claude-projects)를 만들고, Claude가 한 대화에서 세션을 시작하고 추적하도록 합니다.571클라우드 세션이 작동하는 방식에 대한 자세한 내용은 [클라우드에서 Claude Code 사용하기](/docs/ko/claude-code-on-the-web)를 참조하세요. 한 가지 작업이 많은 클라우드 세션이 필요할 때 사이드바에서 **Projects**를 선택하여 [프로젝트](/docs/ko/claude-projects)를 만들고, Claude가 한 대화에서 세션을 시작하고 추적하도록 합니다.

478 572

500* **해당 세션에 대해 켜는 경우**: 세션의 **Remote Control** 스위치를 사용하거나 해당 세션의 프롬프트 상자에 `/remote-control`을 입력합니다.594* **해당 세션에 대해 켜는 경우**: 세션의 **Remote Control** 스위치를 사용하거나 해당 세션의 프롬프트 상자에 `/remote-control`을 입력합니다.

501* **시작할 때 연결되는 경우**: **Settings > Claude Code**에서 **Connect new sessions to Remote Control**이 켜져 있는 동안 새 세션이 자동으로 연결됩니다. 이 설정을 한 번도 변경하지 않았다면 Desktop은 사용자 설정 또는 관리형 설정의 [`remoteControlAtStartup`](/docs/ko/settings-reference#remotecontrolatstartup)을 따르고, 그다음 조직의 기본값을 따릅니다.595* **시작할 때 연결되는 경우**: **Settings > Claude Code**에서 **Connect new sessions to Remote Control**이 켜져 있는 동안 새 세션이 자동으로 연결됩니다. 이 설정을 한 번도 변경하지 않았다면 Desktop은 사용자 설정 또는 관리형 설정의 [`remoteControlAtStartup`](/docs/ko/settings-reference#remotecontrolatstartup)을 따르고, 그다음 조직의 기본값을 따릅니다.

502 596

503세션이 연결되어 있는지 확인하려면 도구 모음에서 세션 제목 앞의 노트북 아이콘을 확인합니다. 세션이 연결되어 있거나 연결 중인 동안 아이콘이 강조 표시됩니다. 아이콘을 클릭하면 세션의 **Remote Control** 스위치가 열립니다.597세션이 연결되어 있는지 확인하려면 [세션 세부 정보 패널](#see-session-details)의 **Environment** 카드에서 **Remote Control** 스위치를 확인합니다.

504 598

505세션이 다른 기기에 표시되지 않도록 하려면 필요한 수준에서 Remote Control을 끕니다:599세션이 다른 기기에 표시되지 않도록 하려면 필요한 수준에서 Remote Control을 끕니다:

506 600

538 외부 도구 연결하기632 외부 도구 연결하기

539</h3>633</h3>

540 634

541로컬 및 [SSH](#ssh-sessions) 세션의 경우 프롬프트 상자 옆의 **+** 버튼을 클릭하고 **Connectors**를 선택하여 Google Calendar, Slack, GitHub, Linear, Notion 등과 같은 통합을 추가합니다. 세션 전이나 중에 커넥터를 추가할 수 있습니다. **+** 버튼은 클라우드 또는 WSL 세션에서 사용할 수 없지만 [routines](/docs/ko/routines)은 routine 생성 시 커넥터를 구성합니다.635커넥터는 그래픽 설정 흐름을 갖춘 [MCP 서버](/docs/ko/mcp)입니다.

636

637Claude 계정을 사용하는 로컬 또는 [SSH](#ssh-sessions) 세션에서 커넥터를 추가하려면 세션 전이나 중에 프롬프트 상자 옆의 \*\*+\*\*를 클릭합니다. **Add connectors**를 선택하여 커넥터 디렉터리를 엽니다. 메뉴에 **Connectors**가 대신 표시되면 이를 선택한 다음 **Browse connectors**를 선택합니다.

638

639<Note>

640 다음 경우는 다른 페이지에서 다룹니다:

542 641

543커넥터를 관리하거나 연결을 해제하려면 데스크톱 앱의 Settings → Connectors로 이동하거나 프롬프트 상자의 Connectors 메뉴에서 **Manage connectors**를 선택합니다.642 * **WSL 세션에서 Connectors가 회색으로 비활성화된 경우**: [터미널 또는 커넥터를 사용할 수 없는 경우](/docs/ko/desktop-wsl#check-for-the-terminal-and-connectors)를 참조하세요

643 * **클라우드 세션**: [커넥터가 Claude Code에 연결되는 방식](/docs/ko/mcp#how-connectors-reach-claude-code)을 참조하세요

644</Note>

544 645

545연결되면 Claude는 캘린더를 읽고, 메시지를 보내고, 문제를 만들고, 도구와 직접 상호작용할 수 있습니다. Claude에게 세션에 구성된 커넥터가 무엇인지 물어볼 수 있습니다.646연결되면 Claude는 캘린더를 읽고, 메시지를 보내고, 이슈를 만들고, 도구와 직접 상호작용할 수 있습니다. Claude에게 세션에 구성된 커넥터가 무엇인지 물어볼 수 있습니다. 커넥터를 관리하거나 연결을 해제하려면 데스크톱 앱의 **Settings > Connectors**로 이동합니다.

546 647

547커넥터는 그래픽 설정 흐름이 있는 [MCP servers](/docs/ko/mcp)입니다. 지원되는 서비스와의 빠른 통합을 위해 사용합니다. Connectors에 나열되지 않은 통합의 경우 [설정 파일](/docs/ko/mcp#installing-mcp-servers)을 통해 MCP 서버를 수동으로 추가합니다. [사용자 정의 커넥터를 만들](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) 수도 있습니다.648Connectors에 나열되지 않은 통합의 경우 [설정 파일](/docs/ko/mcp#installing-mcp-servers)을 통해 MCP 서버를 수동으로 추가합니다. [사용자 정의 커넥터를 만들](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) 수도 있습니다.

548 649

549<h3 id="use-skills">650<h3 id="use-skills">

550 skills 사용하기651 skills 사용하기

564 665

565[Plugins](/docs/ko/plugins/overview)는 Claude Code에 skills, agents, hooks, MCP servers, LSP 구성을 추가하는 재사용 가능한 패키지입니다. 터미널을 사용하지 않고 데스크톱 앱에서 플러그인을 설치할 수 있습니다.666[Plugins](/docs/ko/plugins/overview)는 Claude Code에 skills, agents, hooks, MCP servers, LSP 구성을 추가하는 재사용 가능한 패키지입니다. 터미널을 사용하지 않고 데스크톱 앱에서 플러그인을 설치할 수 있습니다.

566 667

567로컬 및 [SSH](#ssh-sessions) 세션의 경우 프롬프트 상자 옆의 **+** 버튼을 클릭하고 **Plugins**를 선택하여 설치된 플러그인과 해당 skills를 봅니다. 플러그인을 추가하려면 서브메뉴에서 **Add plugin**을 선택하여 플러그인 브라우저를 열면 공식 Anthropic marketplace를 포함한 구성된 [marketplaces](/docs/ko/plugins/overview)의 사용 가능한 플러그인이 표시됩니다. **Manage plugins**를 선택하여 플러그인을 활성화, 비활성화 또는 제거합니다.668로컬 세션 또는 [SSH 세션](#ssh-sessions)에서 프롬프트 상자 옆의 \*\*+\*\*를 클릭하고 **Add plugins**를 선택하여 플러그인 브라우저를 엽니다. 메뉴에 **Plugins**가 대신 표시되면 이를 선택한 다음 **Browse plugins**를 선택하거나, 플러그인을 활성화, 비활성화 또는 제거하려면 **Manage plugins**를 선택합니다.

568 669

569플러그인은 사용자 계정, 특정 프로젝트 또는 로컬 전용으로 범위를 지정할 수 있습니다. 조직이 플러그인을 중앙에서 관리하는 경우 해당 플러그인은 CLI에서와 동일한 방식으로 데스크톱 세션에서 사용 가능합니다. 단, 데스크톱 앱이 [`disableSideloadFlags`](/docs/ko/settings-reference#disablesideloadflags)에서 보류하는 플러그인은 제외됩니다.670플러그인은 사용자 계정, 특정 프로젝트 또는 로컬 전용으로 범위를 지정할 수 있습니다. 조직이 플러그인을 중앙에서 관리하는 경우 해당 플러그인은 CLI에서와 동일한 방식으로 데스크톱 세션에서 사용 가능합니다. 단, 데스크톱 앱이 [`disableSideloadFlags`](/docs/ko/settings-reference#disablesideloadflags)에서 보류하는 플러그인은 제외됩니다.

570 671

634| `cwd` | string | 프로젝트 루트에 상대적인 작업 디렉토리. 기본값은 프로젝트 루트입니다. 프로젝트 루트를 명시적으로 참조하려면 `${workspaceFolder}`를 사용합니다 |735| `cwd` | string | 프로젝트 루트에 상대적인 작업 디렉토리. 기본값은 프로젝트 루트입니다. 프로젝트 루트를 명시적으로 참조하려면 `${workspaceFolder}`를 사용합니다 |

635| `env` | object | `{ "NODE_ENV": "development" }`와 같은 키-값 쌍으로 추가 환경 변수. 이 파일이 저장소에 커밋되므로 여기에 비밀을 넣지 마세요. 비밀을 개발 서버에 전달하려면 [로컬 환경 편집기](#local-sessions)에서 설정합니다. |736| `env` | object | `{ "NODE_ENV": "development" }`와 같은 키-값 쌍으로 된 추가 환경 변수. 이 파일은 저장소에 커밋되므로 여기에 비밀 정보를 넣지 마세요. 비밀 정보는 [개발 서버의 환경 변수 설정](#set-environment-variables-for-dev-servers)을 참조하세요. |

795* **SSH**: SSH를 통해 연결하는 원격 머신(예: 자신의 서버, 클라우드 VM 또는 개발 컨테이너)에서 실행됩니다. 실행 중인 작업은 [Desktop 연결이 끊긴 동안에도 계속 진행](#keep-a-task-running-while-desktop-is-disconnected)될 수 있지만, Claude 계정을 사용하는 경우 로그인이 만료되면 중지될 수 있습니다.896* **SSH**: SSH를 통해 연결하는 원격 머신(예: 자신의 서버, 클라우드 VM 또는 개발 컨테이너)에서 실행됩니다. 실행 중인 작업은 [Desktop 연결이 끊긴 동안에도 계속 진행](#keep-a-task-running-while-desktop-is-disconnected)될 수 있지만, Claude 계정을 사용하는 경우 로그인이 만료되면 중지될 수 있습니다.

796* **WSL** (Windows): 머신의 [WSL 2 배포판](/docs/ko/desktop-wsl)에서 실행되며, Linux 도구 모음 및 기본 경로를 사용합니다897* **WSL** (Windows): 머신의 [WSL 2 배포판](/docs/ko/desktop-wsl)에서 실행되며, Linux 도구 모음 및 기본 경로를 사용합니다

797 898

899<h3 id="create-a-saved-environment">

900 저장된 환경 만들기

901</h3>

902

903저장된 환경은 Claude가 실행되는 위치를 기록하는 [환경 선택기](#start-a-session)의 항목으로, 이후 세션을 그곳에서 시작할 수 있게 해 줍니다. 로컬 또는 SSH 환경에는 Claude가 작업하는 폴더도 함께 저장됩니다. 저장된 로컬 및 SSH 환경을 사용하려면 [Claude Desktop v2.37337.0 이상이 필요합니다](#check-which-layout-you-have).

904

905<Steps>

906 <Step title="New environment 대화 상자 열기">

907 프롬프트 상자 아래의 환경 선택기를 열고 메뉴 하단에서 **New environment**를 선택합니다.

908 </Step>

909

910 <Step title="Claude가 실행될 위치 선택">

911 **Local**, **SSH** 또는 [**Cloud**](#cloud-sessions) 탭을 선택하고 해당 탭의 양식을 작성합니다. **SSH** 탭에서는 [연결](#ssh-sessions)과 원격 머신의 폴더를 선택합니다.

912 </Step>

913

914 <Step title="환경 저장">

915 **Create environment**를 선택하거나, **Cloud** 탭에서는 **Add environment**를 선택합니다.

916 </Step>

917</Steps>

918

919<h4 id="environments-that-desktop-creates-for-you">

920 Desktop이 자동으로 만드는 환경

921</h4>

922

923직접 만들지 않은 로컬 또는 SSH 환경이 환경 선택기에 표시된다면 Desktop이 자동으로 만든 것입니다. [현재 레이아웃](#check-which-layout-you-have)에서 Code 탭을 처음 열면 Desktop은 최대 8개의 환경을 만듭니다. 이 환경은 지난 한 달 동안 가장 많이 사용한 로컬 및 SSH 폴더를 기반으로 합니다. 이 환경은 [편집하거나 삭제](#use-edit-or-remove-a-saved-environment)할 수 있습니다.

924

925<h4 id="use-edit-or-remove-a-saved-environment">

926 저장된 환경 사용, 편집 또는 제거

927</h4>

928

929[환경 선택기](#start-a-session)에서 해당 환경의 항목을 찾습니다.

930

931* **세션 시작**: 항목을 선택합니다.

932* **편집 또는 삭제**: 항목 위에 마우스를 올리고 톱니바퀴 아이콘을 클릭합니다. 로컬 또는 SSH 환경을 삭제하려면 **Edit environment**에서 **Delete environment**를 클릭합니다.

933* **클라우드 환경 보관**: [환경 보관](/docs/ko/cloud-environments#archive-an-environment)을 참조하십시오.

934

798<h3 id="local-sessions">935<h3 id="local-sessions">

799 로컬 세션936 로컬 세션

800</h3>937</h3>

801 938

802데스크톱 앱이 항상 전체 셸 환경을 상속하지는 않습니다. macOS에서 Dock 또는 Finder에서 앱을 실행하면 `~/.zshrc` 또는 `~/.bashrc`와 같은 셸 프로필을 읽어 Claude Code에 `PATH` 및 고정된 Claude Code 변수 집합을 제공하지만, 거기에서 내보낸 다른 변수는 제공하지 않습니다. Windows에서 앱은 사용자 및 시스템 환경 변수를 상속하지만 PowerShell 프로필을 읽지 않습니다.939데스크톱 앱이 항상 전체 셸 환경을 상속하지는 않습니다. macOS에서 Dock 또는 Finder에서 앱을 실행하면 `~/.zshrc` 또는 `~/.bashrc`와 같은 셸 프로필을 읽어 Claude Code에 `PATH` 및 고정된 Claude Code 변수 집합을 제공하지만, 거기에서 내보낸 다른 변수는 제공하지 않습니다. Windows에서 앱은 사용자 및 시스템 환경 변수를 상속하지만 PowerShell 프로필을 읽지 않습니다.

803 940

804로컬 세션 및 개발 서버에 대한 환경 변수를 설정하려면 프롬프트 상자의 환경 드롭다운을 열고 **Local** 위에 마우스를 올린 다음 기어 아이콘을 클릭하여 로컬 환경 편집기를 엽니다. 여기에 저장한 변수는 머신에 암호화되어 저장되며 시작하는 모든 로컬 세션 및 미리보기 서버에 적용됩니다. `~/.claude/settings.json` 파일의 `env` 키에 변수를 추가할 수도 있습니다. 단, 이는 Claude 세션에만 도달하고 개발 서버에는 도달하지 않습니다. 지원되는 변수의 전체 목록은 [환경 변수](/docs/ko/env-vars)를 참조하세요.941<h4 id="set-environment-variables-for-local-sessions">

942 로컬 세션의 환경 변수 설정

943</h4>

944

945저장된 로컬 환경에 변수를 추가하고 그 환경에서 세션을 시작합니다. Desktop은 `API_TIMEOUT_MS` 같은 [일부 변수를 직접 설정](#environment-variables-desktop-sets-itself)하며, 이러한 변수의 경우 세션은 사용자가 설정한 값 대신 Desktop의 값을 받습니다.

946

947<Note>

948 환경 선택기가 프롬프트 상자 위에 있다면 저장된 로컬 환경이 없는 [이전 레이아웃](#check-which-layout-you-have)을 사용하고 있는 것입니다. 대신 [로컬 환경 편집기](#use-the-local-environment-editor)를 사용하십시오.

949</Note>

950

951<Steps>

952 <Step title="환경 양식 열기">

953 [**New environment**](#create-a-saved-environment) 또는 [**Edit environment**](#use-edit-or-remove-a-saved-environment)를 엽니다.

954 </Step>

955

956 <Step title="변수 입력">

957 **Environment variables**를 선택하고 한 줄에 하나씩 `KEY=value`를 입력한 다음 **Done**을 선택합니다.

958 </Step>

959

960 <Step title="환경 저장">

961 **Create environment** 또는 **Save**를 선택합니다.

962 </Step>

963</Steps>

964

965해당 환경에서 시작한 세션만 이 변수를 받습니다.

966

967모든 로컬 세션에 변수를 설정하려면 `~/.claude/settings.json` 파일의 [`env` 키](/docs/ko/env-vars#set-variables-in-settings-files)에 추가합니다. Desktop이 세션을 시작하는 환경에 해당 변수가 이미 있으면 Claude Code는 [그 값을 무시](/docs/ko/settings-reference#how-env-values-interact-with-your-shell)합니다. 지원되는 전체 변수 목록은 [환경 변수](/docs/ko/env-vars)를 참조하십시오.

968

969<h4 id="set-environment-variables-for-dev-servers">

970 개발 서버의 환경 변수 설정

971</h4>

972

973비밀 값을 [`launch.json`](#configure-preview-servers)에 커밋하지 않고 개발 서버에 제공하려면 다음 위치 중 하나에 설정한 다음 Desktop을 다시 시작합니다.

974

975* **macOS 및 Linux**: 셸 프로필에서 export합니다

976* **Windows**: 사용자 또는 시스템 환경 변수에 추가합니다

977* **모든 플랫폼**: 열 수 있는 경우 [로컬 환경 편집기](#use-the-local-environment-editor)에 저장합니다

978

979개발 서버는 [저장된 환경](#create-a-saved-environment)이나 `~/.claude/settings.json`에 추가한 변수를 받지 않습니다.

980

981<h4 id="use-the-local-environment-editor">

982 로컬 환경 편집기 사용

983</h4>

984

985로컬 환경 편집기를 열려면 저장된 환경의 항목이 아니라 사용자 컴퓨터 항목의 톱니바퀴 아이콘을 클릭합니다.

986

987* **프롬프트 상자 아래의 선택기**: **Local** 아래 첫 번째 항목인 사용자 컴퓨터 항목 위에 마우스를 올립니다. 톱니바퀴 아이콘이 나타나면 클릭합니다. 나타나지 않으면 편집기를 사용할 수 없으므로 [로컬 세션](#set-environment-variables-for-local-sessions) 또는 [개발 서버](#set-environment-variables-for-dev-servers)의 변수를 다른 방법으로 설정합니다.

988* **프롬프트 상자 위의 선택기**: **Local** 위에 마우스를 올리고 톱니바퀴 아이콘을 클릭합니다

989

990한 줄에 하나씩 `KEY=value`를 입력하고 **Save changes**를 선택합니다. 여기에 저장한 변수는 사용자의 컴퓨터에 암호화되어 저장됩니다. 로컬 세션은 이 변수를 받지만, `API_TIMEOUT_MS`처럼 [Desktop이 직접 설정하는](#environment-variables-desktop-sets-itself) 변수는 예외입니다. 개발 서버에 변수를 제공하려면 Desktop을 다시 시작합니다.

991

992<h4 id="environment-variables-desktop-sets-itself">

993 Desktop이 직접 설정하는 환경 변수

994</h4>

995

996`API_TIMEOUT_MS` 또는 `ANTHROPIC_BASE_URL`을 설정했는데 로컬 세션에서 아무것도 바뀌지 않았다면, Desktop이 이 [변수](/docs/ko/env-vars#variables)를 비롯한 여러 변수를 직접 설정하기 때문입니다. 셸 프로필, Windows 사용자 또는 시스템 변수, 로컬 환경 편집기, 저장된 환경 중 어디에서 설정하든 로컬 세션은 Desktop의 값을 받습니다. 로컬 세션에서 Claude Code는 설정 파일의 [값을 무시](/docs/ko/settings-reference#how-env-values-interact-with-your-shell)하므로, 설정 파일로 옮겨도 효과가 없습니다.

997

998* `API_TIMEOUT_MS`: 로컬 세션은 15분에 해당하는 `900000`을 받습니다. 더 긴 타임아웃이 필요하면 [Claude Code CLI를 설치](/docs/ko/quickstart)하여 Desktop 대신 사용하십시오. [셸에서 변수를 설정](/docs/ko/env-vars#set-variables-in-your-shell)하고 터미널에서 `claude`를 실행합니다.

999* `ANTHROPIC_BASE_URL`: Claude 계정으로 로그인한 경우 로컬 세션은 Anthropic의 API 호스트를 받습니다. 게이트웨이를 사용하려면 대신 Desktop의 [서드파티 추론 구성](/docs/ko/llm-gateway-connect#desktop-app)을 설정하십시오.

1000

1001<h4 id="turn-off-extended-thinking">

1002 확장 사고 끄기

1003</h4>

805 1004

806[확장 사고](/docs/ko/model-config#extended-thinking)는 기본적으로 활성화되어 있으며, 복잡한 추론 작업의 성능을 향상시키지만 추가 토큰을 사용합니다. Anthropic API에서 사고를 끄려면 로컬 환경 편집기에서 `MAX_THINKING_TOKENS`을 `0`으로 설정합니다. 이는 Opus 5.5, Sonnet 5.5, Haiku 5.5 또는 Fable 모델에는 영향을 주지 않으며, 이들은 항상 확장 사고를 사용합니다. Anthropic API에서 사고를 끈 상태에서 Claude Code는 [해당 조합을 허용하지 않는](/docs/ko/errors#effort-isnt-available-with-thinking-turned-off) Opus 5와 같은 모델에 더 높은 수준 대신 노력 `high`를 보냅니다.1005[확장 사고](/docs/ko/model-config#extended-thinking)는 기본적으로 활성화되어 있으며, 복잡한 추론 작업의 성능을 향상시키지만 추가 토큰을 사용합니다. 끄려면 [저장된 로컬 환경](#set-environment-variables-for-local-sessions) 또는 [로컬 환경 편집기](#use-the-local-environment-editor)에서 `MAX_THINKING_TOKENS`를 `0`으로 설정합니다. 그러면 Anthropic API에서 사고가 꺼지지만, 항상 확장 사고를 사용하는 Opus 5.5, Sonnet 5.5, Haiku 5.5 및 Fable 모델은 예외입니다.

1006

1007Opus 5에서는 세션을 시작하기 전에 effort를 `high` 이하로 선택해야 합니다. [현재 레이아웃](#check-which-layout-you-have)에서 모델 선택기를 열고 **Effort** 아래에서 수준을 선택합니다. 더 높은 수준으로 세션을 시작했다면 `high` 이하로 새 세션을 시작하십시오.

1008

1009<h4 id="fixed-thinking-budgets">

1010 고정 사고 예산

1011</h4>

807 1012

808[적응형 추론](/docs/ko/model-config#adjust-effort-level)이 있는 모델에서는 적응형 추론이 사고 깊이를 제어하기 때문에 Claude Code가 양수 `MAX_THINKING_TOKENS` 값의 숫자 자체를 무시합니다. Opus 4.6 및 Sonnet 4.6에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 `1`로 설정하여 고정 사고 예산을 사용합니다. Fable 모델, Sonnet 5 이상, Haiku 5.5, Opus 4.7 이상은 항상 적응형 추론을 사용하며 고정 예산 모드가 없습니다.1013[적응형 추론](/docs/ko/model-config#adjust-effort-level)이 있는 모델에서는 적응형 추론이 사고 깊이를 제어하기 때문에 Claude Code가 양수 `MAX_THINKING_TOKENS` 값의 숫자 자체를 무시합니다. Opus 4.6 및 Sonnet 4.6에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 `1`로 설정하여 고정 사고 예산을 사용합니다. Fable 모델, Sonnet 5 이상, Haiku 5.5, Opus 4.7 이상은 항상 적응형 추론을 사용하며 고정 예산 모드가 없습니다.

809 1014

811 관리되는 디바이스의 로컬 세션1016 관리되는 디바이스의 로컬 세션

812</h4>1017</h4>

813 1018

814관리자는 [`disableDesktopLocalSessions` 관리 설정](#managed-settings)으로 로컬 세션을 비활성화할 수 있습니다. 비활성화된 경우 **Local**은 환경 드롭다운에 남아 있지만 회색으로 표시되고 선택할 수 없으며, 조직이 이를 비활성화했다는 내용의 도구 설명이 표시됩니다. Windows에서 [WSL](/docs/ko/desktop-wsl) 항목(관리되는 디바이스에서의 가용성은 [별도로 관리됨](/docs/ko/admin-setup#wsl-sessions-in-claude-code-desktop))도 같은 방식으로 회색으로 표시됩니다. 새 세션은 구성된 경우 첫 번째 SSH 연결로 기본 설정되며, 기존 세션을 계속하려고 하면 Desktop은 이 디바이스에서 로컬 세션을 사용할 수 없다는 메시지를 표시합니다. [SSH](#ssh-sessions) 또는 [클라우드](#cloud-sessions) 환경을 선택하거나 IT 팀에 문의하세요.1019환경 선택기에서 사용자 컴퓨터 항목이 **Disabled by your organization** 툴팁과 함께 회색으로 표시된다면 관리자가 [로컬 세션을 끈](#managed-settings) 것입니다. Windows에서는 관리 대상 기기에서의 사용 가능 여부가 [별도로 관리되는](/docs/ko/admin-setup#wsl-sessions-in-claude-code-desktop) [WSL](/docs/ko/desktop-wsl) 항목도 같은 방식으로 회색으로 표시됩니다.

1020

1021SSH 연결이 구성되어 있으면 새 세션은 기본적으로 첫 번째 SSH 연결을 사용합니다. 기존 로컬 세션을 계속하려고 하면 Desktop은 이 기기에서 로컬 세션을 사용할 수 없다는 메시지를 표시합니다. [저장된 로컬 환경](#create-a-saved-environment)을 선택하면 다음 오류가 표시됩니다: `Couldn’t switch environments: the Local environment isn’t available anymore.` 대신 [SSH](#ssh-sessions) 또는 [클라우드](#cloud-sessions) 환경을 선택하거나 IT 팀에 문의하십시오.

815 1022

816<h3 id="cloud-sessions">1023<h3 id="cloud-sessions">

817 클라우드 세션1024 클라우드 세션

819 1026

820클라우드 세션은 앱을 닫아도 백그라운드에서 계속됩니다. 사용량은 별도의 컴퓨팅 요금 없이 [구독 계획 한도](/docs/ko/costs)에 포함됩니다.1027클라우드 세션은 앱을 닫아도 백그라운드에서 계속됩니다. 사용량은 별도의 컴퓨팅 요금 없이 [구독 계획 한도](/docs/ko/costs)에 포함됩니다.

821 1028

822다양한 네트워크 액세스 수준 및 환경 변수를 가진 사용자 정의 클라우드 환경을 만들 수 있습니다. 이를 관리하려면 프롬프트 상자의 환경 드롭다운을 열고 **Cloud**를 선택합니다:1029클라우드 환경을 추가, 편집 또는 [보관](/docs/ko/cloud-environments#archive-an-environment)하려면 [환경 선택기](#start-a-session)를 엽니다.

823 1030

824* **환경 추가**: **클라우드 환경 추가**를 선택합니다1031* **환경 추가**: 선택기 메뉴 하단에서 **New environment**를 선택한 다음 [**New environment** 대화 상자](#create-a-saved-environment)의 **Cloud** 탭을 선택합니다

825* **자신의 환경 중 하나를 편집하거나 보관**: 위에 마우스를 올린 다음 기어 아이콘을 클릭합니다1032* **자신의 환경 중 하나를 편집하거나 보관**: 위에 마우스를 올린 다음 기어 아이콘을 클릭합니다

826 1033

827네트워크 액세스 및 환경 변수 구성에 대한 자세한 내용은 [클라우드 환경 구성](/docs/ko/cloud-environments)을 참조하세요.1034네트워크 액세스 및 환경 변수 구성에 대한 자세한 내용은 [클라우드 환경 구성](/docs/ko/cloud-environments)을 참조하세요.

836 Desktop을 [타사 제공업체](/docs/ko/third-party-integrations)와 함께 사용하는 경우 SSH 세션에는 별도의 설정이 필요합니다. [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)를 참조하세요.1043 Desktop을 [타사 제공업체](/docs/ko/third-party-integrations)와 함께 사용하는 경우 SSH 세션에는 별도의 설정이 필요합니다. [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)를 참조하세요.

837</Note>1044</Note>

838 1045

839SSH 연결을 추가하려면 세션을 시작하기 전에 프롬프트 상자의 환경 드롭다운을 열고 \*\*SSH > SSH 연결 추가…\*\*를 선택한 다음 연결 세부 정보를 입력합니다:1046[**New environment** 대화 상자](#create-a-saved-environment)에서 SSH 연결을 추가한 다음 해당 연결에서 세션을 시작합니다. 새 세션의 프롬프트 상자 아래에 환경 선택기가 없다면 이전 레이아웃을 사용하고 있는 것입니다. [사용 중인 레이아웃 확인](#check-which-layout-you-have)을 참조하십시오.

1047

1048<Steps>

1049 <Step title="New environment 대화 상자 열기">

1050 세션을 시작하기 전에 프롬프트 상자 아래의 환경 선택기를 열고 메뉴 하단에서 **New environment**를 선택합니다.

1051 </Step>

1052

1053 <Step title="연결 추가">

1054 **New environment** 대화 상자의 **SSH** 탭에서 **Host** 목록을 열고 \*\*Add SSH connection…\*\*을 선택한 다음 연결 세부 정보를 입력합니다.

840 1055

841* **Name**: 이 연결의 친화적인 레이블1056 * **Name**: 이 연결을 식별하기 위한 이름입니다.

842* **SSH host**: `user@hostname` 또는 `~/.ssh/config`에 정의된 호스트1057 * **SSH host**: `user@hostname` 또는 `~/.ssh/config`에 정의된 호스트입니다.

843* **SSH port**: 비워두면 기본값은 22이거나 SSH 구성의 포트를 사용합니다1058 * **SSH port**: 비워 두면 기본값 22를 사용하거나 SSH 구성의 포트를 사용합니다.

844* **SSH key (optional)**: `~/.ssh/id_ed25519`와 같은 개인 키의 경로. SSH 구성 또는 SSH 에이전트를 사용하려면 비워둡니다.1059 * **SSH key (optional)**: `~/.ssh/id_ed25519` 같은 개인 키 경로입니다. SSH 구성이나 SSH 에이전트를 사용하려면 비워 둡니다.

845* **Worktree folder**: 새 세션이 워크트리를 생성하는 원격 머신의 폴더(예: `~/worktrees`). [원격 머신의 기본값](#choose-where-ssh-session-worktrees-go)을 사용하려면 비워둡니다.1060 * **Worktree folder**: 새 세션이 worktree를 만드는 원격 머신의 폴더입니다(예: `~/worktrees`). [원격 머신의 기본값](#choose-where-ssh-session-worktrees-go)을 사용하려면 비워 둡니다.

846 1061

847추가되면 연결이 환경 드롭다운의 **SSH** 아래에 나타납니다. 이를 선택하여 해당 머신에서 세션을 시작합니다. Claude는 원격 머신에서 파일 및 도구에 액세스하여 실행됩니다.1062 그런 다음 **Add SSH connection**을 선택합니다.

1063 </Step>

1064

1065 <Step title="연결에서 세션 시작">

1066 원격 머신의 폴더를 선택하고 **Create environment**를 클릭합니다. 머신과 폴더는 이후 세션을 위해 [저장된 환경](#create-a-saved-environment)으로 함께 유지됩니다. Desktop이 새 세션에 이 환경을 선택하므로, 작업을 입력하고 **Enter**를 누르십시오.

1067 </Step>

1068</Steps>

848 1069

849원격 머신은 Linux, macOS 또는 [Windows](#windows-remote-machines)를 실행할 수 있습니다. 데스크톱은 처음 연결할 때 원격 머신에 Claude Code를 자동으로 설치합니다. 연결되면 SSH 세션은 권한 모드, 커넥터, 플러그인 및 MCP 서버를 지원합니다.1070원격 머신은 Linux, macOS 또는 [Windows](#windows-remote-machines)를 실행할 수 있습니다. 데스크톱은 처음 연결할 때 원격 머신에 Claude Code를 자동으로 설치합니다. 연결되면 SSH 세션은 권한 모드, 커넥터, 플러그인 및 MCP 서버를 지원합니다.

850 1071

1175 1396

1176Desktop 연결이 끊긴 동안에는 파일 편집 및 일부 도구가 실패할 수 있습니다. 작업에 이들이 필요하다면 Desktop을 연결된 상태로 유지하세요:1397Desktop 연결이 끊긴 동안에는 파일 편집 및 일부 도구가 실패할 수 있습니다. 작업에 이들이 필요하다면 Desktop을 연결된 상태로 유지하세요:

1177 1398

1178* **워크트리**: [워크트리](#work-in-parallel-with-sessions)를 사용하는 세션에서는 Claude가 파일을 편집하기 전에 Desktop이 각 편집을 확인합니다. Desktop 연결이 끊긴 동안에는 각 편집이 약 30초간 대기한 후 실패합니다. 셸 명령은 계속 실행됩니다. Linux 또는 macOS 원격 머신에서는 [편집이 계속 작동할 수 있습니다](#worktree-edits-while-disconnected). 확실하지 않다면 워크트리 없이 세션을 시작하세요.1399* **Worktree**: [worktree](#run-a-session-in-its-own-worktree)를 사용하는 세션에서 Desktop은 Claude가 각 파일을 편집하기 전에 이를 확인합니다. Desktop 연결이 끊긴 동안 각 편집은 약 30초간 대기한 후 실패합니다. 셸 명령은 계속 실행됩니다. Linux 또는 macOS 원격 머신에서는 [편집이 계속 작동할 수 있습니다](#worktree-edits-while-disconnected). 확실하지 않다면 worktree 없이 세션을 시작하십시오.

1179* **폴더 제한**: 조직에서 세션이 사용할 수 있는 폴더를 제한하는 경우 Desktop은 워크트리 여부와 관계없이 각 파일 읽기, 검색, 편집을 확인합니다. Desktop 연결이 끊긴 동안에는 각 작업이 최대 10분간 대기한 후 실패합니다.1400* **폴더 제한**: 조직에서 세션이 사용할 수 있는 폴더를 제한하는 경우 Desktop은 워크트리 여부와 관계없이 각 파일 읽기, 검색, 편집을 확인합니다. Desktop 연결이 끊긴 동안에는 각 작업이 최대 10분간 대기한 후 실패합니다.

1180* **커넥터**: [커넥터](#connect-external-tools) 및 Desktop이 제공하는 기타 도구는 Desktop을 통해 실행되므로, 연결이 끊긴 동안에는 각 호출이 약 30초 후에 실패합니다1401* **커넥터**: [커넥터](#connect-external-tools) 및 Desktop이 제공하는 기타 도구는 Desktop을 통해 실행되므로, 연결이 끊긴 동안에는 각 호출이 약 30초 후에 실패합니다

1181* **워크플로**: Desktop은 각 새 [워크플로](/docs/ko/workflows)가 시작되기 전에 이를 확인하므로, Desktop 연결이 끊긴 동안에는 새 워크플로가 최대 10분간 대기한 후 실패합니다1402* **워크플로**: Desktop은 각 새 [워크플로](/docs/ko/workflows)가 시작되기 전에 이를 확인하므로, Desktop 연결이 끊긴 동안에는 새 워크플로가 최대 10분간 대기한 후 실패합니다

1264 SSH 세션 워크트리 위치 선택1485 SSH 세션 워크트리 위치 선택

1265</h4>1486</h4>

1266 1487

1267조직에서 세션이 사용할 수 있는 폴더를 제한하지 않는 한, 새 SSH 세션은 다음 중 처음으로 설정된 위치에 [워크트리](#work-in-parallel-with-sessions)를 생성합니다:1488조직에서 세션이 사용할 수 있는 폴더를 제한하지 않는 한, 새 SSH 세션은 다음 위치 중 설정된 첫 번째 위치에 [worktree](#run-a-session-in-its-own-worktree)를 만듭니다.

1268 1489

12691. SSH 연결의 **Worktree folder**14901. SSH 연결의 **Worktree folder**

12702. 원격 머신의 `~/.claude/settings.json`에 있는 [`worktree.location`](/docs/ko/settings-reference#worktree-location)14912. 원격 머신의 `~/.claude/settings.json`에 있는 [`worktree.location`](/docs/ko/settings-reference#worktree-location)

1272 1493

1273각 프로젝트는 설정한 폴더 안에 자체 하위 폴더를 가지므로, `~/worktrees`를 사용하면 워크트리 경로는 `~/worktrees/<project>-<id>/<worktree-name>`이 됩니다. 설정한 폴더가 프로젝트 내부에 있으면 Desktop은 해당 프로젝트에 대해 이를 무시하고 기본값을 사용합니다. [Windows 원격 머신](#windows-remote-machines)에서는 Desktop이 항상 기본값을 사용합니다.1494각 프로젝트는 설정한 폴더 안에 자체 하위 폴더를 가지므로, `~/worktrees`를 사용하면 워크트리 경로는 `~/worktrees/<project>-<id>/<worktree-name>`이 됩니다. 설정한 폴더가 프로젝트 내부에 있으면 Desktop은 해당 프로젝트에 대해 이를 무시하고 기본값을 사용합니다. [Windows 원격 머신](#windows-remote-machines)에서는 Desktop이 항상 기본값을 사용합니다.

1274 1495

1275이전에 추가한 연결이나 조직에서 관리하는 연결에 **Worktree folder**를 설정하려면 환경 드롭다운에서 해당 연결 위에 마우스를 올린 다음 기어 아이콘을 클릭합니다.1496<a id="set-the-worktree-folder-on-an-existing-connection" />

1276 1497

1277이 필드를 사용하려면 Claude Desktop v1.44121.0 이상이 필요합니다. 조직에서 세션이 사용할 수 있는 폴더를 제한하는 경우 Desktop은 이 필드를 숨기고 워크트리를 프로젝트 내부에 유지합니다.1498<h5 id="set-the-worktree-folder-on-an-existing-connection">

1499 기존 연결에서 worktree 폴더 설정

1500</h5>

1501

1502이전에 추가한 연결이나 조직에서 관리하는 연결의 설정에서 **Worktree folder**를 설정합니다. 이 필드에는 Claude Desktop v1.44121.0 이상이 필요합니다. 조직에서 세션이 사용할 수 있는 폴더를 제한하는 경우 Desktop은 이 필드를 숨기고 worktree를 프로젝트 내부에 둡니다.

1503

1504<Steps>

1505 <Step title="연결 찾기">

1506 [환경 선택기](#start-a-session)를 열고 **SSH** 아래에서 연결을 찾습니다.

1507 </Step>

1508

1509 <Step title="연결 설정 열기">

1510 연결 위에 마우스를 올리고 톱니바퀴 아이콘을 클릭합니다. 열린 대화 상자에서 **Host** 옆에 \*\*Edit connection…\*\*이 표시되면 \*\*Edit connection…\*\*을 선택합니다.

1511 </Step>

1512

1513 <Step title="폴더 설정">

1514 **Worktree folder**에 원격 머신의 폴더(예: `~/worktrees`)를 입력하고 **Save changes**를 선택합니다.

1515 </Step>

1516</Steps>

1278 1517

1279<h4 id="files-and-processes-on-the-remote-machine">1518<h4 id="files-and-processes-on-the-remote-machine">

1280 원격 머신의 파일 및 프로세스1519 원격 머신의 파일 및 프로세스

1321 한 세션의 프로세스 종료1560 한 세션의 프로세스 종료

1322</h5>1561</h5>

1323 1562

1324한 세션의 Claude Code 프로세스를 종료하려면 Desktop이 원격 머신에 연결되어 있는 동안 Desktop에서 [세션을 보관](#work-in-parallel-with-sessions)합니다. 이 프로세스는 작업이 완료된 후에도, Desktop을 종료한 후에도 계속 실행됩니다.1563한 세션의 Claude Code 프로세스를 종료하려면, Desktop이 원격 머신에 연결되어 있는 동안 Desktop에서 [세션을 보관](#archive-a-session)합니다. 프로세스는 작업이 완료된 후에도, Desktop을 종료한 후에도 계속 실행됩니다.

1325 1564

1326워크트리가 있는 세션을 보관하기 전에 [세션으로 병렬 작업](#work-in-parallel-with-sessions)을 참조하세요.1565worktree에 커밋되지 않은 변경 사항이 있는 세션을 보관하기 전에 [세션 보관 시 커밋되지 않은 변경 사항 유지](#keep-uncommitted-changes-when-a-session-is-archived)를 참조하십시오.

1327 1566

1328<h5 id="see-which-user-the-processes-run-as">1567<h5 id="see-which-user-the-processes-run-as">

1329 프로세스가 실행되는 사용자 확인1568 프로세스가 실행되는 사용자 확인

1474 팀을 위해 SSH 연결을 미리 구성합니다1713 팀을 위해 SSH 연결을 미리 구성합니다

1475</h4>1714</h4>

1476 1715

1477관리자는 [관리형 설정](/docs/ko/managed-settings)에서 `sshConfigs`를 설정하여 팀 멤버에게 SSH 연결을 배포할 수 있습니다. 이러한 방식으로 정의된 연결은 각 사용자의 환경 드롭다운에 자동으로 나타나며 관리되는 것으로 표시됩니다. 사용자는 이를 선택하고 [자체 **Worktree folder**를 설정](#choose-where-ssh-session-worktrees-go)할 수 있지만, 앱에서 그 밖의 항목을 편집하거나 삭제할 수는 없습니다.1716관리자는 [관리형 설정](/docs/ko/managed-settings)에서 `sshConfigs`를 설정하여 팀원에게 SSH 연결을 배포할 수 있습니다.

1717

1718* **사용자에게 표시되는 내용**: 이 방식으로 정의된 연결은 각 사용자의 환경 선택기에 자동으로 나타납니다.

1719* **사용자가 변경할 수 있는 내용**: 사용자는 관리형 연결을 선택하고 해당 연결에 대해 [자신의 **Worktree folder**를 설정](#set-the-worktree-folder-on-an-existing-connection)할 수 있습니다. 앱에서 다른 필드를 편집하거나 연결을 삭제할 수는 없습니다.

1478 1720

1479다음 예제는 단일 연결을 미리 구성합니다:1721다음 예제는 단일 연결을 미리 구성합니다:

1480 1722

1563설정이 적용되는지 확인하려면 개발자의 컴퓨터를 확인합니다:1805설정이 적용되는지 확인하려면 개발자의 컴퓨터를 확인합니다:

1564 1806

1565<Steps>1807<Steps>

1566 <Step title="환경 드롭다운 확인">1808 <Step title="환경 선택기 확인">

1567 Desktop을 종료했다가 다시 연 다음 프롬프트 상자의 환경 드롭다운을 엽니다. **Local**은 회색으로 표시되고 **Shared Dev VM**이 **SSH** 아래에 나타납니다. **Local**을 여전히 사용할 수 있다면 Desktop 버전, 파일이 유효한 JSON인지 여부, 컴퓨터가 읽는 관리형 소스를 확인하세요.1809 Desktop을 종료했다가 다시 연 다음 [환경 선택기](#start-a-session)를 엽니다. 다음이 표시되면 설정이 적용된 것입니다.

1810

1811 * 해당 컴퓨터 항목이 회색으로 표시됨

1812 * **SSH** 아래에 **Shared Dev VM**이 표시됨. 목록에 없다면 단일 **SSH** 행이나 그룹 끝의 **More**를 클릭하세요.

1813

1814 컴퓨터 항목을 여전히 사용할 수 있다면 다음 원인을 확인하세요.

1815

1816 * **Desktop 버전**: Desktop이 v1.37937.0보다 이전 버전이라면 업데이트하세요.

1817 * **관리형 설정 파일**: 파일이 유효한 JSON인지 확인하세요.

1818 * **관리형 소스**: 컴퓨터가 키를 담고 있는 [관리형 소스](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)를 읽는지 확인하세요.

1568 </Step>1819 </Step>

1569 1820

1570 <Step title="허용 목록에 없는 호스트 추가">1821 <Step title="허용 목록에 없는 호스트 추가">

1571 `other.example.com`처럼 허용 목록에 없는 호스트명으로 [SSH 연결을 추가](#ssh-sessions)합니다. Desktop은 연결을 저장하지만 연결을 거부하며, 조직의 설정이 해당 연결을 허용하지 않는다는 메시지를 표시합니다.1822 `other.example.com`처럼 허용 목록에 없는 호스트 이름으로 [SSH 연결을 추가](#ssh-sessions)합니다. Desktop은 연결을 저장하지만 연결을 거부하며, 조직의 설정에서 해당 연결을 허용하지 않는다고 알립니다.

1572 </Step>1823 </Step>

1573</Steps>1824</Steps>

1574 1825

1612| `browserExternalPageTools` | Claude가 [Browser 창](#browse-external-sites)에서 외부 페이지를 읽거나 작동하기 위해 도구를 사용하지 못하도록 하려면 `"disabled"`로 설정합니다. 사용자는 여전히 외부 사이트로 직접 이동할 수 있으며, 로컬 개발 서버 미리보기는 영향을 받지 않습니다. |1863| `browserExternalPageTools` | Claude가 [Browser 창](#browse-external-sites)에서 외부 페이지를 읽거나 작동하기 위해 도구를 사용하지 못하도록 하려면 `"disabled"`로 설정합니다. 사용자는 여전히 외부 사이트로 직접 이동할 수 있으며, 로컬 개발 서버 미리보기는 영향을 받지 않습니다. |

1613| `disableMobileSimulatorTools` | Claude의 [iOS Simulator 창](/docs/ko/desktop-ios-simulator#turn-off-simulator-access)에서 장치를 제어하고 캡처하는 도구를 차단하려면 `true`로 설정합니다. 창은 사용자의 자신의 탭에 대해 사용 가능하게 유지됩니다. Claude의 액세스만 제거됩니다. 값은 JSON 부울 `true`여야 합니다. 문자열 `"true"`는 무시됩니다. |1864| `disableMobileSimulatorTools` | Claude의 [iOS Simulator 창](/docs/ko/desktop-ios-simulator#turn-off-simulator-access)에서 장치를 제어하고 캡처하는 도구를 차단하려면 `true`로 설정합니다. 창은 사용자의 자신의 탭에 대해 사용 가능하게 유지됩니다. Claude의 액세스만 제거됩니다. 값은 JSON 부울 `true`여야 합니다. 문자열 `"true"`는 무시됩니다. |

1614| `disableBrowserExternalNavigation` | [Browser 창](#browse-external-sites)에서 외부 브라우징을 완전히 끄려면 `true`로 설정합니다. 사용자와 Claude 모두 외부 사이트로 이동할 수 없으며, localhost 개발 서버 미리보기는 영향을 받지 않습니다. 값은 JSON 부울 `true`여야 합니다. 문자열 `"true"`는 무시됩니다. |1865| `disableBrowserExternalNavigation` | [Browser 창](#browse-external-sites)에서 외부 브라우징을 완전히 끄려면 `true`로 설정합니다. 사용자와 Claude 모두 외부 사이트로 이동할 수 없으며, localhost 개발 서버 미리보기는 영향을 받지 않습니다. 값은 JSON 부울 `true`여야 합니다. 문자열 `"true"`는 무시됩니다. |

1615| `sshConfigs` | 환경 드롭다운에 나타나는 [SSH 연결](#pre-configure-ssh-connections-for-your-team)을 사전 구성합니다. 사용자는 관리형 연결을 삭제할 수 없으며, 자신의 **Worktree folder** 외에는 아무것도 편집할 수 없습니다. |1866| `sshConfigs` | 환경 선택기에 나타나는 [SSH 연결](#pre-configure-ssh-connections-for-your-team)을 사전 구성합니다. 사용자는 관리형 연결을 삭제할 수 없으며, 자신의 **Worktree folder** 외에는 아무것도 편집할 수 없습니다. |

1616| `sshHostAllowlist` | [SSH 세션](#restrict-which-ssh-hosts-users-can-connect-to)을 확인된 호스트명이 이러한 패턴 중 하나와 일치하는 호스트로 제한합니다. 관리형 설정에서만 읽습니다. |1867| `sshHostAllowlist` | [SSH 세션](#restrict-which-ssh-hosts-users-can-connect-to)을 확인된 호스트명이 이러한 패턴 중 하나와 일치하는 호스트로 제한합니다. 관리형 설정에서만 읽습니다. |

1617| `disableDesktopLocalSessions` | [장치에서 실행되는 Code 세션](#local-sessions-on-managed-devices)을 끄려면 `true`로 설정하여 다른 호스트로의 SSH 세션과 클라우드 세션을 사용 가능하게 유지합니다. 값은 JSON 부울 `true`여야 합니다. 관리형 설정에서만 읽습니다. Claude Desktop v1.37937.0 이상이 필요합니다. |1868| `disableDesktopLocalSessions` | [장치에서 실행되는 Code 세션](#local-sessions-on-managed-devices)을 끄려면 `true`로 설정하여 다른 호스트로의 SSH 세션과 클라우드 세션을 사용 가능하게 유지합니다. 값은 JSON 부울 `true`여야 합니다. 관리형 설정에서만 읽습니다. Claude Desktop v1.37937.0 이상이 필요합니다. |

1618| `disableSshSavedPasswords` | Desktop이 SSH 비밀번호 저장을 제안하지 않고 이전에 저장한 비밀번호를 사용하거나 표시하지 않도록 하려면 `true`로 설정합니다. 이 설정을 켜도 저장된 비밀번호는 삭제되지 않습니다. 관리형 설정에서만 읽습니다. Claude Desktop v1.49585.0 이상이 필요합니다. |1869| `disableSshSavedPasswords` | Desktop이 SSH 비밀번호 저장을 제안하지 않고 이전에 저장한 비밀번호를 사용하거나 표시하지 않도록 하려면 `true`로 설정합니다. 이 설정을 켜도 저장된 비밀번호는 삭제되지 않습니다. 관리형 설정에서만 읽습니다. Claude Desktop v1.49585.0 이상이 필요합니다. |

1756 2007

1757| CLI | Desktop 동등물 |2008| CLI | Desktop 동등물 |

1758| - | - |2009| - | - |

1762| `--dangerously-skip-permissions` | 권한 모드 무시. Pro 및 Max 플랜에서는 설정 → Claude Code → "권한 모드 무시 허용"에서 활성화합니다. Team 및 Enterprise 플랜에서는 조직 정책이 제어합니다 |2013| `--dangerously-skip-permissions` | 권한 모드 무시. Pro 및 Max 플랜에서는 설정 → Claude Code → "권한 모드 무시 허용"에서 활성화합니다. Team 및 Enterprise 플랜에서는 조직 정책이 제어합니다 |

1769 2020

1770<h3 id="shared-configuration">2021<h3 id="shared-configuration">

1771 공유 구성2022 공유 구성

1777* `~/.claude.json` 또는 `.mcp.json`에 구성된 \*\*[MCP 서버](/docs/ko/mcp)\*\*는 둘 다에서 작동합니다2028* `~/.claude.json` 또는 `.mcp.json`에 구성된 \*\*[MCP 서버](/docs/ko/mcp)\*\*는 둘 다에서 작동합니다

1778* 설정에 정의된 **[훅](/docs/ko/hooks)** 및 \*\*[스킬](/docs/ko/skills)\*\*은 둘 다에 적용됩니다2029* 설정에 정의된 **[훅](/docs/ko/hooks)** 및 \*\*[스킬](/docs/ko/skills)\*\*은 둘 다에 적용됩니다

1779* `~/.claude.json` 및 `~/.claude/settings.json`의 \*\*[설정](/docs/ko/settings)\*\*은 공유됩니다. `settings.json`의 권한 규칙, 허용된 도구 및 기타 설정은 Desktop 세션에 적용됩니다.2030* `~/.claude.json` 및 `~/.claude/settings.json`의 \*\*[설정](/docs/ko/settings)\*\*은 공유됩니다. `settings.json`의 권한 규칙, 허용된 도구 및 기타 설정은 Desktop 세션에 적용됩니다.

1780* **모델**: 동일한 [모델](/docs/ko/model-config#available-models)을 둘 다에서 사용할 수 있습니다. Desktop에서는 전송 버튼 옆의 드롭다운에서 모델을 선택합니다. 동일한 드롭다운에서 세션 중간에 모델을 변경할 수 있습니다.2031* **모델**: 동일한 [모델](/docs/ko/model-config#available-models)을 둘 다에서 사용할 수 있습니다. Desktop에서는 프롬프트 상자 아래 행의 모델 선택기에서 모델을 선택합니다. 동일한 선택기에서 세션 중간에 모델을 변경할 수 있습니다.

1781 2032

1782<h4 id="mcp-servers-from-the-claude-desktop-chat-app">2033<h4 id="mcp-servers-from-the-claude-desktop-chat-app">

1783 Claude Desktop 채팅 앱의 MCP 서버2034 Claude Desktop 채팅 앱의 MCP 서버

1805| [타사 제공자](/docs/ko/third-party-integrations) | Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry | 기본적으로 Anthropic의 API. 게이트웨이 라우팅의 경우 [데스크톱 앱을 게이트웨이에 연결](/docs/ko/llm-gateway-connect#desktop-app)을 참조하세요. Code 탭을 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 자체 호스팅 LLM 게이트웨이에서 실행하려면 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 참조하세요. |2056| [타사 제공자](/docs/ko/third-party-integrations) | Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry | 기본적으로 Anthropic의 API. 게이트웨이 라우팅의 경우 [데스크톱 앱을 게이트웨이에 연결](/docs/ko/llm-gateway-connect#desktop-app)을 참조하세요. Code 탭을 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 자체 호스팅 LLM 게이트웨이에서 실행하려면 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 참조하세요. |

1833 문제 해결2084 문제 해결

1834</h2>2085</h2>

1835 2086

1836아래 섹션은 데스크톱 앱에 특정한 문제를 다룹니다. `API Error: 500`, `529 Overloaded`, `429`, `Prompt is too long`과 같이 채팅에 나타나는 런타임 API 오류의 경우 [오류 참조](/docs/ko/errors)를 참조하세요. 이러한 오류와 수정 사항은 CLI, 데스크톱, 웹에서 동일합니다.2087아래 섹션은 데스크톱 앱에 특정한 문제를 다룹니다. `API Error: 500`, `529 Overloaded`, `429`, `Prompt is too long`과 같이 채팅에 나타나는 런타임 API 오류의 경우 [오류 참조](/docs/ko/errors)를 참조하세요.

1837 2088

1838<h3 id="check-your-version">2089<h3 id="check-your-version">

1839 버전 확인하기2090 버전 확인하기

1852 2103

1853세션에서 실행되는 Claude Code 버전을 확인하려면 **Code** 탭의 로컬 세션에서 `/status`를 입력하고 **Claude Code** 행을 확인합니다. 이 행에는 `2.1.286`과 같은 버전이 표시됩니다.2104세션에서 실행되는 Claude Code 버전을 확인하려면 **Code** 탭의 로컬 세션에서 `/status`를 입력하고 **Claude Code** 행을 확인합니다. 이 행에는 `2.1.286`과 같은 버전이 표시됩니다.

1854 2105

1855로컬 세션용 최신 버전을 받으려면 macOS에서는 **Claude → Check for Updates**를, Windows에서는 **Help → Check for Updates**를 연 다음 새 세션을 시작합니다.2106로컬 세션용 최신 버전을 받으려면 macOS에서는 \*\*Claude > Check for Updates…\*\*를, Windows에서는 \*\*Help > Check for Updates…\*\*를 연 다음 새 세션을 시작합니다.

1856 2107

1857로컬 세션에서 **Code** 탭은 자체 버전 번호를 가진 별도의 Claude Code 사본을 실행합니다. 데스크톱 앱이 해당 사본을 다운로드하고 업데이트하므로 터미널의 `claude` 명령과 버전이 다를 수 있으며, 한쪽을 업데이트해도 다른 쪽은 업데이트되지 않습니다.2108로컬 세션에서 **Code** 탭은 자체 버전 번호를 가진 별도의 Claude Code 사본을 실행합니다. 데스크톱 앱이 해당 사본을 다운로드하고 업데이트하므로 터미널의 `claude` 명령과 버전이 다를 수 있으며, 한쪽을 업데이트해도 다른 쪽은 업데이트되지 않습니다.

1858 2109

2110<h3 id="check-which-layout-you-have">

2111 사용 중인 레이아웃 확인하기

2112</h3>

2113

2114새 세션의 프롬프트 상자 아래에 [환경 선택기](#start-a-session)가 없으면 이전 레이아웃을 사용 중인 것입니다:

2115

2116* **[v2.37337.0 이전 데스크톱](#check-your-version)**: 업데이트하여 현재 레이아웃을 사용합니다. macOS에서는 \*\*Claude > Check for Updates…\*\*를, Windows에서는 \*\*Help > Check for Updates…\*\*를 선택합니다.

2117* **[타사 제공업체](/docs/ko/third-party-integrations)**: 이전 레이아웃이 유지되므로 별도로 할 일은 없습니다.

2118

2119이전 레이아웃에서는 프롬프트 상자 위에서 환경과 프로젝트 폴더를 선택하고, 그 아래 행에서 권한 모드와 모델을 선택합니다. 이전 레이아웃에는 [세션 세부 정보 패널](#see-session-details)과 [저장된 로컬 및 SSH 환경](#create-a-saved-environment)이 없습니다.

2120

1859<h3 id="403-or-authentication-errors-in-the-code-tab">2121<h3 id="403-or-authentication-errors-in-the-code-tab">

1860 Code 탭의 403 또는 인증 오류2122 Code 탭의 403 또는 인증 오류

1861</h3>2123</h3>

desktop-ios-simulator.md +2 −2

Details

160* Xcode 및 iOS 시뮬레이터가 설치되어 있고 [권장 Xcode 버전](#requirements)을 사용하고 있는지 확인합니다.160* Xcode 및 iOS 시뮬레이터가 설치되어 있고 [권장 Xcode 버전](#requirements)을 사용하고 있는지 확인합니다.

161* 조직이 Claude Code를 관리하면 [시뮬레이터 도구가 정책에 의해 비활성화](#turn-off-simulator-access)될 수 있습니다.161* 조직이 Claude Code를 관리하면 [시뮬레이터 도구가 정책에 의해 비활성화](#turn-off-simulator-access)될 수 있습니다.

162* HIPAA 구성이 활성화된 Enterprise 조직에 속하면 시뮬레이터 창을 사용할 수 없습니다.162* HIPAA 구성이 활성화된 Enterprise 조직에 속하면 시뮬레이터 창을 사용할 수 없습니다.

163* 시뮬레이터 창에는 Claude Desktop v1.24012.0 이상이 필요합니다. **Claude → Check for Updates**를 열고 앱을 다시 시작합니다.163* 시뮬레이터 창에는 Claude Desktop v1.24012.0 이상이 필요합니다. \*\*Claude > Check for Updates…\*\*를 열고 앱을 다시 시작합니다.

164 164

165<h3 id="the-simulator-pane-says-no-simulators-were-found">165<h3 id="the-simulator-pane-says-no-simulators-were-found">

166 시뮬레이터 창에 시뮬레이터를 찾을 수 없다고 표시됨166 시뮬레이터 창에 시뮬레이터를 찾을 수 없다고 표시됨

174 174

175* [Desktop의 컴퓨터 사용](/docs/ko/desktop#let-claude-use-your-computer): 전용 창이 없는 앱용 화면 제어175* [Desktop의 컴퓨터 사용](/docs/ko/desktop#let-claude-use-your-computer): 전용 창이 없는 앱용 화면 제어

176* [CLI의 컴퓨터 사용](/docs/ko/computer-use): CLI가 iOS 시뮬레이터에 접근하는 방식176* [CLI의 컴퓨터 사용](/docs/ko/computer-use): CLI가 iOS 시뮬레이터에 접근하는 방식

177* [세션과 병렬로 작업](/docs/ko/desktop#work-in-parallel-with-sessions): 세션이 변경 사항을 격리하는 방식177* [자체 워크트리에서 세션 실행](/docs/ko/desktop#run-a-session-in-its-own-worktree): 세션이 변경 사항을 격리하는 방식

178* [Claude Code Desktop 시작하기](/docs/ko/desktop-quickstart)178* [Claude Code Desktop 시작하기](/docs/ko/desktop-quickstart)

desktop-quickstart.md +11 −9

Details

63 63

64<Steps>64<Steps>

65 <Step title="환경 및 폴더 선택">65 <Step title="환경 및 폴더 선택">

~~66 **Local**을 선택하여 파일을 직접 사용하여 머신에서 Claude를 실행합니다. **Select folder**를 클릭하고 프로젝트 디렉토리를 선택합니다.~~66 [프롬프트 상자 아래의 행](/docs/ko/desktop#start-a-session)에서 첫 번째 컨트롤인 환경 선택기를 클릭하고 **Local** 그룹의 맨 위 항목을 선택합니다. 그런 다음 환경 선택기 옆의 프로젝트 폴더 컨트롤을 클릭하고 \*\*Open folder…\*\*를 선택한 후 프로젝트 디렉토리를 선택합니다.

68 프롬프트 상자 아래에 환경 선택기가 표시되지 않으면 이전 레이아웃을 사용하고 있는 것입니다. [사용 중인 레이아웃 확인](/docs/ko/desktop#check-which-layout-you-have)을 참조하십시오.

67 69

68 <Tip>70 <Tip>

69 잘 알고 있는 작은 프로젝트부터 시작하십시오. Claude Code가 무엇을 할 수 있는지 가장 빠르게 확인할 수 있는 방법입니다.71 잘 알고 있는 작은 프로젝트부터 시작하십시오. Claude Code가 무엇을 할 수 있는지 가장 빠르게 확인할 수 있는 방법입니다.

72 다음을 선택할 수도 있습니다:74 다음을 선택할 수도 있습니다:

73 75

74 * **Cloud**: 앱을 닫아도 계속되는 클라우드에서 세션을 실행합니다. 클라우드 세션이 어떻게 작동하는지는 [웹의 Claude Code](/docs/ko/claude-code-on-the-web)를 참조하십시오.76 * **Cloud**: 앱을 닫아도 계속되는 클라우드에서 세션을 실행합니다. 클라우드 세션이 어떻게 작동하는지는 [웹의 Claude Code](/docs/ko/claude-code-on-the-web)를 참조하십시오.

75 * **SSH**: SSH를 통해 원격 머신(예: 자신의 서버, 클라우드 VM 또는 개발 컨테이너)에 연결합니다. Desktop은 처음 연결할 때 원격 머신에 Claude Code를 자동으로 설치합니다. 실행 중인 작업은 [Desktop 연결이 끊어진 동안에도 계속 진행](/docs/ko/desktop#keep-a-task-running-while-desktop-is-disconnected)될 수 있지만, Claude 계정을 사용하는 경우 로그인이 만료되면 중지될 수 있습니다.77 * **SSH**: SSH를 통해 원격 머신(예: 자신의 서버, 클라우드 VM 또는 개발 컨테이너)에 연결합니다. 먼저 [연결을 추가](/docs/ko/desktop#ssh-sessions)하십시오. Desktop은 처음 연결할 때 원격 머신에 Claude Code를 자동으로 설치합니다. 실행 중인 작업은 [Desktop 연결이 끊어진 동안에도 계속 진행](/docs/ko/desktop#keep-a-task-running-while-desktop-is-disconnected)될 수 있지만, Claude 계정을 사용하는 경우 로그인이 만료되면 중지될 수 있습니다.

76 * **WSL** (Windows): [WSL 2 배포판](/docs/ko/desktop-wsl) 내에서 세션을 실행합니다. Claude Code, 도구 및 git은 Linux 측에서 기본 경로로 실행됩니다.78 * **WSL** (Windows): [WSL 2 배포판](/docs/ko/desktop-wsl) 내에서 세션을 실행합니다. Claude Code, 도구 및 git은 Linux 측에서 기본 경로로 실행됩니다.

77 </Step>79 </Step>

78 80

79 <Step title="모델 선택">81 <Step title="모델 선택">

80 전송 버튼 옆의 드롭다운에서 모델을 선택합니다. 사용 가능한 모델의 비교는 [models](/docs/ko/model-config#available-models)를 참조하십시오. 나중에 동일한 드롭다운에서 모델을 변경할 수 있습니다.82 프롬프트 상자 아래 행의 오른쪽 끝 부근에 있는 모델 선택기에서 모델을 선택합니다. 사용 가능한 모델의 비교는 [models](/docs/ko/model-config#available-models)를 참조하십시오. 나중에 모델 선택기에서 모델을 변경할 수 있습니다.

81 </Step>83 </Step>

82 84

83 <Step title="Claude에게 작업 지시">85 <Step title="Claude에게 작업 지시">

91 </Step>93 </Step>

92 94

93 <Step title="변경 사항 검토 및 수락">95 <Step title="변경 사항 검토 및 수락">

~~94 다음에 일어나는 일은 전송 버튼 옆의 선택기에 표시된 [permission mode](/docs/ko/desktop#choose-a-permission-mode)에 따라 달라집니다:~~96 프롬프트 상자 아래 행에서 [permission mode](/docs/ko/desktop#choose-a-permission-mode)를 확인하여 Claude가 승인을 기다리는지 확인합니다:

95 97

96 * **Auto or Accept edits**: Claude가 파일 변경 사항을 적용하고 `+12 -1`과 같은 표시기가 나타나므로 diff 보기에서 검토할 수 있습니다.98 * **Auto or Accept edits**: Claude가 파일 변경 사항을 적용하고 `+12 -1`과 같은 표시기가 나타나므로 diff 보기에서 검토할 수 있습니다.

97 * **Manual**: Claude는 각 변경 사항을 제안하고 적용하기 전에 승인을 기다립니다. 파일은 수락할 때까지 수정되지 않으며, 변경 사항을 거부하면 Claude는 대신 어떻게 진행할지 묻습니다.99 * **Manual**: Claude는 각 변경 사항을 제안하고 적용하기 전에 승인을 기다립니다.

98 100

99 Manual 모드에서는 다음을 볼 수 있습니다:101 Manual 모드에서는 다음을 볼 수 있습니다:

100 102

112 114

113**중단 및 방향 조정.** 언제든지 Claude를 리디렉션할 수 있습니다. 중지 버튼을 클릭하여 즉시 중단하거나, 수정 사항을 입력하고 **Enter**를 눌러 실행 중인 작업을 중지하지 않고 전송할 수 있습니다. 어느 쪽이든 완료될 때까지 기다리거나 다시 시작할 필요가 없습니다.115**중단 및 방향 조정.** 언제든지 Claude를 리디렉션할 수 있습니다. 중지 버튼을 클릭하여 즉시 중단하거나, 수정 사항을 입력하고 **Enter**를 눌러 실행 중인 작업을 중지하지 않고 전송할 수 있습니다. 어느 쪽이든 완료될 때까지 기다리거나 다시 시작할 필요가 없습니다.

114 116

115**Claude에 더 많은 컨텍스트 제공.** 프롬프트 상자에 `@filename`을 입력하여 특정 파일을 대화에 가져오거나, 첨부 버튼을 사용하여 이미지 및 PDF를 첨부하거나, 파일을 프롬프트에 직접 드래그 앤 드롭할 수 있습니다. Claude가 더 많은 컨텍스트를 가질수록 결과가 더 좋습니다. [파일 및 컨텍스트 추가](/docs/ko/desktop#add-files-and-context-to-prompts)를 참조하세요.117**Claude에 더 많은 컨텍스트 제공.** 프롬프트 상자에 `@filename`을 입력하여 특정 파일을 대화에 가져옵니다. Claude가 더 많은 컨텍스트를 가질수록 결과가 더 좋습니다. [파일 및 컨텍스트 추가](/docs/ko/desktop#add-files-and-context-to-prompts)를 참조하세요.

116 118

117**반복 가능한 작업에 스킬 사용.** `/`를 입력하거나 **+** → **Slash commands**를 클릭하여 [기본 제공 명령어](/docs/ko/commands), [사용자 정의 스킬](/docs/ko/skills) 및 플러그인 스킬을 찾아봅니다. 스킬은 코드 검토 체크리스트 또는 배포 단계와 같이 필요할 때마다 호출할 수 있는 재사용 가능한 프롬프트입니다.119**반복 가능한 작업에 스킬 사용.** `/`를 입력하거나 **+** → **Slash commands**를 클릭하여 [기본 제공 명령어](/docs/ko/commands), [사용자 정의 스킬](/docs/ko/skills) 및 플러그인 스킬을 찾아봅니다. 스킬은 코드 검토 체크리스트 또는 배포 단계와 같이 필요할 때마다 호출할 수 있는 재사용 가능한 프롬프트입니다.

118 120

125* **Accept edits**: Claude는 더 빠른 반복을 위해 파일 편집을 자동으로 수락합니다.127* **Accept edits**: Claude는 더 빠른 반복을 위해 파일 편집을 자동으로 수락합니다.

126* **Plan**: Claude는 파일을 편집하지 않고 접근 방식을 제안하며, 이는 대규모 리팩토링 전에 유용합니다.128* **Plan**: Claude는 파일을 편집하지 않고 접근 방식을 제안하며, 이는 대규모 리팩토링 전에 유용합니다.

127 129

128**더 많은 기능을 위해 플러그인 추가.** 프롬프트 상자 옆의 **+** 버튼을 클릭하고 **Plugins**를 선택하여 스킬, 에이전트, MCP 서버 등을 추가하는 [플러그인](/docs/ko/desktop#install-plugins)을 찾아보고 설치합니다.130**더 많은 기능을 위해 플러그인 추가.** 스킬, 에이전트, MCP 서버 등을 추가하는 [플러그인](/docs/ko/desktop#install-plugins)을 설치합니다.

129 131

130**작업 공간 정렬.** 채팅, diff, 터미널, 파일 및 브라우저 창을 원하는 레이아웃으로 드래그합니다. \*\*Ctrl+\`\*\*를 사용하여 터미널을 열어 세션과 함께 명령어를 실행하거나, 파일 경로를 클릭하여 파일 창에서 열 수 있습니다. [작업 공간 정렬](/docs/ko/desktop#arrange-your-workspace)을 참조하세요.132**워크스페이스 정렬.** 채팅, diff, 터미널, 파일 및 브라우저 창을 원하는 레이아웃으로 드래그합니다. \*\*Ctrl+\`\*\*를 사용하여 터미널을 열어 세션과 함께 명령을 실행하거나, 파일 경로를 클릭하여 열 수 있습니다. [워크스페이스 정렬](/docs/ko/desktop#arrange-your-workspace)을 참조하세요.

131 133

132**앱 미리보기.** 데스크톱에서 개발 서버를 실행하면 앱이 브라우저 창에서 열리며, 이는 [외부 사이트를 열 수도](/docs/ko/desktop#browse-external-sites) 있습니다. Claude는 실행 중인 앱을 보고, 엔드포인트를 테스트하고, 로그를 검사하고, 보는 것에 대해 반복할 수 있습니다. [앱 미리보기](/docs/ko/desktop#preview-your-app)를 참조하세요.134**앱 미리보기.** 데스크톱에서 개발 서버를 실행하면 앱이 브라우저 창에서 열리며, 이는 [외부 사이트를 열 수도](/docs/ko/desktop#browse-external-sites) 있습니다. Claude는 실행 중인 앱을 보고, 엔드포인트를 테스트하고, 로그를 검사하고, 보는 것에 대해 반복할 수 있습니다. [앱 미리보기](/docs/ko/desktop#preview-your-app)를 참조하세요.

133 135

134**풀 요청 추적.** PR을 연 후 Claude Code는 CI 확인 결과를 모니터링하고 실패를 자동으로 수정하거나 모든 확인이 통과되면 PR을 병합할 수 있습니다. [풀 요청 상태 모니터링](/docs/ko/desktop#monitor-pull-request-status)을 참조하세요.136**풀 리퀘스트 추적.** PR을 연 후 Claude Code는 CI 확인 결과를 모니터링하고 실패를 자동으로 수정할 수 있습니다. [풀 리퀘스트 상태 모니터링](/docs/ko/desktop#monitor-pull-request-status)을 참조하세요.

135 137

136**Claude를 일정에 따라 실행.** [예약된 작업](/docs/ko/desktop-scheduled-tasks)을 설정하여 Claude를 정기적으로 자동으로 실행합니다: 매일 아침 일일 코드 검토, 주간 종속성 감사 또는 연결된 도구에서 정보를 가져오는 브리핑입니다.138**Claude를 일정에 따라 실행.** [예약된 작업](/docs/ko/desktop-scheduled-tasks)을 설정하여 Claude를 정기적으로 자동으로 실행합니다: 매일 아침 일일 코드 검토, 주간 종속성 감사 또는 연결된 도구에서 정보를 가져오는 브리핑입니다.

137 139

desktop-scheduled-tasks.md +1 −1

Details

33</Tip>33</Tip>

34 34

35<Note>35<Note>

36 기본적으로 예약된 작업은 커밋되지 않은 변경 사항을 포함하여 작업 디렉토리의 현재 상태에 대해 실행됩니다. 작업을 만들 때 worktree 토글을 활성화하여 각 실행이 자신의 격리된 Git worktree를 갖도록 하면, [병렬 세션](/docs/ko/desktop#work-in-parallel-with-sessions)과 동일한 방식으로 작동합니다.36 기본적으로 예약 작업은 커밋되지 않은 변경 사항을 포함하여 작업 디렉터리의 현재 상태에 대해 실행됩니다. 작업을 만들 때 worktree 토글을 활성화하면 각 실행이 자체 [격리된 Git worktree](/docs/ko/desktop#run-a-session-in-its-own-worktree)를 갖게 됩니다.

37</Note>37</Note>

38 38

39<h2 id="create-a-scheduled-task">39<h2 id="create-a-scheduled-task">

desktop-wsl.md +20 −6

Details

24 24

25<Steps>25<Steps>

26 <Step title="배포판 선택">26 <Step title="배포판 선택">

~~27 Code 탭에서 새 세션을 시작하고 환경 선택기를 엽니다. 설치된 WSL 2 배포판이 **WSL** 섹션에 나타납니다. 하나를 선택합니다.~~27 Code 탭에서 새 세션을 시작하고 프롬프트 상자 아래, 또는 [이전 레이아웃](/docs/ko/desktop#check-which-layout-you-have)에서는 프롬프트 상자 위에 있는 [환경 선택기](/docs/ko/desktop#start-a-session)를 엽니다. 설치된 WSL 2 배포판이 **WSL** 섹션에 나타납니다. 하나를 선택합니다.

28 </Step>28 </Step>

29 29

30 <Step title="폴더 선택">30 <Step title="폴더 선택">

32 </Step>32 </Step>

33 33

34 <Step title="폴더 신뢰">34 <Step title="폴더 신뢰">

35 폴더의 첫 번째 세션에는 작업 영역 신뢰 대화 상자가 표시됩니다. 신뢰는 배포판 및 폴더별로 부여됩니다. 한 배포판의 폴더를 신뢰하는 것이 다른 배포판이나 Windows의 동일한 경로에 적용되지는 않습니다.35 폴더의 첫 번째 세션에는 워크스페이스 신뢰 대화 상자가 표시됩니다. 신뢰는 배포판 및 폴더별로 부여됩니다. 한 배포판의 폴더를 신뢰하는 것이 다른 배포판이나 Windows의 동일한 경로에 적용되지는 않습니다.

36 </Step>36 </Step>

37</Steps>37</Steps>

38 38

39배포판의 첫 번째 세션은 Claude가 내부에 설정되는 동안 약간 더 오래 걸립니다. 일반 폴더 선택기에서 `\\wsl.localhost\...` 폴더를 열 수도 있으며, 해당 배포판 내에서 다시 열립니다.39배포판의 첫 번째 세션은 Claude가 내부에 설정되는 동안 약간 더 오래 걸립니다. 일반 폴더 선택기에서 `\\wsl.localhost\...` 폴더를 열 수도 있으며, 해당 배포판 내에서 다시 열립니다.

40 40

~~41최근에 사용한 폴더는 배포판별로 선택기에 나타나므로 프로젝트에 다시 연결하는 것은 한 번의 클릭입니다.~~

43<h2 id="what-works-in-a-wsl-session">41<h2 id="what-works-in-a-wsl-session">

44 WSL 세션에서 작동하는 기능42 WSL 세션에서 작동하는 기능

45</h2>43</h2>

46 44

47병렬 세션, 측면 채팅, 시각적 diff 검토, 분기 및 풀 요청 상태, worktrees는 모두 배포판 내의 git 및 도구 체인으로 지원됩니다. "편집기에서 열기"는 [Remote - WSL](https://code.visualstudio.com/docs/remote/wsl)을 통해 배포판에 연결된 VS Code를 엽니다.45병렬 세션, 측면 채팅, 시각적 diff 검토, 브랜치 및 풀 리퀘스트 상태, worktree는 모두 배포판 내의 git 및 도구 체인으로 지원됩니다. "편집기에서 열기"는 [Remote - WSL](https://code.visualstudio.com/docs/remote/wsl)을 통해 배포판에 연결된 VS Code를 엽니다.

47WSL 세션에서 Desktop 기능을 사용할 수 없거나 제한되는 경우 다음 중 하나에 해당하는지 확인합니다.

49* **터미널 및 커넥터**: 세션에 [통합 터미널](/docs/ko/desktop#run-commands-in-the-terminal), [커넥터](/docs/ko/desktop#connect-external-tools) 또는 둘 다 없을 수 있습니다. [터미널 또는 커넥터를 사용할 수 없는 경우](#check-for-the-terminal-and-connectors)를 참조하세요.

50* **[플러그인](/docs/ko/desktop#install-plugins)**: WSL 세션에서는 사용할 수 없습니다

51* **파일 편집**: [파일 창](/docs/ko/desktop#open-and-edit-files)에서 파일을 볼 수는 있지만 편집할 수는 없으므로 Claude에게 변경을 요청합니다

52* **첨부 파일**: **+** 메뉴에 **파일 또는 사진 추가** 대신 **이미지 추가**가 표시되면 이미지만 첨부할 수 있습니다. [프롬프트에 파일 및 컨텍스트 추가](/docs/ko/desktop#add-files-and-context-to-prompts)를 참조하세요.

54<a id="check-for-the-terminal-and-connectors" />

56<h3 id="if-the-terminal-or-connectors-are-unavailable">

57 터미널 또는 커넥터를 사용할 수 없는 경우

58</h3>

60WSL 세션의 통합 터미널이나 커넥터는 사용자가 직접 켤 수 없습니다.

48 61

49WSL 세션에서 아직 사용할 수 없는 몇 가지 기능이 있습니다. 통합 터미널, 커넥터 및 플러그인, 세션 포킹, 파일 브라우저 창, 그리고 작성기에서 `@`를 입력할 때의 파일 제안입니다.62* **Claude 계정**: 두 기능은 별도로 출시되고 있습니다. \*\*Help > Check for Updates…\*\*를 선택하고, 업데이트한 후에도 기능이 여전히 없다면 따로 조치할 것은 없습니다.

63* **[서드파티 제공업체](/docs/ko/third-party-integrations)**: WSL 세션에서는 터미널이나 커넥터가 제공되지 않으며, Desktop을 업데이트해도 달라지지 않습니다

50 64

51<h2 id="managed-devices">65<h2 id="managed-devices">

52 관리되는 디바이스66 관리되는 디바이스

env-vars.md +7 −11

Details

196| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 요청이 전송되는 GCP 프로젝트 ID입니다. [GCP 자격 증명 구성](/docs/ko/google-vertex-ai#3-configure-gcp-credentials)을 참조하세요 |196| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 요청이 전송되는 GCP 프로젝트 ID입니다. [GCP 자격 증명 구성](/docs/ko/google-vertex-ai#3-configure-gcp-credentials)을 참조하세요 |

197| `ANTHROPIC_WORKSPACE_ID` | [워크로드 아이덴티티 페더레이션](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)용 워크스페이스 ID입니다. 페더레이션 규칙의 범위가 둘 이상의 워크스페이스로 지정된 경우, 토큰 교환이 대상 워크스페이스를 알 수 있도록 이 값을 설정합니다 |197| `ANTHROPIC_WORKSPACE_ID` | [워크로드 아이덴티티 페더레이션](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)용 워크스페이스 ID입니다. 페더레이션 규칙의 범위가 둘 이상의 워크스페이스로 지정된 경우, 토큰 교환이 대상 워크스페이스를 알 수 있도록 이 값을 설정합니다 |

198| `API_FORCE_IDLE_TIMEOUT` | 바이트가 도착하지 않을 때 스트리밍 모델 응답을 중단하는 5분 본문 유휴 타임아웃을 재정의합니다. 느린 [게이트웨이](/docs/ko/llm-gateway)나 로컬 모델이 청크 사이에 5분 넘게 멈추는 경우처럼 타임아웃을 끄려면 `0`으로, 모든 제공자에서 켜 두려면 `1`로 설정합니다. 설정하지 않으면 직접 연결한 Anthropic API, [Claude Platform on AWS](/docs/ko/claude-platform-on-aws), 그리고 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`이 설정된 Amazon Bedrock 이외의 제공자에서 타임아웃이 활성화됩니다. [스트림 워치독](/docs/ko/network-config#streaming-idle-watchdogs)은 이와 독립적으로 실행되며, 여기서 `0`으로 설정하더라도 오랫동안 아무 응답이 없는 일시 중지를 중단합니다 |198| `API_FORCE_IDLE_TIMEOUT` | 바이트가 도착하지 않을 때 스트리밍 모델 응답을 중단하는 5분 본문 유휴 타임아웃을 재정의합니다. 느린 [게이트웨이](/docs/ko/llm-gateway)나 로컬 모델이 청크 사이에 5분 넘게 멈추는 경우처럼 타임아웃을 끄려면 `0`으로, 모든 제공자에서 켜 두려면 `1`로 설정합니다. 설정하지 않으면 직접 연결한 Anthropic API, [Claude Platform on AWS](/docs/ko/claude-platform-on-aws), 그리고 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`이 설정된 Amazon Bedrock 이외의 제공자에서 타임아웃이 활성화됩니다. [스트림 워치독](/docs/ko/network-config#streaming-idle-watchdogs)은 이와 독립적으로 실행되며, 여기서 `0`으로 설정하더라도 오랫동안 아무 응답이 없는 일시 중지를 중단합니다 |

199| `API_TIMEOUT_MS` | API 요청의 타임아웃(밀리초)입니다(기본값: 600000, 즉 10분; 최댓값: 2147483647). 스트리밍 요청은 이 시간 내에 응답 헤더를 받아야 합니다. 느린 네트워크에서나 프록시를 통해 라우팅할 때 요청이 시간 초과되면 이 값을 늘립니다 |199| `API_TIMEOUT_MS` | 각 API 요청 시도가 응답 헤더를 받아야 하는 시간(밀리초)입니다(기본값: 600000, 즉 10분; 최대: 2147483647). 그 이후 스트리밍 응답이 실행되는 시간은 제한하지 않습니다. 양수 값을 설정하면 [비스트리밍 요청](/docs/ko/errors#streaming-response-ended-before-any-complete-data-was-received)의 각 시도가 이 시간 안에 완료되어야 합니다. 느린 네트워크에서 또는 프록시를 통해 라우팅할 때 요청이 시간 초과되면 이 값을 늘립니다 |

200| `AWS_BEARER_TOKEN_BEDROCK` | 인증용 Amazon Bedrock API 키입니다([Amazon Bedrock API 키](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/) 참조) |200| `AWS_BEARER_TOKEN_BEDROCK` | 인증용 Amazon Bedrock API 키입니다([Amazon Bedrock API 키](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/) 참조) |

201| `BASH_DEFAULT_TIMEOUT_MS` | 포그라운드 Bash 또는 PowerShell 도구 명령의 기본 타임아웃(밀리초)입니다(기본값: 120000, 즉 2분). [백그라운드 명령의 기본 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands)보다 큰 값은 무인 세션에서 해당 기본값을 대체합니다. 백그라운드 시간 제한에는 Claude Code v2.1.285 이상이 필요합니다 |201| `BASH_DEFAULT_TIMEOUT_MS` | 포그라운드 Bash 또는 PowerShell 도구 명령의 기본 타임아웃(밀리초)입니다(기본값: 120000, 즉 2분). [백그라운드 명령의 기본 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands)보다 큰 값은 무인 세션에서 해당 기본값을 대체합니다. 백그라운드 시간 제한에는 Claude Code v2.1.285 이상이 필요합니다 |

202| `BASH_MAX_OUTPUT_LENGTH` | Claude Code가 명령 결과로 다시 읽어 들이는 bash 출력의 최대 문자 수입니다(기본값: 30000, 최댓값: 150000). [`bashOutputMaxChars`](/docs/ko/settings-reference#bashoutputmaxchars) 설정을 지정하면 Claude Code는 이 변수를 무시합니다. [출력 제한](/docs/ko/tools-reference#output-limits)을 참조하세요 |202| `BASH_MAX_OUTPUT_LENGTH` | Claude Code가 명령 결과로 다시 읽어 들이는 bash 출력의 최대 문자 수입니다(기본값: 30000, 최댓값: 150000). [`bashOutputMaxChars`](/docs/ko/settings-reference#bashoutputmaxchars) 설정을 지정하면 Claude Code는 이 변수를 무시합니다. [출력 제한](/docs/ko/tools-reference#output-limits)을 참조하세요 |

230| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | v2.1.283에서 제거되었습니다. 대신 `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE`을 사용합니다 |230| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | v2.1.283에서 제거되었습니다. 대신 `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE`을 사용합니다 |

231| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | [자동 압축 윈도우](/docs/ko/model-config#set-the-auto-compact-window)를 `100000`에서 `1000000` 사이의 토큰 수로 설정합니다. `500000` 같은 일반 정수만 허용합니다: `500k` 같은 값은 `500`으로 읽혀 최솟값인 100K로 조정됩니다. 실제 윈도우는 모델의 컨텍스트 윈도우로도 제한됩니다. `/autocompact` 명령, `--autocompact` 플래그, `autoCompactWindow` 설정보다 우선합니다. 상태줄의 `used_percentage`는 항상 모델의 전체 컨텍스트 윈도우를 기준으로 측정하므로, 이 변수를 설정하면 해당 백분율은 더 이상 압축이 실행될 시점을 나타내지 않습니다 |231| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | [자동 압축 윈도우](/docs/ko/model-config#set-the-auto-compact-window)를 `100000`에서 `1000000` 사이의 토큰 수로 설정합니다. `500000` 같은 일반 정수만 허용합니다: `500k` 같은 값은 `500`으로 읽혀 최솟값인 100K로 조정됩니다. 실제 윈도우는 모델의 컨텍스트 윈도우로도 제한됩니다. `/autocompact` 명령, `--autocompact` 플래그, `autoCompactWindow` 설정보다 우선합니다. 상태줄의 `used_percentage`는 항상 모델의 전체 컨텍스트 윈도우를 기준으로 측정하므로, 이 변수를 설정하면 해당 백분율은 더 이상 압축이 실행될 시점을 나타내지 않습니다 |

232| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 자동 [IDE 연결](/docs/ko/vs-code)을 재정의합니다. 기본적으로 Claude Code는 지원되는 IDE의 통합 터미널에서 실행될 때 자동으로 연결됩니다. 이를 방지하려면 `false`로 설정합니다. tmux가 상위 터미널을 가리는 경우처럼 자동 감지가 실패할 때 연결 시도를 강제하려면 `true`로 설정합니다. [`autoConnectIde`](/docs/ko/settings-reference#autoconnectide) 전역 구성 설정보다 우선합니다 |232| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 자동 [IDE 연결](/docs/ko/vs-code)을 재정의합니다. 기본적으로 Claude Code는 지원되는 IDE의 통합 터미널에서 실행될 때 자동으로 연결됩니다. 이를 방지하려면 `false`로 설정합니다. tmux가 상위 터미널을 가리는 경우처럼 자동 감지가 실패할 때 연결 시도를 강제하려면 `true`로 설정합니다. [`autoConnectIde`](/docs/ko/settings-reference#autoconnectide) 전역 구성 설정보다 우선합니다 |

233| `CLAUDE_CODE_AUTO_MODE_MODEL` | Claude Code가 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 보내는 분류기 요청의 모델을 설정합니다. `claude-sonnet-4-6`과 같은 전체 모델 ID를 사용합니다. Claude Code가 이 값을 무시하는 경우는 [분류기 모델 선택](/docs/ko/permission-modes#choose-the-classifier-model)을 참조하세요. Claude Code v2.1.302 이상이 필요합니다 |

233| `CLAUDE_CODE_AUTO_MODE_SERVER` | Claude Code가 서버에 [자동 모드 작업 검토](/docs/ko/permission-modes#server-side-classifier-review)를 요청할지 여부를 제어합니다. 대신 Claude Code 자체의 분류기 요청을 사용하려면 `0`으로 설정합니다. Anthropic API에 직접 연결하는 경우 v2.1.281 이상이 필요합니다. 연결된 섹션에 변수가 설정되지 않았을 때 어떤 세션이 어느 버전부터 서버에 요청하는지 나와 있습니다. Claude Code v2.1.271 이상이 필요합니다 |234| `CLAUDE_CODE_AUTO_MODE_SERVER` | Claude Code가 서버에 [자동 모드 작업 검토](/docs/ko/permission-modes#server-side-classifier-review)를 요청할지 여부를 제어합니다. 대신 Claude Code 자체의 분류기 요청을 사용하려면 `0`으로 설정합니다. Anthropic API에 직접 연결하는 경우 v2.1.281 이상이 필요합니다. 연결된 섹션에 변수가 설정되지 않았을 때 어떤 세션이 어느 버전부터 서버에 요청하는지 나와 있습니다. Claude Code v2.1.271 이상이 필요합니다 |

234| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | 요청이 [`AWS default-chain credential resolve timed out`](/docs/ko/errors#aws-default-chain-credential-resolve-timed-out) 오류로 실패하기 전에 Claude Code가 AWS 기본 자격 증명 공급자 체인이 자격 증명을 생성하기를 기다리는 시간(밀리초)입니다(기본값: `60000`). `aws-vault` 같은 래퍼를 통한 MFA 포함 브라우저 기반 SSO 로그인처럼 체인의 한 단계가 실제로 더 오래 걸리는 경우 값을 늘립니다. Amazon Bedrock, [Claude Platform on AWS](/docs/ko/claude-platform-on-aws), [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)에 적용됩니다. [자격 증명 캐싱 및 확인 타임아웃](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout)을 참조하세요. Claude Code v2.1.207 이상이 필요합니다 |235| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | 요청이 [`AWS default-chain credential resolve timed out`](/docs/ko/errors#aws-default-chain-credential-resolve-timed-out) 오류로 실패하기 전에 Claude Code가 AWS 기본 자격 증명 공급자 체인이 자격 증명을 생성하기를 기다리는 시간(밀리초)입니다(기본값: `60000`). `aws-vault` 같은 래퍼를 통한 MFA 포함 브라우저 기반 SSO 로그인처럼 체인의 한 단계가 실제로 더 오래 걸리는 경우 값을 늘립니다. Amazon Bedrock, [Claude Platform on AWS](/docs/ko/claude-platform-on-aws), [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)에 적용됩니다. [자격 증명 캐싱 및 확인 타임아웃](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout)을 참조하세요. Claude Code v2.1.207 이상이 필요합니다 |

235| `CLAUDE_CODE_BASH_EDIT_DIFF` | `0`으로 설정하면 [Bash 명령이 실행되는 동안 변경된 파일의 diff](/docs/ko/hooks#bash)를 끄고, `1`로 설정하면 모든 권한 모드에서 이를 기록합니다. [`bashEditDiffEnabled`](/docs/ko/settings-reference#basheditdiffenabled) 설정보다 우선합니다. Claude Code v2.1.269 이상이 필요합니다 |236| `CLAUDE_CODE_BASH_EDIT_DIFF` | `0`으로 설정하면 [Bash 명령이 실행되는 동안 변경된 파일의 diff](/docs/ko/hooks#bash)를 끄고, `1`로 설정하면 모든 권한 모드에서 이를 기록합니다. [`bashEditDiffEnabled`](/docs/ko/settings-reference#basheditdiffenabled) 설정보다 우선합니다. Claude Code v2.1.269 이상이 필요합니다 |

244| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | v2.1.186에서 제거되었으며 현재는 아무 동작도 하지 않습니다. 이전에는 스트리밍 API 요청의 연결, TLS, 응답 헤더 단계에 대해 별도의 타임아웃을 설정했습니다. 요청별 타임아웃에는 `API_TIMEOUT_MS`를 사용합니다. 스트리밍 요청의 응답 헤더 단계에 대해서는 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`를 참조하세요 |245| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | v2.1.186에서 제거되어 현재는 아무 효과가 없습니다. 이전에는 스트리밍 API 요청의 연결, TLS, 응답 헤더 단계에 대해 별도의 타임아웃을 설정했습니다. 대신 `API_TIMEOUT_MS`를 사용합니다. 스트리밍 요청의 응답 헤더 단계는 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`를 참조하세요 |

245| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 디버그 로그 파일 경로를 재정의합니다. 이름과 달리 디렉터리가 아닌 파일 경로입니다. `--debug`, `/debug` 또는 `DEBUG` 환경 변수를 통해 디버그 모드를 별도로 활성화해야 하며, 이 변수만 설정해서는 로깅이 활성화되지 않습니다. [`--debug-file`](/docs/ko/cli-reference#cli-flags) 플래그는 두 가지를 한 번에 수행합니다. 기본값은 `~/.claude/debug/<session-id>.txt`입니다 |246| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 디버그 로그 파일 경로를 재정의합니다. 이름과 달리 디렉터리가 아닌 파일 경로입니다. `--debug`, `/debug` 또는 `DEBUG` 환경 변수를 통해 디버그 모드를 별도로 활성화해야 하며, 이 변수만 설정해서는 로깅이 활성화되지 않습니다. [`--debug-file`](/docs/ko/cli-reference#cli-flags) 플래그는 두 가지를 한 번에 수행합니다. 기본값은 `~/.claude/debug/<session-id>.txt`입니다 |

246| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 디버그 로그 파일에 기록되는 최소 로그 수준입니다. 값: `verbose`, `debug`(기본값), `info`, `warn`, `error`. 전체 상태줄 명령 출력 같은 대용량 진단 정보를 포함하려면 `verbose`로 설정하고, 노이즈를 줄이려면 `error`로 높입니다 |247| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 디버그 로그 파일에 기록되는 최소 로그 수준입니다. 값: `verbose`, `debug`(기본값), `info`, `warn`, `error`. 전체 상태줄 명령 출력 같은 대용량 진단 정보를 포함하려면 `verbose`로 설정하고, 노이즈를 줄이려면 `error`로 높입니다 |

247| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | `1`로 설정하면 [1M 컨텍스트 윈도우](/docs/ko/model-config#extended-context) 지원을 끕니다. Claude Code는 모델 선택기에서 `[1m]` 모델 변형을 제거하고, 기본적으로 1M 윈도우로 실행되는 모델을 200K 윈도우로 제한합니다. [1M 컨텍스트 끄기](/docs/ko/model-config#turn-off-1m-context)를 참조하세요. 규정 준수 요구 사항이 있는 엔터프라이즈 환경에 유용합니다. 인식되지 않는 `[1m]` 모델 ID의 윈도우를 보정하는 역할에 대해서는 [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 보정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요 |248| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | `1`로 설정하면 [1M 컨텍스트 윈도우](/docs/ko/model-config#extended-context) 지원을 끕니다. Claude Code는 모델 선택기에서 `[1m]` 모델 변형을 제거하고, 기본적으로 1M 윈도우로 실행되는 모델을 200K 윈도우로 제한합니다. [1M 컨텍스트 끄기](/docs/ko/model-config#turn-off-1m-context)를 참조하세요. 규정 준수 요구 사항이 있는 엔터프라이즈 환경에 유용합니다. 인식되지 않는 `[1m]` 모델 ID의 윈도우를 보정하는 역할에 대해서는 [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 보정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요 |

304| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Claude가 도구 호출 입력을 생성하는 동안 API에서 이를 스트리밍할지 여부를 제어합니다. 이 기능이 꺼져 있으면 긴 파일 쓰기와 같은 대용량 도구 입력은 Claude가 생성을 마친 후에야 도착하므로 멈춘 것처럼 보일 수 있습니다. Anthropic API에서는 기본적으로 활성화되어 있습니다. Amazon Bedrock과 Google Cloud's Agent Platform에서는 배포된 컨테이너가 지원하는 모델별로 활성화됩니다. 사용하지 않으려면 `0`으로 설정합니다. `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` 또는 `ANTHROPIC_BEDROCK_BASE_URL`을 통해 프록시로 라우팅할 때 강제로 켜려면 `1`로 설정합니다. Microsoft Foundry와 [게이트웨이](/docs/ko/llm-gateway) 연결에서는 기본적으로 꺼져 있습니다 |305| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Claude가 도구 호출 입력을 생성하는 동안 API에서 이를 스트리밍할지 여부를 제어합니다. 이 기능이 꺼져 있으면 긴 파일 쓰기와 같은 대용량 도구 입력은 Claude가 생성을 마친 후에야 도착하므로 멈춘 것처럼 보일 수 있습니다. Anthropic API에서는 기본적으로 활성화되어 있습니다. Amazon Bedrock과 Google Cloud's Agent Platform에서는 배포된 컨테이너가 지원하는 모델별로 활성화됩니다. 사용하지 않으려면 `0`으로 설정합니다. `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` 또는 `ANTHROPIC_BEDROCK_BASE_URL`을 통해 프록시로 라우팅할 때 강제로 켜려면 `1`로 설정합니다. Microsoft Foundry와 [게이트웨이](/docs/ko/llm-gateway) 연결에서는 기본적으로 꺼져 있습니다 |

305| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `ANTHROPIC_BASE_URL`이 LiteLLM, Kong 또는 내부 프록시와 같은 Anthropic 호환 게이트웨이를 가리킬 때 게이트웨이의 `/v1/models` 엔드포인트에서 `/model` 선택기를 채우려면 `1`로 설정합니다. 공유 API 키를 사용하는 게이트웨이에서는 해당 키로 액세스할 수 있는 모든 모델이 모든 사용자에게 표시되므로 기본적으로 꺼져 있습니다. 검색된 모델은 세션이 받는 [`availableModels`](/docs/ko/settings-reference#availablemodels) 허용 목록으로 계속 필터링됩니다. [게이트웨이 구성에서는 서버 관리형 전달을 사용할 수 없으므로](/docs/ko/server-managed-settings#platform-availability) 목록은 [MDM 또는 관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)을 통해 전달합니다 |306| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `ANTHROPIC_BASE_URL`이 LiteLLM, Kong 또는 내부 프록시와 같은 Anthropic 호환 게이트웨이를 가리킬 때 게이트웨이의 `/v1/models` 엔드포인트에서 `/model` 선택기를 채우려면 `1`로 설정합니다. 공유 API 키를 사용하는 게이트웨이에서는 해당 키로 액세스할 수 있는 모든 모델이 모든 사용자에게 표시되므로 기본적으로 꺼져 있습니다. 검색된 모델은 세션이 받는 [`availableModels`](/docs/ko/settings-reference#availablemodels) 허용 목록으로 계속 필터링됩니다. [게이트웨이 구성에서는 서버 관리형 전달을 사용할 수 없으므로](/docs/ko/server-managed-settings#platform-availability) 목록은 [MDM 또는 관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)을 통해 전달합니다 |

307| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 프롬프트 입력에 회색으로 표시되는 예측인 프롬프트 제안을 끄려면 `false`로 설정합니다. `/config`의 **Prompt suggestions** 토글이 기록하는 [`promptSuggestionEnabled`](/docs/ko/settings-reference#promptsuggestionenabled) 설정보다 우선합니다. Claude Code는 또한 [계정이 사용 한도에 가깝거나 도달한 동안 제안을 일시 중지합니다](/docs/ko/interactive-mode#when-claude-code-skips-suggestions). 한도에 도달할 때까지 제안을 계속 켜 두려면 `true`로 설정합니다. Claude Code v2.1.238 이상이 필요합니다. [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions)을 참조하세요 |308| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 프롬프트 입력란에 회색으로 표시되는 예측인 프롬프트 제안을 끄려면 `false`로 설정합니다. `/config`의 **Prompt suggestions** 토글이 기록하는 [`promptSuggestionEnabled`](/docs/ko/settings-reference#promptsuggestionenabled) 설정보다 우선합니다. Claude Code는 또한 [계정이 사용 한도에 가까워지거나 도달하면 제안을 일시 중지합니다](/docs/ko/interactive-mode#when-claude-code-skips-suggestions). 한도에 도달할 때까지 이 일시 중지가 적용되지 않도록 하려면 `true`로 설정합니다. Claude Code v2.1.238 이상이 필요합니다. [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions)을 참조하세요 |

308| `CLAUDE_CODE_ENABLE_TASKS` | [작업 추적 도구가 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 Claude Code가 제공하는 작업 추적 도구를 선택합니다. 기본적으로 Claude Code는 Task 도구인 `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`를 제공합니다. 대신 레거시 `TodoWrite` 도구를 사용하려면 `0`으로 설정합니다. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하세요 |309| `CLAUDE_CODE_ENABLE_TASKS` | [작업 추적 도구가 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 Claude Code가 제공하는 작업 추적 도구를 선택합니다. 기본적으로 Claude Code는 Task 도구인 `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`를 제공합니다. 대신 레거시 `TodoWrite` 도구를 사용하려면 `0`으로 설정합니다. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하세요 |

309| `CLAUDE_CODE_ENABLE_TELEMETRY` | 메트릭과 로깅을 위한 OpenTelemetry 데이터 수집을 활성화하려면 `1`로 설정합니다. OTel 익스포터를 구성하기 전에 필요합니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |310| `CLAUDE_CODE_ENABLE_TELEMETRY` | 메트릭과 로깅을 위한 OpenTelemetry 데이터 수집을 활성화하려면 `1`로 설정합니다. OTel 익스포터를 구성하기 전에 필요합니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

310| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 모든 모델에서 작업 추적 도구를 사용하려면 `1`로 설정합니다. 이 변수가 없으면 Claude Code는 [Task 도구 사용 가능 여부](/docs/ko/tools-reference#task-tool-availability)에 나열된 모델에서만 기본적으로 해당 도구를 제공합니다. `CLAUDE_CODE_ENABLE_TASKS`는 여전히 Task 도구 또는 `TodoWrite`를 선택합니다. Claude Code v2.1.233 이상이 필요합니다 |311| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 모든 모델에서 작업 추적 도구를 사용하려면 `1`로 설정합니다. 이 변수가 없으면 Claude Code는 [Task 도구 사용 가능 여부](/docs/ko/tools-reference#task-tool-availability)에 나열된 모델에서만 기본적으로 해당 도구를 제공합니다. `CLAUDE_CODE_ENABLE_TASKS`는 여전히 Task 도구 또는 `TodoWrite`를 선택합니다. Claude Code v2.1.233 이상이 필요합니다 |

316| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 터미널이 취소선을 지원하지만 자동으로 감지되지 않는 경우(예: `TERM_PROGRAM`이 전달되지 않은 SSH 환경) Claude의 응답에서 `~~text~~`를 취소선으로 강제 렌더링하려면 `1`로 설정합니다. 이 변수가 없으면 감지되지 않은 터미널에서는 텍스트를 취소선으로 렌더링하는 대신 `~~` 마커가 그대로 표시됩니다. Claude Code v2.1.186 이상이 필요합니다 |317| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 터미널이 취소선을 지원하지만 자동으로 감지되지 않는 경우(예: `TERM_PROGRAM`이 전달되지 않은 SSH 환경) Claude의 응답에서 `~~text~~`를 취소선으로 강제 렌더링하려면 `1`로 설정합니다. 이 변수가 없으면 감지되지 않은 터미널에서는 텍스트를 취소선으로 렌더링하는 대신 `~~` 마커가 그대로 표시됩니다. Claude Code v2.1.186 이상이 필요합니다 |

317| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 터미널이 DEC private mode 2026 [동기화된 출력](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)을 지원하지만 자동으로 감지되지 않을 때 이를 강제로 활성화하려면 `1`로 설정합니다. BSU/ESU를 구현하지만 기능 프로브에 응답하지 않는 Emacs `eat`와 같은 에뮬레이터에 유용합니다. tmux에서는 아무 효과가 없습니다. [전체 화면 렌더링](/docs/ko/fullscreen)으로 전환하는 `CLAUDE_CODE_NO_FLICKER`와 달리 렌더러를 변경하지 않습니다 |318| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 터미널이 DEC private mode 2026 [동기화된 출력](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)을 지원하지만 자동으로 감지되지 않을 때 이를 강제로 활성화하려면 `1`로 설정합니다. BSU/ESU를 구현하지만 기능 프로브에 응답하지 않는 Emacs `eat`와 같은 에뮬레이터에 유용합니다. tmux에서는 아무 효과가 없습니다. [전체 화면 렌더링](/docs/ko/fullscreen)으로 전환하는 `CLAUDE_CODE_NO_FLICKER`와 달리 렌더러를 변경하지 않습니다 |

318| `CLAUDE_CODE_FORCE_TERMINAL_IMAGES` | 터미널이 유니코드 플레이스홀더를 사용하여 kitty 그래픽 프로토콜 이미지를 그리지만 자동으로 감지되지 않을 때 [mod `Image` 요소](/docs/ko/plugins/mods/reference#elements)를 그림으로 그리려면 `1`로 설정합니다. [Claude Code가 감지하는 터미널](/docs/ko/plugins/mods/gallery#image-and-client)과 tmux나 screen 내부에서는 도움이 되지 않는 이유를 참조하세요 |319| `CLAUDE_CODE_FORCE_TERMINAL_IMAGES` | 터미널이 유니코드 플레이스홀더를 사용하여 kitty 그래픽 프로토콜 이미지를 그리지만 자동으로 감지되지 않을 때 [mod `Image` 요소](/docs/ko/plugins/mods/reference#elements)를 그림으로 그리려면 `1`로 설정합니다. [Claude Code가 감지하는 터미널](/docs/ko/plugins/mods/gallery#image-and-client)과 tmux나 screen 내부에서는 도움이 되지 않는 이유를 참조하세요 |

319| `CLAUDE_CODE_FORK_SUBAGENT` | Claude가 직접 [포크된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 생성할 수 있게 하는 [포크 모드](/docs/ko/sub-agents#turn-fork-mode-on-or-off)를 제어하며, 대화형 세션에서만 기본적으로 켜져 있습니다. `claude -p`와 Agent SDK에서도 켜려면 `1`로, 모든 종류의 세션에서 끄려면 `0`으로 설정합니다. 포크 모드가 켜져 있는지와 관계없이 `/subtask`를 실행할 수 있습니다. 대화형 기본값에는 Claude Code v2.1.232 이상이 필요하며, 이전 버전에서는 포크 모드를 켜려면 변수를 `1`로 설정합니다 |320| `CLAUDE_CODE_FORK_SUBAGENT` | 기본적으로 켜져 있으며 Claude가 스스로 [포크](/docs/ko/sub-agents#fork-the-current-conversation)를 시작할 수 있게 하는 포크 모드를 제어합니다. 포크 모드가 켜져 있는 동안 Claude는 로컬 머신의 대화형 터미널, VS Code 또는 데스크톱 세션에서 [서브에이전트를 기다릴](/docs/ko/sub-agents#run-subagents-in-foreground-or-background) 수 없습니다. 포크 모드를 끄려면 `0`으로 설정하십시오. 버전은 [포크 모드 끄기](/docs/ko/sub-agents#turn-fork-mode-on-or-off)를 참조하십시오 |

320| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | `claude -p --output-format stream-json` 출력에 [서브에이전트](/docs/ko/sub-agents) 텍스트와 thinking 블록을 내보내려면 `1`로 설정하며, [`--forward-subagent-text`](/docs/ko/cli-reference#cli-flags) 플래그와 동일하게 동작합니다. 하네스가 `claude`를 호출하면서 플래그를 직접 전달할 수 없을 때 이 변수를 사용합니다. stream-json 출력을 사용하는 비대화형 모드 외부에서는 오류와 함께 종료되는 플래그와 달리, 변수는 해당 환경에서 무시되므로 프로세스 전체에 설정해도 중첩된 호출이 계속 작동합니다. Claude Code v2.1.211 이상이 필요합니다 |321| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | `claude -p --output-format stream-json` 출력에 [서브에이전트](/docs/ko/sub-agents) 텍스트와 thinking 블록을 내보내려면 `1`로 설정하며, [`--forward-subagent-text`](/docs/ko/cli-reference#cli-flags) 플래그와 동일하게 동작합니다. 하네스가 `claude`를 호출하면서 플래그를 직접 전달할 수 없을 때 이 변수를 사용합니다. stream-json 출력을 사용하는 비대화형 모드 외부에서는 오류와 함께 종료되는 플래그와 달리, 변수는 해당 환경에서 무시되므로 프로세스 전체에 설정해도 중첩된 호출이 계속 작동합니다. Claude Code v2.1.211 이상이 필요합니다 |

321| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 사용자 지정 프록시나 Amazon Bedrock 또는 Claude Platform on AWS와 같은 타사 제공업체에서 `x-claude-code-request-class`, `x-claude-code-compaction` 등의 [게이트웨이 힌트 헤더](/docs/ko/llm-gateway-protocol#gateway-hint-headers)를 보내려면 `1`로 설정합니다. Claude Code가 기본적으로 헤더를 보내는 Anthropic API 직접 연결을 포함한 모든 연결에서 헤더 전송을 중지하려면 `0`으로 설정합니다. Claude Code v2.1.273 이상이 필요합니다 |322| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 사용자 지정 프록시나 Amazon Bedrock 또는 Claude Platform on AWS와 같은 타사 제공업체에서 `x-claude-code-request-class`, `x-claude-code-compaction` 등의 [게이트웨이 힌트 헤더](/docs/ko/llm-gateway-protocol#gateway-hint-headers)를 보내려면 `1`로 설정합니다. Claude Code가 기본적으로 헤더를 보내는 Anthropic API 직접 연결을 포함한 모든 연결에서 헤더 전송을 중지하려면 `0`으로 설정합니다. Claude Code v2.1.273 이상이 필요합니다 |

322| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`가 켜는 [게이트웨이 모델 검색](/docs/ko/llm-gateway-protocol#model-discovery) 요청의 타임아웃(밀리초)입니다(기본값: `3000`). 시작 시 게이트웨이가 `/v1/models`에 응답하는 데 3초보다 오래 걸리면 값을 늘립니다. 숫자만 허용되며, `0`, 음수 값 및 기타 표기는 기본값을 유지합니다. Claude Code v2.1.269 이상이 필요합니다 |323| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`가 켜는 [게이트웨이 모델 검색](/docs/ko/llm-gateway-protocol#model-discovery) 요청의 타임아웃(밀리초)입니다(기본값: `3000`). 시작 시 게이트웨이가 `/v1/models`에 응답하는 데 3초보다 오래 걸리면 값을 늘립니다. 숫자만 허용되며, `0`, 음수 값 및 기타 표기는 기본값을 유지합니다. Claude Code v2.1.269 이상이 필요합니다 |

340| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 메인 대화 아래에 허용되는 [서브에이전트 계층](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents) 수입니다 (기본값: 3). 기본값에서는 서브에이전트가 자체 서브에이전트를 생성할 수 있으며, 세 번째 계층의 서브에이전트는 더 이상 생성할 수 없습니다. 중첩을 끄려면 `1`로 설정합니다. v2.1.217부터 v2.1.218까지는 기본값이 1이었으므로 제한을 올리지 않으면 서브에이전트가 자체 서브에이전트를 생성할 수 없었으며, v2.1.219에서 기본값이 3으로 올라갔습니다. 숫자로만 된 양의 정수를 허용하며 그 밖의 값은 무시되므로, 제한을 조정할 수는 있지만 제거할 수는 없습니다. Claude Code v2.1.217 이상이 필요합니다 |341| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 메인 대화 아래에 허용되는 [서브에이전트 계층](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents) 수입니다 (기본값: 3). 기본값에서는 서브에이전트가 자체 서브에이전트를 생성할 수 있으며, 세 번째 계층의 서브에이전트는 더 이상 생성할 수 없습니다. 중첩을 끄려면 `1`로 설정합니다. v2.1.217부터 v2.1.218까지는 기본값이 1이었으므로 제한을 올리지 않으면 서브에이전트가 자체 서브에이전트를 생성할 수 없었으며, v2.1.219에서 기본값이 3으로 올라갔습니다. 숫자로만 된 양의 정수를 허용하며 그 밖의 값은 무시되므로, 제한을 조정할 수는 있지만 제거할 수는 없습니다. Claude Code v2.1.217 이상이 필요합니다 |

341| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 병렬로 실행할 수 있는 읽기 전용 도구와 서브에이전트의 최대 수입니다(기본값: 10). 값이 높을수록 병렬성은 증가하지만 더 많은 리소스를 소비합니다 |342| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 병렬로 실행할 수 있는 읽기 전용 도구와 서브에이전트의 최대 수입니다(기본값: 10). 값이 높을수록 병렬성은 증가하지만 더 많은 리소스를 소비합니다 |

342| `CLAUDE_CODE_MAX_TURNS` | 명시적인 제한이 전달되지 않았을 때 에이전트 턴 수를 제한합니다. [`--max-turns`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 같으며, 둘 다 설정된 경우 플래그가 우선합니다. 양의 정수가 아닌 값은 제한 없음으로 취급되지 않고 시작 시 오류와 함께 거부됩니다 |343| `CLAUDE_CODE_MAX_TURNS` | 명시적인 제한이 전달되지 않았을 때 에이전트 턴 수를 제한합니다. [`--max-turns`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 같으며, 둘 다 설정된 경우 플래그가 우선합니다. 양의 정수가 아닌 값은 제한 없음으로 취급되지 않고 시작 시 오류와 함께 거부됩니다 |

343| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | [WebSearch](/docs/ko/tools-reference#session-search-limit) 호출의 상한입니다(기본값: 200). Claude가 상한에 도달하면 이후의 WebSearch 호출은 이미 수집한 정보로 계속 진행하라는 알림을 반환합니다. 상한이 없는 양의 정수를 허용합니다. 그 밖의 값은 무시되고 기본값이 적용되므로 상한을 올릴 수는 있지만 끌 수는 없습니다. Claude Code v2.1.212 이상이 필요합니다 |344| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | [WebSearch](/docs/ko/tools-reference#session-search-limit) 호출의 상한입니다(기본값: 200). Claude가 상한에 도달하면 이후 WebSearch 호출은 이미 수집한 정보로 계속 진행하고 답변에서 그 사실을 밝히라는 알림을 반환합니다. 상한 없는 양의 정수를 허용합니다. 그 외의 값은 무시되고 기본값이 적용되므로, 상한을 높일 수는 있지만 끌 수는 없습니다. Claude Code v2.1.212 이상이 필요합니다 |

345| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 아직 실행 중인 MCP 도구 호출이 [백그라운드 작업으로 이동](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls)하기까지의 경과 시간(밀리초)입니다(기본값: 120000, 즉 2분). 자동 백그라운드 전환을 끄려면 `0`으로 설정합니다. Claude Code v2.1.212 이상이 필요합니다 |346| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 아직 실행 중인 MCP 도구 호출이 [백그라운드 작업으로 이동](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls)하기까지의 경과 시간(밀리초)입니다(기본값: 120000, 즉 2분). 자동 백그라운드 전환을 끄려면 `0`으로 설정합니다. Claude Code v2.1.212 이상이 필요합니다 |

346| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [비대화형](/docs/ko/headless) 세션의 첫 번째 턴이 아직 연결 중인 MCP 서버를 기다리는 시간(밀리초)으로, 기본 [첫 번째 턴 대기](/docs/ko/agent-sdk/mcp#connection-timing)를 대체합니다. 설정하면 대기는 보류 중인 모든 서버를 대상으로 하며, [자체 호스팅 환경](/docs/ko/self-hosted-environments-configuration#connection-timing)에서는 대기 시간만 변경합니다. `0`으로 설정하면 대기를 건너뜁니다. [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 서버는 값과 관계없이 자체 `MCP_TIMEOUT` 대기를 유지합니다. Claude Code v2.1.274 이상이 필요합니다 |347| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [비대화형](/docs/ko/headless) 세션의 첫 번째 턴이 아직 연결 중인 MCP 서버를 기다리는 시간(밀리초)으로, 기본 [첫 번째 턴 대기](/docs/ko/agent-sdk/mcp#connection-timing)를 대체합니다. 설정하면 대기는 보류 중인 모든 서버를 대상으로 하며, [자체 호스팅 환경](/docs/ko/self-hosted-environments-configuration#connection-timing)에서는 대기 시간만 변경합니다. `0`으로 설정하면 대기를 건너뜁니다. [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 서버는 값과 관계없이 자체 `MCP_TIMEOUT` 대기를 유지합니다. Claude Code v2.1.274 이상이 필요합니다 |

599* [`/skill-doctor`](/docs/ko/skills#find-unused-skills) 실행 또는 `/plugin` **Stats** 탭에서 해당 보고서 열기600* [`/skill-doctor`](/docs/ko/skills#find-unused-skills) 실행 또는 `/plugin` **Stats** 탭에서 해당 보고서 열기

600* claude.ai 계정에서 활성화된 [스킬](/docs/ko/skills#where-synced-skills-load) 및 [플러그인](/docs/ko/plugins/loading#synced-plugins)을 터미널 세션에 동기화601* claude.ai 계정에서 활성화된 [스킬](/docs/ko/skills#where-synced-skills-load) 및 [플러그인](/docs/ko/plugins/loading#synced-plugins)을 터미널 세션에 동기화

601* [You should know mod](/docs/ko/interactive-mode#you-should-know-suggestions) 켜기602* [You should know mod](/docs/ko/interactive-mode#you-should-know-suggestions) 켜기

602* VS Code 확장 프로그램의 채팅 패널에서 [mod](/docs/ko/plugins/mods/overview#where-mods-run)가 그리는 내용 보기. mod의 훅은 계속 실행됩니다

603* [advisor 도구](/docs/ko/advisor#requirements) 사용603* [advisor 도구](/docs/ko/advisor#requirements) 사용

604* [아티팩트의 댓글](/docs/ko/artifacts#collect-comments-on-an-artifact) 읽기 또는 답글 달기604* [아티팩트의 댓글](/docs/ko/artifacts#collect-comments-on-an-artifact) 읽기 또는 답글 달기

605* Claude가 [다른 조직의 공개 아티팩트](/docs/ko/artifacts#read-an-artifact-shared-with-you)를 읽도록 하기605* Claude가 [다른 조직의 공개 아티팩트](/docs/ko/artifacts#read-an-artifact-shared-with-you)를 읽도록 하기

613 설치 또는 업그레이드 후 첫 세션613 설치 또는 업그레이드 후 첫 세션

614</h3>614</h3>

615 615

616Claude Code를 설치한 후 또는 새 기능이 추가된 버전으로 업그레이드한 후 첫 세션에서는 [플래그로 제어되는 기능](#features-that-need-feature-flag-fetching)이 누락될 수 있습니다. 또한 해당 세션은 이후 세션과 다른 [권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)로 시작될 수 있습니다. Claude Code가 해당 세션 중에 플래그를 가져오면 이를 머신에 저장하므로, 해당 머신의 다음 세션에서는 기능이 제공되고 평소의 시작 권한 모드가 적용됩니다.616Claude Code를 설치한 후 또는 새 기능이 추가된 버전으로 업그레이드한 후 첫 세션에서는 [플래그로 제어되는 기능](#features-that-need-feature-flag-fetching)이 누락될 수 있습니다. Claude Code가 해당 세션 중에 기능 플래그를 가져오면 이를 머신에 저장하므로, 해당 머신의 다음 세션에서는 기능이 제공됩니다.

~~617~~

618새로 설치한 후 `claude -p`, Agent SDK 또는 VS Code 확장 프로그램과 같은 비대화형 세션에서는 Claude Code가 [시작 권한 모드를 선택](/docs/ko/permission-modes#which-mode-a-session-starts-in)하기 전에 플래그를 가져올 수 있지만, 항상 플래그를 기다리지는 않습니다.

619 617

620다음과 같은 구성에서는 첫 세션 이후의 세션도 새로 가져온 플래그 없이 시작됩니다.618다음과 같은 구성에서는 첫 세션 이후의 세션도 새로 가져온 플래그 없이 시작됩니다.

621 619

622* **매 실행마다 깨끗한 환경**: 각 실행이 CI 컨테이너 또는 이전 세션이 저장한 플래그가 없는 다른 환경에서 시작되는 경우, 모든 실행이 첫 세션이 됩니다620* **매 실행마다 깨끗한 환경**: 각 실행이 CI 컨테이너 또는 이전 세션이 저장한 플래그가 없는 다른 환경에서 시작되는 경우, 모든 실행이 첫 세션이 됩니다

623* **API 키 없는 게이트웨이 토큰**: API 키 없이 `ANTHROPIC_AUTH_TOKEN`으로 인증하고 `ANTHROPIC_BASE_URL`이 [LLM 게이트웨이](/docs/ko/llm-gateway)와 같이 Anthropic이 아닌 호스트를 가리키는 경우, Claude Code에는 플래그를 가져오는 데 사용할 자격 증명이 없습니다621* **API 키 없는 게이트웨이 토큰**: API 키 없이 `ANTHROPIC_AUTH_TOKEN`으로 인증하고 `ANTHROPIC_BASE_URL`이 [LLM 게이트웨이](/docs/ko/llm-gateway)와 같이 Anthropic이 아닌 호스트를 가리키는 경우, Claude Code에는 플래그를 가져오는 데 사용할 자격 증명이 없습니다

624 622

625이러한 구성에서 세션이 시작될 권한 모드를 선택하려면 [다른 권한 모드로 시작하기](/docs/ko/permission-modes#start-in-a-different-mode)를 참조하십시오.

~~626~~

627<h2 id="see-also">623<h2 id="see-also">

628 참고 항목624 참고 항목

629</h2>625</h2>

errors.md +33 −6

Details

41| `Auto mode classifier transcript exceeded context window` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |41| `Auto mode classifier transcript exceeded context window` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |

42| `Agent aborted: auto mode classifier request refused by the safety safeguard` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |42| `Agent aborted: auto mode classifier request refused by the safety safeguard` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |

43| `The server-side auto mode classifier gave no verdict` | [서버 오류](#the-server-returned-no-safety-verdict) |43| `The server-side auto mode classifier gave no verdict` | [서버 오류](#the-server-returned-no-safety-verdict) |

44| `<tool> was not reviewed and did not run: the conversation is too long for auto mode's classifier` | [서버 오류](#was-not-reviewed-and-did-not-run) |

44| `Auto mode is unavailable — the server returned no safety verdict for the last 10 responses` | [서버 오류](#the-server-returned-no-safety-verdict) |45| `Auto mode is unavailable — the server returned no safety verdict for the last 10 responses` | [서버 오류](#the-server-returned-no-safety-verdict) |

45| `Agent terminated early due to an API error` | [서버 오류](#agent-terminated-early-due-to-an-api-error) |46| `Agent terminated early due to an API error` | [서버 오류](#agent-terminated-early-due-to-an-api-error) |

46| `You've hit your session limit` / `You've hit your weekly limit` / `You've hit your Opus limit` / `You've hit your Sonnet limit` | [사용 한도](#youve-hit-your-session-limit) |47| `You've hit your session limit` / `You've hit your weekly limit` / `You've hit your Opus limit` / `You've hit your Sonnet limit` | [사용 한도](#youve-hit-your-session-limit) |

471| [`CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS`](/docs/ko/env-vars) | 설정 안 됨 | `CLAUDE_CODE_RETRY_WATCHDOG`이 설정된 경우 각 API 요청이 `429` 및 `529` 오류가 해소되기를 기다리는 최대 시간(밀리초)입니다. 설정하지 않으면 대기 시간에 제한이 없습니다. Claude Code v2.1.295 이상이 필요합니다. |472| [`CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS`](/docs/ko/env-vars) | 설정 안 됨 | `CLAUDE_CODE_RETRY_WATCHDOG`이 설정된 경우 각 API 요청이 `429` 및 `529` 오류가 해소되기를 기다리는 최대 시간(밀리초)입니다. 설정하지 않으면 대기 시간에 제한이 없습니다. Claude Code v2.1.295 이상이 필요합니다. |

472| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](/docs/ko/env-vars) | 500 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 시작 지연 시간(밀리초)입니다. API가 용량 한계에 도달했을 때 재시도를 더 긴 기간에 걸쳐 분산하려면 최대 32000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](/docs/ko/fast-mode#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.292 이상이 필요합니다. |473| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](/docs/ko/env-vars) | 500 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 시작 지연 시간(밀리초)입니다. API가 용량 한계에 도달했을 때 재시도를 더 긴 기간에 걸쳐 분산하려면 최대 32000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](/docs/ko/fast-mode#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.292 이상이 필요합니다. |

473| [`CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS`](/docs/ko/env-vars) | 32000 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 상한(밀리초)입니다. API가 용량 한계에 도달했을 때 이후 재시도 간격이 계속 벌어지도록 하려면 최대 64000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](/docs/ko/fast-mode#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.296 이상이 필요합니다. |474| [`CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS`](/docs/ko/env-vars) | 32000 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 상한(밀리초)입니다. API가 용량 한계에 도달했을 때 이후 재시도 간격이 계속 벌어지도록 하려면 최대 64000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](/docs/ko/fast-mode#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.296 이상이 필요합니다. |

474| [`API_TIMEOUT_MS`](/docs/ko/env-vars) | 600000 | 요청당 타임아웃(밀리초)입니다. 느린 네트워크나 프록시의 경우 값을 높이세요. [No response from API](#no-response-from-api)에 설명된 대로, Claude Code가 응답 헤더를 기다리는 시간의 상한으로도 사용됩니다. |475| [`API_TIMEOUT_MS`](/docs/ko/env-vars) | 600000 | 각 요청 시도가 응답 헤더를 받기까지 주어지는 시간(밀리초)입니다. 그 이후 스트리밍 응답이 진행되는 시간은 제한하지 않습니다. 느린 네트워크나 프록시의 경우 값을 높이세요. 이 값이 첫 바이트 기한의 상한으로 사용되는 방식은 [No response from API](#no-response-from-api)를 참조하세요. |

475| [`CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES`](/docs/ko/env-vars) | 설정 안 됨 | 시간 초과된 [비스트리밍 요청](#streaming-response-ended-before-any-complete-data-was-received)을 다시 보내는 횟수의 한도입니다. 한도에 도달하면 요청이 실패합니다. 생성하는 데 타임아웃보다 오래 걸리는 Claude의 응답은 다시 보낼 때마다 다시 시간 초과되므로, 더 빨리 실패하려면 `0`과 같은 낮은 값으로 설정하세요. 각 비스트리밍 시도는 로컬 세션에서 300초 후, 또는 `API_TIMEOUT_MS`를 양수 값으로 설정한 경우 해당 시간 후에 시간 초과됩니다. Claude Code v2.1.285 이상이 필요합니다. |476| [`CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES`](/docs/ko/env-vars) | 설정 안 됨 | 시간 초과된 [비스트리밍 요청](#streaming-response-ended-before-any-complete-data-was-received)을 다시 보내는 횟수의 한도입니다. 한도에 도달하면 요청이 실패합니다. 생성하는 데 타임아웃보다 오래 걸리는 Claude의 응답은 다시 보낼 때마다 다시 시간 초과되므로, 더 빨리 실패하려면 `0`과 같은 낮은 값으로 설정하세요. 각 비스트리밍 시도는 로컬 세션에서 300초 후, 또는 `API_TIMEOUT_MS`를 양수 값으로 설정한 경우 해당 시간 후에 시간 초과됩니다. Claude Code v2.1.285 이상이 필요합니다. |

476| [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/ko/env-vars) | 설정 안 됨 | 스트리밍 요청의 첫 번째 응답 바이트에 대한 기한(밀리초)입니다. Claude Code v2.1.242 이상이 필요합니다. 이 값이 설정되지 않았을 때 Claude Code가 기한을 정하는 방법은 [No response from API](#no-response-from-api)를 참조하세요. |477| [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/ko/env-vars) | 설정 안 됨 | 스트리밍 요청의 첫 번째 응답 바이트에 대한 기한(밀리초)입니다. Claude Code v2.1.242 이상이 필요합니다. 이 값이 설정되지 않았을 때 Claude Code가 기한을 정하는 방법은 [No response from API](#no-response-from-api)를 참조하세요. |

477 478

535Request timed out536Request timed out

536```537```

537 538

538이는 높은 부하 기간 동안 또는 모델이 매우 큰 응답을 생성할 때 발생할 수 있습니다. 기본 요청 타임아웃은 10분입니다.539기본 요청 타임아웃은 10분입니다.

539 540

540**수행할 작업:**541**수행할 작업:**

541 542

627<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.628<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.

628```629```

629 630

630대화형 세션에서는 이 메시지 대신 도구 호출 아래에 흐린 `Not run · auto mode's check had no usable answer` 행이 나타납니다. `Ctrl+O`를 눌러 [트랜스크립트 뷰어](/docs/ko/interactive-mode#transcript-viewer)에서 메시지를 확인합니다. [서버가 안전 판정을 반환하지 않음](#the-server-returned-no-safety-verdict) 아래의 거부도 동일한 행을 표시합니다. v2.1.296 이전에는 메시지가 호출 아래에 빨간색 오류로 나타났습니다.631대화형 세션에서는 이 메시지 대신 도구 호출 아래에 흐린 `Not run · auto mode's check had no usable answer` 행이 나타납니다. `Ctrl+O`를 눌러 [트랜스크립트 뷰어](/docs/ko/interactive-mode#transcript-viewer)에서 메시지를 확인합니다. [서버가 안전 판정을 반환하지 않음](#the-server-returned-no-safety-verdict) 아래의 `gave no verdict` 거부도 동일한 행을 표시합니다. v2.1.296 이전에는 메시지가 호출 아래에 빨간색 오류로 나타났습니다.

631 632

632Claude Code가 실패 범주를 결정할 수 있을 때 `temporarily unavailable` 뒤의 괄호에 범주를 명시합니다. 예를 들어 `<model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now`입니다. 범주는 `(rate-limited)`, `(overloaded)`, `(server error)`, `(timed out)` 및 `(connection failed)`입니다. `(timed out)` 또는 `(connection failed)`가 반복되면 연결을 확인하세요. [API에 연결할 수 없음](#unable-to-connect-to-api)을 참조하세요. v2.1.229 이전에는 메시지가 범주를 명시하지 않았고 `Wait briefly and then try this action again`으로 읽혔습니다.633Claude Code가 실패 범주를 결정할 수 있을 때 `temporarily unavailable` 뒤의 괄호에 범주를 명시합니다. 예를 들어 `<model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now`입니다. 범주는 `(rate-limited)`, `(overloaded)`, `(server error)`, `(timed out)` 및 `(connection failed)`입니다. `(timed out)` 또는 `(connection failed)`가 반복되면 연결을 확인하세요. [API에 연결할 수 없음](#unable-to-connect-to-api)을 참조하세요. v2.1.229 이전에는 메시지가 범주를 명시하지 않았고 `Wait briefly and then try this action again`으로 읽혔습니다.

633 634

638* 몇 초 후 재시도합니다. Claude는 동일한 메시지를 보고 일반적으로 자동으로 재시도합니다. 일시적 실패는 [자동 모드 적격성](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)과 무관합니다. 설정을 변경할 필요가 없습니다639* 몇 초 후 재시도합니다. Claude는 동일한 메시지를 보고 일반적으로 자동으로 재시도합니다. 일시적 실패는 [자동 모드 적격성](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)과 무관합니다. 설정을 변경할 필요가 없습니다

639* 재시도가 계속 실패하면 읽기 전용 작업을 계속하고 나중에 차단된 작업으로 돌아옵니다640* 재시도가 계속 실패하면 읽기 전용 작업을 계속하고 나중에 차단된 작업으로 돌아옵니다

640* Amazon Bedrock에서 메시지가 모든 재시도에서 반환되면 계정이 명시된 모델을 호출할 수 있는지 확인합니다: 표준 Amazon Bedrock 모델의 경우 [IAM 정책](/docs/ko/amazon-bedrock#iam-configuration)이 호출을 허용하는지 확인합니다. Mantle 모델 ID의 경우 [AWS 계정 팀에 문의](/docs/ko/amazon-bedrock#mantle-endpoint-errors)합니다641* Amazon Bedrock에서 메시지가 모든 재시도에서 반환되면 계정이 명시된 모델을 호출할 수 있는지 확인합니다: 표준 Amazon Bedrock 모델의 경우 [IAM 정책](/docs/ko/amazon-bedrock#iam-configuration)이 호출을 허용하는지 확인합니다. Mantle 모델 ID의 경우 [AWS 계정 팀에 문의](/docs/ko/amazon-bedrock#mantle-endpoint-errors)합니다

642* 메시지가 모든 재시도에서 반환되고 [`CLAUDE_CODE_AUTO_MODE_MODEL`](/docs/ko/permission-modes#choose-the-classifier-model)에 설정한 모델을 명시하는 경우, 세션이 실행되는 API 또는 클라우드 제공자가 해당 모델 ID를 제공하는지 확인합니다. 제공하지 않으면 변수를 해당 제공자가 제공하는 모델 ID로 설정하거나, 변수를 해제하여 [기본 분류기 모델](/docs/ko/permission-modes#default-classifier-model)을 사용합니다.

641 643

642분류기 요청이 OAuth 토큰이 만료되었거나 다른 세션에서 회전되었기 때문에 실패할 때 Claude Code는 토큰을 새로 고치고 요청을 한 번 재시도하므로 일상적인 토큰 만료는 이 메시지로 표시되지 않습니다. v2.1.216 이전에는 만료되었거나 회전된 토큰이 각 분류기 요청을 실패시켰고 토큰이 새로 고쳐질 때까지 자동 모드가 확인 대상인 모든 작업을 이 메시지와 함께 거부했습니다.644분류기 요청이 OAuth 토큰이 만료되었거나 다른 세션에서 회전되었기 때문에 실패할 때 Claude Code는 토큰을 새로 고치고 요청을 한 번 재시도하므로 일상적인 토큰 만료는 이 메시지로 표시되지 않습니다. v2.1.216 이전에는 만료되었거나 회전된 토큰이 각 분류기 요청을 실패시켰고 토큰이 새로 고쳐질 때까지 자동 모드가 확인 대상인 모든 작업을 이 메시지와 함께 거부했습니다.

643 645

672* 대화형 세션에서 다른 [권한 모드](/docs/ko/permission-modes)로 전환하여 확인 요청이 표시될 때 작업을 승인할 수 있습니다674* 대화형 세션에서 다른 [권한 모드](/docs/ko/permission-modes)로 전환하여 확인 요청이 표시될 때 작업을 승인할 수 있습니다

673* 트리거 내용 없이 새 대화를 시작합니다675* 트리거 내용 없이 새 대화를 시작합니다

674 676

675대화가 분류기의 컨텍스트 윈도우보다 커졌을 때:677대화가 Claude Code의 분류기 요청에 비해 너무 길고 Claude Code가 [자체적으로 압축](#was-not-reviewed-and-did-not-run)할 수 없을 때:

676 678

677```text theme={null}679```text theme={null}

678Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)680Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

715 717

716**수행할 작업:**718**수행할 작업:**

717 719

720* 대화형 세션에서 `Ctrl+O`를 눌러 [트랜스크립트 뷰어](/docs/ko/interactive-mode#transcript-viewer)에서 거부 텍스트를 확인합니다.

721* 거부가 `(the conversation is too long for the check)`를 명시하면 Claude Code 프롬프트에서 `/compact`를 실행하여 대화를 줄입니다. 대화가 짧아질 때까지는 다른 메시지를 보내도 동일한 거부를 받습니다. [자동 압축](/docs/ko/settings-reference#autocompactenabled)을 끈 경우 다시 켜서 다음에는 Claude Code가 자체적으로 압축하도록 합니다.

718* 다른 메시지를 보내 Claude가 다시 시도하도록 합니다. 응답 수 계산이 다시 시작됩니다.722* 다른 메시지를 보내 Claude가 다시 시도하도록 합니다. 응답 수 계산이 다시 시작됩니다.

719* 중지가 반복되고 요청이 [LLM 게이트웨이 또는 프록시](/docs/ko/llm-gateway)를 통과하면 스트리밍 응답을 자르거나 다시 쓰는지 확인합니다. [서버 측 분류기 검토](/docs/ko/permission-modes#server-side-classifier-review)는 어떤 게이트웨이 동작이 거부를 유발하는지 설명하며, [게이트웨이 호환성 가이드](/docs/ko/llm-gateway-protocol#feature-pass-through)는 변경되지 않은 상태로 통과시켜야 할 내용을 나열합니다.723* 중지가 반복되고 요청이 [LLM 게이트웨이 또는 프록시](/docs/ko/llm-gateway)를 통과하면 스트리밍 응답을 자르거나 다시 쓰는지 확인합니다. [서버 측 분류기 검토](/docs/ko/permission-modes#server-side-classifier-review)는 어떤 게이트웨이 동작이 거부를 유발하는지 설명하며, [게이트웨이 호환성 가이드](/docs/ko/llm-gateway-protocol#feature-pass-through)는 변경되지 않은 상태로 통과시켜야 할 내용을 나열합니다.

720* Claude Code를 시작하기 전에 `CLAUDE_CODE_AUTO_MODE_SERVER=0`을 설정하여 대신 자체 분류기 요청을 사용합니다. v2.1.281 이전에는 Claude Code가 Anthropic API에 대한 직접 연결에서 변수를 읽지 않았습니다.724* Claude Code를 시작하기 전에 `CLAUDE_CODE_AUTO_MODE_SERVER=0`을 설정하여 대신 자체 분류기 요청을 사용합니다. v2.1.281 이전에는 Claude Code가 Anthropic API에 대한 직접 연결에서 변수를 읽지 않았습니다.

722 726

723v2.1.280 이전에는 Claude Code가 판정이 없는 응답의 각 작업을 즉시 거부했고 턴을 중지하지 않았습니다.727v2.1.280 이전에는 Claude Code가 판정이 없는 응답의 각 작업을 즉시 거부했고 턴을 중지하지 않았습니다.

724 728

729v2.1.302 이전에는 Anthropic API에 대한 직접 연결에서 Claude Code가 서버 검사에 비해 너무 길어진 대화를 압축하지 않았습니다.

730

731<h3 id="was-not-reviewed-and-did-not-run">

732 Was not reviewed and did not run

733</h3>

734

735`was not reviewed and did not run` 거부는 대화가 너무 길어 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기가 작업을 검사할 수 없으므로 작업이 실행되지 않았음을 의미합니다. Claude Code는 Claude에게 다음 메시지를 반환합니다:

736

737```text theme={null}

738<tool> was not reviewed and did not run: the conversation is too long for auto mode's classifier. Claude Code will try to compact the conversation before the next request; if this action is still needed after that, issue it again and it will be reviewed normally.

739```

740

741압축이 실패하면 분류기가 검사할 수 없는 이후 작업은 다른 두 메시지 중 하나를 받습니다:

742

743* [`gave no verdict (the conversation is too long for the check)`](#the-server-returned-no-safety-verdict) 거부

744* [`Auto mode classifier transcript exceeded context window`](#auto-mode-cannot-determine-the-safety-of-an-action) 메시지

745

746**수행할 작업:**

747

748* 메시지가 알리는 압축이 성공하면 아무것도 할 필요가 없습니다.

749* 두 메시지 중 하나가 표시되면 Claude Code 프롬프트에서 `/compact`를 실행하여 직접 대화를 줄입니다. [자동 압축](/docs/ko/settings-reference#autocompactenabled)을 끈 경우 다시 켜서 다음에는 Claude Code가 자체적으로 압축하도록 합니다.

750

725<h3 id="agent-terminated-early-due-to-an-api-error">751<h3 id="agent-terminated-early-due-to-an-api-error">

726 API 오류로 인해 에이전트가 조기에 종료됨752 API 오류로 인해 에이전트가 조기에 종료됨

727</h3>753</h3>

4554* 오류가 지정하는 각 항목을 [서브에이전트에서 사용 가능한 도구](/docs/ko/sub-agents#available-tools)에 대해 수정합니다.4580* 오류가 지정하는 각 항목을 [서브에이전트에서 사용 가능한 도구](/docs/ko/sub-agents#available-tools)에 대해 수정합니다.

4555* 세션에 없는 도구의 항목을 제거합니다. 예를 들어 연결되지 않은 서버의 MCP 도구입니다.4581* 세션에 없는 도구의 항목을 제거합니다. 예를 들어 연결되지 않은 서버의 MCP 도구입니다.

4556* 항목이 연결된 MCP 서버를 지정하는 경우, 해당 서버의 [도구 이름](/docs/ko/permissions#mcp)에 표기된 서버 이름과 항목을 비교합니다. 예를 들어 `mcp__reports__v2__get_totals`의 `reports__v2`입니다. 해당 서버의 경우 `mcp__` 뒤에 전체 이름과 `__*`를 붙인 `mcp__reports__v2__*`로 작성합니다. `reports`라는 서버를 지정하는 더 짧은 `mcp__reports`를 사용하면 서브에이전트는 `reports__v2` 도구를 하나도 받지 못합니다.4582* 항목이 연결된 MCP 서버를 지정하는 경우, 해당 서버의 [도구 이름](/docs/ko/permissions#mcp)에 표기된 서버 이름과 항목을 비교합니다. 예를 들어 `mcp__reports__v2__get_totals`의 `reports__v2`입니다. 해당 서버의 경우 `mcp__` 뒤에 전체 이름과 `__*`를 붙인 `mcp__reports__v2__*`로 작성합니다. `reports`라는 서버를 지정하는 더 짧은 `mcp__reports`를 사용하면 서브에이전트는 `reports__v2` 도구를 하나도 받지 못합니다.

4557* [백그라운드 서브에이전트가 제거하는](/docs/ko/sub-agents#available-tools) 도구(예: `CronCreate`)의 경우 항목을 제거합니다. 도구를 유지하려면 [포크 모드를 끄고](/docs/ko/sub-agents#turn-fork-mode-on-or-off) Claude에 서브에이전트를 포그라운드에서 실행하도록 요청합니다.4583* [백그라운드 서브에이전트가 제거하는](/docs/ko/sub-agents#available-tools) 도구(예: `CronCreate`)의 경우 항목을 제거합니다.

4584* 대신 `CronCreate`와 같은 도구를 유지하려면 [Claude가 서브에이전트를 기다리도록 합니다](/docs/ko/sub-agents#let-claude-wait-for-a-subagent). Claude가 기다리는 서브에이전트는 포그라운드에서 실행되어 도구를 유지하기 때문입니다. 정의에 `background: true`가 설정되어 있으면 해당 필드가 서브에이전트를 백그라운드에 유지하므로 먼저 해당 필드를 제거합니다.

4558* 도구를 나열하는 대신 `tools` 필드를 삭제하여 서브에이전트에 [서브에이전트에서 사용 가능한 모든 도구](/docs/ko/sub-agents#available-tools)를 제공합니다.4585* 도구를 나열하는 대신 `tools` 필드를 삭제하여 서브에이전트에 [서브에이전트에서 사용 가능한 모든 도구](/docs/ko/sub-agents#available-tools)를 제공합니다.

4559* `Agent`만 포함하는 `tools` 목록의 경우 [깊이 제한](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)을 높이거나 에이전트에 최소한 하나의 다른 도구를 제공합니다. Claude Code는 해당 제한에서 `Agent`를 보류하므로 다른 항목이 없는 목록은 도구 없음으로 해석됩니다.4586* `Agent`만 포함하는 `tools` 목록의 경우 [깊이 제한](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)을 높이거나 에이전트에 최소한 하나의 다른 도구를 제공합니다. Claude Code는 해당 제한에서 `Agent`를 보류하므로 다른 항목이 없는 목록은 도구 없음으로 해석됩니다.

4560 4587

5405**수행할 작업:**5432**수행할 작업:**

5406 5433

5407* VS Code에서 오류와 함께 표시되는 **View output logs** 링크를 따라 기본 오류를 확인합니다.5434* VS Code에서 오류와 함께 표시되는 **View output logs** 링크를 따라 기본 오류를 확인합니다.

5408* Agent SDK 애플리케이션에서 메시지 루프 주변의 오류를 캡처합니다. [CLI process exit](/docs/ko/agent-sdk/troubleshooting#cli-process-exit) 아래의 항목은 각 SDK 언어에서 코드가 수신하는 내용을 다룹니다.5435* Agent SDK 애플리케이션에서 메시지 루프 주변의 오류를 캡처합니다. [CLI 프로세스 종료](/docs/ko/agent-sdk/troubleshooting#cli-process-exit) 아래의 항목은 각 SDK 언어에서 코드가 수신하는 내용을 다룹니다.

5409* 터미널에서 동일한 프로젝트에서 `claude`를 실행합니다. 오류는 일반적으로 실제 오류 메시지와 함께 재현되며, 이를 이 페이지에서 조회할 수 있습니다.5436* 터미널에서 동일한 프로젝트에서 `claude`를 실행합니다. 오류는 일반적으로 실제 오류 메시지와 함께 재현되며, 이를 이 페이지에서 조회할 수 있습니다.

5410* 터미널에서 `claude doctor`를 실행하여 설치 및 구성을 확인합니다.5437* 터미널에서 `claude doctor`를 실행하여 설치 및 구성을 확인합니다.

5411 5438

fast-mode.md +1 −1

Details

47* 빠른 모드가 활성화되어 있는 동안 프롬프트 옆에 작은 `↯` 아이콘이 나타납니다47* 빠른 모드가 활성화되어 있는 동안 프롬프트 옆에 작은 `↯` 아이콘이 나타납니다

48* 언제든지 `/fast`를 다시 실행하여 빠른 모드가 켜져 있는지 꺼져 있는지 확인합니다48* 언제든지 `/fast`를 다시 실행하여 빠른 모드가 켜져 있는지 꺼져 있는지 확인합니다

49 49

50Opus 5.5는 Claude Code v2.1.280 이상에서 빠른 모드 기본값입니다. v2.1.280 이전에는 v2.1.219부터 Opus 5로 기본 설정되었고, v2.1.154부터 v2.1.218까지는 Opus 4.8로 기본 설정되었으며, v2.1.142부터 v2.1.153까지는 Opus 4.7로 기본 설정되었습니다.50Opus 5.5는 Claude Code v2.1.280 이상에서 빠른 모드 기본값입니다. v2.1.280 이전에는 v2.1.219부터 Opus 5로 기본 설정되었고, v2.1.154부터 v2.1.218까지는 Opus 4.8로 기본 설정되었습니다.

51 51

52`/fast`를 다시 실행하여 빠른 모드를 비활성화하면 Opus에 유지됩니다. 다른 모델로 전환하려면 `/model`을 사용합니다.52`/fast`를 다시 실행하여 빠른 모드를 비활성화하면 Opus에 유지됩니다. 다른 모델로 전환하려면 `/model`을 사용합니다.

53 53

fullscreen.md +3 −3

Details

101* **프롬프트 입력 필드를 클릭**하여 입력 중인 텍스트의 어디든지 커서를 위치시킵니다.101* **프롬프트 입력 필드를 클릭**하여 입력 중인 텍스트의 어디든지 커서를 위치시킵니다.

102* **`/` 명령어 또는 `@` 파일 목록의 제안을 클릭**하여 수락합니다. 마우스를 가져가면 커서 아래의 행이 강조됩니다.102* **`/` 명령어 또는 `@` 파일 목록의 제안을 클릭**하여 수락합니다. 마우스를 가져가면 커서 아래의 행이 강조됩니다.

103* **선택 메뉴의 옵션을 클릭**하여 선택합니다. 이는 권한 프롬프트, `/model`, `/config` 및 옵션 목록을 표시하는 기타 대화상자를 포함합니다.103* **선택 메뉴의 옵션을 클릭**하여 선택합니다. 이는 권한 프롬프트, `/model`, `/config` 및 옵션 목록을 표시하는 기타 대화상자를 포함합니다.

104* **다중 선택 메뉴의 옵션을 클릭**하여 토글하고, 제출 버튼을 클릭하여 선택 사항을 확인합니다. 다중 선택 질문의 `기타` 행과 같은 자유 텍스트 행을 클릭하면 입력 필드에 포커스가 이동하여 답변을 입력할 수 있습니다. Claude Code v2.1.208 이상이 필요합니다.104* **다중 선택 메뉴의 옵션을 클릭**하여 토글하고, 제출 버튼을 클릭하여 선택 사항을 확인합니다. 다중 선택 질문의 `Other` 행과 같은 자유 텍스트 행을 클릭하면 입력 필드에 포커스가 이동하여 답변을 입력할 수 있습니다.

105* **`/config` 패널에서 설정의 값을 클릭**하여 변경하고, 마우스 휠로 설정 목록을 스크롤합니다. Claude Code v2.1.271 이상이 필요합니다.105* **`/config` 패널에서 설정의 값을 클릭**하여 변경하고, 마우스 휠로 설정 목록을 스크롤합니다. Claude Code v2.1.271 이상이 필요합니다.

106* **선택 또는 다중 선택 메뉴를 마우스 휠로 스크롤**하여 한 번에 표시되는 것보다 더 많은 옵션이 있을 때(예: 짧은 터미널 창의 `/model` 목록), 휠이 포인터가 옵션 위에 있을 때 목록을 스크롤합니다. Claude Code v2.1.280 이상이 필요합니다.106* **선택 또는 다중 선택 메뉴를 마우스 휠로 스크롤**하여 한 번에 표시되는 것보다 더 많은 옵션이 있을 때(예: 짧은 터미널 창의 `/model` 목록), 휠이 포인터가 옵션 위에 있을 때 목록을 스크롤합니다. Claude Code v2.1.280 이상이 필요합니다.

107* **스크롤바가 있는 오버플로우 목록을 스크롤합니다.** `/skills`, `/mcp` 및 `/plugin`의 설치됨 목록과 같은 목록 패널에서, 포인터가 목록 위에 있을 때 더 많은 행이 맞지 않는 목록 옆에 스크롤바가 나타납니다. 트랙을 클릭하여 해당 지점으로 이동하거나 썸을 드래그합니다. Claude Code v2.1.281 이상이 필요합니다.107* **스크롤바가 있는 오버플로우 목록을 스크롤합니다.** `/skills`, `/mcp` 및 `/plugin`의 설치됨 목록과 같은 목록 패널에서, 포인터가 목록 위에 있을 때 더 많은 행이 맞지 않는 목록 옆에 스크롤바가 나타납니다. 트랙을 클릭하여 해당 지점으로 이동하거나 썸을 드래그합니다. Claude Code v2.1.281 이상이 필요합니다.

147| 마우스 휠 | 한 번에 몇 줄씩 스크롤 |147| 마우스 휠 | 한 번에 몇 줄씩 스크롤 |

148 148

149[압축](/docs/ko/context-window#what-survives-compaction) 후에도 세션의 시작 부분으로 스크롤백할 수 있습니다. Claude는 압축 요약에서 계속 작동하지만, Claude Code는 반복된 압축 전체에서 전체 화면 스크롤백에서 모든 이전 메시지를 유지합니다.149[압축](/docs/ko/context-window#what-survives-compaction)된 세션을 닫았다가 [재개](/docs/ko/sessions#what-a-resumed-session-restores)하면 위로 스크롤할 때 `Conversation compacted` 행에서 멈추며, 이전 메시지는 디스크의 [트랜스크립트 파일](/docs/ko/sessions#where-transcripts-are-stored)에 그대로 남아 있습니다. 해당 메시지의 세부 정보가 필요하면 Claude에게 그 파일에서 찾아보도록 요청하세요.

150 150

151MacBook 키보드와 같이 전용 `PgUp`, `PgDn`, `Home` 또는 `End` 키가 없는 키보드에서는 `Fn`을 화살표 키와 함께 누르세요: `Fn+↑`는 `PgUp`을 보내고, `Fn+↓`는 `PgDn`을 보내고, `Fn+←`는 `Home`을 보내고, `Fn+→`는 `End`를 보냅니다. `Ctrl+Fn+→`는 macOS의 Claude Code에 도달하지 않으므로 MacBook 키보드는 기본적으로 작동하는 하단으로 이동 단축키가 없습니다. 대신 다음 옵션 중 하나를 사용하세요:151MacBook 키보드와 같이 전용 `PgUp`, `PgDn`, `Home` 또는 `End` 키가 없는 키보드에서는 `Fn`을 화살표 키와 함께 누르세요: `Fn+↑`는 `PgUp`을 보내고, `Fn+↓`는 `PgDn`을 보내고, `Fn+←`는 `Home`을 보내고, `Fn+→`는 `End`를 보냅니다. `Ctrl+Fn+→`는 macOS의 Claude Code에 도달하지 않으므로 MacBook 키보드는 기본적으로 작동하는 하단으로 이동 단축키가 없습니다. 대신 다음 옵션 중 하나를 사용하세요:

152 152

162 자동 추적162 자동 추적

163</h3>163</h3>

164 164

165위로 스크롤하면 자동 추적이 일시 중지되어 새 출력이 사용자를 다시 하단으로 끌어당기지 않습니다. 위로 스크롤했을 때 `하단으로 이동` 버튼이 대화 기록의 하단 가장자리 위에 떠 있으며, 새 출력이 도착하면 `3개의 새 메시지`와 같은 개수를 표시합니다. 이를 클릭하거나, `Ctrl+End`를 누르거나, 하단까지 스크롤하여 추적을 재개하세요.165위로 스크롤하면 자동 추적이 일시 중지되어 새 출력이 사용자를 다시 하단으로 끌어당기지 않습니다. 위로 스크롤했을 때 `Jump to bottom` 버튼이 트랜스크립트의 하단 가장자리 위에 떠 있으며, 새 출력이 도착하면 `3 new messages`와 같은 개수를 표시합니다. 이를 클릭하거나, `Ctrl+End`를 누르거나, 하단까지 스크롤하여 추적을 재개하세요.

166 166

167자동 추적이 일시 중지된 동안 응답 스트리밍이 완료되면 뷰도 스크롤한 위치에 유지됩니다.167자동 추적이 일시 중지된 동안 응답 스트리밍이 완료되면 뷰도 스크롤한 위치에 유지됩니다.

168 168

headless.md +5 −4

Details

138 파이프된 stdin은 10MB로 제한됩니다. 제한을 초과하면 Claude Code는 명확한 오류 메시지와 함께 0이 아닌 상태로 종료됩니다. 더 큰 입력으로 작업하려면 콘텐츠를 파일에 작성하고 파이프하는 대신 프롬프트에서 파일 경로를 참조하십시오.138 파이프된 stdin은 10MB로 제한됩니다. 제한을 초과하면 Claude Code는 명확한 오류 메시지와 함께 0이 아닌 상태로 종료됩니다. 더 큰 입력으로 작업하려면 콘텐츠를 파일에 작성하고 파이프하는 대신 프롬프트에서 파일 경로를 참조하십시오.

139</Note>139</Note>

140 140

141Claude Code가 stdin을 읽을 수 없는 경우(예: 이를 시작한 프로세스가 끝을 연결 해제한 경우) Claude Code는 stderr에 경고를 인쇄하고 명령줄의 프롬프트로 계속 진행합니다. v2.1.211 이전에는 Windows에서 읽을 수 없는 stdin이 세션을 충돌시키거나 출력 없이 자동으로 종료되었습니다.141Claude Code가 stdin을 읽을 수 없는 경우(예: 이를 시작한 프로세스가 끝을 연결 해제한 경우) Claude Code는 stderr에 경고를 인쇄하고 명령줄의 프롬프트로 계속 진행합니다.

142 142

143<h3 id="add-claude-to-a-build-script">143<h3 id="add-claude-to-a-build-script">

144 빌드 스크립트에 Claude 추가144 빌드 스크립트에 Claude 추가

213 213

214스트림의 마지막 줄은 최종 응답 텍스트, 비용 및 세션 메타데이터가 포함된 `result` 메시지입니다.214스트림의 마지막 줄은 최종 응답 텍스트, 비용 및 세션 메타데이터가 포함된 `result` 메시지입니다.

215 215

216소비자가 스트림을 천천히 읽으면 Claude Code는 대기 중인 출력이 드레인될 때까지 기다리며, 대기 시간을 여전히 대기 중인 양에 따라 조정하고 최대 30초로 제한합니다. v2.1.214 이전에는 종료 대기가 약 2초로 제한되어 큰 응답의 끝이 잘릴 수 있었습니다.216소비자가 스트림을 천천히 읽으면 Claude Code는 대기 중인 출력이 드레인될 때까지 기다리며, 대기 시간을 여전히 대기 중인 양에 따라 조정하고 최대 30초로 제한합니다.

217 217

218다음 예제는 [jq](https://jqlang.org/)를 사용하여 텍스트 델타를 필터링하고 스트리밍 텍스트만 표시합니다. `-r` 플래그는 원시 문자열(따옴표 없음)을 출력하고 `-j`는 줄 바꿈 없이 조인하므로 토큰이 연속으로 스트리밍됩니다:218다음 예제는 [jq](https://jqlang.org/)를 사용하여 텍스트 델타를 필터링하고 스트리밍 텍스트만 표시합니다. `-r` 플래그는 원시 문자열(따옴표 없음)을 출력하고 `-j`는 줄 바꿈 없이 조인하므로 토큰이 연속으로 스트리밍됩니다:

219 219

249 249

250이러한 메시지 중 일부가 스트림에서 누락된 경우 Claude Code 버전이 다음 최소 버전을 충족하는지 확인하십시오:250이러한 메시지 중 일부가 스트림에서 누락된 경우 Claude Code 버전이 다음 최소 버전을 충족하는지 확인하십시오:

251 251

252* **`--forward-subagent-text` 및 `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`**: v2.1.211 이상

253* **모든 중첩 깊이에서의 전달**: v2.1.219 이상252* **모든 중첩 깊이에서의 전달**: v2.1.219 이상

254* **Claude가 주 대화에서 Skill 도구로 시작하는 포크된 스킬**: `tool_use` 및 `tool_result` 블록은 v2.1.86 이상, 첫 번째 `user` 메시지와 텍스트 및 사고 블록은 v2.1.265 이상253* **Claude가 주 대화에서 Skill 도구로 시작하는 포크된 스킬**: `tool_use` 및 `tool_result` 블록은 v2.1.86 이상, 첫 번째 `user` 메시지와 텍스트 및 사고 블록은 v2.1.265 이상

255* **포크된 스킬이 생성하는 서브에이전트의 메시지, 그리고 서브에이전트 또는 다른 포크된 스킬 내에서 시작된 포크된 스킬의 메시지**: v2.1.275 이상254* **포크된 스킬이 생성하는 서브에이전트의 메시지, 그리고 서브에이전트 또는 다른 포크된 스킬 내에서 시작된 포크된 스킬의 메시지**: v2.1.275 이상

336 --allowedTools "Bash,Read,Edit"335 --allowedTools "Bash,Read,Edit"

337```336```

338 337

339전체 세션에 대한 기준선을 설정하려면 개별 도구를 나열하는 대신 [권한 모드](/docs/ko/permission-modes)를 전달합니다. 권한 모드를 설정하지 않는 실행은 [기본 제공 시작 권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)를 사용하며, 이는 `auto`일 수 있으므로 원하는 권한 모드를 전달합니다:338나열하지 않은 도구에 대한 호출은 승인이 필요하지 않으면 실행됩니다. [Manual 모드](/docs/ko/permission-modes#available-modes) `claude -p` 실행에서 승인이 필요한 호출은 [`PermissionRequest` 훅](/docs/ko/hooks#permissionrequest) 또는 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)과 같은 무언가가 승인하지 않으면 거부됩니다. Claude Code v2.1.302 이상에서는 [권한 모드를 설정하는 것이 없을 때](/docs/ko/permission-modes#which-mode-a-non-interactive-run-starts-in) `claude -p` 실행이 Manual 모드에서 시작됩니다.

339

340개별 도구를 나열하는 대신 전체 세션에 대한 기준선을 설정하려면 `--permission-mode`로 `auto`, `dontAsk` 또는 `acceptEdits`와 같은 [권한 모드](/docs/ko/permission-modes)를 전달합니다:

340 341

341* **`auto`**: `--permission-mode auto`를 전달하여 사용자 대신 분류기가 대부분의 작업을 검토하도록 합니다342* **`auto`**: `--permission-mode auto`를 전달하여 사용자 대신 분류기가 대부분의 작업을 검토하도록 합니다

342* **`dontAsk`**: Claude Code는 그렇지 않으면 프롬프트할 모든 호출을 거부하며, 이는 잠긴 CI 실행에 유용합니다. Manual 모드에서 승인이 필요하지 않은 작업(예: 작업 디렉터리의 파일 읽기 및 [읽기 전용 명령 집합](/docs/ko/permissions#read-only-commands))과 `--allowedTools` 항목 또는 `permissions.allow` 규칙이 적용되는 작업은 여전히 실행됩니다. `AskUserQuestion`, [조직이 `ask`로 설정한](/docs/ko/mcp#organization-controls-on-connector-tools) 커넥터 도구, [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구 및 [네트워크 경로에서의 읽기](/docs/ko/permissions#network-paths)는 허용 규칙이 일치해도 거부됩니다343* **`dontAsk`**: Claude Code는 그렇지 않으면 프롬프트할 모든 호출을 거부하며, 이는 잠긴 CI 실행에 유용합니다. Manual 모드에서 승인이 필요하지 않은 작업(예: 작업 디렉터리의 파일 읽기 및 [읽기 전용 명령 집합](/docs/ko/permissions#read-only-commands))과 `--allowedTools` 항목 또는 `permissions.allow` 규칙이 적용되는 작업은 여전히 실행됩니다. `AskUserQuestion`, [조직이 `ask`로 설정한](/docs/ko/mcp#organization-controls-on-connector-tools) 커넥터 도구, [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구 및 [네트워크 경로에서의 읽기](/docs/ko/permissions#network-paths)는 허용 규칙이 일치해도 거부됩니다

hooks.md +26 −32

Details

423* **[프롬프트 hook](#prompt-and-agent-hook-fields)** (`type: "prompt"`): Claude 모델에 단일 턴 평가를 위한 프롬프트를 보냅니다. 모델은 결정을 JSON으로 반환합니다. [프롬프트 기반 hook](#prompt-based-hooks)을 참조하십시오.423* **[프롬프트 hook](#prompt-and-agent-hook-fields)** (`type: "prompt"`): Claude 모델에 단일 턴 평가를 위한 프롬프트를 보냅니다. 모델은 결정을 JSON으로 반환합니다. [프롬프트 기반 hook](#prompt-based-hooks)을 참조하십시오.

424* **[에이전트 hook](#prompt-and-agent-hook-fields)** (`type: "agent"`): Read, Grep 및 Glob과 같은 도구를 사용하여 조건을 확인한 후 결정을 반환할 수 있는 서브에이전트를 생성합니다. 에이전트 hook은 실험적이며 변경될 수 있습니다. [에이전트 기반 hook](#agent-based-hooks)을 참조하십시오.424* **[에이전트 hook](#prompt-and-agent-hook-fields)** (`type: "agent"`): Read, Grep 및 Glob과 같은 도구를 사용하여 조건을 확인한 후 결정을 반환할 수 있는 서브에이전트를 생성합니다. 에이전트 hook은 실험적이며 변경될 수 있습니다. [에이전트 기반 hook](#agent-based-hooks)을 참조하십시오.

425 425

426일치하는 모든 hook은 병렬로 실행됩니다. 동일한 핸들러를 둘 이상의 설정 파일에서 정의하면 한 번 실행됩니다. 플러그인 또는 스킬의 동일한 핸들러 복사본은 별도로 유지됩니다.426이벤트가 발생하면 일치하는 hook이 병렬로 실행됩니다. 그중 프롬프트 또는 에이전트 hook이 12개를 초과하면 한 번에 12개가 실행되고 나머지는 실행 중인 hook이 완료되는 대로 시작됩니다. 대기 중인 각 hook의 [`timeout`](#common-fields)은 해당 hook이 시작될 때부터 계산됩니다.

427

428동일한 핸들러를 둘 이상의 설정 파일에서 정의하면 한 번 실행됩니다. 플러그인 또는 스킬의 동일한 핸들러 복사본은 별도로 유지됩니다.

427 429

428핸들러는 Claude Code의 환경이 있는 현재 디렉터리에서 실행됩니다. 예를 들어 다른 셸이 세션 중간에 삭제한 worktree 또는 임시 디렉터리와 같이 현재 디렉터리가 더 이상 존재하지 않으면 Claude Code는 다음 중 여전히 존재하는 첫 번째 디렉터리에서 명령 hook을 실행합니다: 세션이 시작된 디렉터리, 프로젝트 루트, 홈 디렉터리 또는 시스템 임시 디렉터리. Claude Code는 [디버그 로그](#debug-hooks)에서 폴백 디렉터리의 이름을 지정하는 경고를 기록합니다. 데스크톱 앱에서 시작하는 worktree 세션의 경우 [worktree가 주 체크아웃과 공유하는 항목](/docs/ko/worktrees#what-worktrees-share-with-the-main-checkout)을 참조하십시오.430핸들러는 Claude Code의 환경이 있는 현재 디렉터리에서 실행됩니다. 예를 들어 다른 셸이 세션 중간에 삭제한 worktree 또는 임시 디렉터리와 같이 현재 디렉터리가 더 이상 존재하지 않으면 Claude Code는 다음 중 여전히 존재하는 첫 번째 디렉터리에서 명령 hook을 실행합니다: 세션이 시작된 디렉터리, 프로젝트 루트, 홈 디렉터리 또는 시스템 임시 디렉터리. Claude Code는 [디버그 로그](#debug-hooks)에서 폴백 디렉터리의 이름을 지정하는 경고를 기록합니다. 데스크톱 앱에서 시작하는 worktree 세션의 경우 [worktree가 주 체크아웃과 공유하는 항목](/docs/ko/worktrees#what-worktrees-share-with-the-main-checkout)을 참조하십시오.

429 431

445 447

446`if` 필드는 정확히 하나의 권한 규칙을 보유합니다. 규칙을 결합하기 위한 `&&`, `||` 또는 목록 구문이 없습니다. 여러 조건을 적용하려면 각각에 대해 별도의 hook 핸들러를 정의하십시오.448`if` 필드는 정확히 하나의 권한 규칙을 보유합니다. 규칙을 결합하기 위한 `&&`, `||` 또는 목록 구문이 없습니다. 여러 조건을 적용하려면 각각에 대해 별도의 hook 핸들러를 정의하십시오.

447 449

448파일 도구의 `if` 조건에서 `"Edit(src/**)"` 같은 단일 세그먼트 디렉터리 패턴은 작업 디렉터리의 `src` 디렉터리와 그 아래의 파일만 일치합니다. 모든 깊이에서 `src`라는 디렉터리와 일치하려면 `"Edit(**/src/**)"` 형식으로 작성하십시오. v2.1.214 이전에는 `"Edit(src/**)"`가 작업 디렉터리 아래의 모든 깊이에서 `src`라는 디렉터리와 일치했습니다.450파일 도구의 `if` 조건에서 `"Edit(src/**)"` 같은 단일 세그먼트 디렉터리 패턴은 작업 디렉터리의 `src` 디렉터리와 그 아래의 파일만 일치합니다. 모든 깊이에서 `src`라는 디렉터리와 일치하려면 `"Edit(**/src/**)"` 형식으로 작성하십시오.

449 451

450<h4 id="bash-if-matching">452<h4 id="bash-if-matching">

451 `if` 패턴이 Bash 명령과 일치하는 방식453 `if` 패턴이 Bash 명령과 일치하는 방식

825 종료 코드 출력827 종료 코드 출력

826</h3>828</h3>

827 829

828hook의 종료 코드는 도구 호출이나 프롬프트처럼 hook을 트리거한 작업을 계속 진행할지를 Claude Code에 알려줍니다. 완료된 실행의 결과는 다음 세 가지 중 하나입니다:830hook 실행이 끝나면 Claude Code는 종료 코드를 사용하여 도구 호출이나 프롬프트처럼 hook을 트리거한 작업을 계속 진행할지 결정합니다:

829 831

830* **성공**: hook이 0으로 종료합니다. Claude Code는 hook이 출력한 [JSON 출력](#json-output) 필드를 적용하며, 해당 필드가 작업을 차단하거나 거부하지 않는 한 작업이 진행됩니다. 예외는 [백그라운드 프로세스를 시작하는 hook](#hooks-that-start-a-background-process)에서 다룹니다.832* **성공**: hook이 0으로 종료합니다. Claude Code는 hook이 출력한 [JSON 출력](#json-output) 필드를 적용하며, 해당 필드가 작업을 차단하거나 거부하지 않는 한 작업이 진행됩니다. 예외는 [백그라운드 프로세스를 시작하는 hook](#hooks-that-start-a-background-process)에서 다룹니다.

831* **차단 오류**: hook이 2로 종료합니다. [차단할 수 있는 이벤트](#exit-code-2-behavior-per-event)에서 Claude Code는 작업을 중지합니다.833* **차단 오류**: hook이 2로 종료합니다. [차단할 수 있는 이벤트](#exit-code-2-behavior-per-event)에서 Claude Code는 작업을 중지합니다.

853 종료 코드 0855 종료 코드 0

854</h4>856</h4>

855 857

856종료 0은 성공을 의미하며, 구조화된 제어를 위해 JSON을 출력할 때 의도된 종료 코드입니다.858종료 0은 성공을 의미하며, 구조화된 제어를 위해 JSON을 출력할 때 의도된 종료 코드입니다. hook이 0으로 종료하지만 구문 분석할 수 없거나 [스키마 검증](#json-output)에 실패하는 JSON을 출력하면, [실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)이 아닌 한 작업이 진행됩니다. 이 실행은 필드가 적용된 성공이 아니라 [차단하지 않는 오류](#exit-code-output)가 됩니다.

~~857~~

858대부분의 이벤트에서 Claude Code는 stdout을 디버그 로그에 기록하고 트랜스크립트에는 표시하지 않습니다. 예외는 `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart`, `PostModelSwitch`이며, 여기서 Claude Code는 일반 텍스트 stdout을 Claude가 보고 활용할 수 있는 컨텍스트로 추가합니다.

859 859

860[async](#how-async-hooks-execute)가 아닌 hook의 경우, Claude Code는 전체 출력이 주변에 공백 외에는 아무것도 없는 하나의 JSON 객체일 때 stdout을 [JSON 출력](#json-output)으로 구문 분석하고, 그렇지 않으면 일반 텍스트 또는 구문 분석 실패로 처리합니다:860출력을 수정하려면 `<hook name> hook error` 알림에 표시되는 구문 분석 또는 검증 메시지를 활용합니다. [async](#how-async-hooks-execute)가 아닌 hook의 경우, 한 줄 또는 여러 줄에 걸쳐 하나의 JSON 객체를 출력하고 그 주변에 공백 외에는 아무것도 없을 때만 stdout이 [JSON 출력](#json-output)으로 간주됩니다. Claude Code는 그 밖의 stdout을 일반 텍스트 또는 구문 분석 실패로 읽습니다:

861 861

862* **한 줄 또는 여러 줄에 걸친 하나의 JSON 객체**: JSON 출력으로 구문 분석됩니다.

863* **`{`로 시작하지 않거나, `{`로 시작하지만 `}`로 끝나지 않는 출력**: 일반 텍스트입니다. 이 규칙에 따라 JSON 배열과 따옴표로 묶인 JSON 문자열은 일반 텍스트입니다.862* **`{`로 시작하지 않거나, `{`로 시작하지만 `}`로 끝나지 않는 출력**: 일반 텍스트입니다. 이 규칙에 따라 JSON 배열과 따옴표로 묶인 JSON 문자열은 일반 텍스트입니다.

864* **각각 자체적으로 JSON으로 구문 분석되는 두 줄 이상이며, 첫 줄이 `{`로 시작하고 마지막 줄이 `}`로 끝나는 출력**: 필드를 설정하는 JSON 출력 객체인 줄이 없으면 일반 텍스트이고, 그러한 줄이 있으면 구문 분석 실패입니다.863* **각각 자체적으로 JSON으로 구문 분석되는 두 줄 이상이며, 첫 줄이 `{`로 시작하고 마지막 줄이 `}`로 끝나는 출력**: 필드를 설정하는 JSON 출력 객체인 줄이 없으면 일반 텍스트입니다. 그러한 줄이 있으면 구문 분석 실패이므로, 해당 객체만 stdout에 출력하고 다른 내용은 출력하지 않습니다.

865* **`{`로 시작하고 `}`로 끝나지만 유효한 JSON이 아닌 그 밖의 출력**: 구문 분석 실패입니다.864* **`{`로 시작하고 `}`로 끝나지만 유효한 JSON이 아닌 그 밖의 출력**: 구문 분석 실패입니다.

866 865

867[실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)이 아닌 한, 구문 분석 실패 또는 [스키마 검증](#json-output)에 실패한 구문 분석된 객체는 [차단하지 않는 오류](#exit-code-output)입니다. `<hook name> hook error` 알림에 구문 분석 또는 검증 메시지가 표시됩니다. 일반 텍스트 stdout을 컨텍스트로 추가하는 이벤트에서 Claude Code는 구문 분석에 실패한 stdout을 추가하지 않습니다.866대부분의 이벤트에서 Claude Code는 stdout을 디버그 로그에 기록하고 트랜스크립트에는 표시하지 않습니다. 예외는 `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart`, `PostModelSwitch`이며, 여기서 Claude Code는 일반 텍스트 stdout을 Claude가 보고 활용할 수 있는 컨텍스트로 추가합니다. 이러한 이벤트에서 Claude Code는 구문 분석에 실패한 stdout을 추가하지 않습니다.

868 867

869Claude는 0으로 종료하는 hook의 stderr을 보지 못합니다. `PreToolUse`와 같은 이벤트에서 직접 읽으려면 [디버그 로깅](#debug-hooks)을 활성화합니다. `PostToolUse` 또는 `PostToolUseFailure` hook에서 Claude에 경고를 표시하려면 대신 종료 2로 나가면 도구가 이미 실행되었더라도 [Claude가 stderr을 봅니다](#exit-code-2-behavior-per-event).868Claude는 0으로 종료하는 hook의 stderr을 보지 못합니다. `PreToolUse`와 같은 이벤트에서 직접 읽으려면 [디버그 로깅](#debug-hooks)을 활성화합니다. `PostToolUse` 또는 `PostToolUseFailure` hook에서 Claude에 경고를 표시하려면 대신 종료 2로 나가면 도구가 이미 실행되었더라도 [Claude가 stderr을 봅니다](#exit-code-2-behavior-per-event).

870 869

907 다른 종료 코드906 다른 종료 코드

908</h4>907</h4>

909 908

910[실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)이 아닌 한, 0 또는 2 이외의 종료 코드와 함께 stdout에 일반 텍스트를 출력하거나 아무것도 출력하지 않으면 [차단하지 않는 오류](#exit-code-output)입니다. 작업이 진행되면 트랜스크립트에 `Failed with non-blocking status code:`와 hook의 stderr 첫 번째 줄이 포함된 `<hook name> hook error` 알림이 표시됩니다.909`Failed with non-blocking status code:`가 포함된 `<hook name> hook error` 알림은 hook의 종료 코드가 0 또는 2가 아니었고 stdout이 일반 텍스트이거나 비어 있었음을 의미합니다. [실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)이 아닌 한 이는 [차단하지 않는 오류](#exit-code-output)이므로 hook이 작업을 중지하지 않았습니다. 알림에 표시되는 첫 번째 줄이 아닌 hook의 전체 stderr을 캡처하려면 [디버그 로깅](#debug-hooks)을 활성화합니다.

911 910

912예를 들어 `Bash`에 대한 `PreToolUse` hook이 stderr에 `something broke`를 출력하고 1로 종료하면 `PreToolUse:Bash hook error` 알림에 다음 줄이 표시됩니다:911예를 들어 `Bash`에 대한 `PreToolUse` hook이 stderr에 `something broke`를 출력하고 1로 종료하면 `PreToolUse:Bash hook error` 알림에 다음 줄이 표시됩니다:

913 912

915Failed with non-blocking status code: something broke914Failed with non-blocking status code: something broke

916```915```

917 916

918첫 번째 줄이 아닌 전체 stderr을 캡처하려면 [디버그 로깅](#debug-hooks)을 활성화합니다.917다음 줄처럼 알림에 셸의 `No such file or directory` 메시지가 표시되면, 예를 들어 스크립트 경로가 존재하지 않아서 hook이 전혀 실행되지 않은 것입니다:

~~919~~

920[실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)이 아닌 한, 시작할 수 없는 hook도 차단하지 않는 오류입니다. 셸 형식에서 스크립트 경로가 존재하지 않거나 실행 가능하지 않으면 셸은 127과 같은 코드로 종료되고 알림에 인터프리터의 메시지가 표시됩니다. 예를 들어 스크립트 경로가 존재하지 않으면 알림에 다음과 같은 줄이 표시됩니다:

921 918

922```text theme={null}919```text theme={null}

923Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory920Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory

924```921```

925 922

923경로가 잘못되었다면 hook이 구성된 곳에서 수정합니다. 셸 형식에서 스크립트 경로가 존재하지 않거나 실행 가능하지 않으면 셸은 127과 같은 코드로 종료되고 알림에 인터프리터의 메시지가 표시됩니다. [실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)이 아닌 한, 시작할 수 없는 hook도 차단하지 않는 오류입니다.

924

926정책 hook을 설정할 때는 첫 번째 실행에서 이 알림을 확인하세요. `settings.json`의 경로에 오타가 있으면 hook이 전혀 실행되지 않습니다. hook을 시작할 수 없을 때 작업을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.925정책 hook을 설정할 때는 첫 번째 실행에서 이 알림을 확인하세요. `settings.json`의 경로에 오타가 있으면 hook이 전혀 실행되지 않습니다. hook을 시작할 수 없을 때 작업을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.

927 926

928<Warning>927<Warning>

933 타임아웃932 타임아웃

934</h4>933</h4>

935 934

936[`async: true`](#run-hooks-in-the-background)로 실행하는 명령 hook을 제외하고, Claude Code는 [`timeout`](#common-fields)에 도달한 `command`, `http`, `mcp_tool` hook을 취소하고 hook의 출력을 버리므로 대부분의 이벤트에서 시간 초과된 hook은 결정을 내리지 않습니다.935[`async: true`](#run-hooks-in-the-background)로 실행하는 명령 hook을 제외하고, Claude Code는 [`timeout`](#common-fields)에 도달한 `command`, `http`, `mcp_tool` hook을 취소하고 hook의 출력을 버리므로 대부분의 이벤트에서 시간 초과된 hook은 결정을 내리지 않습니다. [`PreModelSwitch`](#premodelswitch)에서는 타임아웃으로 취소된 hook이 모델 전환을 차단합니다.

937 936

938[`PreModelSwitch`](#premodelswitch)에서는 타임아웃으로 취소된 hook이 모델 전환을 차단합니다. `PreToolUse`에서는 두 hook 유형이 다르게 동작합니다:937`PreToolUse`에서 시간 초과된 `command`, `http`, `mcp_tool` hook은 도구 호출을 차단하지 않습니다. 단, [실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)은 예외입니다. 호출은 일반 [권한 흐름](/docs/ko/permissions)을 통해 계속되므로 멈춘 hook이 게이트 역할을 할 것이라고 기대하지 마세요. `command` 또는 `http` hook이 시간 초과될 때 호출을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다. 타임아웃을 초과한 [Agent SDK 콜백 hook](/docs/ko/agent-sdk/hooks)은 [도구 호출을 차단합니다](#pretooluse).

~~939~~

940* 시간 초과된 `command`, `http`, `mcp_tool` hook은 도구 호출을 차단하지 않습니다. 단, [실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)은 예외입니다. 호출은 일반 [권한 흐름](/docs/ko/permissions)을 통해 계속되므로 멈춘 hook이 게이트 역할을 할 것이라고 기대하지 마세요. `command` 또는 `http` hook이 시간 초과될 때 호출을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.

941* 타임아웃을 초과한 [Agent SDK 콜백 hook](/docs/ko/agent-sdk/hooks)은 [도구 호출을 차단합니다](#pretooluse).

942 938

943<h4 id="hooks-that-start-a-background-process">939<h4 id="hooks-that-start-a-background-process">

944 백그라운드 프로세스를 시작하는 hook940 백그라운드 프로세스를 시작하는 hook

1086 HTTP 응답 처리1082 HTTP 응답 처리

1087</h3>1083</h3>

1088 1084

1089HTTP hook은 종료 코드와 stdout 대신 HTTP 상태 코드와 응답 본문을 사용합니다. 아래의 결과는 대부분의 이벤트에 적용됩니다. `WorktreeCreate`와 같이 [이벤트별 표](#exit-code-2-behavior-per-event)에 자체 실패 규칙이 있는 이벤트는 실패한 HTTP hook에도 해당 규칙을 적용합니다:1085HTTP hook은 종료 코드와 stdout 대신 HTTP 상태 코드와 응답 본문을 사용합니다. 요청이 실패하거나 2xx가 아닌 상태를 반환할 때 작업을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다. 도구 호출을 차단하거나 권한을 거부하려면 적절한 [결정 필드](#decision-control)를 포함하는 JSON 본문과 함께 2xx 응답을 반환합니다.

1086

1087[차단하지 않는 오류](#exit-code-output) 후에는 [실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)이 아닌 한 작업이 진행됩니다. `WorktreeCreate`와 같이 [이벤트별 표](#exit-code-2-behavior-per-event)에 자체 실패 규칙이 있는 이벤트를 제외하면, 각 응답 또는 실패에 대해 다음과 같은 결과가 나옵니다:

1090 1088

1091* **빈 본문의 2xx**: 성공, 출력 없는 종료 코드 0과 동일1089* **빈 본문의 2xx**: 성공, 출력 없는 종료 코드 0과 동일

1092* **JSON 객체 본문의 2xx**: 명령 hook과 동일한 [JSON 출력](#json-output) 스키마를 사용하여 구문 분석됩니다. 스키마 검증에 실패하는 본문은 차단하지 않는 오류입니다1090* **JSON 객체 본문의 2xx**: 명령 hook과 동일한 [JSON 출력](#json-output) 스키마를 사용하여 구문 분석됩니다. 스키마 검증에 실패하는 본문은 차단하지 않는 오류입니다

1095* **연결 실패**: 차단하지 않는 오류1093* **연결 실패**: 차단하지 않는 오류

1096* **타임아웃**: [타임아웃](#timeouts)에 설명된 대로 hook이 취소됩니다1094* **타임아웃**: [타임아웃](#timeouts)에 설명된 대로 hook이 취소됩니다

1097 1095

1098[차단하지 않는 오류](#exit-code-output) 후에는 [실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)이 아닌 한 작업이 진행됩니다. 도구 호출을 차단하거나 권한을 거부하려면 적절한 [결정 필드](#decision-control)를 포함하는 JSON 본문과 함께 2xx 응답을 반환합니다. 요청이 실패하거나 2xx가 아닌 상태를 반환할 때 작업을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.

~~1099~~

1100<h3 id="json-output">1096<h3 id="json-output">

1101 JSON 출력1097 JSON 출력

1102</h3>1098</h3>

1320| `fork` | 기존 세션에서 분기된 새 세션: `--resume` 또는 `--continue`와 함께 사용한 `--fork-session`, `/fork` 백그라운드 복사본, `/branch`, 또는 [백그라운드로 이동](/docs/ko/agent-view#from-inside-a-session)한 대화 |1316| `fork` | 기존 세션에서 분기된 새 세션: `--resume` 또는 `--continue`와 함께 사용한 `--fork-session`, `/fork` 백그라운드 복사본, `/branch`, 또는 [백그라운드로 이동](/docs/ko/agent-view#from-inside-a-session)한 대화 |

1321 1317

1322v2.1.214 이전에는 분기된 세션이 source를 `"resume"`으로 보고했습니다.

~~1323~~

1324대화형 세션을 시작하거나, 실행 시 `--continue` 또는 `--resume`으로 대화를 재개하거나, `/clear`를 실행하면 SessionStart 훅이 백그라운드에서 실행됩니다. 바로 입력할 수 있으며, 재개한 대화는 훅을 기다리지 않고 표시됩니다. 다만 Claude의 첫 번째 응답은 여전히 훅이 완료될 때까지 기다리므로 훅의 컨텍스트가 Claude에 전달됩니다.1318대화형 세션을 시작하거나, 실행 시 `--continue` 또는 `--resume`으로 대화를 재개하거나, `/clear`를 실행하면 SessionStart 훅이 백그라운드에서 실행됩니다. 바로 입력할 수 있으며, 재개한 대화는 훅을 기다리지 않고 표시됩니다. 다만 Claude의 첫 번째 응답은 여전히 훅이 완료될 때까지 기다리므로 훅의 컨텍스트가 Claude에 전달됩니다.

1325 1319

1326세션 내에서 `/resume`으로 대화를 전환하는 경우에는 전환 자체가 훅이 완료될 때까지 기다립니다. 백그라운드 훅이 아직 실행 중일 때 `/clear`를 실행하거나 다른 대화로 전환하면, 훅이 반환하는 내용은 세션에 적용되지 않습니다.1320세션 내에서 `/resume`으로 대화를 전환하는 경우에는 전환 자체가 훅이 완료될 때까지 기다립니다. 백그라운드 훅이 아직 실행 중일 때 `/clear`를 실행하거나 다른 대화로 전환하면, 훅이 반환하는 내용은 세션에 적용되지 않습니다.

1583 1577

1584[`async: true`](#run-hooks-in-the-background)로 실행하는 command 훅을 제외하고, 타임아웃에 도달한 `UserPromptSubmit` command, HTTP 또는 MCP 도구 훅은 취소되며 `additionalContext`를 포함한 출력이 버려집니다. 프롬프트는 해당 컨텍스트 없이 여전히 Claude에 전달됩니다. 대신 프롬프트를 차단하려면 command 또는 HTTP 훅에 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정하십시오. 트랜스크립트에는 훅 이름, 발생한 타임아웃, 출력이 버려졌다는 사실을 알리는 알림이 표시됩니다.1578[`async: true`](#run-hooks-in-the-background)로 실행하는 command 훅을 제외하고, 타임아웃에 도달한 `UserPromptSubmit` command, HTTP 또는 MCP 도구 훅은 취소되며 `additionalContext`를 포함한 출력이 버려집니다. 프롬프트는 해당 컨텍스트 없이 여전히 Claude에 전달됩니다. 대신 프롬프트를 차단하려면 command 또는 HTTP 훅에 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정하십시오. 트랜스크립트에는 훅 이름, 발생한 타임아웃, 출력이 버려졌다는 사실을 알리는 알림이 표시됩니다.

1585 1579

1586`UserPromptSubmit`의 [Agent SDK 콜백 훅](/docs/ko/agent-sdk/hooks)이 타임아웃에 도달하면 훅과 타임아웃을 명시한 메시지와 함께 프롬프트를 차단합니다. 해당 위치의 콜백은 실패 시 허용되어서는 안 되는 정책 게이트 역할을 할 수 있기 때문입니다. 세션은 계속됩니다. v2.1.208 이전에는 해당 이벤트에서 콜백 타임아웃이 발생하면 실행 오류와 함께 턴이 종료되었습니다.1580`UserPromptSubmit`의 [Agent SDK 콜백 훅](/docs/ko/agent-sdk/hooks)이 타임아웃에 도달하면 훅 이름과 타임아웃을 명시한 메시지와 함께 프롬프트를 차단합니다. 해당 위치의 콜백은 실패 시 열려서는 안 되는 정책 게이트 역할을 할 수 있기 때문입니다. 세션은 계속됩니다.

1587 1581

1588<h4 id="userpromptsubmit-input">1582<h4 id="userpromptsubmit-input">

1589 UserPromptSubmit 입력1583 UserPromptSubmit 입력

2058 2052

2059| 필드 | 유형 | 예시 | 설명 |2053| 필드 | 유형 | 예시 | 설명 |

2060| :- | :- | :- | :- |2054| :- | :- | :- | :- |

2061| `status` | string | `"completed"` | 포그라운드 서브에이전트는 `"completed"`, 백그라운드 서브에이전트는 `"async_launched"`입니다. 서브에이전트는 기본적으로 백그라운드에서 실행되므로, `run_in_background`를 생략한 Agent 호출도 `"async_launched"`를 생성합니다 |2055| `status` | string | `"completed"` | 포그라운드 서브에이전트는 `"completed"`, 백그라운드 서브에이전트는 `"async_launched"`입니다. 어떤 서브에이전트가 각 방식으로 실행되는지는 [포그라운드 또는 백그라운드에서 서브에이전트 실행](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)을 참조하십시오 |

2063| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | 서브에이전트의 최종 텍스트 블록입니다. 보고서가 `SubagentHandback`을 통해 전달되는 서브에이전트의 경우에는 그 대신 해당 인계에 대한 짧은 메모가 담깁니다 |2057| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | 서브에이전트의 최종 텍스트 블록입니다. 보고서가 `SubagentHandback`을 통해 전달되는 서브에이전트의 경우에는 그 대신 해당 인계에 대한 짧은 메모가 담깁니다 |

2072 2066

2073백그라운드 서브에이전트의 경우, 도구는 작업이 백그라운드로 이동할 때 반환되므로 `tool_response`에는 사용량 필드가 없습니다. 백그라운드 실행은 즉시 반환되고, Claude Code가 실행 도중 백그라운드로 전환한 포그라운드 작업은 그 전환 시점에 반환됩니다. 응답에는 `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, `resolvedModel`이 있습니다.2067백그라운드 서브에이전트의 경우, 도구는 작업이 백그라운드로 이동할 때 반환되므로 `tool_response`에는 사용량 필드가 없습니다. 백그라운드 실행은 즉시 반환되고, Claude Code가 실행 도중 백그라운드로 전환한 포그라운드 작업은 그 전환 시점에 반환됩니다. 응답에는 `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, `resolvedModel`이 있습니다.

2074 2068

2075`completed` 응답에서 `resolvedModel`은 서브에이전트가 시작한 모델을 나타내며, 이는 `availableModels`나 다른 재정의가 적용되는 경우처럼 `tool_input`의 `model` 값과 다를 수 있습니다. `async_launched` 응답에서 `resolvedModel`은 에이전트가 백그라운드로 이동했을 때 사용 중이던 모델을 나타내므로, 백그라운드 전환 전에 발생한 교체가 반영됩니다. `modelsUsed`와 백그라운드 전환 시점의 `resolvedModel` 동작에는 Claude Code v2.1.212 이상이 필요합니다.2069`completed` 응답에서 `resolvedModel`은 서브에이전트가 시작할 때 사용한 모델을 나타내며, `availableModels`나 다른 재정의가 적용되는 경우처럼 `tool_input`의 `model` 값과 다를 수 있습니다. `async_launched` 응답에서 `resolvedModel`은 에이전트가 백그라운드로 이동했을 때 사용 중이던 모델을 나타내므로, 백그라운드로 이동하기 전에 발생한 교체가 반영됩니다.

2076 2070

2077<a id="askuserquestion" />2071<a id="askuserquestion" />

2078 2072

2120 2114

2121훅이 `"ask"`를 반환하면, 사용자에게 표시되는 권한 프롬프트에 훅의 출처를 식별하는 레이블이 포함됩니다. 설정 파일이나 에이전트 frontmatter의 훅은 `[settings]`, 플러그인의 훅은 `[plugin:<name>]`, 스킬 frontmatter의 훅은 `[skill]`입니다. 이를 통해 사용자는 어떤 구성 출처가 확인을 요청하는지 이해할 수 있습니다.2115훅이 `"ask"`를 반환하면, 사용자에게 표시되는 권한 프롬프트에 훅의 출처를 식별하는 레이블이 포함됩니다. 설정 파일이나 에이전트 frontmatter의 훅은 `[settings]`, 플러그인의 훅은 `[plugin:<name>]`, 스킬 frontmatter의 훅은 `[skill]`입니다. 이를 통해 사용자는 어떤 구성 출처가 확인을 요청하는지 이해할 수 있습니다.

2122 2116

2123훅의 `"ask"`는 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서도 권한 프롬프트를 강제합니다. 분류기는 여전히 도구 호출을 거부할 수 있지만, 호출을 조용히 승인할 수는 없습니다. v2.1.211 이전에는 분류기가 [샌드박스](/docs/ko/sandboxing) 밖에서 실행되는 Bash 명령을 훅이 요청한 프롬프트를 표시하지 않고 승인할 수 있었습니다. 이때도 분류기는 해당 명령에 자체 안전 규칙을 적용했으며, 훅의 `"deny"`는 항상 준수되었습니다.2117훅의 `"ask"`는 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서도 권한 프롬프트를 강제합니다. 분류기는 여전히 도구 호출을 거부할 수 있지만, 호출을 조용히 승인할 수는 없습니다.

2124 2118

2125```json theme={null}2119```json theme={null}

2126{2120{

3696| `source` | string | 요청의 출처: `/model <name>`, `/config`의 Model 설정, 빠른 모드 켜기의 경우 `"command"`, 모델 선택기의 경우 `"picker"`, Agent SDK 호스트 또는 Remote Control에서 보낸 `set_model` 요청이나 `apply_flag_settings` 요청의 모델 변경의 경우 `"sdk"` |3690| `source` | string | 요청의 출처: `/model <name>`, `/config`의 Model 설정, 빠른 모드 켜기의 경우 `"command"`, 모델 선택기의 경우 `"picker"`, Agent SDK 호스트 또는 Remote Control에서 보낸 `set_model` 요청이나 `apply_flag_settings` 요청의 모델 변경의 경우 `"sdk"` |

3700| `estimated_cache_write_usd` | number | `cache_ttl` 요금으로 `to_model`의 프롬프트 캐시에 `context_tokens`를 쓰는 예상 비용(미국 달러)으로, 다음 응답은 제외됩니다. 서버가 전체 컨텍스트를 다시 캐싱할 필요가 없을 수도 있으므로 추정치로 취급하세요 |3694| `estimated_cache_write_usd` | number | `cache_ttl` 요금으로 `to_model`의 프롬프트 캐시에 `context_tokens`를 쓰는 예상 비용(미국 달러)으로, 다음 응답은 제외됩니다. 서버가 전체 컨텍스트를 다시 캐싱할 필요가 없을 수도 있으므로 추정치로 취급하세요 |

3701| `pricing` | string | Claude Code가 `estimated_cache_write_usd`의 가격을 책정한 방식: 조직이 자체 요금을 구성한 경우 해당 요금으로 책정한 `"configured"`, 정가로 책정한 `"catalog"`, 또는 `to_model`의 가격을 알 수 없어 Claude Code가 기본 요금을 가정한 `"default"` |3695| `pricing` | string | Claude Code가 `estimated_cache_write_usd`의 가격을 책정한 방식: 조직이 자체 요금을 구성한 경우 해당 요금으로 책정한 `"configured"`, 정가로 책정한 `"catalog"`, 또는 `to_model`의 가격을 알 수 없어 Claude Code가 기본 요금을 가정한 `"default"` |

3702 3696

3757 3751

3758타임아웃 전에 응답하지 않는 PreModelSwitch 훅은 전환을 차단합니다. 이 이벤트의 기본 타임아웃은 30초입니다.3752타임아웃 전에 응답하지 않는 PreModelSwitch 훅은 전환을 차단합니다. 이 이벤트의 기본 타임아웃은 30초입니다.

3759 3753

37600 또는 2가 아닌 종료 코드의 동작은 [기타 종료 코드](#other-exit-codes)를 참조하십시오.3754유효한 JSON 출력 없이 0 또는 2 이외의 종료 코드를 반환하면 [비차단 오류](#other-exit-codes)이므로 전환이 진행됩니다. 단, [실패 시 작업을 차단하는](#block-the-action-when-a-hook-fails) 훅은 예외입니다.

3761 3755

3762<h3 id="postmodelswitch">3756<h3 id="postmodelswitch">

3763 PostModelSwitch3757 PostModelSwitch

4275`ok: false`일 때 발생하는 동작은 이벤트에 따라 다릅니다.4269`ok: false`일 때 발생하는 동작은 이벤트에 따라 다릅니다.

4276 4270

4277* `Stop` 및 `SubagentStop`: 사유가 Claude의 다음 지시로 다시 전달되고 턴이 계속됩니다. 단, 응답에서 `impossible: true`도 함께 설정한 경우에는 Claude Code가 중지를 허용하고 턴이 종료됩니다4271* `Stop` 및 `SubagentStop`: 사유가 Claude의 다음 지시로 다시 전달되고 턴이 계속됩니다. 단, 응답에서 `impossible: true`도 함께 설정한 경우에는 Claude Code가 중지를 허용하고 턴이 종료됩니다

4278* `PreToolUse`: 도구 호출이 거부됩니다. 기본적으로 턴이 종료되고 거부 사유가 채팅에 경고 줄로 표시됩니다. 대신 사유를 도구 오류로 Claude에 반환하여 Claude가 조정하고 계속 진행할 수 있게 하려면 `continueOnBlock: true`를 설정하십시오. 이는 명령 훅의 `permissionDecision: "deny"`와 동일합니다. v2.1.210 이전에는 거부 사유가 도구 오류로 Claude에 반환되고 턴이 계속되었습니다4272* `PreToolUse`: 도구 호출이 거부됩니다. 기본적으로 턴이 종료되고 거부 사유가 채팅에 경고 줄로 표시됩니다. 대신 사유를 도구 오류로 Claude에 반환하여 Claude가 조정하고 계속 진행할 수 있게 하려면 `continueOnBlock: true`를 설정하십시오. 이는 명령 훅의 `permissionDecision: "deny"`와 동일합니다

4279* `PostToolUse`: 기본적으로 턴이 종료되고 사유가 채팅에 경고 줄로 표시됩니다. 대신 사유를 Claude에 다시 전달하고 턴을 계속하려면 `continueOnBlock: true`를 설정하십시오4273* `PostToolUse`: 기본적으로 턴이 종료되고 사유가 채팅에 경고 줄로 표시됩니다. 대신 사유를 Claude에 다시 전달하고 턴을 계속하려면 `continueOnBlock: true`를 설정하십시오

4280* `PostToolBatch`, `UserPromptSubmit`, `UserPromptExpansion`: 턴이 종료되고 사유가 경고 줄로 표시됩니다. 이 이벤트들은 `continue`와 관계없이 `decision: "block"`에서 턴을 종료합니다4274* `PostToolBatch`, `UserPromptSubmit`, `UserPromptExpansion`: 턴이 종료되고 사유가 경고 줄로 표시됩니다. 이 이벤트들은 `continue`와 관계없이 `decision: "block"`에서 턴을 종료합니다

4281* `PostToolUseFailure` 및 `TaskCreated`: `continueOnBlock`과 관계없이 사유가 도구 오류로 Claude에 반환되고 턴이 계속됩니다4275* `PostToolUseFailure` 및 `TaskCreated`: `continueOnBlock`과 관계없이 사유가 도구 오류로 Claude에 반환되고 턴이 계속됩니다

hooks-guide.md +19 −24

Details

497 Hooks 작동 방식497 Hooks 작동 방식

498</h2>498</h2>

499 499

500Claude Code는 라이프사이클의 특정 지점에서 hook 이벤트를 발생시킵니다. 이벤트가 발생하면 Claude Code는 일치하는 모든 hooks를 병렬로 실행합니다. [Hook 핸들러 필드](/docs/ko/hooks#hook-handler-fields)를 참조하여 중복 핸들러가 처리되는 방식을 확인하세요. 아래 표는 각 이벤트와 발생 시기를 보여줍니다:500Claude Code는 라이프사이클의 특정 지점에서 hook 이벤트를 발생시킵니다. 이벤트가 발생하면 Claude Code는 일치하는 hooks를 병렬로 실행합니다. [Hook 핸들러 필드](/docs/ko/hooks#hook-handler-fields)를 참조하여 중복 핸들러가 처리되는 방식을 확인하세요. 아래 표는 각 이벤트와 발생 시기를 보여줍니다:

501 501

502| 이벤트 | 발생 시점 |502| 이벤트 | 발생 시점 |

503| :- | :- |503| :- | :- |

627exit 0 # exit 0 = 결정 없음; 정상적인 권한 흐름이 적용됩니다627exit 0 # exit 0 = 결정 없음; 정상적인 권한 흐름이 적용됩니다

628```628```

629 629

630종료 코드는 다음에 일어날 일을 결정합니다:630종료 코드가 0과 2 이외의 값이고 유효한 JSON 출력이 없으면, 해당 hook이 [실패 시 작업을 차단하는](/docs/ko/hooks#block-the-action-when-a-hook-fails) hook이 아닌 한 대부분의 이벤트에서 작업이 진행됩니다. `onFailure`가 `"block"`으로 설정된 hook이 그 예입니다. 이의가 없음을 알리려면 0으로 종료하고, 작업을 차단하려면 2로 종료합니다:

631 631

632* **Exit 0**: hook이 종료 코드를 통해 이의를 제기하지 않습니다.632* **Exit 0**: `PreToolUse` hook에서 0으로 종료해도 exit 0은 도구 호출을 승인하지 않으므로 도구 호출은 여전히 정상적인 [권한 흐름](/docs/ko/permissions)을 거칩니다. `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` 및 `PostModelSwitch` hooks의 경우 Claude Code는 [일반 텍스트로 처리](/docs/ko/hooks#exit-code-0)하는 stdout을 Claude의 컨텍스트에 추가합니다.

633 * `PreToolUse` hook의 경우 이것은 도구 호출을 승인하지 않습니다: 정상적인 [권한 흐름](/docs/ko/permissions)이 여전히 적용됩니다.633* **Exit 2**: stderr에 이유를 작성합니다. 이벤트에 따라 Claude가 이를 피드백으로 받아 조정하거나, 사용자에게 표시되거나, `ConfigChange` 및 `Elicitation`처럼 메시지가 표시되지 않습니다. 일부 이벤트는 차단될 수 없습니다: `SessionStart` 및 기타의 경우 exit 2는 stderr를 사용자에게 표시하고 실행이 계속됩니다. 전체 목록은 [이벤트별 exit 코드 2 동작](/docs/ko/hooks#exit-code-2-behavior-per-event)을 참조하세요.

634 * `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` 및 `PostModelSwitch` hooks의 경우 Claude Code는 stdout을 [일반 텍스트로 처리](/docs/ko/hooks#exit-code-0)하여 Claude의 컨텍스트에 추가합니다.634* **다른 종료 코드**: `WorktreeCreate`가 0이 아닌 모든 종료에서 실패하는 것과 같은 이벤트별 예외는 [Exit code output](/docs/ko/hooks#exit-code-output)을 참조하세요. 다른 이벤트에서는 해당 hook이 실패 시 작업을 차단하는 hook이 아닌 한, hook이 stdout에 출력한 내용을 기준으로 해당하는 경우를 찾습니다:

635* **Exit 2**: Claude Code가 작업을 차단합니다. stderr에 이유를 작성하세요. 이것이 어디에 도달하는지는 이벤트에 따라 다릅니다: 일부 이벤트는 이를 Claude에 피드백으로 전달하여 조정할 수 있도록 하고, 다른 이벤트는 사용자에게 표시하며, `ConfigChange` 및 `Elicitation`과 같은 몇 가지는 메시지를 표시하지 않습니다. 일부 이벤트는 차단될 수 없습니다: `SessionStart` 및 기타의 경우 exit 2는 stderr를 사용자에게 표시하고 실행이 계속됩니다. 전체 목록은 [이벤트별 exit 코드 2 동작](/docs/ko/hooks#exit-code-2-behavior-per-event)을 참조하세요.635 * 스키마 검증을 통과하는 구문 분석된 객체: Claude Code는 종료 코드를 무시하고 JSON만이 결과를 결정하며 hook은 오류로 보고되지 않습니다.

636* **다른 종료 코드**: 대부분의 이벤트에서 작업은 [차단되지 않는 오류](/docs/ko/hooks#exit-code-output)로 진행됩니다. 단, 해당 hook이 [실패 시 작업을 차단하는](/docs/ko/hooks#block-the-action-when-a-hook-fails) hook이거나 JSON 출력이 검증을 통과하는 경우는 예외입니다:636 * 스키마 검증에 실패하는 구문 분석된 객체 또는 Claude Code가 [JSON으로 구문 분석](/docs/ko/hooks#exit-code-0)하려고 하지만 유효한 JSON이 아닌 stdout: 작업이 차단되지 않는 오류로 진행됩니다. 검증 또는 구문 분석 메시지는 `<hook name> hook error` 공지에서 확인하세요.

637 * 스키마 검증을 통과하는 구문 분석된 객체: Claude Code는 종료 코드를 무시하고 JSON만이 결과를 결정하며 hook은 오류로 보고되지 않습니다. `WorktreeCreate`가 0이 아닌 종료에서 실패하는 것과 같은 이벤트별 예외는 참조의 [Exit code output](/docs/ko/hooks#exit-code-output) 섹션에 나열됩니다.

638 * 스키마 검증에 실패하는 구문 분석된 객체 또는 Claude Code가 [JSON으로 구문 분석](/docs/ko/hooks#exit-code-0)하려고 하지만 유효한 JSON이 아닌 stdout: 차단되지 않는 오류입니다. 공지는 검증 또는 구문 분석 메시지를 포함합니다.

639 * Claude Code가 [일반 텍스트로 처리](/docs/ko/hooks#exit-code-0)하는 stdout 또는 빈 stdout: 작업이 차단되지 않는 오류로 진행됩니다. 트랜스크립트는 `<hook name> hook error` 공지를 표시한 후 `Failed with non-blocking status code:`로 접두사가 붙은 stderr의 첫 번째 줄을 표시합니다. 전체 stderr를 캡처하려면 `claude --debug`를 사용하거나 세션 중에 `/debug`를 실행하여 [디버그 로깅](/docs/ko/hooks#debug-hooks)을 활성화하세요.637 * Claude Code가 [일반 텍스트로 처리](/docs/ko/hooks#exit-code-0)하는 stdout 또는 빈 stdout: 작업이 차단되지 않는 오류로 진행됩니다. 트랜스크립트는 `<hook name> hook error` 공지를 표시한 후 `Failed with non-blocking status code:`로 접두사가 붙은 stderr의 첫 번째 줄을 표시합니다. 전체 stderr를 캡처하려면 `claude --debug`를 사용하거나 세션 중에 `/debug`를 실행하여 [디버그 로깅](/docs/ko/hooks#debug-hooks)을 활성화하세요.

640 638

641<h4 id="structured-json-output">639<h4 id="structured-json-output">

662 660

663`"deny"`를 사용하면 Claude Code는 도구 호출을 취소하고 `permissionDecisionReason`을 Claude에게 피드백으로 전달합니다.661`"deny"`를 사용하면 Claude Code는 도구 호출을 취소하고 `permissionDecisionReason`을 Claude에게 피드백으로 전달합니다.

664 662

665`PreToolUse`에서 Claude Code는 각 `permissionDecision` 값을 다음과 같이 처리합니다:663`PreToolUse`에서는 사용자에게 일반 권한 프롬프트를 표시하도록 `"ask"`를 반환하거나, 대화형 권한 프롬프트를 건너뛰도록 `"allow"`를 반환할 수도 있습니다. `"allow"`를 사용해도 엔터프라이즈 관리형 거부 목록을 포함한 거부 및 확인 규칙은 여전히 적용되며, 다음에 대한 프롬프트도 마찬가지로 적용됩니다:

666 664

667* `"allow"`: 대화형 권한 프롬프트를 건너뜁니다. 엔터프라이즈 관리형 거부 목록을 포함한 거부 및 확인 규칙은 여전히 적용되며, 다음에 대한 프롬프트도 마찬가지로 적용됩니다:665* [네트워크 경로](/docs/ko/permissions#network-paths)에서의 읽기

~~668~~ 666* [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구

669 * [네트워크 경로](/docs/ko/permissions#network-paths)에서의 읽기667* 해당 설정이 Claude Code에 도달하는 세션에서 [조직이 `ask`로 설정한](/docs/ko/mcp#organization-controls-on-connector-tools) 커넥터 도구

670 * [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구

671 * 해당 설정이 Claude Code에 도달하는 세션에서 [조직이 `ask`로 설정한](/docs/ko/mcp#organization-controls-on-connector-tools) 커넥터 도구

672 668

673 플랜 모드에서 `"allow"`가 어떻게 동작하는지는 [플랜 모드의 hook 승인](/docs/ko/permissions#hook-approvals-in-plan-mode)을 참조하세요.669 플랜 모드에서 `"allow"`가 어떻게 동작하는지는 [플랜 모드의 hook 승인](/docs/ko/permissions#hook-approvals-in-plan-mode)을 참조하세요.

674* `"deny"`: 도구 호출을 취소하고 이유를 Claude에 전송합니다

675* `"ask"`: 일반적으로 사용자에게 권한 프롬프트를 표시합니다

676 670

677네 번째 값인 `"defer"`는 `-p` 플래그가 있는 [비대화형 모드](/docs/ko/headless)에서 사용 가능합니다. 도구 호출을 보존하여 프로세스를 종료하므로 Agent SDK 래퍼가 입력을 수집하고 재개할 수 있습니다. 참조의 [나중에 도구 호출 연기](/docs/ko/hooks#defer-a-tool-call-for-later)를 참조하세요.671네 번째 값인 `"defer"`는 `-p` 플래그가 있는 [비대화형 모드](/docs/ko/headless)에서 사용 가능합니다. 도구 호출을 보존하여 프로세스를 종료하므로 Agent SDK 래퍼가 입력을 수집하고 재개할 수 있습니다. 참조의 [나중에 도구 호출 연기](/docs/ko/hooks#defer-a-tool-call-for-later)를 참조하세요.

678 672

893* `"ok": true`: 작업이 진행됩니다887* `"ok": true`: 작업이 진행됩니다

894* `"ok": false`: 어떤 일이 발생하는지는 이벤트에 따라 다릅니다:888* `"ok": false`: 어떤 일이 발생하는지는 이벤트에 따라 다릅니다:

895 * `Stop` 및 `SubagentStop`: `reason`이 Claude로 피드백되어 계속 작업하도록 합니다. 단, 응답이 `"impossible": true`를 설정하여 조건을 절대 만족할 수 없는 것으로 표시하는 경우, Claude Code는 중지를 허용하고 턴이 종료됩니다889 * `Stop` 및 `SubagentStop`: `reason`이 Claude로 피드백되어 계속 작업하도록 합니다. 단, 응답이 `"impossible": true`를 설정하여 조건을 절대 만족할 수 없는 것으로 표시하는 경우, Claude Code는 중지를 허용하고 턴이 종료됩니다

896 * `PreToolUse`: 도구 호출이 거부됩니다. 기본적으로 턴이 종료되고 거부 `reason`이 경고 줄로 채팅에 나타납니다. 훅에서 `continueOnBlock: true`를 설정하여 대신 `reason`을 Claude에 도구 오류로 반환하면, Claude가 조정하고 계속할 수 있습니다. v2.1.210 이전에는 거부 `reason`이 Claude에 도구 오류로 반환되었고 턴이 계속되었습니다890 * `PreToolUse`: 도구 호출이 거부됩니다. 기본적으로 턴이 종료되고 거부 `reason`이 경고 줄로 채팅에 나타납니다. 훅에서 `continueOnBlock: true`를 설정하여 대신 `reason`을 Claude에 도구 오류로 반환하면, Claude가 조정하고 계속할 수 있습니다

897 * `PostToolUse`: 기본적으로 턴이 종료되고 `reason`이 경고 줄로 채팅에 나타납니다. `continueOnBlock: true`를 설정하여 `reason`을 Claude로 피드백하고 대신 턴을 계속합니다891 * `PostToolUse`: 기본적으로 턴이 종료되고 `reason`이 경고 줄로 채팅에 나타납니다. `continueOnBlock: true`를 설정하여 `reason`을 Claude로 피드백하고 대신 턴을 계속합니다

898 * `PostToolBatch`, `UserPromptSubmit`, 및 `UserPromptExpansion`: 턴이 종료되고 `reason`이 경고 줄로 채팅에 나타납니다892 * `PostToolBatch`, `UserPromptSubmit`, 및 `UserPromptExpansion`: 턴이 종료되고 `reason`이 경고 줄로 채팅에 나타납니다

899 893

1019 Hooks 및 권한 모드1013 Hooks 및 권한 모드

1020</h3>1014</h3>

1021 1015

1022`PreToolUse` hooks는 모든 [권한 모드](/docs/ko/permission-modes)에서 권한 모드 확인 전에 발생하며, `dontAsk`를 포함합니다. `permissionDecision: "deny"`를 반환하는 hook은 `bypassPermissions` 모드 또는 `--dangerously-skip-permissions`에서도 도구를 차단합니다. 이를 통해 사용자가 권한 모드를 변경하여 우회할 수 없는 정책을 적용할 수 있습니다.1016설정 파일이나 플러그인의 `hooks/hooks.json`에 있는 훅으로는 권한 규칙이 허용하는 범위를 넘어 제한을 완화할 수 없으며, 훅의 `"deny"`는 모든 권한 모드에서 유지됩니다:

~~1023~~

1024반대는 성립하지 않습니다. 설정 파일 및 플러그인의 `hooks/hooks.json`에 있는 훅은 제한을 강화할 수 있지만 권한 규칙이 허용하는 범위를 넘어 완화할 수는 없습니다. `"allow"`를 반환하는 훅은 설정의 거부 규칙을 우회하지 않으며, 다음에 대한 프롬프트를 억제할 수 없습니다:

1025 1017

1026* [네트워크 경로](/docs/ko/permissions#network-paths)에서의 읽기1018* **`"allow"`보다 우선하는 항목**: `"allow"`를 반환하는 훅은 설정의 거부 규칙을 우회하지 않으며, 다음에 대한 프롬프트를 억제할 수 없습니다:

1027* [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구1019 * [네트워크 경로](/docs/ko/permissions#network-paths)에서의 읽기

1028* 해당 설정이 Claude Code에 도달하는 세션에서 [조직이 `ask`로 설정한](/docs/ko/mcp#organization-controls-on-connector-tools) 커넥터 도구1020 * [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구

1021 * 해당 설정이 Claude Code에 도달하는 세션에서 [조직이 `ask`로 설정한](/docs/ko/mcp#organization-controls-on-connector-tools) 커넥터 도구

1029 1022

1030[플랜 모드](/docs/ko/permissions#hook-approvals-in-plan-mode)에서 `PreToolUse` 훅이 파일 편집에 대해 `"allow"`를 반환하면, 훅이 없을 때 해당 편집이 받았을 것과 동일한 프롬프트, 차단 또는 승인이 적용됩니다. 훅 승인에 대한 이 제한을 해제하려면 [플랜을 승인](/docs/ko/permission-modes#review-and-approve-a-plan)하거나 다른 권한 모드로 전환합니다.1023[플랜 모드](/docs/ko/permissions#hook-approvals-in-plan-mode)에서 `PreToolUse` 훅이 파일 편집에 대해 `"allow"`를 반환하면, 훅이 없을 때 해당 편집이 받았을 것과 동일한 프롬프트, 차단 또는 승인이 적용됩니다. 훅 승인에 대한 이 제한을 해제하려면 [플랜을 승인](/docs/ko/permission-modes#review-and-approve-a-plan)하거나 다른 권한 모드로 전환합니다.

1031 1024

1025* **모든 권한 모드에서의 `"deny"`**: `permissionDecision: "deny"`를 반환하는 훅은 `bypassPermissions` 모드 또는 `--dangerously-skip-permissions`에서도 도구를 차단합니다. `PreToolUse` 훅은 `dontAsk`를 포함한 모든 [권한 모드](/docs/ko/permission-modes)에서 권한 모드 확인 전에 발생합니다. 이를 통해 사용자가 권한 모드를 변경하여 우회할 수 없는 정책을 적용할 수 있습니다.

1026

1032설치한 [mod](/docs/ko/plugins/mods/overview)가 `tool.check`를 처리하는 경우, 훅이 관리형 설정에 있지 않는 한 `PreToolUse` 훅이 차단한 호출을 승인할 수 있습니다. 플랜 모드에서 mod는 이러한 호출이 읽기 전용인 경우 승인할 수 있지만, 파일 편집이나 읽기 전용이 아닌 다른 호출은 승인할 수 없습니다. [훅으로 권한 확장](/docs/ko/permissions#extend-permissions-with-hooks)에서 어떤 규칙이 mod보다 우선하는지 나열합니다.1027설치한 [mod](/docs/ko/plugins/mods/overview)가 `tool.check`를 처리하는 경우, 훅이 관리형 설정에 있지 않는 한 `PreToolUse` 훅이 차단한 호출을 승인할 수 있습니다. 플랜 모드에서 mod는 이러한 호출이 읽기 전용인 경우 승인할 수 있지만, 파일 편집이나 읽기 전용이 아닌 다른 호출은 승인할 수 없습니다. [훅으로 권한 확장](/docs/ko/permissions#extend-permissions-with-hooks)에서 어떤 규칙이 mod보다 우선하는지 나열합니다.

1033 1028

1034<h3 id="hook-not-firing">1029<h3 id="hook-not-firing">

interactive-mode.md +5 −5

Details

183 INSERT 모드 키 시퀀스 재매핑183 INSERT 모드 키 시퀀스 재매핑

184</h3>184</h3>

185 185

186[`vimInsertModeRemaps`](/docs/ko/settings-reference#viminsertmoderemaps) 설정은 두 개의 키 INSERT 모드 시퀀스를 Escape로 매핑하므로, `jj`와 같은 매핑은 사용자를 NORMAL 모드로 돌려보냅니다. Claude Code v2.1.208 이상이 필요합니다.186[`vimInsertModeRemaps`](/docs/ko/settings-reference#viminsertmoderemaps) 설정은 두 개의 키 INSERT 모드 시퀀스를 Escape로 매핑하므로, `jj`와 같은 매핑은 사용자를 NORMAL 모드로 돌려보냅니다.

187 187

188다음 `~/.claude/settings.json` 예제는 vim 모드를 켜고 `jj`를 Escape로 매핑합니다:188다음 `~/.claude/settings.json` 예제는 vim 모드를 켜고 `jj`를 Escape로 매핑합니다:

189 189

248| `cc` | 줄 변경 |248| `cc` | 줄 변경 |

249| `C` | 줄의 끝까지 변경 |249| `C` | 줄의 끝까지 변경 |

251| `s` | 문자 대체: 커서 아래의 문자를 삭제하고 INSERT 모드로 진입합니다. Claude Code v2.1.211 이상이 필요합니다 |251| `s` | 문자 대체: 커서 아래의 문자를 삭제하고 INSERT 모드로 진입합니다 |

252| `S` | 줄 대체: 줄을 지우고 INSERT 모드로 진입합니다. Claude Code v2.1.211 이상이 필요합니다 |252| `S` | 줄 대체: 줄을 지우고 INSERT 모드로 진입합니다 |

253| `yy`/`Y` | 줄 야앙크(복사) |253| `yy`/`Y` | 줄 야앙크(복사) |

255| `p` | 커서 뒤에 붙여넣기 |255| `p` | 커서 뒤에 붙여넣기 |

471* 대화의 첫 번째 턴 이후, 일부 세션에서471* 대화의 첫 번째 턴 이후, 일부 세션에서

472* 이전 응답이 오류로 끝났습니다.472* 이전 응답이 오류로 끝났습니다.

473* Plan Mode에 있는 동안473* Plan Mode에 있는 동안

474* 계정이 사용량 한도에 가깝거나 도달했습니다. 한계에 도달할 때까지 제안을 계속 표시하려면 [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](/docs/ko/env-vars)을 `true`로 설정합니다. v2.1.238 이전에는 Claude Code가 변수를 `true`로 설정해도 한계 근처에서 제안을 건너뛰었습니다.474* 계정이 사용 한도에 가깝거나 도달했습니다. 한도에 도달할 때까지 이 건너뛰기가 적용되지 않도록 하려면 [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](/docs/ko/env-vars)을 `true`로 설정합니다. v2.1.238 이전에는 Claude Code가 변수를 `true`로 설정해도 한도 근처에서 제안을 건너뛰었습니다.

475* [에이전트 팀](/docs/ko/agent-teams)에서 기본적으로 팀원의 세션에서. 리드의 세션은 제안을 표시합니다.475* [에이전트 팀](/docs/ko/agent-teams)에서 기본적으로 팀원의 세션에서. 리드의 세션은 제안을 표시합니다.

476 476

477`Showing fewer prompt suggestions · use one to bring them back` 알림은 연속으로 많은 제안을 사용하지 않고 넘겼기 때문에 Claude Code가 제안을 덜 자주 표시하고 있다는 의미입니다. 평소 빈도로 되돌리려면 제안을 사용하거나 [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](/docs/ko/env-vars)을 `true`로 설정합니다.477`Showing fewer prompt suggestions · use one to bring them back` 알림은 연속으로 많은 제안을 사용하지 않고 넘겼기 때문에 Claude Code가 제안을 덜 자주 표시하고 있다는 의미입니다. 평소 빈도로 되돌리려면 제안을 사용하거나 [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](/docs/ko/env-vars)을 `true`로 설정합니다.

759 759

760가장 최신의 이전 곁질문 5개가 현재 답변 위에 흐릿한 목록으로 나타나며, 더 오래된 것의 개수가 표시됩니다. 이들은 대화 기록에서 벗어납니다.760가장 최신의 이전 곁질문 5개가 현재 답변 위에 흐릿한 목록으로 나타나며, 더 오래된 것의 개수가 표시됩니다. 이들은 대화 기록에서 벗어납니다.

761 761

762오버레이를 해제한 후 돌아가려면 질문 없이 `/btw`를 실행하세요. 오버레이는 가장 최근의 교환에서 다시 열립니다. v2.1.212 이전에는 질문 없이 `/btw`를 실행하면 대신 사용 메시지를 출력했습니다.762오버레이를 해제한 후 돌아가려면 질문 없이 `/btw`를 실행하세요. 오버레이는 가장 최근의 교환에서 다시 열립니다.

763 763

764답변이 나타나면 오버레이는 다음 키를 허용합니다.764답변이 나타나면 오버레이는 다음 키를 허용합니다.

765 765

keybindings.md +3 −4

Details

463| `abovePrompt:highlightPrevious` | Up | 포커스된 선택 상자에서 이전 옵션 강조 표시 |463| `abovePrompt:highlightPrevious` | Up | 포커스된 선택 상자에서 이전 옵션 강조 표시 |

464 464

465두 컨텍스트는 기본적으로 이러한 작업에 추가 키를 바인딩합니다:465[`AbovePrompt` 컨텍스트](#contexts)에서는 기본적으로 Right 및 Left도 `abovePrompt:next` 및 `abovePrompt:previous`를 실행하고, Space도 `abovePrompt:press`를 실행합니다.

~~466~~

467* **`AbovePrompt`**: Right 및 Left도 `abovePrompt:next` 및 `abovePrompt:previous`를 실행하고, Space도 `abovePrompt:press`를 실행합니다

468* **`AbovePromptInput`**: Down 및 Up도 `abovePrompt:next` 및 `abovePrompt:previous`를 실행합니다

469 466

470`AbovePrompt` 컨텍스트는 또한 Up, Down, PageUp, PageDown, Home 및 End를 [창 스크롤 작업](#pane-actions)인 `pane:scrollUp`부터 `pane:bottom`까지에 바인딩하므로, 영역에 대해 해당 키 중 하나를 변경하려면 `AbovePrompt` 블록에서 스크롤 작업을 바인딩하세요.467`AbovePrompt` 컨텍스트는 또한 Up, Down, PageUp, PageDown, Home 및 End를 [창 스크롤 작업](#pane-actions)인 `pane:scrollUp`부터 `pane:bottom`까지에 바인딩하므로, 영역에 대해 해당 키 중 하나를 변경하려면 `AbovePrompt` 블록에서 스크롤 작업을 바인딩하세요.

471 468

769* vim NORMAL 모드에서 `?`는 도움말 메뉴를 표시합니다(vim 동작).766* vim NORMAL 모드에서 `?`는 도움말 메뉴를 표시합니다(vim 동작).

770* vim NORMAL 모드에서 `/`는 히스토리 검색을 열며, 표준 모드의 Ctrl+R과 동일합니다.767* vim NORMAL 모드에서 `/`는 히스토리 검색을 열며, 표준 모드의 Ctrl+R과 동일합니다.

771 768

769Claude가 묻는 질문의 `Other` 행에서는 vim 모드일 때 Escape를 눌러도 질문이 바로 취소되지 않습니다. [화면 읽기 프로그램 모드](/docs/ko/accessibility)가 아닌 경우, 이 행은 포커스될 때마다 INSERT 모드로 시작합니다. `Other` 행에서 Escape를 누르면 행이 NORMAL 모드로 전환되거나 입력하던 vim 명령이 취소되며, 질문은 열린 상태로 유지됩니다. 질문을 취소하려면 NORMAL 모드에서 Escape를 한 번 더 누릅니다.

770

772<h2 id="validation">771<h2 id="validation">

773 유효성 검사772 유효성 검사

774</h2>773</h2>

mcp.md +5 −5

Details

324* 로컬, 프로젝트, 사용자 [범위](#mcp-installation-scopes) 또는 관리형 MCP 구성의 서버의 경우, 원점은 해당 구성에 작성된 호스트를 표시하므로 호스트의 `${VAR}` 참조는 메시지에서 확장되지 않습니다.324* 로컬, 프로젝트, 사용자 [범위](#mcp-installation-scopes) 또는 관리형 MCP 구성의 서버의 경우, 원점은 해당 구성에 작성된 호스트를 표시하므로 호스트의 `${VAR}` 참조는 메시지에서 확장되지 않습니다.

325* 상태 또는 오류 코드가 없는 실패의 경우 Claude Code는 원점 없이 오류 텍스트를 표시합니다.325* 상태 또는 오류 코드가 없는 실패의 경우 Claude Code는 원점 없이 오류 텍스트를 표시합니다.

326 326

327구성의 `url`이 비어 있는 원격 서버는 `/mcp`, `claude mcp list` 및 [`/plugin`](/docs/ko/plugins/install) 관리자에서 `not configured`로 표시되며, Claude Code는 연결을 시도하지 않습니다. 플러그인은 나중에 구성할 커넥터를 위해 이와 같은 자리 표시자 항목을 포함할 수 있으므로 Claude Code는 이를 오류 또는 설정 문제로 보고하지 않습니다. `/mcp`의 서버 세부 정보 보기에는 `No URL configured for this server`가 표시됩니다. 연결하려면 항목의 `url`을 설정하세요. v2.1.208 이전에는 Claude Code가 빈 `url`을 재연결 프롬프트와 함께 구성 문제로 보고했습니다.327구성의 `url`이 비어 있는 원격 서버는 `/mcp`, `claude mcp list` 및 [`/plugin`](/docs/ko/plugins/install) 관리자에서 `not configured`로 표시되며, Claude Code는 연결을 시도하지 않습니다. 플러그인은 나중에 구성할 커넥터를 위해 이와 같은 자리 표시자 항목을 포함할 수 있으므로 Claude Code는 이를 오류 또는 설정 문제로 보고하지 않습니다. `/mcp`의 서버 세부 정보 보기에는 `No URL configured for this server`가 표시됩니다. 연결하려면 항목의 `url`을 설정하세요.

328 328

329<h4 id="configuration-warnings">329<h4 id="configuration-warnings">

330 구성 경고330 구성 경고

403* **대화형 터미널 세션에서**는 Claude Code가 해당 서버에서 업데이트된 목록을 가져오므로 서버를 다시 연결할 필요가 없습니다.403* **대화형 터미널 세션에서**는 Claude Code가 해당 서버에서 업데이트된 목록을 가져오므로 서버를 다시 연결할 필요가 없습니다.

404* **`-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless) 및 [Agent SDK](/docs/ko/agent-sdk/overview)에서**는 Claude Code가 이러한 알림에 대해 도구 목록만 새로 고칩니다.404* **`-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless) 및 [Agent SDK](/docs/ko/agent-sdk/overview)에서**는 Claude Code가 이러한 알림에 대해 도구 목록만 새로 고칩니다.

405 405

406새로 고침 요청이 실패하면 Claude Code는 나중에 새로 고침이 성공할 때까지 서버의 이전에 발견된 도구, 프롬프트 및 리소스를 유지합니다. v2.1.214 이전에는 새로 고침 중 일시적 오류가 서버의 도구, 프롬프트 및 리소스를 빈 목록으로 바꿨습니다.406새로 고침 요청이 실패하면 Claude Code는 나중에 새로 고침이 성공할 때까지 서버의 이전에 발견된 도구, 프롬프트 및 리소스를 유지합니다.

407 407

408<h4 id="notification-streams-on-the-v2-runtime">408<h4 id="notification-streams-on-the-v2-runtime">

409 v2 런타임의 알림 스트림409 v2 런타임의 알림 스트림

502 긴 도구 호출의 자동 백그라운드 처리502 긴 도구 호출의 자동 백그라운드 처리

503</h3>503</h3>

504 504

505주 대화에서 2분 이상 실행 중인 MCP 도구 호출은 세션을 차단하는 대신 백그라운드 작업으로 이동합니다. Claude는 작업 ID를 즉시 받고 계속 작업하며, 호출이 완료되면 결과가 작업 알림으로 도착합니다. 자동 백그라운드 처리에는 Claude Code v2.1.212 이상이 필요합니다.505주 대화에서 2분 이상 실행 중인 MCP 도구 호출은 세션을 차단하는 대신 백그라운드 작업으로 이동합니다. Claude는 작업 ID를 즉시 받고 계속 작업하며, 호출이 완료되면 결과가 작업 알림으로 도착합니다.

506 506

507작업은 [`/tasks`](/docs/ko/commands#all-commands)에 나타나며, 여기서 중지할 수도 있습니다. 작업은 세션을 종료하면 유지되지 않습니다. 작업 항목에는 서버가 보고한 최신 진행 상황이 표시됩니다. 작업을 중지하면 Claude Code는 호출을 취소하고 결과가 오지 않는다고 Claude에 알립니다. 중지한다고 해서 서버가 중지된다는 보장은 없습니다: 서버가 이미 작업의 일부를 수행했거나 여전히 작업을 완료할 수 있습니다.507작업은 [`/tasks`](/docs/ko/commands#all-commands)에 나타나며, 여기서 중지할 수도 있습니다. 작업은 세션을 종료하면 유지되지 않습니다. 작업 항목에는 서버가 보고한 최신 진행 상황이 표시됩니다. 작업을 중지하면 Claude Code는 호출을 취소하고 결과가 오지 않는다고 Claude에 알립니다. 중지한다고 해서 서버가 중지된다는 보장은 없습니다: 서버가 이미 작업의 일부를 수행했거나 여전히 작업을 완료할 수 있습니다.

508 508

1301 커넥터가 Claude Code에 도달하는 방식1301 커넥터가 Claude Code에 도달하는 방식

1302</h3>1302</h3>

1303 1303

1304claude.ai 커넥터를 제어하는 설정은 세션이 실행되는 위치에 따라 달라집니다. 일부 세션만 claude.ai에서 커넥터를 가져오기 때문입니다. 아래의 각 행은 한 종류의 세션에서 커넥터가 도착하는 방식과 그곳에서 이를 제어하는 것을 이름 지정합니다. 데스크톱 앱의 [WSL 세션](/docs/ko/desktop-wsl#what-works-in-a-wsl-session)은 아직 커넥터를 사용할 수 없으므로 행이 없습니다.1304claude.ai 커넥터를 제어하는 설정은 세션이 실행되는 위치에 따라 달라집니다. 일부 세션만 claude.ai에서 커넥터를 가져오기 때문입니다. 아래의 각 행은 한 종류의 세션에서 커넥터가 도착하는 방식과 그곳에서 이를 제어하는 것을 이름 지정합니다. 데스크톱 앱의 WSL 세션에는 커넥터가 [아직 순차적으로 제공되는 중](/docs/ko/desktop-wsl#check-for-the-terminal-and-connectors)이므로 행이 없습니다.

1305 1305

1307| :- | :- | :- |1307| :- | :- | :- |

1531 1531

1532[Remote Control](/docs/ko/remote-control)이나 [Agent SDK](/docs/ko/agent-sdk/overview)로 구축한 애플리케이션과 같은 일부 사용 환경에서는 일반적으로 한 번의 탭으로 도구 호출을 승인할 수 있습니다. 이 어노테이션이 지정된 도구의 경우 Claude Code는 한 번의 탭 동작을 제공하지 않고 대신 도구의 전체 권한 프롬프트를 표시합니다. 따라서 승인은 탭이 아니라 프롬프트에 응답하는 사람으로부터 이루어집니다.1532[Remote Control](/docs/ko/remote-control)이나 [Agent SDK](/docs/ko/agent-sdk/overview)로 구축한 애플리케이션과 같은 일부 사용 환경에서는 일반적으로 한 번의 탭으로 도구 호출을 승인할 수 있습니다. 이 어노테이션이 지정된 도구의 경우 Claude Code는 한 번의 탭 동작을 제공하지 않고 대신 도구의 전체 권한 프롬프트를 표시합니다. 따라서 승인은 탭이 아니라 프롬프트에 응답하는 사람으로부터 이루어집니다.

1533 1533

1534Claude Code는 터미널 대화 상자에서만 전체를 표시할 수 있는 모든 권한 요청에 대해서도 같은 방식으로 한 번의 탭 승인을 제공하지 않습니다. 예를 들어 안전 경고가 포함되어 있거나, 원격 사용 환경에서 표시할 수 없는 항상 허용 옵션이 포함된 요청이 이에 해당합니다. 이러한 요청은 Remote Control이 아닌 터미널 대화 상자에서 응답해야 합니다. Claude Code v2.1.214 이상이 필요합니다.1534Claude Code는 터미널 대화 상자에서만 전체를 표시할 수 있는 모든 권한 요청에 대해서도 같은 방식으로 한 번의 탭 승인을 제공하지 않습니다. 예를 들어 안전 경고가 포함되어 있거나, 원격 사용 환경에서 표시할 수 없는 항상 허용 옵션이 포함된 요청이 이에 해당합니다. 이러한 요청은 Remote Control이 아닌 터미널 대화 상자에서 응답해야 합니다.

1535 1535

1536<h2 id="respond-to-mcp-elicitation-requests">1536<h2 id="respond-to-mcp-elicitation-requests">

1537 MCP 유도 요청에 응답하기1537 MCP 유도 요청에 응답하기

memory.md +3 −3

Details

495 495

496## Claude Code496## Claude Code

497 497

498`src/billing/` 아래의 변경 사항에 대해 플랜 모드를 사용합니다.498Use plan mode for changes under `src/billing/`.

499```499```

500 500

501Claude 특정 내용이 필요하지 않으면 심볼릭 링크도 작동합니다:501Claude 특정 내용이 필요하지 않으면 심볼릭 링크도 작동합니다:

521* `.github/copilot-instructions.md`의 Copilot 규칙521* `.github/copilot-instructions.md`의 Copilot 규칙

522* `CLAUDE_CODE_NEW_INIT=1` 설정: `AGENTS.md`, `.devin/rules/`, `.windsurf/rules/` 또는 `.windsurfrules`, `.clinerules`522* `CLAUDE_CODE_NEW_INIT=1` 설정: `AGENTS.md`, `.devin/rules/`, `.windsurf/rules/` 또는 `.windsurfrules`, `.clinerules`

523 523

524[`/import`](/docs/ko/commands)를 실행하여 지원되는 코딩 에이전트의 구성을 Claude Code로 가져올 수도 있습니다. 이는 `AGENTS.md`와 같은 지침 파일의 일회성 복사본을 일치하는 `CLAUDE.md`에 추가하고 MCP 서버, 명령, 하위 에이전트 및 기술을 전달합니다. Claude Code v2.1.213 이상이 필요합니다.524[`/import`](/docs/ko/commands)를 실행하여 지원되는 코딩 에이전트의 구성을 Claude Code로 가져올 수도 있습니다. 이는 `AGENTS.md`와 같은 지침 파일의 일회성 복사본을 일치하는 `CLAUDE.md`에 추가하고 MCP 서버, 명령, 서브에이전트 및 스킬을 가져옵니다.

525 525

526<h2 id="auto-memory">526<h2 id="auto-memory">

527 자동 메모리527 자동 메모리

615 615

616Claude는 세션 중에 메모리 파일을 읽고 씁니다. Claude Code 인터페이스에서 "Saved 2 memories" 또는 "Recalled 2 memories" 같은 메시지가 표시되면 Claude가 `~/.claude/projects/<project>/memory/`를 적극적으로 업데이트하거나 읽고 있는 것입니다.616Claude는 세션 중에 메모리 파일을 읽고 씁니다. Claude Code 인터페이스에서 "Saved 2 memories" 또는 "Recalled 2 memories" 같은 메시지가 표시되면 Claude가 `~/.claude/projects/<project>/memory/`를 적극적으로 업데이트하거나 읽고 있는 것입니다.

617 617

618Claude가 YAML frontmatter로 시작하는 메모리 파일을 쓰면, Claude Code는 쓰기 시각을 `modified` frontmatter 필드에 ISO 8601 타임스탬프로 기록합니다. 이 타임스탬프는 사용자와, 메모리를 다시 읽을 때의 Claude 모두에게 해당 사실이 얼마나 최신인지 보여 줍니다. frontmatter가 있는 파일은 이전 버전에서 생성된 파일을 포함해 Claude가 다음에 쓸 때 이 필드를 갖게 됩니다. Claude Code는 frontmatter가 없는 파일에는 frontmatter를 추가하지 않습니다. `modified` 필드에는 Claude Code v2.1.214 이상이 필요합니다.618Claude가 YAML frontmatter로 시작하는 메모리 파일을 쓰면, Claude Code는 쓰기 시각을 `modified` frontmatter 필드에 ISO 8601 타임스탬프로 기록합니다. 이 타임스탬프는 사용자와, 메모리를 다시 읽을 때의 Claude 모두에게 해당 사실이 얼마나 최신인지 보여 줍니다.

619 619

620<h3 id="audit-and-edit-your-memory">620<h3 id="audit-and-edit-your-memory">

621 메모리 감사 및 편집621 메모리 감사 및 편집

model-config.md +3 −2

Details

274* **스킬 또는 명령 재정의**: Claude Code는 차단된 패밀리 별칭을 포함한 재정의를 무시하고, 스킬 또는 명령은 세션 모델에서 실행됩니다. [서브에이전트에서 실행되는](/docs/ko/skills#run-skills-in-a-subagent) 스킬 또는 명령은 대신 위의 서브에이전트 동작을 따릅니다274* **스킬 또는 명령 재정의**: Claude Code는 차단된 패밀리 별칭을 포함한 재정의를 무시하고, 스킬 또는 명령은 세션 모델에서 실행됩니다. [서브에이전트에서 실행되는](/docs/ko/skills#run-skills-in-a-subagent) 스킬 또는 명령은 대신 위의 서브에이전트 동작을 따릅니다

275* **`advisorModel` 설정**: 어드바이저는 세션에 대해 비활성화됩니다275* **`advisorModel` 설정**: 어드바이저는 세션에 대해 비활성화됩니다

276* **`--advisor` 플래그**: Claude Code는 시작 시 오류로 종료됩니다. [백그라운드 세션](/docs/ko/agent-view)에서는 종료하지 않고 어드바이저 없이 세션을 시작합니다276* **`--advisor` 플래그**: Claude Code는 시작 시 오류로 종료됩니다. [백그라운드 세션](/docs/ko/agent-view)에서는 종료하지 않고 어드바이저 없이 세션을 시작합니다

277* **`CLAUDE_CODE_AUTO_MODE_MODEL`**: Claude Code는 변수를 무시하고, 이 변수를 설정하지 않은 것처럼 [자동 모드 분류기 요청](/docs/ko/permission-modes#default-classifier-model)에 사용할 모델을 선택합니다

277 278

278Claude Code는 `/model` 선택기에서 제외된 모델을 숨깁니다. 나열한 모델 ID가 자체 행도 갖는지는 제공자에 따라 다릅니다:279Claude Code는 `/model` 선택기에서 제외된 모델을 숨깁니다. 나열한 모델 ID가 자체 행도 갖는지는 제공자에 따라 다릅니다:

279 280

285* **[폴백 모델 체인](#fallback-model-chains)**: 허용 목록 외부의 항목은 삭제됩니다286* **[폴백 모델 체인](#fallback-model-chains)**: 허용 목록 외부의 항목은 삭제됩니다

286* **계획 모드 업그레이드**: Anthropic API 및 Claude Platform on AWS에서, [`opusplan`](#opusplan-model-setting)과 같은 업그레이드를 제외된 모델로 수행하면 업그레이드 패밀리의 최신 허용 버전을 사용합니다. 제공자별 모델 ID가 있는 제공자에서, 그리고 허용된 버전이 없을 때, 업그레이드는 건너뛰고 계획은 세션의 모델에서 계속됩니다287* **계획 모드 업그레이드**: Anthropic API 및 Claude Platform on AWS에서, [`opusplan`](#opusplan-model-setting)과 같은 업그레이드를 제외된 모델로 수행하면 업그레이드 패밀리의 최신 허용 버전을 사용합니다. 제공자별 모델 ID가 있는 제공자에서, 그리고 허용된 버전이 없을 때, 업그레이드는 건너뛰고 계획은 세션의 모델에서 계속됩니다

287* **[자동 모델 폴백](#automatic-model-fallback)**: 대상이 제외된 폴백은 실행되지 않으므로, 플래그된 요청은 거부로 끝납니다288* **[자동 모델 폴백](#automatic-model-fallback)**: 대상이 제외된 폴백은 실행되지 않으므로, 플래그된 요청은 거부로 끝납니다

288* **[자동 모드 분류기](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)**: 분류기의 Claude Sonnet 5 기본값은 허용 목록이 Sonnet 5를 허용할 때만 적용됩니다. 제외될 때, 분류기는 허용 목록이 이미 관리하는 세션의 모델에서 실행되거나, 세션이 [Fable 모델](#work-with-fable)에서 실행될 때 Opus 모델에서 실행됩니다. Anthropic API 이외의 제공자에서, 해당 Opus 폴백은 허용 목록을 참조하지 않고 `ANTHROPIC_DEFAULT_OPUS_MODEL`에 설정한 모델에서, 설정하지 않은 경우 Opus 5에서 실행됩니다. Claude Code v2.1.210 이상 필요289* **[자동 모드 분류기](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)**: 허용 목록이 [기본 분류기 모델](/docs/ko/permission-modes#default-classifier-model)을 제외하면, 해당 모델을 사용하게 될 분류기 요청은 세션 모델에서 실행되거나, [Fable](#work-with-fable) 세션에서는 Opus 모델에서 실행됩니다. Anthropic API 이외의 제공자에서, 해당 Opus 폴백은 허용 목록을 참조하지 않고 `ANTHROPIC_DEFAULT_OPUS_MODEL`에 설정한 모델에서, 설정하지 않은 경우 Opus 5에서 실행됩니다. Claude Code v2.1.210 이상 필요

289* **[빠른 모드](/docs/ko/fast-mode)**: 세션이 이후에 실행될 모델이 허용 목록 외부에 있을 때 빠른 모드 활성화가 거부됩니다290* **[빠른 모드](/docs/ko/fast-mode)**: 세션이 이후에 실행될 모델이 허용 목록 외부에 있을 때 빠른 모드 활성화가 거부됩니다

290* **Amazon Bedrock 및 Google Cloud의 Agent Platform의 가용성 폴백**: 세션 도중 계정이 모델에 대한 액세스 권한을 잃으면, 다른 모델로 전환할 때 제외된 모델을 건너뜁니다. [Amazon Bedrock](/docs/ko/amazon-bedrock#when-your-organization-enforces-a-model-allowlist) 및 [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai#when-your-organization-enforces-a-model-allowlist)의 시작 시 모델 확인은 관리형 설정이 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)도 설정할 때만 제외된 모델을 건너뜁니다291* **Amazon Bedrock 및 Google Cloud의 Agent Platform의 가용성 폴백**: 세션 도중 계정이 모델에 대한 액세스 권한을 잃으면, 다른 모델로 전환할 때 제외된 모델을 건너뜁니다. [Amazon Bedrock](/docs/ko/amazon-bedrock#when-your-organization-enforces-a-model-allowlist) 및 [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai#when-your-organization-enforces-a-model-allowlist)의 시작 시 모델 확인은 관리형 설정이 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)도 설정할 때만 제외된 모델을 건너뜁니다

291 292

428 429

429제한된 모델은 `/model` 선택기에서 숨겨집니다. `--model`, `ANTHROPIC_MODEL` 환경 변수, 또는 `model` 설정으로 이름으로 선택하면 `Model "<name>" is restricted by your organization's settings. Using <model> instead.` 알림을 표시하고 세션은 허용된 모델에서 시작됩니다. 제한된 모델에 대해 `/model <name>`을 입력하면 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`로 거부되고 세션은 현재 모델을 유지합니다.430제한된 모델은 `/model` 선택기에서 숨겨집니다. `--model`, `ANTHROPIC_MODEL` 환경 변수, 또는 `model` 설정으로 이름으로 선택하면 `Model "<name>" is restricted by your organization's settings. Using <model> instead.` 알림을 표시하고 세션은 허용된 모델에서 시작됩니다. 제한된 모델에 대해 `/model <name>`을 입력하면 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`로 거부되고 세션은 현재 모델을 유지합니다.

430 431

431`opus`, `sonnet`, `haiku`, 또는 `fable`과 같은 [모델 패밀리 별칭](#restrict-model-selection)은 조직이 이를 허용할 때 일반적인 모델로 해석됩니다. 조직이 해당 모델을 제한할 때, Claude Code는 조직이 허용하는 패밀리의 최신 버전으로 대체하고 동일한 대체 알림을 표시합니다. `/model <alias>`는 패밀리의 모든 버전이 제한될 때만 거부됩니다. `--model`, `ANTHROPIC_MODEL`, 또는 `model` 설정으로 설정된 별칭은 여전히 시작 시 해당 경우에 대체됩니다. v2.1.205 이전에는 패밀리 별칭이 최신 릴리스 버전만을 기반으로 대체되거나 거부되었으며, 이전 버전이 허용되었을 때도 마찬가지였습니다.432`opus`와 같은 [모델 패밀리 별칭](#restrict-model-selection)은 조직이 이를 허용할 때 일반적인 모델로 해석됩니다. 조직이 해당 모델을 제한할 때, Claude Code는 조직이 허용하는 패밀리의 최신 버전으로 대체하고 동일한 대체 알림을 표시합니다. `/model <alias>`는 패밀리의 모든 버전이 제한될 때만 거부됩니다. `--model`, `ANTHROPIC_MODEL`, 또는 `model` 설정으로 설정된 별칭은 여전히 시작 시 해당 경우에 대체됩니다. v2.1.205 이전에는 패밀리 별칭이 최신 릴리스 버전만을 기반으로 대체되거나 거부되었으며, 이전 버전이 허용되었을 때도 마찬가지였습니다.

432 433

433제한은 조직 전체 또는 역할별로 적용됩니다:434제한은 조직 전체 또는 역할별로 적용됩니다:

434 435

monitoring-usage.md +79 −42

Details

137| `OTEL_LOG_TOOL_CONTENT` | [`tool.output` 범위 이벤트](#tool-output-span-event)에서 도구 콘텐츠 로깅 활성화(기본값: 비활성화). 범위 속성은 [자체 게이트](#new-context-gates) 아래에서 도구 콘텐츠를 전달합니다. [추적](#traces-beta) 필요. 콘텐츠는 콘텐츠 제한(기본값 60KB)에서 잘립니다 | `1`로 활성화 |137| `OTEL_LOG_TOOL_CONTENT` | [`tool.output` 범위 이벤트](#tool-output-span-event)에서 도구 콘텐츠 로깅 활성화(기본값: 비활성화). 범위 속성은 [자체 게이트](#new-context-gates) 아래에서 도구 콘텐츠를 전달합니다. [추적](#traces-beta) 필요. 콘텐츠는 콘텐츠 제한(기본값 60KB)에서 잘립니다 | `1`로 활성화 |

138| `OTEL_LOG_MANAGED_SETTINGS` | 편집된 관리 설정 및 편집 전 설정의 SHA-256 다이제스트를 [관리 설정 해결됨](#managed-settings-resolved-event) 이벤트에 추가합니다(기본값: 비활성화). 프로젝트 또는 로컬 설정의 값은 이를 켜지 않습니다. Claude Code v2.1.274 이상 필요 | `1`로 활성화 |138| `OTEL_LOG_MANAGED_SETTINGS` | 편집된 관리 설정 및 편집 전 설정의 SHA-256 다이제스트를 [관리 설정 해결됨](#managed-settings-resolved-event) 이벤트에 추가합니다(기본값: 비활성화). 프로젝트 또는 로컬 설정의 값은 이를 켜지 않습니다. Claude Code v2.1.274 이상 필요 | `1`로 활성화 |

139| `OTEL_LOG_RAW_API_BODIES` | 전체 Anthropic Messages API 요청 및 응답 JSON을 `api_request_body` / `api_response_body` 로그 이벤트로 내보냅니다(기본값: 비활성화). 본문에는 전체 대화 기록이 포함됩니다. 이를 활성화하면 `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_DETAILS` 및 `OTEL_LOG_TOOL_CONTENT`가 드러낼 모든 것에 동의하는 것을 의미합니다 | 콘텐츠 제한(기본값 60KB)에서 잘린 인라인 본문의 경우 `1`, 또는 이벤트의 `body_ref` 포인터가 있는 디스크의 잘리지 않은 본문의 경우 `file:<dir>` |139| `OTEL_LOG_RAW_API_BODIES` | 전체 Anthropic Messages API 요청 및 응답 JSON을 `api_request_body` / `api_response_body` 로그 이벤트로 내보냅니다(기본값: 비활성화). 본문에는 전체 대화 기록이 포함됩니다. 이를 활성화하면 `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_DETAILS` 및 `OTEL_LOG_TOOL_CONTENT`가 드러낼 모든 것에 동의하는 것을 의미합니다 | 콘텐츠 제한(기본값 60KB)에서 잘린 인라인 본문의 경우 `1`, 또는 이벤트의 `body_ref` 포인터가 있는 디스크의 잘리지 않은 본문의 경우 `file:<dir>` |

140| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 콘텐츠 제한: 모델 응답, 도구 콘텐츠, 시스템 프롬프트 및 원본 API 본문과 같은 콘텐츠 포함 속성의 최대 길이(잘림 마커 포함, UTF-16 코드 단위)(기본값: 61440, 즉 60KB). 기본값은 속성 값을 64KB로 제한하는 백엔드용으로 크기가 조정됩니다. 백엔드가 더 큰 값을 허용하는 경우에만 높이거나, 원격 분석 볼륨을 줄이려면 낮추세요. OpenTelemetry SDK 속성 제한인 `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` 또는 해당 logrecord 및 범위 변형이 더 낮게 설정된 경우, Claude Code는 `[TRUNCATED ...]` 마커가 SDK 제한 내에 유지되도록 더 작은 값에서 잘립니다. Claude Code v2.1.214 이상 필요 | `262144` |140| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 콘텐츠 제한: 모델 응답, 도구 콘텐츠, 시스템 프롬프트 및 원본 API 본문과 같은 콘텐츠 포함 속성의 최대 길이(잘림 마커 포함, UTF-16 코드 단위)(기본값: 61440, 즉 60KB). 기본값은 속성 값을 64KB로 제한하는 백엔드용으로 크기가 조정됩니다. 백엔드가 더 큰 값을 허용하는 경우에만 높이거나, 텔레메트리 볼륨을 줄이려면 낮추세요. OpenTelemetry SDK 속성 제한인 `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` 또는 해당 logrecord 및 범위 변형이 더 낮게 설정된 경우, Claude Code는 `[TRUNCATED ...]` 마커가 SDK 제한 내에 유지되도록 더 작은 값에서 잘립니다 | `262144` |

142| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 동적 헤더 새로 고침 간격(기본값: 1740000ms / 29분) | `900000` |142| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 동적 헤더 새로 고침 간격(기본값: 1740000ms / 29분) | `900000` |

143 143

144`http/protobuf` 및 `http/json` 프로토콜의 경우, Claude Code는 각 내보내기 요청을 `Content-Length` 헤더와 함께 보냅니다. v2.1.212 이전에는 v2.1.191 이상의 Claude Code 버전이 청크 전송 인코딩을 사용하여 이러한 요청을 보냈습니다. Azure Monitor 및 기타 선언된 길이가 필요한 엔드포인트는 `411 Length Required` 또는 `400` 오류로 이를 거부했습니다.144`http/protobuf` 및 `http/json` 프로토콜의 경우, Claude Code는 각 내보내기 요청을 `Content-Length` 헤더와 함께 보냅니다.

145 145

146<h3 id="mtls-authentication">146<h3 id="mtls-authentication">

147 mTLS 인증147 mTLS 인증

202 202

203인바운드 추적 컨텍스트는 [이벤트](#events)에도 적용됩니다. `TRACEPARENT`가 설정된 Agent SDK 및 `-p` 세션에서 각 OTLP 이벤트 로그 레코드는 추적 내보내기가 구성되지 않은 경우에도 로깅 백엔드가 이벤트를 추적의 나머지와 상관시킬 수 있도록 애플리케이션의 추적에 조인하는 `trace_id` 및 `span_id` 값을 전달합니다.203인바운드 추적 컨텍스트는 [이벤트](#events)에도 적용됩니다. `TRACEPARENT`가 설정된 Agent SDK 및 `-p` 세션에서 각 OTLP 이벤트 로그 레코드는 추적 내보내기가 구성되지 않은 경우에도 로깅 백엔드가 이벤트를 추적의 나머지와 상관시킬 수 있도록 애플리케이션의 추적에 조인하는 `trace_id` 및 `span_id` 값을 전달합니다.

204 204

205상호작용이 활성화되는 동안 내보낸 레코드는 권한 프롬프트 콜백이나 시작 중에 버퍼링되고 나중에 내보낸 레코드와 같이 범위의 비동기 컨텍스트 외부에서 Claude Code가 내보낸 경우에도 상호작용 범위의 ID를 전달합니다. 활성 상호작용 범위가 없는 상태에서 내보낸 레코드는 인바운드 `TRACEPARENT` ID를 직접 전달합니다. v2.1.214 이전에는 범위의 비동기 컨텍스트 외부에서 내보낸 레코드가 범위의 ID 대신 인바운드 `TRACEPARENT` ID를 전달했습니다. v2.1.212 이전에는 활성 범위 외부에서 내보낸 이벤트 레코드가 `trace_id` 또는 `span_id`를 전달하지 않았습니다.205상호작용이 활성화되는 동안 내보낸 레코드는 권한 프롬프트 콜백이나 시작 중에 버퍼링되고 나중에 내보낸 레코드와 같이 범위의 비동기 컨텍스트 외부에서 Claude Code가 내보낸 경우에도 상호작용 범위의 ID를 전달합니다. 활성 상호작용 범위가 없는 상태에서 내보낸 레코드는 인바운드 `TRACEPARENT` ID를 직접 전달합니다.

206 206

207<h4 id="span-hierarchy">207<h4 id="span-hierarchy">

208 범위 계층 구조208 범위 계층 구조

328| 속성 | 설명 | 게이트 |328| 속성 | 설명 | 게이트 |

329| - | - | - |329| - | - | - |

332| `source` | [도구 결정 이벤트](#tool-decision-event)와 일치하는 결정 소스 | |332| `source` | `accept` 또는 `reject`의 경우 결정의 출처로, `config`, `hook` 또는 `user_temporary`와 같으며 각 의미는 [도구 결정 이벤트](#tool-decision-event)에 설명되어 있습니다. `cancelled`의 경우 결정이 내려지기 전에 대기를 종료한 원인으로, `user_abort`와 같습니다 | |

333

334`source`가 `user_abort`인 `cancelled` 결정은 권한 프롬프트 또는 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 검사가 보류 중인 동안 즉시 전달해야 하는 메시지가 턴을 중단했음을 의미합니다. 예를 들어 자동 모드 검사 중에 사용자가 대기열에 메시지를 넣어 두었다가 [즉시 보낸](/docs/ko/interactive-mode#when-claude-code-sends-what-you-queued) 경우입니다.

333 335

334**`claude_code.tool.execution`**336**`claude_code.tool.execution`**

335 337

820| - | - |822| - | - |

823| `message.uuid` | 세션 기록에 유지되는 메시지의 UUID, `~/.claude/projects/*/*.jsonl` 파일. `assistant_response`, `api_response_body`, 및 명령 디스패치를 제외한 `user_prompt`에 있음, 이는 0개 이상의 메시지를 생성할 수 있음. `assistant_response` 및 `api_response_body`에서 이는 응답의 최종 기록 항목이며, 다음 턴의 `parentUuid`가 이로부터 체인됩니다. Claude Code v2.1.214 이상 필요, 또는 `api_response_body`에서 v2.1.274 이상 |825| `message.uuid` | 세션 트랜스크립트(`~/.claude/projects/*/*.jsonl` 파일)에 저장된 메시지의 UUID입니다. `assistant_response`, `api_response_body`, 그리고 `user_prompt`에 포함되며, 0개 또는 여러 개의 메시지를 생성할 수 있는 명령 디스패치에는 포함되지 않습니다. `assistant_response` 및 `api_response_body`에서는 응답의 마지막 트랜스크립트 항목이며, 다음 턴의 `parentUuid`가 이 항목에 연결됩니다. `api_response_body`에서는 Claude Code v2.1.274 이상이 필요합니다 |

824| `request_id` | `request-id` 응답 헤더에서 읽은 서버 할당 API 요청 ID, 예: `req_011...`. `request-id` 헤더가 없는 응답의 경우, [Amazon Bedrock](/docs/ko/amazon-bedrock)과 같이 값은 `x-amzn-requestid` 헤더에서 대신 옵니다. `api_request`, `api_error`, `api_refusal`, `assistant_response`, `api_response_body`에 있음, 응답이 헤더 중 하나를 전달할 때. `llm_request` 추적 스팬의 동일한 속성과 일치합니다. `x-amzn-requestid` 소스는 Claude Code v2.1.282 이상 필요 |826| `request_id` | `request-id` 응답 헤더에서 읽은 서버 할당 API 요청 ID, 예: `req_011...`. `request-id` 헤더가 없는 응답의 경우, [Amazon Bedrock](/docs/ko/amazon-bedrock)과 같이 값은 `x-amzn-requestid` 헤더에서 대신 옵니다. `api_request`, `api_error`, `api_refusal`, `assistant_response`, `api_response_body`에 있음, 응답이 헤더 중 하나를 전달할 때. `llm_request` 추적 스팬의 동일한 속성과 일치합니다. `x-amzn-requestid` 소스는 Claude Code v2.1.282 이상 필요 |

825| `client_request_id` | `x-client-request-id` 요청 헤더로 전송된 클라이언트 생성 UUID. 첫 번째 당사자 API 연결에서 `api_request` 및 `api_error`에 있음; 타사 공급자 백엔드 및 요청이 비스트리밍 폴백을 통해 재시도되었을 때 없음. 요청을 응답과 쌍으로 만들고 서버 `request_id`를 생성하지 않은 시간 초과와 같은 실패에 대해 사용 가능하게 유지합니다. `llm_request` 추적 스팬의 동일한 속성과 일치합니다. Claude Code v2.1.214 이상 필요 |827| `client_request_id` | `x-client-request-id` 요청 헤더로 전송되는 클라이언트 생성 UUID입니다. 퍼스트파티 API 연결에서 `api_request` 및 `api_error`에 포함되며, 서드파티 제공자 백엔드에서나 요청이 비스트리밍 폴백을 통해 재시도된 경우에는 없습니다. 요청과 응답을 짝지으며, 서버 `request_id`를 생성하지 못한 타임아웃 같은 실패에서도 사용할 수 있습니다. `llm_request` 트레이스 스팬의 동일한 속성과 일치합니다 |

826 828

827단일 프롬프트로 트리거된 모든 활동을 추적하려면 특정 `prompt.id` 값으로 이벤트를 필터링하세요. 이는 user\_prompt 이벤트, 모든 api\_request 이벤트, 해당 프롬프트 처리 중에 발생한 모든 tool\_result 이벤트를 반환합니다.829단일 프롬프트로 트리거된 모든 활동을 추적하려면 특정 `prompt.id` 값으로 이벤트를 필터링하세요. 이는 user\_prompt 이벤트, 모든 api\_request 이벤트, 해당 프롬프트 처리 중에 발생한 모든 tool\_result 이벤트를 반환합니다.

828 830

851* `prompt_length`: 프롬프트의 길이853* `prompt_length`: 프롬프트의 길이

852* `prompt`: 프롬프트 내용. 기본적으로 수정됨. `OTEL_LOG_USER_PROMPTS=1`을 설정하여 포함854* `prompt`: 프롬프트 내용. 기본적으로 수정됨. `OTEL_LOG_USER_PROMPTS=1`을 설정하여 포함

853* `prompt_text`: `prompt`와 동일한 값으로, 동일한 조건에서 가려집니다. 점으로 구분된 속성 이름을 중첩 객체로 저장하는 백엔드는 `prompt.id`를 `prompt`라는 객체 안의 `id`로 읽어 프롬프트 문자열을 잃을 수 있습니다. 이러한 백엔드에서는 `prompt_text`를 대신 읽으세요. Claude Code v2.1.287 이상이 필요합니다855* `prompt_text`: `prompt`와 동일한 값으로, 동일한 조건에서 가려집니다. 점으로 구분된 속성 이름을 중첩 객체로 저장하는 백엔드는 `prompt.id`를 `prompt`라는 객체 안의 `id`로 읽어 프롬프트 문자열을 잃을 수 있습니다. 이러한 백엔드에서는 `prompt_text`를 대신 읽으세요. Claude Code v2.1.287 이상이 필요합니다

854* `message.uuid`: 결과 사용자 메시지의 UUID, 유지된 기록 항목과 일치. 명령 디스패치에서 없음, 0개 이상의 메시지를 생성할 수 있음. Claude Code v2.1.214 이상 필요856* `message.uuid`: 생성된 사용자 메시지의 UUID로, 저장된 트랜스크립트 항목과 일치합니다. 0개 또는 여러 개의 메시지를 생성할 수 있는 명령 디스패치에는 없습니다.

855* `command_name`: 프롬프트가 명령을 호출할 때 명령 이름. `compact` 또는 `debug`와 같은 기본 제공 및 번들 명령 이름은 그대로 내보냄; `reset`과 같은 별칭은 정규 이름이 아닌 입력한 대로 내보냄. 사용자 정의, 플러그인, MCP 명령 이름은 `OTEL_LOG_TOOL_DETAILS=1`이 설정되지 않은 경우 `custom` 또는 `mcp`로 축소됨857* `command_name`: 프롬프트가 명령을 호출할 때 명령 이름. `compact` 또는 `debug`와 같은 기본 제공 및 번들 명령 이름은 그대로 내보냄; `reset`과 같은 별칭은 정규 이름이 아닌 입력한 대로 내보냄. 사용자 정의, 플러그인, MCP 명령 이름은 `OTEL_LOG_TOOL_DETAILS=1`이 설정되지 않은 경우 `custom` 또는 `mcp`로 축소됨

856* `command_source`: 명령이 있을 때 명령의 출처: `builtin`, `custom`, 또는 `mcp`. 플러그인 제공 명령은 `custom`으로 보고됨858* `command_source`: 명령이 있을 때 명령의 출처: `builtin`, `custom`, 또는 `mcp`. 플러그인 제공 명령은 `custom`으로 보고됨

857 859

873* `response`: 응답 텍스트, 콘텐츠 제한에서 잘림 (기본값 60 KB). 기본적으로 `<REDACTED>`로 수정됨. `OTEL_LOG_ASSISTANT_RESPONSES=1`을 설정하여 포함. `OTEL_LOG_ASSISTANT_RESPONSES`가 설정되지 않으면 `OTEL_LOG_USER_PROMPTS`가 대신 제어하므로 프롬프트 로깅이 켜져 있는 동안 응답을 수정된 상태로 유지하려면 `OTEL_LOG_ASSISTANT_RESPONSES=0`을 설정하세요875* `response`: 응답 텍스트, 콘텐츠 제한에서 잘림 (기본값 60 KB). 기본적으로 `<REDACTED>`로 수정됨. `OTEL_LOG_ASSISTANT_RESPONSES=1`을 설정하여 포함. `OTEL_LOG_ASSISTANT_RESPONSES`가 설정되지 않으면 `OTEL_LOG_USER_PROMPTS`가 대신 제어하므로 프롬프트 로깅이 켜져 있는 동안 응답을 수정된 상태로 유지하려면 `OTEL_LOG_ASSISTANT_RESPONSES=0`을 설정하세요

874* `model`: 모델 식별자 (예: "claude-sonnet-5")876* `model`: 모델 식별자 (예: "claude-sonnet-5")

875* `request_id`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 API 요청 ID877* `request_id`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 API 요청 ID

876* `message.uuid`: 응답의 최종 기록 항목의 UUID. API 응답은 콘텐츠 블록당 하나의 기록 항목으로 유지됩니다; 이는 마지막 항목이며, 다음 턴의 `parentUuid`가 이로부터 체인됩니다. Claude Code v2.1.214 이상 필요878* `message.uuid`: 응답의 마지막 트랜스크립트 항목의 UUID입니다. API 응답은 콘텐츠 블록당 하나의 트랜스크립트 항목으로 저장되며, 이 값은 그중 마지막 항목으로 다음 턴의 `parentUuid`가 이 항목에 연결됩니다.

877* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름879* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름

878 880

879<h4 id="tool-result-event">881<h4 id="tool-result-event">

902* `tool_result_size_bytes`: 도구 결과의 크기 (바이트)904* `tool_result_size_bytes`: 도구 결과의 크기 (바이트)

903* `mcp_server_scope`: MCP 서버 범위 식별자 (MCP 도구의 경우)905* `mcp_server_scope`: MCP 서버 범위 식별자 (MCP 도구의 경우)

904* `vcs.ref.head.revision`, `vcs.ref.head.name`, `vcs.ref.head.type` (`OTEL_LOG_TOOL_DETAILS=1`일 때): Bash 또는 PowerShell 도구에 의해 실행된 성공적인 `git commit`의 커밋 ID. `vcs.ref.head.revision`은 커밋 SHA, `vcs.ref.head.name`은 커밋된 브랜치, `vcs.ref.head.type`은 `branch`. 커밋이 분리된 HEAD에서 이루어진 경우 이름과 유형이 생략됩니다. Claude Code v2.1.269 이상 필요906* `vcs.ref.head.revision`, `vcs.ref.head.name`, `vcs.ref.head.type` (`OTEL_LOG_TOOL_DETAILS=1`일 때): Bash 또는 PowerShell 도구에 의해 실행된 성공적인 `git commit`의 커밋 ID. `vcs.ref.head.revision`은 커밋 SHA, `vcs.ref.head.name`은 커밋된 브랜치, `vcs.ref.head.type`은 `branch`. 커밋이 분리된 HEAD에서 이루어진 경우 이름과 유형이 생략됩니다. Claude Code v2.1.269 이상 필요

905* `tool_parameters` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 도구별 매개변수를 포함하는 JSON 문자열. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서 `mcp_server_name`/`mcp_tool_name` 쌍은 플래그가 꺼져 있어도 포함되며, [도구 결정 이벤트](#tool-decision-event)와 동일한 호스트 작성 예외, Claude Code v2.1.214 이상 필요. 매개변수는 도구에 따라 다릅니다:907* `tool_parameters` (`OTEL_LOG_TOOL_DETAILS=1`인 경우): 도구별 매개변수를 포함하는 JSON 문자열입니다. Claude Desktop이 소유한 세션에서 Claude Desktop의 기본 제공 서버의 경우, [도구 결정 이벤트](#tool-decision-event)와 동일한 호스트 작성 예외로 플래그가 꺼져 있어도 `mcp_server_name`/`mcp_tool_name` 쌍이 포함됩니다. 매개변수는 도구에 따라 다릅니다.

906 * Bash 도구의 경우: `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox` 포함, `git commit` 명령이 성공할 때 `git_commit_id` 및 `git_branch`. `git_commit_id`는 커밋이 세션의 작업 디렉토리의 HEAD일 때 전체 커밋 SHA, 그 외의 경우 git의 축약된 SHA. `git_branch`는 커밋된 브랜치, 분리된 HEAD에서 생략됨908 * Bash 도구: `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox`를 포함하며, `git commit` 명령이 성공하면 `git_commit_id`와 `git_branch`도 포함합니다. `git_commit_id`는 커밋이 세션 작업 디렉터리의 HEAD인 경우 전체 커밋 SHA이고, 그렇지 않으면 git의 축약 SHA입니다. `git_branch`는 커밋된 브랜치이며, detached HEAD에서는 생략됩니다

907 * 데스크톱 앱의 작업 공간 Bash 도구의 경우, 또한 `tool_name`을 `Bash`로 보고: `bash_command`, `full_command`, `timeout`만 포함909 * `tool_name`도 `Bash`로 보고하는 데스크톱 앱의 워크스페이스 Bash 도구: `bash_command`, `full_command`, `timeout`만 포함합니다

908 * MCP 도구의 경우: `mcp_server_name`, `mcp_tool_name` 포함910 * MCP 도구: `mcp_server_name`, `mcp_tool_name`을 포함합니다

909 * Skill 도구의 경우: `skill_name` 포함911 * Skill 도구: `skill_name`을 포함합니다

910 * Agent 도구 또는 레거시 Task 도구의 경우: `subagent_type` 포함912 * Agent 도구 또는 레거시 Task 도구: `subagent_type`을 포함합니다

911* `tool_input` (`OTEL_LOG_TOOL_DETAILS=1`일 때): JSON 직렬화된 도구 인수. 512자를 초과하는 개별 값은 잘리며, 전체 페이로드는 약 4 K 문자로 제한됩니다. MCP 도구를 포함한 모든 도구에 적용됩니다.913* `tool_input` (`OTEL_LOG_TOOL_DETAILS=1`일 때): JSON 직렬화된 도구 인수. 512자를 초과하는 개별 값은 잘리며, 전체 페이로드는 약 4 K 문자로 제한됩니다. MCP 도구를 포함한 모든 도구에 적용됩니다.

912 914

913<h4 id="api-request-event">915<h4 id="api-request-event">

933* `cache_read_tokens`: 캐시에서 읽은 토큰 수935* `cache_read_tokens`: 캐시에서 읽은 토큰 수

934* `cache_creation_tokens`: 캐시 생성에 사용된 토큰 수936* `cache_creation_tokens`: 캐시 생성에 사용된 토큰 수

935* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명함.937* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명함.

936* `client_request_id`: `x-client-request-id` 요청 헤더로 전송된 클라이언트 생성 UUID; 존재할 때는 [이벤트 상관 속성](#event-correlation-attributes) 테이블을 참조하세요. Claude Code v2.1.214 이상 필요938* `client_request_id`: `x-client-request-id` 요청 헤더로 전송되는 클라이언트 생성 UUID입니다. 포함되는 경우는 [이벤트 상관 속성](#event-correlation-attributes) 표를 참조하세요

937* `speed`: `"fast"` 또는 `"normal"`, 빠른 모드가 활성화되었는지 여부를 나타냄939* `speed`: `"fast"` 또는 `"normal"`, 빠른 모드가 활성화되었는지 여부를 나타냄

938* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름940* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름

939* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level): `"low"`, `"medium"`, `"high"`, `"xhigh"`, 또는 `"max"`. Claude Code가 노력 수준을 보내지 않을 때 없음, 예를 들어 노력을 지원하지 않는 모델에서.941* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level): `"low"`, `"medium"`, `"high"`, `"xhigh"`, 또는 `"max"`. Claude Code가 노력 수준을 보내지 않을 때 없음, 예를 들어 노력을 지원하지 않는 모델에서.

959* `duration_ms`: 요청 지속 시간 (밀리초)961* `duration_ms`: 요청 지속 시간 (밀리초)

960* `attempt`: 최초 요청을 포함한 시도 횟수입니다. 횟수가 다시 시작되는 시점은 [재시도 소진 감지](#detect-retry-exhaustion)에서 설명합니다962* `attempt`: 최초 요청을 포함한 시도 횟수입니다. 횟수가 다시 시작되는 시점은 [재시도 소진 감지](#detect-retry-exhaustion)에서 설명합니다

961* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명함.963* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명함.

962* `client_request_id`: `x-client-request-id` 요청 헤더로 전송된 클라이언트 생성 UUID. 시간 초과 또는 연결 오류와 같은 실패가 서버 `request_id`를 생성하지 않았을 때도 사용 가능; 존재할 때는 [이벤트 상관 속성](#event-correlation-attributes) 테이블을 참조하세요. Claude Code v2.1.214 이상 필요964* `client_request_id`: `x-client-request-id` 요청 헤더로 전송되는 클라이언트 생성 UUID입니다. 타임아웃이나 연결 오류 같은 실패로 서버 `request_id`가 생성되지 않은 경우에도 사용할 수 있습니다. 포함되는 경우는 [이벤트 상관 속성](#event-correlation-attributes) 표를 참조하세요.

963* `speed`: `"fast"` 또는 `"normal"`, 빠른 모드가 활성화되었는지 여부를 나타냄965* `speed`: `"fast"` 또는 `"normal"`, 빠른 모드가 활성화되었는지 여부를 나타냄

964* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름966* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름

965* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level). Claude Code가 노력 수준을 보내지 않을 때 없음, 예를 들어 노력을 지원하지 않는 모델에서.967* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level). Claude Code가 노력 수준을 보내지 않을 때 없음, 예를 들어 노력을 지원하지 않는 모델에서.

1057* `tool_name`: 도구의 이름 (예: "Read", "Edit", "Write", "NotebookEdit")1059* `tool_name`: 도구의 이름 (예: "Read", "Edit", "Write", "NotebookEdit")

1058* `tool_use_id`: 이 도구 호출의 고유 식별자. 훅에 전달된 `tool_use_id`와 일치하여 OTel 이벤트와 훅 캡처 데이터 간의 상관 관계를 허용합니다.1060* `tool_use_id`: 이 도구 호출의 고유 식별자. 훅에 전달된 `tool_use_id`와 일치하여 OTel 이벤트와 훅 캡처 데이터 간의 상관 관계를 허용합니다.

1059* `decision`: `"accept"` 또는 `"reject"`1061* `decision`: `"accept"` 또는 `"reject"`

1060* `tool_source`: 항상 존재. 도구의 출처, CLI 작성 값의 폐쇄 집합으로. Claude Code v2.1.214 이상 필요1062* `tool_source`: 항상 포함됩니다. 도구의 출처로, CLI가 작성한 닫힌 값 집합입니다.

1061 * `"builtin"`: CLI 자체의 도구1063 * `"builtin"`: CLI 자체 도구

1062 * `"mcp"`: 일반적으로 MCP 서버1064 * `"mcp"`: 일반적인 MCP 서버

1063 * `"sdk_host_builtin_mcp"`: Claude Desktop 자체에 내장된 프로세스 내 서버, Claude Desktop이 소유한 세션에서. Claude Desktop은 자신의 진입점 중 하나에서 시작한 세션을 소유합니다, `claude-desktop`, `claude-desktop-3p`, 또는 `local-agent`, 해당 세션이 중첩된 자식이 아닐 때; 중첩된 세션(Claude Code 자체가 생성하는 세션 포함)은 이러한 서버를 `"mcp"`로 보고합니다1065 * `"sdk_host_builtin_mcp"`: Claude Desktop이 소유한 세션에서 Claude Desktop 자체에 내장된 프로세스 내 서버입니다. Claude Desktop은 자체 엔트리포인트인 `claude-desktop`, `claude-desktop-3p`, `local-agent` 중 하나에서 시작한 세션이 중첩된 하위 세션이 아닌 경우 해당 세션을 소유합니다. Claude Code 자체가 생성하는 세션을 포함한 중첩 세션은 이러한 서버를 `"mcp"`로 보고합니다

1064* `source`: 결정이 나온 위치:1066* `source`: 결정이 비롯된 곳:

1065 * `"config"`: 프롬프트 없이 자동으로 결정됨, 프로젝트 설정, 사용자의 개인 설정의 허용 또는 거부 규칙, 엔터프라이즈 관리 정책, `--allowedTools` 또는 `--disallowedTools` 플래그, 활성 권한 모드, 동일한 대화형 CLI 세션의 이전 프롬프트에서 세션 범위 부여, 또는 도구가 본질적으로 안전하기 때문에 기반. 이벤트는 이러한 소스 중 어느 것이 일치했는지 나타내지 않습니다. Claude Code는 또한 권한 프롬프트 요청 자체가 실패할 때 `"config"`을 보고합니다, 예를 들어 Agent SDK의 [`canUseTool`](/docs/ko/agent-sdk/typescript#canusetool) 콜백 또는 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 도구가 유효하지 않은 결과를 반환할 때, 또는 요청이 보류 중일 때 입력 스트림이 닫힐 때. v2.1.216 이전에는 Claude Code가 이러한 실패를 `"user_reject"`로 보고했습니다.1067 * `"config"`: 다음 소스 중 하나에 의해 확인 요청 없이 자동으로 결정됨:

1068

1069 * 프로젝트 설정

1070 * 사용자 개인 설정의 허용 또는 거부 규칙

1071 * 엔터프라이즈 관리형 정책

1072 * `--allowedTools` 또는 `--disallowedTools` 플래그

1073 * 활성 권한 모드

1074 * 자동 모드 분류기로, 동일한 이벤트가 그 판정을 `classifier_verdict`에 기록함

1075 * 동일한 대화형 CLI 세션의 이전 권한 프롬프트에서 부여된 세션 잔여 기간 동안의 허가

1076 * 본질적으로 안전한 도구

1077

1078 `source` 값은 이 소스 중 어느 것이 일치했는지 나타내지 않습니다.

1079

1080 Claude Code는 권한 프롬프트 요청 자체가 실패한 경우에도 `"config"`를 보고합니다. 예를 들어 Agent SDK의 [`canUseTool`](/docs/ko/agent-sdk/typescript#canusetool) 콜백이나 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 도구가 잘못된 결과를 반환하거나, 요청이 대기 중인 동안 입력 스트림이 닫히면 해당 요청이 실패합니다. v2.1.216 이전에는 Claude Code가 이러한 실패를 `"user_reject"`로 보고했습니다.

1066 * `"hook"`: `PreToolUse` 또는 `PermissionRequest` 훅이 결정을 반환했습니다.1081 * `"hook"`: `PreToolUse` 또는 `PermissionRequest` 훅이 결정을 반환했습니다.

1067 * `"user_permanent"`: 사용자가 권한 프롬프트에서 "Yes, and don't ask again for ..."을 선택했을 때 내보냄, 이는 개인 설정에 허용 규칙을 저장합니다. 대화형 CLI에서 이는 해당 선택 자체에 대해서만 내보냄; 나중의 호출이 저장된 규칙과 일치하면 `"config"`을 대신 내보냅니다. Agent SDK 또는 비대화형 `-p` 세션에서 초기 선택과 나중의 규칙 일치 모두 `"user_permanent"`를 내보냅니다. 수락으로 취급됨.1082 * `"user_permanent"`: 사용자가 권한 프롬프트에서 "Yes, and don't ask again for ..."를 선택하여 개인 설정에 허용 규칙을 저장한 경우 내보내집니다. 대화형 CLI에서는 해당 선택 자체에 대해서만 내보내지며, 저장된 규칙과 일치하는 이후 호출은 대신 `"config"`를 내보냅니다. Agent SDK 또는 비대화형 `-p` 세션에서는 최초 선택과 이후 규칙 일치 모두 `"user_permanent"`를 내보냅니다. 수락으로 처리됩니다.

1068 * `"user_temporary"`: 사용자가 권한 프롬프트에서 "Yes"를 선택했을 때 또는 파일 편집 또는 읽기 프롬프트에서 세션의 나머지 부분에 대한 액세스를 부여하는 옵션을 선택했을 때 내보냄. 대화형 CLI에서 이는 선택 자체에 대해서만 내보냄; 나중의 호출이 해당 세션 범위 부여와 일치하면 `"config"`을 대신 내보냅니다. Agent SDK 또는 비대화형 `-p` 세션에서 선택과 나중의 일치 모두 `"user_temporary"`를 내보냅니다. 수락으로 취급됨.1083 * `"user_temporary"`: 사용자가 권한 프롬프트에서 일회성 승인을 위해 "Yes"를 선택했거나, 파일 편집 또는 읽기 프롬프트에서 세션 잔여 기간 동안 액세스를 부여하는 옵션을 선택한 경우 내보내집니다. 대화형 CLI에서는 해당 선택 자체에 대해서만 내보내지며, 세션 범위 허가로 허용된 이후 호출은 대신 `"config"`를 내보냅니다. Agent SDK 또는 비대화형 `-p` 세션에서는 선택과 이후 일치 모두 `"user_temporary"`를 내보냅니다. 수락으로 처리됩니다.

1069 * `"user_abort"`: 사용자가 답변 없이 권한 프롬프트를 해제했을 때 내보냄. Agent SDK 및 비대화형 `-p` 세션에서 이는 `canUseTool` 또는 `--permission-prompt-tool` 권한 요청이 보류 중일 때 턴을 중단하는 것을 포함합니다; v2.1.216 이전에는 Claude Code가 해당 중단을 `"user_reject"`로 보고했습니다. 거부로 취급됨.1084 * `"user_abort"`: 사용자가 응답하지 않고 권한 프롬프트를 닫은 경우 내보내집니다. Agent SDK 및 비대화형 `-p` 세션에서는 `canUseTool` 또는 `--permission-prompt-tool` 권한 요청이 대기 중인 동안 턴을 중단하는 경우도 포함됩니다. v2.1.216 이전에는 Claude Code가 이러한 중단을 `"user_reject"`로 보고했습니다. 거부로 처리됩니다.

1070 * `"user_reject"`: 사용자가 프롬프트에서 "No"를 선택했을 때 내보냄. 대화형 CLI에서 이는 해당 선택 자체에 대해서만 내보냄; 사용자의 개인 설정의 거부 규칙과 일치하는 호출은 `"config"`을 대신 내보냅니다. Agent SDK 또는 비대화형 `-p` 세션에서 개인 설정의 거부 규칙과 일치하는 호출은 `"user_reject"`를 내보냅니다. 거부로 취급됨.1085 * `"user_reject"`: 확인 요청 시 사용자가 "No"를 선택한 경우 내보내집니다. 대화형 CLI에서는 해당 선택 자체에 대해서만 내보내지며, 사용자 개인 설정의 거부 규칙과 일치하는 호출은 대신 `"config"`를 내보냅니다. Agent SDK 또는 비대화형 `-p` 세션에서는 개인 설정의 거부 규칙과 일치하는 호출이 `"user_reject"`를 내보냅니다. 거부로 처리됩니다.

1071* `tool_parameters` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 도구별 매개변수를 포함하는 JSON 문자열. [도구 결과 이벤트](#tool-result-event)와 동일한 형태, `git_commit_id`와 같은 실행 후 필드 제외. 수락된 호출의 경우 `tool_result`와 다를 수 있습니다 (권한 결정이 `updatedInput`을 통해 도구 입력을 다시 쓸 경우). 이 속성을 사용하여 `decision`이 `"reject"`일 때 어느 명령이 거부되었는지 확인하세요.1086* `classifier_verdict`: 호출에 대한 자동 모드 [분류기](/docs/ko/permission-modes#how-the-classifier-evaluates-actions) 판정이거나, 판정이 없을 때 Claude Code가 호출을 거부한 이유입니다. Claude Code v2.1.301 이상 필요

1072 * `"sdk_host_builtin_mcp"` 도구의 경우: `mcp_server_name` 및 `mcp_tool_name`은 `OTEL_LOG_TOOL_DETAILS`가 꺼져 있어도 포함됩니다, 호스트 애플리케이션이 이러한 이름을 정의하기 때문; 이들 없이 이러한 기본 제공 서버 중 하나에 대한 거부된 호출은 기본 스트림에서 속성화할 수 없습니다. 사용자 구성 MCP 서버의 경우 이벤트의 `tool_name`은 항상 리터럴 `"mcp_tool"`이며, 서버 및 도구 이름은 플래그가 켜져 있을 때만 `tool_parameters`에 나타납니다; 인수 콘텐츠는 어디서나 플래그가 필요합니다. Claude Code v2.1.214 이상 필요1087

1073 * Bash 도구의 경우: `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox` 포함. 데스크톱 앱의 작업 공간 bash 도구도 `tool_name`을 `Bash`로 보고하지만 `bash_command`, `full_command`, `timeout`만 포함합니다1088 * `"allow"`: 분류기가 호출을 승인함

1074 * MCP 도구의 경우: `mcp_server_name`, `mcp_tool_name` 포함1089 * `"block"`: 분류기가 호출을 차단함. 도중에 실패한 분류기 검사도 `"block"`으로 끝날 수 있으므로, 부분적인 분류기 장애는 `"unavailable"`이 아니라 차단 증가로 나타날 수 있습니다

1075 * Skill 도구의 경우: `skill_name` 포함1090 * `"no_verdict"`: 검사가 실행되었지만 [사용 가능한 판정이 없어](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action) Claude Code가 호출을 거부함. 이 거부는 분류기가 호출을 안전하지 않다고 판단했다는 의미가 아닙니다

1076 * Agent 도구 또는 레거시 Task 도구의 경우: `subagent_type` 포함1091 * `"unavailable"`: 속도 제한, 시간 초과, 연결 오류 등으로 분류기에 대한 요청이 실패하여 Claude Code가 호출을 거부함. [서버 측 분류기 검토](/docs/ko/permission-modes#server-side-classifier-review)에서는 [서버가 안전성 판정을 반환하지 않아](/docs/ko/errors#the-server-returned-no-safety-verdict) 거부된 호출에도 표시됩니다

1092

1093 이 속성은 [분류기가 플랜 모드에서 명령을 검토하는](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode) 경우 플랜 모드 호출에도 나타납니다. 다음 경우에는 이 속성이 없습니다.

1094

1095 * 허용 또는 거부 [권한 규칙](/docs/ko/permissions#manage-permissions)이 호출을 결정한 경우

1096 * Claude Code가 자동 모드에서 분류기에 묻지 않고 호출을 승인한 경우

1097 * [반복 차단](/docs/ko/permission-modes#repeated-block-thresholds) 후 Claude Code가 표시한 프롬프트에 사용자가 응답한 경우

1098 * `--permission-prompt-tool` 없는 `-p` 실행에서, 프롬프트에 응답할 사람이 없어 Claude Code가 반복 차단 후 호출을 거부한 경우. 해당 이벤트는 `decision`을 `"reject"`로, `source`를 `"config"`로 보고합니다

1099* `classifier_category` (`OTEL_LOG_TOOL_DETAILS=1`인 경우): 분류기가 호출을 차단할 때 지목한 [내장 규칙](/docs/ko/auto-mode-config#inspect-the-defaults-and-your-effective-config)의 이름으로, 밑줄을 사용한 소문자 형식입니다. 예를 들어 Data Exfiltration 규칙의 경우 `"data_exfiltration"`입니다. Claude Code v2.1.301 이상 필요. 다음 조건을 모두 충족할 때 이 속성이 포함됩니다.

1100 * `classifier_verdict`가 `"block"`인 경우

1101 * [서버 측 분류기 검토](/docs/ko/permission-modes#server-side-classifier-review)를 사용하지 않고 Claude Code가 직접 분류기 요청을 보낸 경우

1102 * 분류기가 정확히 하나의 규칙을 지목했고, 그 규칙이 사용자가 작성한 규칙이 아니라 내장 규칙인 경우

1103* `permission_mode`: 이 호출의 권한 검사가 시작될 때 활성화된 [권한 모드](/docs/ko/permission-modes)로 `"default"`, `"plan"`, `"acceptEdits"`, `"bypassPermissions"`, `"dontAsk"`, `"auto"` 중 하나입니다. 수동 모드는 `"default"`로 표시됩니다. [서브에이전트](/docs/ko/sub-agents#permission-modes) 호출은 세션의 권한 모드가 아닌 서브에이전트의 권한 모드를 보고합니다. Claude Code v2.1.301 이상 필요

1104* `tool_parameters` (`OTEL_LOG_TOOL_DETAILS=1`인 경우): 도구별 매개변수를 포함하는 JSON 문자열입니다. `git_commit_id` 같은 실행 후 필드를 제외하면 [도구 결과 이벤트](#tool-result-event)와 형태가 같습니다. 권한 결정이 `updatedInput`을 통해 도구 입력을 다시 작성하는 경우, 수락된 호출의 값이 `tool_result`와 다를 수 있습니다. `decision`이 `"reject"`일 때 어떤 명령이 거부되었는지 확인하려면 이 속성을 사용하세요.

1105 * `"sdk_host_builtin_mcp"` 도구: 호스트 애플리케이션이 이 이름을 정의하므로 `OTEL_LOG_TOOL_DETAILS`가 꺼져 있어도 `mcp_server_name`과 `mcp_tool_name`이 포함됩니다. 이 이름이 없으면 이러한 기본 제공 서버 중 하나에 대한 거부된 호출을 기본 스트림에서 식별할 수 없습니다. 사용자가 구성한 MCP 서버의 경우 이벤트의 `tool_name`은 항상 리터럴 `"mcp_tool"`이며, 서버 및 도구 이름은 플래그가 켜진 경우에만 `tool_parameters`에 표시됩니다. 인수 내용은 모든 경우에 플래그가 필요합니다.

1106 * Bash 도구: `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox`를 포함합니다. 데스크톱 앱의 워크스페이스 bash 도구도 `tool_name`을 `Bash`로 보고하지만 `bash_command`, `full_command`, `timeout`만 포함합니다

1107 * MCP 도구: `mcp_server_name`, `mcp_tool_name`을 포함합니다

1108 * Skill 도구: `skill_name`을 포함합니다

1109 * Agent 도구 또는 레거시 Task 도구: `subagent_type`을 포함합니다

1077 1110

1078<h4 id="permission-mode-changed-event">1111<h4 id="permission-mode-changed-event">

1079 권한 모드 변경 이벤트1112 권한 모드 변경 이벤트

1081 1114

1082권한 모드가 변경될 때 기록됩니다, 예를 들어 `Shift+Tab` 순환, 계획 모드 종료, 또는 자동 모드 게이트 확인에서.1115권한 모드가 변경될 때 기록됩니다, 예를 들어 `Shift+Tab` 순환, 계획 모드 종료, 또는 자동 모드 게이트 확인에서.

1083 1116

1117도구 호출을 각각 검사된 권한 모드별로 그룹화하려면 [도구 결정 이벤트](#tool-decision-event)의 `permission_mode`를 사용하세요.

1118

1084**이벤트 이름**: `claude_code.permission_mode_changed`1119**이벤트 이름**: `claude_code.permission_mode_changed`

1085 1120

1086**속성**:1121**속성**:

1091* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터1126* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1092* `from_mode`: 이전 권한 모드, 예: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, 또는 `"bypassPermissions"`1127* `from_mode`: 이전 권한 모드, 예: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, 또는 `"bypassPermissions"`

1093* `to_mode`: 새로운 권한 모드1128* `to_mode`: 새로운 권한 모드

1094* `trigger`: 변경을 일으킨 원인입니다. `"shift_tab"`, `"exit_plan_mode"`, `"auto_gate_denied"`, `"auto_opt_in"` 중 하나입니다. SDK가 [`setPermissionMode()`](/docs/ko/agent-sdk/typescript#query-object)를 통해 권한 모드를 설정하는 경우처럼 일부 변경에서는 없습니다1129* `trigger`: 변경을 일으킨 원인입니다. 예: `"shift_tab"`, `"exit_plan_mode"`, `"auto_gate_denied"`. SDK가 [`setPermissionMode()`](/docs/ko/agent-sdk/typescript#query-object)를 통해 권한 모드를 설정하는 경우처럼 일부 변경에서는 없습니다

1095 1130

1096<h4 id="auth-event">1131<h4 id="auth-event">

1097 인증 이벤트1132 인증 이벤트

1402* `total_tool_uses`: 하위 에이전트가 전체 실행에 걸쳐 수행한 도구 호출 수1437* `total_tool_uses`: 하위 에이전트가 전체 실행에 걸쳐 수행한 도구 호출 수

1403* `duration_ms`: 실행 시간 (밀리초)1438* `duration_ms`: 실행 시간 (밀리초)

1404* `model`: 하위 에이전트가 실행하도록 해결된 모델1439* `model`: 하위 에이전트가 실행하도록 해결된 모델

1405* `final_model`: 하위 에이전트의 최종 응답을 생성한 모델, 폴백과 같은 중간 실행 전환 후 `model`과 다릅니다. Claude Code v2.1.212 이상 필요1440* `final_model`: 서브에이전트의 최종 응답을 생성한 모델로, 폴백과 같이 실행 도중 모델이 전환된 경우 `model`과 다릅니다

1406* `model_swapped`: 둘 이상의 모델이 하위 에이전트의 요청을 제공했는지 여부. Claude Code v2.1.212 이상 필요1441* `model_swapped`: 둘 이상의 모델이 서브에이전트의 요청을 처리했는지 여부

1407* `plugin_id_hash`, `plugin.name`: 플러그인 제공 에이전트에 대해 존재. 공식 마켓플레이스 플러그인 이름은 그대로 나타납니다; 다른 플러그인 이름은 `OTEL_LOG_TOOL_DETAILS=1`이 설정되지 않은 경우 `"third-party"`로 대체됩니다1442* `plugin_id_hash`, `plugin.name`: 플러그인 제공 에이전트에 대해 존재. 공식 마켓플레이스 플러그인 이름은 그대로 나타납니다; 다른 플러그인 이름은 `OTEL_LOG_TOOL_DETAILS=1`이 설정되지 않은 경우 `"third-party"`로 대체됩니다

1408 1443

1409<h4 id="feedback-survey-event">1444<h4 id="feedback-survey-event">

1548 비용 메트릭은 근사값입니다. 공식 청구 데이터는 API 제공자(Claude Console, Amazon Bedrock 또는 Google Cloud의 Agent Platform)를 참조하세요.1583 비용 메트릭은 근사값입니다. 공식 청구 데이터는 API 제공자(Claude Console, Amazon Bedrock 또는 Google Cloud의 Agent Platform)를 참조하세요.

1549</Note>1584</Note>

1550 1585

1551Claude Code는 `ANTHROPIC_BASE_URL` 뒤의 게이트웨이 또는 프록시가 여러 프레임에 걸쳐 사용량을 점진적으로 스트리밍할 때를 포함하여 각 스트리밍 응답을 비용 및 토큰 메트릭에 정확히 한 번 계산합니다. v2.1.214 이전에는 둘 이상의 프레임에서 사용량을 전달한 스트림이 추가 프레임당 대략 하나의 추가 전체 요청으로 `claude_code.cost.usage` 및 `claude_code.token.usage`를 부풀렸습니다.1586Claude Code는 `ANTHROPIC_BASE_URL` 뒤의 게이트웨이 또는 프록시가 여러 프레임에 걸쳐 사용량을 점진적으로 스트리밍할 때를 포함하여 각 스트리밍 응답을 비용 및 토큰 메트릭에 정확히 한 번 계산합니다.

1552 1587

1553<h3 id="alerting-and-segmentation">1588<h3 id="alerting-and-segmentation">

1554 경고 및 세분화1589 경고 및 세분화

1570 1605

1571Claude Code는 실패한 API 요청을 내부적으로 재시도하고 포기한 후에만 단일 `claude_code.api_error` 이벤트를 내보내므로 이벤트 자체가 해당 요청의 최종 신호입니다. 중간 재시도 시도는 별도의 이벤트로 기록되지 않습니다.1606Claude Code는 실패한 API 요청을 내부적으로 재시도하고 포기한 후에만 단일 `claude_code.api_error` 이벤트를 내보내므로 이벤트 자체가 해당 요청의 최종 신호입니다. 중간 재시도 시도는 별도의 이벤트로 기록되지 않습니다.

1572 1607

1573이벤트의 `attempt` 속성은 시도 횟수를 기록합니다. `CLAUDE_CODE_MAX_RETRIES`는 기본값이 10이고 최대 15입니다. v2.1.199 이상에서는 `CLAUDE_CODE_RETRY_WATCHDOG`을 설정하여 기본값을 높이고 상한을 제거할 수 있습니다.1608이벤트의 `attempt` 속성은 시도 횟수를 기록합니다. `CLAUDE_CODE_MAX_RETRIES`는 기본값이 10이고 최대 15입니다. [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/ko/env-vars)을 설정하면 기본값이 더 높아지고 상한이 없습니다.

1574 1609

1575요청이 일시적 오류에 대한 모든 재시도를 소진하면 `attempt`는 최대 해당 유효 제한보다 하나 많은 값이 됩니다: 기본값으로는 11입니다.1610요청이 일시적 오류에 대한 모든 재시도를 소진하면 `attempt`는 최대 해당 유효 제한보다 하나 많은 값이 됩니다: 기본값으로는 11입니다.

1576 1611

1646 1681

1647`OTEL_LOG_TOOL_DETAILS` 없이 이러한 이벤트는 식별 세부 정보를 삭제합니다:1682`OTEL_LOG_TOOL_DETAILS` 없이 이러한 이벤트는 식별 세부 정보를 삭제합니다:

1648 1683

1649* `tool_result`: `mcp_server_scope`를 유지하고 사용자 구성 서버의 경우 `tool_name`을 리터럴 `"mcp_tool"`로 수정하며, 인수 내용을 생략합니다. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서는 `tool_parameters` 내부의 `mcp_server_name`/`mcp_tool_name` 쌍도 유지하며, `tool_decision`과 동일한 호스트 작성 예외입니다. Claude Code v2.1.214 이상 필요1684* `tool_result`: `mcp_server_scope`를 유지하고 사용자 구성 서버의 경우 `tool_name`을 리터럴 `"mcp_tool"`로 수정하며, 인수 내용을 생략합니다. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서는 `tool_parameters` 내부의 `mcp_server_name`/`mcp_tool_name` 쌍도 유지하며, `tool_decision`과 동일한 호스트 작성 예외입니다

1650* `tool_decision`: `tool_source`를 유지하고 사용자 구성 서버의 경우 `tool_name`을 리터럴 `"mcp_tool"`로 수정하며, 인수 내용을 생략합니다. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서는 `tool_parameters` 내부의 `mcp_server_name`/`mcp_tool_name` 쌍도 유지합니다. `tool_source` 및 이름 쌍 모두 Claude Code v2.1.214 이상 필요1685* `tool_decision`: `tool_source`를 유지하고 사용자 구성 서버의 경우 `tool_name`을 리터럴 `"mcp_tool"`로 수정하며, 인수 내용을 생략합니다. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서는 `tool_parameters` 내부의 `mcp_server_name`/`mcp_tool_name` 쌍도 유지합니다

1651* `mcp_server_connection`: `server_name` 및 오류 메시지를 생략하지만, `is_plugin`, `plugin_id_hash` 및 `plugin.name`을 유지하며, Anthropic이 아닌 플러그인 이름은 리터럴 `"third-party"`로 수정되므로 플러그인 제공 서버는 상세 로깅 없이도 구별 가능합니다1686* `mcp_server_connection`: `server_name` 및 오류 메시지를 생략하지만, `is_plugin`, `plugin_id_hash` 및 `plugin.name`을 유지하며, Anthropic이 아닌 플러그인 이름은 리터럴 `"third-party"`로 수정되므로 플러그인 제공 서버는 상세 로깅 없이도 구별 가능합니다

1652 1687

1653<h3 id="map-security-questions-to-events">1688<h3 id="map-security-questions-to-events">

1658 1693

1659| 신호 | 이벤트 | 주요 속성 |1694| 신호 | 이벤트 | 주요 속성 |

1660| - | - | - |1695| - | - | - |

1697| 자동 모드 분류기가 도구 호출을 허용 또는 차단했거나, Claude Code가 분류기 판정 없이 호출을 거부함 | `classifier_verdict`가 있는 [`tool_decision`](#tool-decision-event). 판정 없는 거부의 경우 `classifier_verdict`는 `"no_verdict"` 또는 `"unavailable"`입니다 | `classifier_verdict`, `permission_mode`, `tool_name`; `OTEL_LOG_TOOL_DETAILS=1`을 설정한 경우 `classifier_category` |

1699| 서브에이전트가 수행하는 호출을 포함하여 각 도구 호출이 어떤 권한 모드에서 확인되었는지 | [`tool_decision`](#tool-decision-event) | `permission_mode`, `session.id` |

1824 1861

1825 * 상세 베타 추적에서는 스팬이 각 요청과 함께 전송되는 새 사용자 메시지, 도구 결과, 시스템 리마인더, 시스템 프롬프트 텍스트 및 모델 출력도 전달합니다. [상세 베타 추적의 콘텐츠 속성](#new-context-gates)에 각 속성이 나열되어 있습니다. `claude_code.system_prompt` 이벤트는 전체 시스템 프롬프트를 전달합니다1862 * 상세 베타 추적에서는 스팬이 각 요청과 함께 전송되는 새 사용자 메시지, 도구 결과, 시스템 리마인더, 시스템 프롬프트 텍스트 및 모델 출력도 전달합니다. [상세 베타 추적의 콘텐츠 속성](#new-context-gates)에 각 속성이 나열되어 있습니다. `claude_code.system_prompt` 이벤트는 전체 시스템 프롬프트를 전달합니다

1826* 어시스턴트 응답 텍스트는 기본적으로 수집되지 않습니다. 응답 길이만 기록됩니다. 응답 텍스트를 포함하려면 `OTEL_LOG_ASSISTANT_RESPONSES=1`을 설정하세요. Claude Code의 모든 OpenTelemetry 데이터와 마찬가지로 응답 텍스트는 구성한 OTel 엔드포인트로만 전송되며 Anthropic으로는 전송되지 않습니다. 이 변수가 설정되지 않으면 `OTEL_LOG_USER_PROMPTS`가 폴백으로 사용되므로 이벤트에서 프롬프트 콘텐츠는 원하지만 응답 콘텐츠는 원하지 않는 경우 `OTEL_LOG_ASSISTANT_RESPONSES=0`을 설정하세요. 상세 베타 추적에서 `claude_code.llm_request` 스팬은 여전히 [`response.model_output`](#new-context-gates)에 모델 출력을 전달하며, 이는 이 변수가 아닌 `OTEL_LOG_USER_PROMPTS`를 따릅니다1863* 어시스턴트 응답 텍스트는 기본적으로 수집되지 않습니다. 응답 길이만 기록됩니다. 응답 텍스트를 포함하려면 `OTEL_LOG_ASSISTANT_RESPONSES=1`을 설정하세요. Claude Code의 모든 OpenTelemetry 데이터와 마찬가지로 응답 텍스트는 구성한 OTel 엔드포인트로만 전송되며 Anthropic으로는 전송되지 않습니다. 이 변수가 설정되지 않으면 `OTEL_LOG_USER_PROMPTS`가 폴백으로 사용되므로 이벤트에서 프롬프트 콘텐츠는 원하지만 응답 콘텐츠는 원하지 않는 경우 `OTEL_LOG_ASSISTANT_RESPONSES=0`을 설정하세요. 상세 베타 추적에서 `claude_code.llm_request` 스팬은 여전히 [`response.model_output`](#new-context-gates)에 모델 출력을 전달하며, 이는 이 변수가 아닌 `OTEL_LOG_USER_PROMPTS`를 따릅니다

1827* 도구 입력 인수 및 매개변수는 기본적으로 기록되지 않습니다. 이를 포함하려면 `OTEL_LOG_TOOL_DETAILS=1`을 설정하세요. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서 `tool_decision` 및 `tool_result`는 인수 콘텐츠가 아닌 호스트 작성 이름인 `mcp_server_name`/`mcp_tool_name` 쌍을 전달하며, 플래그가 꺼져 있어도 그렇습니다. 이 예외는 Claude Code v2.1.214 이상이 필요합니다. 이 데이터는 구성한 OTEL 엔드포인트로만 전송되며 Anthropic으로는 절대 전송되지 않습니다. 인수에는 여전히 민감한 값이 포함될 수 있으므로 필요에 따라 이러한 속성을 필터링하거나 수정하도록 텔레메트리 백엔드를 구성하세요. 활성화되면:1864* 도구 입력 인수 및 매개변수는 기본적으로 기록되지 않습니다. 이를 포함하려면 `OTEL_LOG_TOOL_DETAILS=1`을 설정하세요. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서 `tool_decision` 및 `tool_result`는 인수 콘텐츠가 아닌 호스트 작성 이름인 `mcp_server_name`/`mcp_tool_name` 쌍을 전달하며, 플래그가 꺼져 있어도 그렇습니다. 이 데이터는 구성한 OTEL 엔드포인트로만 전송되며 Anthropic으로는 절대 전송되지 않습니다. 인수에는 여전히 민감한 값이 포함될 수 있으므로 필요에 따라 이러한 속성을 필터링하거나 수정하도록 텔레메트리 백엔드를 구성하세요. 활성화되면:

1828 * `tool_result` 및 `tool_decision` 이벤트는 Bash 명령, MCP 서버 및 도구 이름, 스킬 이름이 포함된 `tool_parameters` 속성을 포함합니다. `full_command`와 같은 필드는 잘리지 않은 상태로 내보내집니다1865 * `tool_result` 및 `tool_decision` 이벤트는 Bash 명령, MCP 서버 및 도구 이름, 스킬 이름이 포함된 `tool_parameters` 속성을 포함합니다. `full_command`와 같은 필드는 잘리지 않은 상태로 내보내집니다

1829 * `tool_result` 이벤트는 추가로 파일 경로, URL, 검색 패턴 및 기타 인수가 포함된 `tool_input` 속성을 포함합니다. 512자를 초과하는 개별 값은 잘리고 전체는 약 4K 문자로 제한됩니다1866 * `tool_result` 이벤트는 추가로 파일 경로, URL, 검색 패턴 및 기타 인수가 포함된 `tool_input` 속성을 포함합니다. 512자를 초과하는 개별 값은 잘리고 전체는 약 4K 문자로 제한됩니다

1830 * `user_prompt` 이벤트는 사용자 정의, 플러그인 및 MCP 명령의 축자 `command_name`을 포함합니다1867 * `user_prompt` 이벤트는 사용자 정의, 플러그인 및 MCP 명령의 축자 `command_name`을 포함합니다

network-config.md +1 −1

Details

223* `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 두 감시견의 타임아웃을 설정합니다. Claude Code는 5분 미만의 값을 5분으로 올리고, 바이트 수준 감시견의 값을 30분으로 제한합니다.223* `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 두 감시견의 타임아웃을 설정합니다. Claude Code는 5분 미만의 값을 5분으로 올리고, 바이트 수준 감시견의 값을 30분으로 제한합니다.

224* `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS`는 이벤트 수준 감시견을 변경하지 않고 바이트 수준 감시견의 타임아웃을 설정하며, 10초에서 30분 사이로 제한되고, 해당 감시견에 대해 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`보다 우선합니다.224* `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS`는 이벤트 수준 감시견을 변경하지 않고 바이트 수준 감시견의 타임아웃을 설정하며, 10초에서 30분 사이로 제한되고, 해당 감시견에 대해 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`보다 우선합니다.

225* `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`는 첫 바이트 데드라인을 직접 설정합니다. 설정하지 않으면 Claude Code는 바이트 수준 감시견의 타임아웃을 사용하므로, `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 및 `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS`도 데드라인을 변경합니다. 제한, 업로드 허용량, `API_TIMEOUT_MS` 상한, 및 응답 없음 중단 후 재시도가 대기하는 시간에 대해서는 [API에서 응답 없음](/docs/ko/errors#no-response-from-api)을 참조하세요.225* `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`는 첫 바이트 데드라인을 직접 설정합니다. 설정하지 않으면 Claude Code는 바이트 수준 감시견의 타임아웃을 사용하므로, `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 및 `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS`도 데드라인을 변경합니다. 제한, 업로드 허용량, `API_TIMEOUT_MS` 상한, 및 응답 없음 중단 후 재시도가 대기하는 시간에 대해서는 [API에서 응답 없음](/docs/ko/errors#no-response-from-api)을 참조하세요.

226* `API_TIMEOUT_MS`는 응답 헤더 대기 시간을 제한합니다. Claude 앱 게이트웨이 세션처럼 첫 바이트 데드라인이 실행되지 않는 곳에서는, 응답을 받지 못한 요청을 더 빨리 재시도하려면 5분에 해당하는 `300000`보다 낮게 설정하세요. 예상되는 가장 긴 헤더 대기 시간과 가장 긴 [비스트리밍 요청](/docs/ko/errors#streaming-response-ended-before-any-complete-data-was-received)보다 높게 유지하세요. 그보다 오래 걸리는 요청은 재시도할 때마다 다시 시간 초과됩니다.226* `API_TIMEOUT_MS`는 응답 헤더 대기 시간을 제한하며, 헤더 수신 후 응답이 스트리밍되는 시간은 제한하지 않습니다. Claude 앱 게이트웨이 세션처럼 첫 바이트 데드라인이 실행되지 않는 곳에서는, 응답을 받지 못한 요청을 더 빨리 재시도하려면 5분에 해당하는 `300000`보다 낮게 설정하세요. 예상되는 가장 긴 헤더 대기 시간과 가장 긴 [비스트리밍 요청](/docs/ko/errors#streaming-response-ended-before-any-complete-data-was-received)보다 높게 유지하세요. 그보다 오래 걸리는 요청은 재시도할 때마다 다시 시간 초과됩니다.

227* `API_FORCE_IDLE_TIMEOUT`을 `0`으로 설정하면 본문 유휴 타임아웃이 꺼지고, `1`로 설정하면 모든 제공자에 대해 켜집니다. 감시견은 이와 독립적으로 실행되므로, 스트림이 해당 임계값보다 오래 일시 중지되도록 하려면 감시견도 올리거나 비활성화하세요.227* `API_FORCE_IDLE_TIMEOUT`을 `0`으로 설정하면 본문 유휴 타임아웃이 꺼지고, `1`로 설정하면 모든 제공자에 대해 켜집니다. 감시견은 이와 독립적으로 실행되므로, 스트림이 해당 임계값보다 오래 일시 중지되도록 하려면 감시견도 올리거나 비활성화하세요.

228 228

229감시견이 정체된 스트림을 중단하면, Claude Code는 중단을 스트림 중간 실패로 취급하며, 표시되는 내용은 응답이 얼마나 진행되었는지에 따라 달라집니다. Claude Code는 요청을 재시도하거나 오류로 턴을 종료하고, 완료된 출력을 유지하며 [불완전한 응답 알림](/docs/ko/errors#the-response-above-may-be-incomplete)을 표시하거나, 턴을 정상적으로 종료합니다. [자동 재시도](/docs/ko/errors#automatic-retries)는 각 결과가 적용되는 위치를 설명합니다.229감시견이 정체된 스트림을 중단하면, Claude Code는 중단을 스트림 중간 실패로 취급하며, 표시되는 내용은 응답이 얼마나 진행되었는지에 따라 달라집니다. Claude Code는 요청을 재시도하거나 오류로 턴을 종료하고, 완료된 출력을 유지하며 [불완전한 응답 알림](/docs/ko/errors#the-response-above-may-be-incomplete)을 표시하거나, 턴을 정상적으로 종료합니다. [자동 재시도](/docs/ko/errors#automatic-retries)는 각 결과가 적용되는 위치를 설명합니다.

permission-modes.md +106 −9

Details

86| Claude Code를 실행하는 방식 | 기본 제공 시작 권한 모드 |86| Claude Code를 실행하는 방식 | 기본 제공 시작 권한 모드 |

87| :- | :- |87| :- | :- |

88| 모든 설정 파일이 `disableAutoMode`를 `"disable"`로 설정 | `default` |88| 모든 설정 파일이 `disableAutoMode`를 `"disable"`로 설정 | `default` |

89| `claude -p` 또는 [Agent SDK](/docs/ko/agent-sdk/permissions#permission-modes) | [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 `default`. 기능 플래그를 가져오지 않는 세션(예: 타사 공급자 또는 텔레메트리 비활성화)에서는 Claude Code v2.1.285 이상에서 `auto`, 이전 버전에서는 `default`. `auto` 기본값을 보류하는 정책이 있는 조직의 세션은 대신 `default`에서 시작됩니다. |89| `claude -p` 또는 [Agent SDK](/docs/ko/agent-sdk/permissions#permission-modes) | `default` |

90| 조직에 [HIPAA 구성](#hipaa-configuration)이 적용되어 있고 세션이 [적용 대상](/docs/ko/hipaa-setup#check-how-developers-sign-in-and-connect)인 경우 | Claude Code v2.1.285 이상에서 `default`. 자동 모드로 전환하는 것은 계속 가능합니다 |90| 조직에 [HIPAA 구성](#hipaa-configuration)이 적용되어 있고 세션이 [적용 대상](/docs/ko/hipaa-setup#check-how-developers-sign-in-and-connect)인 경우 | Claude Code v2.1.285 이상에서 `default`. 자동 모드로 전환하는 것은 계속 가능합니다 |

91| 터미널 또는 [VS Code 확장 프로그램](/docs/ko/vs-code)을 통해 | Claude Code v2.1.283 이상에서 `auto`; 이전 버전에서는 [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 Pro, Max 또는 Team 플랜의 `auto`, 그 외에는 `default` |91| 터미널 또는 [VS Code 확장 프로그램](/docs/ko/vs-code)을 통해 | Claude Code v2.1.283 이상에서 `auto`; 이전 버전에서는 [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 Pro, Max 또는 Team 플랜의 `auto`, 그 외에는 `default` |

92 92

93[설치 또는 업그레이드 후 첫 번째 세션](/docs/ko/env-vars#first-session-after-an-install-or-upgrade)에서 Claude Code는 기능 플래그가 도착하기 전에 시작 권한 모드를 선택할 수 있습니다. 해당 세션은 표에서 제공하는 것과 다른 권한 모드에서 시작할 수 있습니다.

95플래그, 설정 파일 또는 기본 제공 기본값이 `auto`를 선택하지만 자동 모드를 세션에서 사용할 수 없는 경우, Claude Code는 대신 수동 모드에서 세션을 시작합니다. 자동 모드는 세션이 [가용성 요구 사항](#eliminate-prompts-with-auto-mode)을 충족하지 않을 때(예: 설정 파일이 자동 모드를 비활성화하거나 지원하지 않는 모델) 또는 Anthropic이 서버 측에서 임시로 자동 모드를 비활성화했을 때 사용할 수 없습니다.93플래그, 설정 파일 또는 기본 제공 기본값이 `auto`를 선택하지만 자동 모드를 세션에서 사용할 수 없는 경우, Claude Code는 대신 수동 모드에서 세션을 시작합니다. 자동 모드는 세션이 [가용성 요구 사항](#eliminate-prompts-with-auto-mode)을 충족하지 않을 때(예: 설정 파일이 자동 모드를 비활성화하거나 지원하지 않는 모델) 또는 Anthropic이 서버 측에서 임시로 자동 모드를 비활성화했을 때 사용할 수 없습니다.

96 94

97기본 제공 기본값이 처음으로 세션 중 하나를 자동 모드에서 시작할 때, Claude Code는 이 페이지로 연결되는 알림을 표시합니다.95기본 제공 기본값이 처음으로 세션 중 하나를 자동 모드에서 시작할 때, Claude Code는 이 페이지로 연결되는 알림을 표시합니다.

101 99

102`~/.claude/settings.json`이 `auto` 이외의 `defaultMode`를 설정하고 다른 설정 파일이 설정하지 않으면, 세션은 계속해서 해당 모드에서 시작됩니다. Pro, Max 및 Team 플랜에서, 그리고 [기능 플래그를 가져오지 않는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 Claude Code는 터미널 또는 VS Code 확장 프로그램에서 한 번 설정을 자동 모드로 변경할지 여부를 묻습니다. 거절하면 설정은 그대로 유지됩니다.100`~/.claude/settings.json`이 `auto` 이외의 `defaultMode`를 설정하고 다른 설정 파일이 설정하지 않으면, 세션은 계속해서 해당 모드에서 시작됩니다. Pro, Max 및 Team 플랜에서, 그리고 [기능 플래그를 가져오지 않는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 Claude Code는 터미널 또는 VS Code 확장 프로그램에서 한 번 설정을 자동 모드로 변경할지 여부를 묻습니다. 거절하면 설정은 그대로 유지됩니다.

103 101

102<h3 id="which-mode-a-non-interactive-run-starts-in">

103 `claude -p` 및 Agent SDK 실행에서 거부되는 도구 호출

104</h3>

105

106Claude Code v2.1.302 이상에서는 [권한 모드가 설정되지 않은](#which-mode-a-session-starts-in) `claude -p` 및 [Agent SDK](/docs/ko/agent-sdk/permissions#permission-modes) 실행이 수동 모드에서 시작됩니다. 이 모드는 SDK 옵션과 설정에서 `default`로 표시됩니다. 승인이 필요한 호출은 허용 규칙, 훅, `canUseTool` 콜백 또는 `--permission-prompt-tool`로 승인하지 않는 한 거부됩니다.

107

108이러한 호출이 승인되도록 하려면 허용 규칙을 추가하거나 자동 모드에서 시작합니다.

109

110* **[허용 규칙 추가](/docs/ko/permissions#manage-permissions)**: Claude는 나열된 호출을 실행합니다. `claude -p`에 [`--allowedTools "Bash(npm test)"`](/docs/ko/headless#auto-approve-tools)를 전달하거나 SDK의 [허용 도구 옵션](/docs/ko/agent-sdk/permissions#allow-and-deny-rules)을 설정합니다.

111* **[자동 모드](#eliminate-prompts-with-auto-mode)에서 시작**: 분류기 모델이 호출을 검토하므로 미리 나열할 필요가 없습니다. `claude -p`에 `--permission-mode auto`를 전달하거나 SDK의 [권한 모드 옵션](/docs/ko/agent-sdk/permissions#set-permission-mode)을 설정합니다.

112

113다음 예제는 CLI와 각 SDK에서 자동 모드를 사용하는 형태를 보여 줍니다.

114

115<Tabs>

116 <Tab title="CLI">

117 ```bash theme={null}

118 claude -p "Run the test suite and fix any failures" --permission-mode auto

119 ```

120 </Tab>

121

122 <Tab title="TypeScript">

123 ```typescript theme={null}

124 const options = {

125 permissionMode: "auto"

126 };

127 ```

128 </Tab>

129

130 <Tab title="Python">

131 ```python theme={null}

132 from claude_agent_sdk import ClaudeAgentOptions

133

134 options = ClaudeAgentOptions(permission_mode="auto")

135 ```

136 </Tab>

137</Tabs>

138

139v2.1.302 이전에는 이러한 실행이 [기능 플래그를 가져오지](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 않는 경우(예: [타사 공급자](/docs/ko/third-party-integrations) 사용 시 또는 `DISABLE_TELEMETRY` 설정 시) 자동 모드에서 시작될 수 있었습니다.

140

104<h3 id="start-in-a-different-mode">141<h3 id="start-in-a-different-mode">

105 다른 권한 모드에서 시작142 다른 권한 모드에서 시작

106</h3>143</h3>

216 </Tab>253 </Tab>

217 254

218 <Tab title="Desktop">255 <Tab title="Desktop">

219 **세션 중**: Code 탭에서 전송 버튼 옆의 모드 선택기를 사용합니다. 모든 모드가 선택기에 나타나는 것은 아닙니다:256 **세션 중**: Code 탭에서 프롬프트 상자 아래 행에 있는 모드 선택기를 사용합니다. 모든 모드가 선택기에 나타나는 것은 아닙니다:

220 257

221 * **Auto**: [auto mode를 사용할 수 있을 때](#eliminate-prompts-with-auto-mode) 나타납니다.258 * **Auto**: [auto mode를 사용할 수 있을 때](#eliminate-prompts-with-auto-mode) 나타납니다.

222 * **Bypass permissions**: Pro 및 Max 플랜에서 Desktop 설정의 **Allow bypass permissions mode** 토글이 필요합니다. Team 및 Enterprise 플랜에서는 조직 정책이 대신 제어합니다.259 * **Bypass permissions**: Pro 및 Max 플랜에서 Desktop 설정의 **Allow bypass permissions mode** 토글이 필요합니다. Team 및 Enterprise 플랜에서는 조직 정책이 대신 제어합니다.

345 Bedrock, Agent Platform 또는 Foundry의 자동 모드382 Bedrock, Agent Platform 또는 Foundry의 자동 모드

346</h3>383</h3>

347 384

348[Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai), [Microsoft Foundry](/docs/ko/microsoft-foundry) 및 로그인한 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션에서는 자동 모드를 기본적으로 사용할 수 있습니다. 다른 것이 권한 모드를 설정하지 않으면 해당 섹션의 테이블이 나열하는 버전에서도 [기본 제공 시작 권한 모드](#which-mode-a-session-starts-in)입니다. 시작 권한 모드를 직접 선택하려면 [다른 권한 모드에서 시작](#start-in-a-different-mode)이 설명하는 대로 `permissions.defaultMode`를 설정하거나 VS Code 확장의 모드 표시기에서 권한 모드를 선택하세요.385[Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai), [Microsoft Foundry](/docs/ko/microsoft-foundry) 및 로그인한 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션에서는 자동 모드를 기본적으로 사용할 수 있습니다. 여기서 권한 모드를 설정하지 않으면 대화형 세션은 자동 모드로 시작하고, `claude -p` 또는 Agent SDK 실행은 구성 값이 `default`인 Manual 모드로 시작합니다:

386

387* **대화형 터미널 및 VS Code 세션**: 자동 이외의 권한 모드로 시작하려면 [다른 권한 모드에서 시작](#start-in-a-different-mode)이 설명하는 대로 `permissions.defaultMode`를 설정하거나 VS Code 확장의 [모드 표시기](#switch-permission-modes)에서 하나를 선택하세요. [세션이 시작되는 모드](#which-mode-a-session-starts-in)에는 이러한 세션을 자동 모드로 시작하는 Claude Code 버전이 나열되어 있습니다.

388* **`claude -p` 및 Agent SDK 실행**: 자동 모드로 시작하려면 `claude -p`에 `--permission-mode auto`를 전달하거나, TypeScript에서는 `permissionMode: "auto"`, Python에서는 `permission_mode="auto"`를 전달하세요. 권한 모드를 전달하지 않는 경우 [`claude -p` 및 Agent SDK 실행에서 거부되는 도구 호출](#which-mode-a-non-interactive-run-starts-in)을 참조하세요. 이 섹션은 이전 Claude Code 버전도 다룹니다.

349 389

350이러한 제공자에서는 Claude Sonnet 5 이상, Opus 4.7 이상, Haiku 5.5 및 Fable 모델만 지원됩니다. 다른 모델에서는 세션이 Manual로 시작됩니다. 이러한 제공자에서 Haiku 5.5로 자동 모드를 사용하려면 Claude Code v2.1.293 이상이 필요합니다.390이러한 제공자에서는 Claude Sonnet 5 이상, Opus 4.7 이상, Haiku 5.5 및 Fable 모델만 지원됩니다. 다른 모델에서는 세션이 Manual로 시작됩니다. 이러한 제공자에서 Haiku 5.5로 자동 모드를 사용하려면 Claude Code v2.1.293 이상이 필요합니다.

351 391

368 408

369서버에 요청하는 것을 건너뛰고 항상 Claude Code의 자체 분류기 요청을 사용하려면 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/ko/env-vars)을 설정하세요. Anthropic API에 대한 직접 연결에서 변수에는 Claude Code v2.1.281 이상이 필요합니다. 거기서 `1`로 설정하면 아직 서버 검토가 없는 세션에서 서버 검토를 켭니다. 단, `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`도 설정한 경우는 제외합니다. `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`을 설정하고 `CLAUDE_CODE_AUTO_MODE_SERVER`를 설정하지 않으면 Claude Code도 서버에 요청하는 것을 중지합니다. [사전 릴리스 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)가 설명하는 경우는 제외합니다.409서버에 요청하는 것을 건너뛰고 항상 Claude Code의 자체 분류기 요청을 사용하려면 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/ko/env-vars)을 설정하세요. Anthropic API에 대한 직접 연결에서 변수에는 Claude Code v2.1.281 이상이 필요합니다. 거기서 `1`로 설정하면 아직 서버 검토가 없는 세션에서 서버 검토를 켭니다. 단, `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`도 설정한 경우는 제외합니다. `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`을 설정하고 `CLAUDE_CODE_AUTO_MODE_SERVER`를 설정하지 않으면 Claude Code도 서버에 요청하는 것을 중지합니다. [사전 릴리스 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)가 설명하는 경우는 제외합니다.

370 410

411<h3 id="default-classifier-model">

412 기본 분류기 모델

413</h3>

414

415기본적으로 분류기 요청은 Claude Sonnet 5로 전송됩니다. `/status`에 `Auto mode server`가 `Enabled`로 표시되면 [서버 검토](#server-side-classifier-review) 범위 밖의 호출에 대해서만 전송됩니다.

416

417이 표에서 세션과 일치하는 첫 번째 행을 찾으세요. Sonnet 5 대신 해당 행의 모델이 사용됩니다.

418

419| 세션 | 분류기 모델 |

420| - | - |

421| Anthropic이 구성한 분류기 모델이 있음 | 구성된 모델. 어떤 모델인지 [디버그 로그를 확인](#classifier-model-check)하세요 |

422| Claude Sonnet 4.6에서 실행됨 | Sonnet 4.6 |

423| [`ANTHROPIC_DEFAULT_SONNET_MODEL`](/docs/ko/model-config#environment-variables)이 설정됨 | 해당 값, 또는 값이 Claude Sonnet 5.5 또는 Claude Opus 5.5이면 Sonnet 5 |

424

425Sonnet 5 또는 `ANTHROPIC_DEFAULT_SONNET_MODEL`의 모델을 제공자에서 사용할 수 없거나 조직의 [모델 정책](/docs/ko/model-config#restrict-model-selection)에서 제외한 경우 Claude Code는 대체 모델을 사용합니다. 이는 세션의 모델이며, [Fable 세션](/docs/ko/model-config#work-with-fable)에서는 Opus 모델입니다.

426

427<h3 id="choose-the-classifier-model">

428 분류기 모델 선택

429</h3>

430

431Claude Code v2.1.302 이상에서는 [`CLAUDE_CODE_AUTO_MODE_MODEL`](/docs/ko/env-vars)을 전체 모델 ID로 설정하여 [기본값](#default-classifier-model) 이외의 모델에서 분류기를 실행할 수 있습니다. 클라우드 제공자 자체의 전체 모델 ID도 작동합니다. 다음 `~/.claude/settings.json` 예제는 Claude Sonnet 4.6을 설정합니다:

432

433```json theme={null}

434{

435 "env": {

436 "CLAUDE_CODE_AUTO_MODE_MODEL": "claude-sonnet-4-6"

437 }

438}

439```

440

441<h4 id="classifier-model-not-reviewing">

442 지정한 모델이 검토하지 않는 경우

443</h4>

444

445| 상황 | 발생하는 일 | 수행할 작업 |

446| - | - | - |

447| 세션에서 `/status`에 [`Auto mode server`](#server-side-classifier-review)가 `Enabled`로 표시됨 | 지정한 모델은 서버가 검토하지 않는 것만 검토합니다 | 필요 없음 |

448| Claude Opus 5, Claude Sonnet 5.5, Claude Opus 5.5 또는 조직의 [모델 정책](/docs/ko/model-config#restrict-model-selection)에서 제외하는 모델을 설정함 | [기본 분류기 모델](#default-classifier-model)이 검토합니다 | 다른 모델을 설정하세요 |

449| Anthropic이 세션에 대한 분류기 모델을 구성함 | 해당 모델이 검토합니다 | 필요 없음 |

450| 제공자가 해당 모델을 제공할 수 없음 | 요청이 실패하고 Claude Code가 [검토 대상 작업을 모두 거부합니다](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action) | 제공자가 제공하는 모델을 설정하거나 변수를 제거하세요 |

451

452<h4 id="classifier-model-check">

453 분류기가 사용한 모델 확인

454</h4>

455

456셸에서 [`--debug-file`](/docs/ko/cli-reference#cli-flags)을 사용하여 자동 모드 세션을 시작하세요:

457

458```bash theme={null}

459claude --permission-mode auto --debug-file classifier-debug.log

460```

461

462Claude에게 읽기 전용이 아닌 셸 명령을 실행하게 한 다음 로그에서 `classifier_request_started`를 검색하세요:

463

464* **`model=` 뒤에 지정한 모델이 있음**: 변수가 적용되었습니다

465* **`model=` 뒤에 다른 모델이 있음**: 로그에서 `ignoring CLAUDE_CODE_AUTO_MODE_MODEL`을 검색하세요. 그 이유와 수행할 단계가 있는 경우 이를 알려 줍니다

466* **해당 줄이 없음**: Claude Code 프롬프트에서 `/status`의 `Auto mode server`를 확인하세요:

467 * **`Enabled`**: [서버](#server-side-classifier-review)가 이 세션의 호출을 검토하도록 설정되어 있습니다. 변경할 것이 없습니다.

468 * **`Disabled`**: [권한 모드](#switch-permission-modes)가 auto인지 확인한 다음 Claude에게 읽기 전용이 아닌 다른 명령을 실행하게 하세요.

469

371<h3 id="what-the-classifier-blocks-by-default">470<h3 id="what-the-classifier-blocks-by-default">

372 분류기가 기본적으로 차단하는 것471 분류기가 기본적으로 차단하는 것

373</h3>472</h3>

384* 공유 인프라 수정483* 공유 인프라 수정

385* 세션 전에 존재했던 파일을 돌이킬 수 없게 파괴484* 세션 전에 존재했던 파일을 돌이킬 수 없게 파괴

386* 강제 푸시485* 강제 푸시

387* 실행될 때 비밀이나 민감한 데이터를 저장소 외부로 보내거나 배포가 노출하는 것을 확대할 변경 사항을 커밋하거나 푸시합니다. 이는 비밀을 아직 받지 않는 대상으로 전달하는 CI 워크플로 또는 배포 구성, 비밀 스토어를 읽고 데이터를 보내는 스크립트 또는 설정 단계, 그리고 배포가 게시하는 것을 확대하는 구성 변경(예: 레지스트리, 가시성, 아티팩트 또는 소스맵 설정)을 다룹니다. 검사는 모든 브랜치에 적용되고, 저장소가 공개인 경우에도 적용되며, 해당 커밋이나 푸시가 파이프라인을 트리거하는지 여부에 관계없이 커밋되거나 푸시될 때 발생합니다. 이를 지우려면 커밋이나 푸시만이 아니라 실행 효과를 이름 지정해야 합니다. v2.1.211 이전에는 이 검사가 기본 브랜치로 범위가 지정되었습니다: 거기로의 푸시는 민감한 콘텐츠, 요청한 것과 비교하여 숨겨지거나 잘못 설명된 변경 사항, 저장소 외부에서 이식된 콘텐츠 또는 요청한 검토를 우회하여 라우팅된 콘텐츠를 전달할 때 차단되었습니다486* 실행될 때 비밀이나 민감한 데이터를 저장소 외부로 보내거나 배포가 노출하는 것을 확대할 변경 사항을 커밋하거나 푸시합니다. 이는 비밀을 아직 받지 않는 대상으로 전달하는 CI 워크플로 또는 배포 구성, 비밀 스토어를 읽고 데이터를 보내는 스크립트 또는 설정 단계, 그리고 배포가 게시하는 것을 확대하는 구성 변경(예: 레지스트리, 가시성, 아티팩트 또는 소스맵 설정)을 다룹니다. 검사는 모든 브랜치에 적용되고, 저장소가 공개인 경우에도 적용되며, 해당 커밋이나 푸시가 파이프라인을 트리거하는지 여부에 관계없이 커밋되거나 푸시될 때 발생합니다. 이를 지우려면 커밋이나 푸시만이 아니라 실행 효과를 이름 지정해야 합니다

388* `git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop` 또는 `git stash clear`는 분류기가 커밋되지 않은 변경 사항을 삭제할 것으로 가정합니다487* `git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop` 또는 `git stash clear`는 분류기가 커밋되지 않은 변경 사항을 삭제할 것으로 가정합니다

389* HEAD의 커밋이 이 세션에서 생성되지 않았을 때 `git commit --amend`488* HEAD의 커밋이 이 세션에서 생성되지 않았을 때 `git commit --amend`

390* v2.1.198부터 HEAD의 커밋이 이미 푸시되었을 때 `git commit --amend`. 메시지 전용 단어 변경은 차단되지 않습니다: Claude가 이 세션 중에 생성한 커밋에서 새로 스테이징된 것이 없는 `--amend -m`489* v2.1.198부터 HEAD의 커밋이 이미 푸시되었을 때 `git commit --amend`. 메시지 전용 단어 변경은 차단되지 않습니다: Claude가 이 세션 중에 생성한 커밋에서 새로 스테이징된 것이 없는 `--amend -m`

568 </Accordion>667 </Accordion>

569 668

570 <Accordion title="비용 및 지연 시간">669 <Accordion title="비용 및 지연 시간">

571 분류기는 `/model` 선택과 관계없이 기본적으로 Claude Sonnet 5에서 실행됩니다. Anthropic이 서버 측에서 구성한 분류기 모델이 있으면 이 기본값보다 우선합니다. 세션의 모델이 Claude Sonnet 4.6이거나 [`availableModels`](/docs/ko/model-config#restrict-model-selection)에서 Sonnet 5를 제외한 경우, 분류기는 대신 세션의 모델에서 실행되며, 세션이 [Fable 모델](/docs/ko/model-config#work-with-fable)에서 실행되는 경우에는 Opus 모델에서 실행됩니다. Anthropic API 이외의 제공자에서 이 Opus 폴백은 [`ANTHROPIC_DEFAULT_OPUS_MODEL`](/docs/ko/model-config#environment-variables)에 설정한 모델이며, 설정하지 않은 경우 Opus 5입니다.670 Claude Code의 분류기 요청은 `/model` 선택과 다른 모델에서 실행될 수 있습니다. [어떤 모델에서 실행되는지](#default-classifier-model) 참조하세요.

~~572~~

573 세션의 첫 번째 자동 모드 요청은 Sonnet 5 기본값을 검증합니다: 요청이 성공하면 Sonnet 5는 세션의 분류기 모델로 유지되고, 모델을 사용할 수 없기 때문에 실패하면 세션은 폴백을 대신 사용합니다.

574 671

575 Enterprise 플랜 및 Claude API를 사용하는 계정, [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws), Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 분류기 호출은 토큰 사용량에 계산됩니다. 각 검사는 트랜스크립트의 일부와 보류 중인 작업을 보내며 실행 전에 왕복을 추가합니다. 읽기 및 보호된 경로 외부의 작업 디렉터리 편집은 분류기를 건너뛰므로 오버헤드는 주로 셸 명령 및 네트워크 작업에서 나옵니다. 서버가 세션의 모델 요청의 일부로 작업을 검토하는 경우 계산할 별도의 분류기 호출이 없습니다. [서버 측 분류기 검토](#server-side-classifier-review)를 참조하세요.672 Enterprise 플랜 및 Claude API를 사용하는 계정, [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws), Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 분류기 호출은 토큰 사용량에 계산됩니다. 각 검사는 트랜스크립트의 일부와 보류 중인 작업을 보내며 실행 전에 왕복을 추가합니다. 읽기 및 보호된 경로 외부의 작업 디렉터리 편집은 분류기를 건너뛰므로 오버헤드는 주로 셸 명령 및 네트워크 작업에서 나옵니다. 서버가 세션의 모델 요청의 일부로 작업을 검토하는 경우 계산할 별도의 분류기 호출이 없습니다. [서버 측 분류기 검토](#server-side-classifier-review)를 참조하세요.

576 673

permissions.md +3 −3

Details

391 391

392Claude Code는 v2.1.290 이상에서 붙여넣은 이미지 경로와 디렉터리 목록을 확인합니다.392Claude Code는 v2.1.290 이상에서 붙여넣은 이미지 경로와 디렉터리 목록을 확인합니다.

393 393

394`Read` deny 규칙은 동일한 경로에서 [Edit 및 Write 도구](/docs/ko/errors#file-is-covered-by-a-read-deny-rule)도 차단하며, 새 파일 생성도 포함됩니다. NotebookEdit은 포함되지 않으므로 도구가 변경할 수 없는 경로에 대해 `Edit` deny 규칙을 추가합니다. 확인은 편집 시 Claude Code v2.1.208 이상이 필요하며, 쓰기 시 v2.1.228 이상이 필요합니다.394`Read` deny 규칙은 동일한 경로에서 [Edit 및 Write 도구](/docs/ko/errors#file-is-covered-by-a-read-deny-rule)도 차단하며, 새 파일 생성도 포함됩니다. NotebookEdit은 포함되지 않으므로 도구가 변경할 수 없는 경로에 대해 `Edit` deny 규칙을 추가합니다. Write 도구의 경우 이 확인에는 Claude Code v2.1.228 이상이 필요합니다.

395 395

396Claude Code는 `Edit(path)` 및 `Read(path)` 규칙에 대해서만 파일 권한을 확인합니다. `Write`, `NotebookEdit`, `Glob` 또는 레거시 `MultiEdit` 도구에 대해 경로 규칙을 작성하면 Claude Code는 규칙을 수락하지만 절대 참조하지 않으며, `--allowedTools`에 전달된 `Glob` 규칙을 제외하고 [시작 시 경고](/docs/ko/errors#is-not-matched-by-file-permission-checks)합니다. `Write(docs/**)`, `NotebookEdit(docs/**)` 또는 `MultiEdit(docs/**)` 대신 `Edit(docs/**)`를 사용하고, `Glob(docs/**)` 대신 `Read(docs/**)`를 사용합니다. Claude Code는 `Write`에 대한 deny 규칙과 같이 경로가 없는 도구 이름 규칙에 대해서는 경고하지 않으며, 해당 규칙을 모든 곳에서 도구 수준으로 일치시킵니다. Claude Code v2.1.210 이상이 필요합니다.396Claude Code는 `Edit(path)` 및 `Read(path)` 규칙에 대해서만 파일 권한을 확인합니다. `Write`, `NotebookEdit`, `Glob` 또는 레거시 `MultiEdit` 도구에 대해 경로 규칙을 작성하면 Claude Code는 규칙을 수락하지만 절대 참조하지 않으며, `--allowedTools`에 전달된 `Glob` 규칙을 제외하고 [시작 시 경고](/docs/ko/errors#is-not-matched-by-file-permission-checks)합니다. `Write(docs/**)`, `NotebookEdit(docs/**)` 또는 `MultiEdit(docs/**)` 대신 `Edit(docs/**)`를 사용하고, `Glob(docs/**)` 대신 `Read(docs/**)`를 사용합니다. Claude Code는 `Write`에 대한 deny 규칙과 같이 경로가 없는 도구 이름 규칙에 대해서는 경고하지 않으며, 해당 규칙을 모든 곳에서 도구 수준으로 일치시킵니다.

397 397

398<Warning>398<Warning>

399 Read 및 Edit deny 규칙은 Claude의 기본 제공 파일 도구, Bash에서 Claude Code가 인식하는 `cat`, `head`, `tail`, `sed` 및 `tee`와 같은 파일 명령, 그리고 `> file` 및 `< file`과 같은 Bash [리다이렉션](#redirections)의 대상에 적용됩니다. 이들은 파일이 있는 디렉터리에서 실행한 `grep -r pattern .`처럼 파일 이름을 지정하지 않고 파일을 읽는 명령이나, 파일을 직접 여는 Python 또는 Node 스크립트처럼 파일을 간접적으로 읽거나 쓰는 임의의 서브프로세스에는 적용되지 않습니다. 경로에 대한 모든 프로세스의 액세스를 차단하는 OS 수준 적용을 위해 [샌드박스를 활성화합니다](/docs/ko/sandboxing).399 Read 및 Edit deny 규칙은 Claude의 기본 제공 파일 도구, Bash에서 Claude Code가 인식하는 `cat`, `head`, `tail`, `sed` 및 `tee`와 같은 파일 명령, 그리고 `> file` 및 `< file`과 같은 Bash [리다이렉션](#redirections)의 대상에 적용됩니다. 이들은 파일이 있는 디렉터리에서 실행한 `grep -r pattern .`처럼 파일 이름을 지정하지 않고 파일을 읽는 명령이나, 파일을 직접 여는 Python 또는 Node 스크립트처럼 파일을 간접적으로 읽거나 쓰는 임의의 서브프로세스에는 적용되지 않습니다. 경로에 대한 모든 프로세스의 액세스를 차단하는 OS 수준 적용을 위해 [샌드박스를 활성화합니다](/docs/ko/sandboxing).

762 762

763샌드박싱을 활성화하고 `autoAllowBashIfSandboxed`를 기본값인 `true`로 유지하면, 권한에 bare `Bash` ask 규칙이 포함되어 있거나 [동등한 `Bash(*)` 형식](#match-all-uses-of-a-tool)이 포함되어 있어도 샌드박스된 Bash 명령은 프롬프트 없이 실행됩니다. 샌드박스 경계는 전체 도구 프롬프트를 대체합니다.763샌드박싱을 활성화하고 `autoAllowBashIfSandboxed`를 기본값인 `true`로 유지하면, 권한에 bare `Bash` ask 규칙이 포함되어 있거나 [동등한 `Bash(*)` 형식](#match-all-uses-of-a-tool)이 포함되어 있어도 샌드박스된 Bash 명령은 프롬프트 없이 실행됩니다. 샌드박스 경계는 전체 도구 프롬프트를 대체합니다.

764 764

765[계획 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서 Claude Code는 이 대체를 건너뜁니다. ask 규칙이 없으면 [기본 제공 읽기 전용 명령](#read-only-commands)은 여전히 프롬프트 없이 실행되고, 다른 모든 셸 명령은 계획 중일 때 일반 권한 흐름을 거칩니다. Claude Code가 거기서 명령을 제어하는 방식은 [계획 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)를 참조하십시오. bare `Bash` ask 규칙이 있으면 샌드박스된 읽기 전용 명령을 포함한 모든 Bash 명령이 프롬프트되며, 이는 샌드박싱 외부와 동일합니다. v2.1.212 이전에는 대체가 계획 모드에서도 적용되었습니다.765[플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서 Claude Code는 이 대체를 건너뜁니다. ask 규칙이 없으면 [기본 제공 읽기 전용 명령](#read-only-commands)은 여전히 프롬프트 없이 실행되고, 다른 모든 셸 명령은 계획 중일 때 일반 권한 흐름을 거칩니다. Claude Code가 거기서 명령을 제어하는 방식은 [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)를 참조하십시오. bare `Bash` ask 규칙이 있으면 샌드박스된 읽기 전용 명령을 포함한 모든 Bash 명령이 확인을 요청하며, 이는 샌드박싱 외부와 동일합니다.

766 766

767이러한 검사는 여전히 적용됩니다:767이러한 검사는 여전히 적용됩니다:

768 768

plugins/install.md +2 −2

Details

95 95

96 <Steps>96 <Steps>

97 <Step title="플러그인 브라우저 열기">97 <Step title="플러그인 브라우저 열기">

98 프롬프트 상자 옆의 **+** 버튼을 클릭하고 **Plugins**를 선택한 후 **Add plugin**을 선택합니다. 플러그인 브라우저가 마켓플레이스의 플러그인과 함께 열립니다.98 프롬프트 상자 옆의 **+** 버튼을 클릭하고 **Add plugins**를 선택합니다. **+** 메뉴에 **Add plugins** 대신 **Plugins**가 표시되면 **Plugins**를 선택한 후 **Browse plugins**를 선택합니다. 플러그인 브라우저가 마켓플레이스의 플러그인과 함께 열립니다.

99 </Step>99 </Step>

100 100

101 <Step title="플러그인 선택">101 <Step title="플러그인 선택">

107 </Step>107 </Step>

108 </Steps>108 </Steps>

109 109

110 나중에 활성화, 비활성화 또는 제거하려면 **+ > Plugins > Manage plugins**를 사용합니다. 플러그인 브라우저는 데스크톱 앱의 클라우드 세션에서 사용할 수 없습니다. [데스크톱 앱에서 플러그인 설치](/docs/ko/desktop#install-plugins)를 참조하세요.110 나중에 플러그인을 활성화, 비활성화 또는 제거하려면 [데스크톱 앱에서 플러그인 설치](/docs/ko/desktop#install-plugins)를 참조하세요.

111 </Tab>111 </Tab>

112 112

113 <Tab title="VS Code">113 <Tab title="VS Code">

plugins/mods/interface.md +1 −1

Details

362 VS Code 확장에서 그리기362 VS Code 확장에서 그리기

363</h3>363</h3>

364 364

365VS Code 확장에서는 확장 버전이 2.1.299 이상이고 [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션인 경우 mod가 그리는 내용이 채팅 패널에 나타납니다. 패널용 `ui.render` 훅에서 `e.surface`는 `vscode`입니다. 패널이 어떤 지점과 요소를 그리는지, 어떤 prop을 무시하는지 확인하려면 [렌더링 지점](/docs/ko/plugins/mods/reference#render-sites) 및 [요소](/docs/ko/plugins/mods/reference#elements) 표를 참조하십시오.365VS Code 확장에서는 확장 버전 2.1.299 이상에서 mod가 그리는 내용이 채팅 패널에 나타납니다. Amazon Bedrock 세션처럼 [기능 플래그를 가져오지 않는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에는 2.1.304 이상이 필요합니다. 패널용 `ui.render` 훅에서 `e.surface`는 `vscode`입니다. 패널이 어떤 지점과 요소를 그리는지, 어떤 prop을 무시하는지 확인하려면 [렌더링 지점](/docs/ko/plugins/mods/reference#render-sites) 및 [요소](/docs/ko/plugins/mods/reference#elements) 표를 참조하십시오.

366 366

367mod가 터미널뿐 아니라 패널에서도 작동하도록 하려면 다음 차이점을 고려하십시오.367mod가 터미널뿐 아니라 패널에서도 작동하도록 하려면 다음 차이점을 고려하십시오.

368 368

plugins/mods/overview.md +1 −1

Details

219| 에디터의 통합 터미널과 JetBrains 플러그인을 포함한 터미널의 `claude` | 예 | 예 |219| 에디터의 통합 터미널과 JetBrains 플러그인을 포함한 터미널의 `claude` | 예 | 예 |

220| Desktop 앱의 Code 탭(WSL 세션 제외) | 예 | 예. 단, [요소 표](/docs/ko/plugins/mods/reference#elements)에서 터미널 전용으로 표시된 요소는 제외 |220| Desktop 앱의 Code 탭(WSL 세션 제외) | 예 | 예. 단, [요소 표](/docs/ko/plugins/mods/reference#elements)에서 터미널 전용으로 표시된 요소는 제외 |

221| Desktop 앱의 [WSL 세션](/docs/ko/desktop-wsl) | 아니요. WSL 세션에서는 플러그인을 사용할 수 없기 때문입니다 | 아니요 |221| Desktop 앱의 [WSL 세션](/docs/ko/desktop-wsl) | 아니요. WSL 세션에서는 플러그인을 사용할 수 없기 때문입니다 | 아니요 |

222| VS Code 확장 프로그램의 채팅 패널 | 예 | 예. 확장 프로그램 버전 2.1.299 이상이며 [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션인 경우입니다. 패널이 그리는 항목은 [렌더링 지점](/docs/ko/plugins/mods/reference#render-sites) 표와 [요소](/docs/ko/plugins/mods/reference#elements) 표에 표시되어 있습니다. |222| VS Code 확장 프로그램의 채팅 패널 | 예 | 예. 확장 프로그램 버전 2.1.299 이상이 필요합니다. Amazon Bedrock 세션처럼 [기능 플래그를 가져오지 않는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에는 2.1.304 이상이 필요합니다. 패널이 그리는 항목은 [렌더링 지점](/docs/ko/plugins/mods/reference#render-sites) 표와 [요소](/docs/ko/plugins/mods/reference#elements) 표에 표시되어 있습니다. |

223| `claude -p` 및 [Agent SDK](/docs/ko/agent-sdk/overview) | 예 | 아니요 |223| `claude -p` 및 [Agent SDK](/docs/ko/agent-sdk/overview) | 예 | 아니요 |

225| [클라우드 세션](/docs/ko/claude-code-on-the-web) | 예. [클라우드 세션에 전달되는](/docs/ko/cloud-environments#what-carries-over-from-your-setup) 플러그인의 경우 | 아니요 |225| [클라우드 세션](/docs/ko/claude-code-on-the-web) | 예. [클라우드 세션에 전달되는](/docs/ko/cloud-environments#what-carries-over-from-your-setup) 플러그인의 경우 | 아니요 |

plugins/mods/reference.md +1 −1

Details

257 257

258렌더링 지점은 Claude Code 인터페이스의 확장 지점입니다. 각 행은 `ui.render` 훅에서 `e.component`의 값이며, `e.props`의 필드와 해당 지점을 렌더링하는 앱을 함께 보여 줍니다. `e.surface`는 `terminal`, `desktop`, `vscode`처럼 그리기를 수행하는 앱을 나타냅니다. [Claude Code가 이미 그리는 요소 변경하기](/docs/ko/plugins/mods/interface#change-what-claude-code-already-draws)에서는 훅이 각 지점에서 무엇을 할 수 있는지를 선택지별 예시와 함께 보여 줍니다.258렌더링 지점은 Claude Code 인터페이스의 확장 지점입니다. 각 행은 `ui.render` 훅에서 `e.component`의 값이며, `e.props`의 필드와 해당 지점을 렌더링하는 앱을 함께 보여 줍니다. `e.surface`는 `terminal`, `desktop`, `vscode`처럼 그리기를 수행하는 앱을 나타냅니다. [Claude Code가 이미 그리는 요소 변경하기](/docs/ko/plugins/mods/interface#change-what-claude-code-already-draws)에서는 훅이 각 지점에서 무엇을 할 수 있는지를 선택지별 예시와 함께 보여 줍니다.

259 259

260VS Code 확장 프로그램에서 렌더링하려면 확장 프로그램 버전 2.1.299 이상과 [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션이 필요합니다. [VS Code 확장 프로그램에서 그리기](/docs/ko/plugins/mods/interface#draw-in-the-vs-code-extension)에 확장 프로그램이 다르게 그리는 요소가 정리되어 있습니다.260VS Code 확장 프로그램에서 렌더링하려면 확장 프로그램 버전 2.1.299 이상이 필요합니다. [기능 플래그를 가져오지 않는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서는 2.1.304 이상이 필요합니다. [VS Code 확장 프로그램에서 그리기](/docs/ko/plugins/mods/interface#draw-in-the-vs-code-extension)에 확장 프로그램이 다르게 그리는 요소가 정리되어 있습니다.

261 261

263| :- | :- | :- | :- |263| :- | :- | :- | :- |

plugins/mods/troubleshoot.md +1 −1

Details

315 315

316* **해당 앱에서 지점 또는 요소가 그려지지 않는 경우**: [렌더링 지점](/docs/ko/plugins/mods/reference#render-sites) 표에서 해당 지점을, [요소](/docs/ko/plugins/mods/reference#elements) 표에서 해당 요소를 찾습니다. 앱에 없는 요소라면 훅에서 `e.surface`를 확인하고 앱이 그릴 수 있는 트리를 반환합니다.316* **해당 앱에서 지점 또는 요소가 그려지지 않는 경우**: [렌더링 지점](/docs/ko/plugins/mods/reference#render-sites) 표에서 해당 지점을, [요소](/docs/ko/plugins/mods/reference#elements) 표에서 해당 요소를 찾습니다. 앱에 없는 요소라면 훅에서 `e.surface`를 확인하고 앱이 그릴 수 있는 트리를 반환합니다.

317* **VS Code 확장이 2.1.299보다 오래된 경우**: 채팅 패널은 [확장 버전](/docs/ko/vs-code#install-the-extension) 2.1.299부터 mod를 위해 그립니다. VS Code의 Extensions 보기에서 버전을 확인하고 그곳에서 확장을 업데이트합니다.317* **VS Code 확장이 2.1.299보다 오래된 경우**: 채팅 패널은 [확장 버전](/docs/ko/vs-code#install-the-extension) 2.1.299부터 mod를 위해 그립니다. VS Code의 Extensions 보기에서 버전을 확인하고 그곳에서 확장을 업데이트합니다.

318* **VS Code 세션이 기능 플래그를 가져오지 않는 경우**: 채팅 패널에서 그리려면 기능 플래그 가져오기가 필요합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry를 사용하거나 [Claude apps gateway](/docs/ko/claude-apps-gateway)를 통하는 세션은 이를 건너뛰며, [기능 플래그 가져오기가 필요한 기능](/docs/ko/env-vars#features-that-need-feature-flag-fetching)에 나열된 다른 경우도 마찬가지입니다. 이러한 세션에서 그림을 보려면 대신 VS Code의 통합 터미널 같은 터미널에서 `claude`를 실행합니다.318* **확장이 2.1.304보다 오래되었고 세션이 기능 플래그를 가져오지 않는 경우**: 확장을 업데이트하거나, 대신 VS Code의 통합 터미널에서 `claude`를 실행합니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry의 세션은 가져오기를 건너뜁니다. [Claude apps gateway](/docs/ko/claude-apps-gateway) 세션처럼 이를 건너뛰는 다른 경우는 [기능 플래그 가져오기가 필요한 기능](/docs/ko/env-vars#features-that-need-feature-flag-fetching)을 참조하세요.

319 319

320<h2 id="an-edit-or-a-value-is-lost">320<h2 id="an-edit-or-a-value-is-lost">

321 편집 내용이나 값이 사라짐321 편집 내용이나 값이 사라짐

plugins/troubleshooting.md +1 −1

Details

40 40

41대신 사용 중인 표면에서 플러그인을 설치합니다:41대신 사용 중인 표면에서 플러그인을 설치합니다:

42 42

43* **Claude 데스크톱 앱, 로컬 또는 SSH 세션**: 프롬프트 옆의 **+** 버튼을 클릭한 다음 **플러그인**, **플러그인 추가**를 클릭하여 [플러그인 브라우저](/docs/ko/desktop#install-plugins)를 엽니다.43* **Claude 데스크톱 앱, 로컬 또는 SSH 세션**: [플러그인 설치](/docs/ko/plugins/install#install-a-plugin) 아래의 **데스크톱 앱** 탭을 사용합니다.

44* **VS Code 확장**: [플러그인 설치](/docs/ko/plugins/install#install-a-plugin) 아래의 **VS Code** 탭을 사용합니다.44* **VS Code 확장**: [플러그인 설치](/docs/ko/plugins/install#install-a-plugin) 아래의 **VS Code** 탭을 사용합니다.

45* **웹의 Claude Code 또는 데스크톱 클라우드 세션**: 클라우드 세션에는 플러그인 브라우저가 없습니다. 클라우드 세션이 로드하는 내용은 [플러그인 설치](/docs/ko/plugins/install#install-a-plugin)의 **클라우드 세션** 탭을 참조합니다.45* **웹의 Claude Code 또는 데스크톱 클라우드 세션**: 클라우드 세션에는 플러그인 브라우저가 없습니다. 클라우드 세션이 로드하는 내용은 [플러그인 설치](/docs/ko/plugins/install#install-a-plugin)의 **클라우드 세션** 탭을 참조합니다.

46* **액세스 권한이 있는 터미널**: `claude`를 실행하고 거기서 `/plugin`을 입력하거나, 세션을 시작하지 않고 셸에서 `claude plugin install <plugin>@<marketplace>`를 실행합니다.46* **액세스 권한이 있는 터미널**: `claude`를 실행하고 거기서 `/plugin`을 입력하거나, 세션을 시작하지 않고 셸에서 `claude plugin install <plugin>@<marketplace>`를 실행합니다.

sandbox-environments.md +9 −3

Details

122mkdir -p ~/.claude && { [ -f ~/.claude.json ] || echo '{}' > ~/.claude.json; }122mkdir -p ~/.claude && { [ -f ~/.claude.json ] || echo '{}' > ~/.claude.json; }

123```123```

124 124

125설정 파일이 준비되면 `npx`로 Claude Code를 시작하고 `claude`를 래핑할 명령으로 전달하십시오:125쓰기를 허용한 모든 경로 바깥의 prefix 아래에 런타임을 전역으로 설치하십시오:

126 126

127```bash theme={null}127```bash theme={null}

128npx @anthropic-ai/sandbox-runtime claude128npm install -g @anthropic-ai/sandbox-runtime

129```129```

130 130

131Claude Code는 구성한 파일 시스템 및 네트워크 경계가 있는 샌드박스 내에서 시작됩니다. 동일한 명령은 독립 실행형 MCP 서버 또는 기타 도우미 프로세스를 샌드박싱하는 데에도 작동합니다.131설정 파일이 준비되면 프로젝트 디렉터리에서 런타임을 통해 Claude Code를 시작하십시오:

132

133```bash theme={null}

134srt claude

135```

136

137Claude Code는 구성한 파일 시스템 및 네트워크 경계가 있는 샌드박스 내에서 시작됩니다. 동일한 `srt` 명령은 독립 실행형 MCP 서버 또는 기타 도우미 프로세스를 샌드박싱하는 데에도 작동합니다.

132 138

133<h3 id="what-the-runtime-blocks-on-its-own">139<h3 id="what-the-runtime-blocks-on-its-own">

134 런타임이 자체적으로 차단하는 항목140 런타임이 자체적으로 차단하는 항목

security-guidance.md +1 −1

Details

33 33

34`/plugin`은 터미널 CLI에서 대화형 패널을 엽니다. Claude가 이 환경에서 `/plugin`을 사용할 수 없다고 응답하면 다른 방법으로 설치합니다:34`/plugin`은 터미널 CLI에서 대화형 패널을 엽니다. Claude가 이 환경에서 `/plugin`을 사용할 수 없다고 응답하면 다른 방법으로 설치합니다:

35 35

36* **Claude 데스크톱 앱, 로컬 또는 SSH 세션**: 프롬프트 옆의 **+** 버튼을 클릭한 후 **플러그인**, **플러그인 추가**를 클릭하여 [플러그인 브라우저](/docs/ko/desktop#install-plugins)를 엽니다36* **Claude 데스크톱 앱, 로컬 또는 SSH 세션**: [플러그인 설치](/docs/ko/plugins/install#install-a-plugin)의 **Desktop app** 탭을 사용합니다

37* **VS Code 확장**: [**플러그인 관리** 대화상자](/docs/ko/vs-code#manage-plugins)에서 설치합니다37* **VS Code 확장**: [**플러그인 관리** 대화상자](/docs/ko/vs-code#manage-plugins)에서 설치합니다

38* **클라우드 세션**: 클라우드 세션은 사용자 설정이나 저장소의 `.claude/settings.json`에서 플러그인을 로드하지 않습니다. [설정에서 전달되는 항목](/docs/ko/cloud-environments#what-carries-over-from-your-setup)에서 설명하는 대로입니다. 조직이 관리 설정을 통해 배포하는 플러그인의 경우 [조직의 플러그인 관리](/docs/ko/plugins/org)를 참조하세요38* **클라우드 세션**: 클라우드 세션은 사용자 설정이나 저장소의 `.claude/settings.json`에서 플러그인을 로드하지 않습니다. [설정에서 전달되는 항목](/docs/ko/cloud-environments#what-carries-over-from-your-setup)에서 설명하는 대로입니다. 조직이 관리 설정을 통해 배포하는 플러그인의 경우 [조직의 플러그인 관리](/docs/ko/plugins/org)를 참조하세요

39 39

self-hosted-environments-deploy.md +10 −1

Details

554* **[`--retire-at`](/docs/ko/self-hosted-environments-reference#runner-cli-flags) 사용 시**: 은퇴 시간과 호스트가 중지되는 시간 사이에 일반적인 턴이 완료될 만큼의 시간, [러너 수명 주기](/docs/ko/self-hosted-environments#runner-lifecycle)에서 설명하는 백그라운드 작업 대기 시간, 그리고 로그에 기록된 시간을 더한 만큼의 여유를 두세요. 은퇴 시간은 시작할 때마다 계산하세요(예: `date +%s` + 러너의 의도된 수명).554* **[`--retire-at`](/docs/ko/self-hosted-environments-reference#runner-cli-flags) 사용 시**: 은퇴 시간과 호스트가 중지되는 시간 사이에 일반적인 턴이 완료될 만큼의 시간, [러너 수명 주기](/docs/ko/self-hosted-environments#runner-lifecycle)에서 설명하는 백그라운드 작업 대기 시간, 그리고 로그에 기록된 시간을 더한 만큼의 여유를 두세요. 은퇴 시간은 시작할 때마다 계산하세요(예: `date +%s` + 러너의 의도된 수명).

555* **[`--defer-shutdown-max-min`](#defer-the-drain-past-the-first-signal) 사용 시**: 중지 타임아웃은 구성한 분과 드레인이 시작되기 전의 추가 대기 시간(기본 설정에서 75초)도 포함해야 합니다. [첫 신호 이후 드레인 연기](#defer-the-drain-past-the-first-signal)에서 두 가지를 모두 설명합니다. 러너는 이 더 긴 시간도 시작 시 로그에 기록합니다.555* **[`--defer-shutdown-max-min`](#defer-the-drain-past-the-first-signal) 사용 시**: 중지 타임아웃은 구성한 분과 드레인이 시작되기 전의 추가 대기 시간(기본 설정에서 75초)도 포함해야 합니다. [첫 신호 이후 드레인 연기](#defer-the-drain-past-the-first-signal)에서 두 가지를 모두 설명합니다. 러너는 이 더 긴 시간도 시작 시 로그에 기록합니다.

556 556

557<h3 id="post-a-status-message-before-a-restart">

558 재시작 전 상태 메시지 게시

559</h3>

560

561세션을 중단시킬 재시작 전에 [Owner](/docs/ko/cloud-environments#organization-shared-environments)가 [**Cloud environments** 관리자 페이지](https://claude.ai/admin-settings/cloud-environments)에서 해당 환경에 상태 메시지를 게시하도록 하세요. [claude.ai/code](https://claude.ai/code)에서 멤버는 해당 환경의 세션에서 이 메시지를 확인합니다. Owner가 게시할 때 만료 시간을 설정하도록 하거나, 러너가 다시 가동되면 메시지를 제거하도록 하세요.

562

557<h3 id="defer-the-drain-past-the-first-signal">563<h3 id="defer-the-drain-past-the-first-signal">

558 첫 신호 이후 드레인 연기564 첫 신호 이후 드레인 연기

559</h3>565</h3>

632 버전 고정638 버전 고정

633</h2>639</h2>

634 640

635각 세션의 자식 Claude Code 프로세스는 러너의 자신의 바이너리를 실행하고, 러너는 생성하는 세션 내에서 자동 업데이트를 끕니다. 따라서 모든 세션은 호스트에 설치하거나 이미지에 빌드한 버전을 실행합니다. 호스트 수준 업데이트는 러너가 다음 번에 시작할 때 적용됩니다.641각 세션의 자식 프로세스는 기본적으로 러너 자신의 바이너리를 실행하고, 러너는 생성하는 세션 내에서 자동 업데이트를 끕니다. 이 기본 설정에서는 모든 세션이 호스트에 설치하거나 이미지에 빌드한 버전을 실행합니다. 호스트 수준 업데이트는 러너가 다음 번에 시작할 때 적용됩니다.

636 642

637세션이 실행할 버전과 버전이 변경되는 시점을 선택합니다.643세션이 실행할 버전과 버전이 변경되는 시점을 선택합니다.

638 644

640* **플릿을 한 버전으로 유지하려면**: 이미지를 고정된 버전으로 빌드하거나 베어 호스트에 특정 버전을 설치하고 [자동 업데이트를 비활성화](/docs/ko/setup#disable-auto-updates)하세요.646* **플릿을 한 버전으로 유지하려면**: 이미지를 고정된 버전으로 빌드하거나 베어 호스트에 특정 버전을 설치하고 [자동 업데이트를 비활성화](/docs/ko/setup#disable-auto-updates)하세요.

641* **고정 플릿을 업그레이드하려면**: 현재 버전과 설치할 버전 사이의 [변경 로그](/docs/en/changelog) 항목을 읽은 다음, 새로운 버전을 설치하거나 이미지를 다시 빌드하고 러너를 재시작하세요.647* **고정 플릿을 업그레이드하려면**: 현재 버전과 설치할 버전 사이의 [변경 로그](/docs/en/changelog) 항목을 읽은 다음, 새로운 버전을 설치하거나 이미지를 다시 빌드하고 러너를 재시작하세요.

642* **온디맨드 러너를 업그레이드하려면**: 현재 버전과 설치할 버전 사이의 [변경 로그](/docs/en/changelog) 항목을 읽은 다음, [`spawn-runner` 훅](/docs/ko/self-hosted-environments-configuration#the-spawn-runner-hook)이 시작하는 이미지를 변경하세요. 새로 생성되는 각 러너는 새 버전을 받습니다. [`--min-idle`](/docs/ko/self-hosted-environments-reference#orchestrator-cli-flags)이 시작한 대기 러너를 포함하여 이미 실행 중인 러너는 종료될 때까지 기존 버전을 유지합니다. 해당 러너의 작업 지시는 일회용이므로 재시작하지 마세요.648* **온디맨드 러너를 업그레이드하려면**: 현재 버전과 설치할 버전 사이의 [변경 로그](/docs/en/changelog) 항목을 읽은 다음, [`spawn-runner` 훅](/docs/ko/self-hosted-environments-configuration#the-spawn-runner-hook)이 시작하는 이미지를 변경하세요. 새로 생성되는 각 러너는 새 버전을 받습니다. [`--min-idle`](/docs/ko/self-hosted-environments-reference#orchestrator-cli-flags)이 시작한 대기 러너를 포함하여 이미 실행 중인 러너는 종료될 때까지 기존 버전을 유지합니다. 해당 러너의 작업 지시는 일회용이므로 재시작하지 마세요.

649* **세션이 다른 바이너리를 시작하는 경우**: [`--exec-path`](/docs/ko/self-hosted-environments-reference#runner-cli-flags) 또는 [`command` 훅](/docs/ko/self-hosted-environments-configuration#command)을 사용하여 러너 자신의 바이너리가 아닌 다른 Claude Code 바이너리를 시작하는 경우, 세션은 해당 바이너리의 버전을 실행합니다. 러너를 업데이트할 때 해당 바이너리도 함께 업데이트하세요.

643* **플러그인**: 플러그인 마켓플레이스도 자동 업데이트되지 않습니다. 바이너리가 고정된 상태로 유지되는 동안 플러그인이 자동 업데이트되도록 하려면 러너의 환경에서 `FORCE_AUTOUPDATE_PLUGINS=1`을 설정하세요.650* **플러그인**: 플러그인 마켓플레이스도 자동 업데이트되지 않습니다. 바이너리가 고정된 상태로 유지되는 동안 플러그인이 자동 업데이트되도록 하려면 러너의 환경에서 `FORCE_AUTOUPDATE_PLUGINS=1`을 설정하세요.

644 651

645<h2 id="scale-the-fleet">652<h2 id="scale-the-fleet">

699 * **플래그를 활성화하기 전에**: 소스 원격의 `claude/*` refs에 푸시할 수 있는 사람을 제한합니다. 재개 시 러너는 이전에 푸시된 브랜치를 누가 푸시했는지 확인하지 않고 가져옵니다.706 * **플래그를 활성화하기 전에**: 소스 원격의 `claude/*` refs에 푸시할 수 있는 사람을 제한합니다. 재개 시 러너는 이전에 푸시된 브랜치를 누가 푸시했는지 확인하지 않고 가져옵니다.

700* **세션 중간에 추가한 저장소는 클론에 실패할 수 있음**: Claude는 HTTPS를 통해 `git clone`으로 저장소를 클론합니다. [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)가 없는 러너에서는 호스트에서 해당 저장소를 읽을 수 있는 수단이 없으면 git 인증 오류로 클론이 실패합니다. 가능하면 세션을 만들 때 세션에 필요한 모든 저장소를 선택합니다.707* **세션 중간에 추가한 저장소는 클론에 실패할 수 있음**: Claude는 HTTPS를 통해 `git clone`으로 저장소를 클론합니다. [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)가 없는 러너에서는 호스트에서 해당 저장소를 읽을 수 있는 수단이 없으면 git 인증 오류로 클론이 실패합니다. 가능하면 세션을 만들 때 세션에 필요한 모든 저장소를 선택합니다.

701* **일부 커넥터는 자체 호스팅 세션에 나타나지 않음**: claude.ai 설정에서 아직 연결하지 않은 커넥터는 자체 호스팅 세션에 나열되지 않으며, 세션은 연결하라는 메시지를 표시하지 않습니다. 먼저 설정에서 연결한 후 새로운 세션을 시작합니다. 이미 실행 중인 세션에 커넥터를 추가해도 Claude에서 해당 도구를 사용할 수 없습니다. 새로 추가된 커넥터를 선택하려면 새로운 세션을 시작합니다.708* **일부 커넥터는 자체 호스팅 세션에 나타나지 않음**: claude.ai 설정에서 아직 연결하지 않은 커넥터는 자체 호스팅 세션에 나열되지 않으며, 세션은 연결하라는 메시지를 표시하지 않습니다. 먼저 설정에서 연결한 후 새로운 세션을 시작합니다. 이미 실행 중인 세션에 커넥터를 추가해도 Claude에서 해당 도구를 사용할 수 없습니다. 새로 추가된 커넥터를 선택하려면 새로운 세션을 시작합니다.

709* **누군가 세션을 보관 또는 삭제하거나, 세션 메뉴에서 러너를 해제하는 경우**: [`--push-outcome-on-release`](/docs/ko/self-hosted-environments-reference#runner-cli-flags) 푸시에 의존할 수 없습니다. 이러한 경우 커밋을 저장하려면 [`post-session` 훅](/docs/ko/self-hosted-environments-configuration#post-session)에서 `HEAD`를 복구 브랜치로 푸시합니다. 해당 문서의 예제에서 시작하는 경우, 예제는 스냅샷 커밋 후에만 푸시하므로 커밋되지 않은 항목이 없을 때도 푸시하도록 수정합니다.

702 710

703<h3 id="report-an-issue">711<h3 id="report-an-issue">

704 문제 보고712 문제 보고

745 모든 호출이 세션 약 30분 후에 실패하기 시작하면 래퍼 스크립트가 세션의 stdin을 끊었을 가능성이 높으므로 토큰 회전이 도달할 수 없습니다. [stdin 및 파일 디스크립터 3 유지](/docs/ko/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached)를 참조하세요.753 모든 호출이 세션 약 30분 후에 실패하기 시작하면 래퍼 스크립트가 세션의 stdin을 끊었을 가능성이 높으므로 토큰 회전이 도달할 수 없습니다. [stdin 및 파일 디스크립터 3 유지](/docs/ko/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached)를 참조하세요.

746 754

747 v2.1.274 이전에 러너는 실패한 가져오기 후 몇 번의 시도 후 재시도를 중지하고 다음 예약된 것을 기다렸습니다. 실패한 턴은 가져오기를 트리거하지 않았으므로 모든 턴은 다음 예약된 가져오기까지 401로 실패했습니다.755 v2.1.274 이전에 러너는 실패한 가져오기 후 몇 번의 시도 후 재시도를 중지하고 다음 예약된 것을 기다렸습니다. 실패한 턴은 가져오기를 트리거하지 않았으므로 모든 턴은 다음 예약된 가져오기까지 401로 실패했습니다.

756* **claude.ai/code에서 턴이 `This model needs a newer version of Claude Code`와 함께 실패함**: 러너가 세션을 시작할 때 사용하는 Claude Code 버전이 세션의 모델이 요구하는 버전보다 오래되어 API가 [요청을 거부](/docs/ko/errors#claude-code-does-not-support-this-model)합니다. [버전 고정](#pin-the-version)에 설명된 대로 메시지가 요구하는 버전 또는 그 이후 버전으로 러너를 업그레이드하세요. 그때까지는 세션에서 다른 모델을 선택할 수 있습니다.

748* **Pod이 드레인 중간에 종료됨**: `terminationGracePeriodSeconds`를 최소한 러너가 시작 시 기록하는 값으로 올리세요. [종료 타이밍](#shutdown-timing)을 참조하세요.757* **Pod이 드레인 중간에 종료됨**: `terminationGracePeriodSeconds`를 최소한 러너가 시작 시 기록하는 값으로 올리세요. [종료 타이밍](#shutdown-timing)을 참조하세요.

749 758

750로깅이 초기화되면 러너는 `[runner:fatal]` 라인을 포함한 수명 주기 로그를 stdout에, 디버그 출력을 stderr에 쓰며, 모두 JSON이 아닌 일반 텍스트 라인입니다. 위의 문제 해결 항목에서 설명하는 기본 디렉터리 실패는 그 이전에 stderr에 출력됩니다. `--log-file`로 두 스트림을 모두 캡처하세요. 이렇게 하면 `self-hosted-runner doctor`가 이를 추적할 수도 있습니다. 또는 플랫폼의 로그 수집으로 캡처하세요.759로깅이 초기화되면 러너는 `[runner:fatal]` 라인을 포함한 수명 주기 로그를 stdout에, 디버그 출력을 stderr에 쓰며, 모두 JSON이 아닌 일반 텍스트 라인입니다. 위의 문제 해결 항목에서 설명하는 기본 디렉터리 실패는 그 이전에 stderr에 출력됩니다. `--log-file`로 두 스트림을 모두 캡처하세요. 이렇게 하면 `self-hosted-runner doctor`가 이를 추적할 수도 있습니다. 또는 플랫폼의 로그 수집으로 캡처하세요.

server-managed-settings.md +2 −2

Details

201* 캐시된 설정은 네트워크 장애를 통해 유지됩니다. 시작 가져오기가 실패하면, Claude Code는 대화형 세션에서 캐시된 정책이 적용 중임을 경고합니다.201* 캐시된 설정은 네트워크 장애를 통해 유지됩니다. 시작 가져오기가 실패하면, Claude Code는 대화형 세션에서 캐시된 정책이 적용 중임을 경고합니다.

202* 가져오기가 성공할 때까지, 시작 시 보류된 값은 보류된 상태로 유지됩니다.202* 가져오기가 성공할 때까지, 시작 시 보류된 값은 보류된 상태로 유지됩니다.

203 203

204Claude Code는 서버가 세션의 페이로드를 확인할 때까지 캐시된 `env` 블록의 여러 범주의 변수를 보류합니다. 이는 캐시된 프록시, 인증서 기관, 엔드포인트, 또는 자격증명 값이 페이로드를 확인하는 설정 가져오기를 리디렉션, 가로채기, 또는 재인증하는 것을 방지합니다. 강화는 서버에서 가져온 설정 캐시에만 적용됩니다. MDM 또는 `managed-settings.json`을 통해 배포된 [엔드포인트 관리 설정](/docs/ko/managed-settings#delivery-mechanisms)은 영향을 받지 않습니다. 보류에는 Claude Code v2.1.198 이상이 필요합니다. v2.1.198 이전에는 전체 캐시된 `env` 블록이 시작 시 적용됩니다. 보류된 범주는 다음을 포함합니다:204Claude Code는 서버가 세션의 페이로드를 확인할 때까지 캐시된 `env` 블록의 여러 범주의 변수를 보류합니다. 이는 캐시된 프록시, 인증 기관, 엔드포인트, 또는 자격 증명 값이 페이로드를 확인하는 설정 가져오기를 리디렉션, 가로채기, 또는 재인증하는 것을 방지합니다. 이 강화 조치는 서버에서 가져온 설정 캐시에만 적용됩니다. MDM 또는 `managed-settings.json`을 통해 배포된 [엔드포인트 관리형 설정](/docs/ko/managed-settings#delivery-mechanisms)은 영향을 받지 않습니다. 보류된 범주는 다음을 포함합니다:

205 205

206* `HTTPS_PROXY`, `NODE_EXTRA_CA_CERTS`, mTLS 클라이언트 인증서 변수 `CLAUDE_CODE_CLIENT_CERT` 및 `CLAUDE_CODE_CLIENT_KEY`와 같은 프록시 및 TLS 구성206* `HTTPS_PROXY`, `NODE_EXTRA_CA_CERTS`, mTLS 클라이언트 인증서 변수 `CLAUDE_CODE_CLIENT_CERT` 및 `CLAUDE_CODE_CLIENT_KEY`와 같은 프록시 및 TLS 구성

207* `ANTHROPIC_BASE_URL`, `CLAUDE_CODE_USE_BEDROCK` 및 `CLAUDE_CODE_USE_VERTEX`와 같은 공급자 선택 변수, `ANTHROPIC_BEDROCK_BASE_URL`과 같은 공급자 엔드포인트 URL을 포함한 API 라우팅 및 공급자 선택207* `ANTHROPIC_BASE_URL`, `CLAUDE_CODE_USE_BEDROCK` 및 `CLAUDE_CODE_USE_VERTEX`와 같은 공급자 선택 변수, `ANTHROPIC_BEDROCK_BASE_URL`과 같은 공급자 엔드포인트 URL을 포함한 API 라우팅 및 공급자 선택

312 312

313Claude Code는 항상 대화를 표시할 수 없습니다. 아래의 각 경우는 어느 설정이 적용되는지와 다음에 대화를 볼 때를 나타냅니다:313Claude Code는 항상 대화를 표시할 수 없습니다. 아래의 각 경우는 어느 설정이 적용되는지와 다음에 대화를 볼 때를 나타냅니다:

314 314

315* **대화를 표시할 수 없는 대화형 세션**: Claude Code는 전달된 설정을 적용하지 않고 마지막으로 승인된 설정을 유지합니다. 대화는 대화를 표시할 수 있는 다음 세션에 나타납니다. Claude Code v2.1.211 이상이 필요합니다.315* **대화상자를 표시할 수 없는 대화형 세션**: Claude Code는 전달된 설정을 적용하지 않고 마지막으로 승인된 설정을 유지합니다. 대화상자는 이를 표시할 수 있는 다음 세션에 나타납니다.

316* **`claude install` 또는 `claude update`**: Claude Code는 두 명령 중 어느 것 중에도 대화를 표시하지 않습니다. 명령은 마지막으로 승인된 설정으로 실행되고, 대화는 다음 대화형 세션에 나타납니다. Claude Code가 [`forceRemoteSettingsRefresh`](#enforce-fail-closed-startup) 설정 또는 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 배포와 같이 시작 시 설정 가져오기를 기다리면, 대신 명령 중에 대화를 표시하며, 파이프에서의 설치 실행이 실패합니다. [설치 중 `Raw mode is not supported`](/docs/ko/troubleshoot-install#raw-mode-is-not-supported-during-install)를 참조하세요. v2.1.246 이전에는 Claude Code가 이러한 명령 중에도 대화를 표시하려고 했습니다.316* **`claude install` 또는 `claude update`**: Claude Code는 두 명령 중 어느 것 중에도 대화를 표시하지 않습니다. 명령은 마지막으로 승인된 설정으로 실행되고, 대화는 다음 대화형 세션에 나타납니다. Claude Code가 [`forceRemoteSettingsRefresh`](#enforce-fail-closed-startup) 설정 또는 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 배포와 같이 시작 시 설정 가져오기를 기다리면, 대신 명령 중에 대화를 표시하며, 파이프에서의 설치 실행이 실패합니다. [설치 중 `Raw mode is not supported`](/docs/ko/troubleshoot-install#raw-mode-is-not-supported-during-install)를 참조하세요. v2.1.246 이전에는 Claude Code가 이러한 명령 중에도 대화를 표시하려고 했습니다.

317* **오류가 응답 전에 대화를 닫음**: Claude Code는 전달된 설정을 적용하지 않고 마지막으로 승인된 설정을 유지합니다. 대화를 표시할 수 있는 다음 세션에 다시 표시합니다.317* **오류가 응답 전에 대화를 닫음**: Claude Code는 전달된 설정을 적용하지 않고 마지막으로 승인된 설정을 유지합니다. 대화를 표시할 수 있는 다음 세션에 다시 표시합니다.

318* **`claude -p` 또는 Agent SDK 세션과 같은 비대화형 실행**: Claude Code는 대화를 표시할 수 없으므로, 전달된 설정이 승인을 요구할 때, 해당 실행에만 이를 적용합니다. 이를 승인된 것으로 기록하거나 [로컬 캐시](#fetch-and-caching-behavior)에 쓰지 않으며, 다음 대화형 세션은 대화를 표시합니다. 사용자가 대화형 세션에서 승인할 때까지, 각 비대화형 실행은 시작 시 설정을 다시 가져옵니다. v2.1.207 이전에는 비대화형 실행이 설정을 승인된 것으로 저장했으므로, 나중의 대화형 세션은 이들에 대해 대화를 표시하지 않았습니다.318* **`claude -p` 또는 Agent SDK 세션과 같은 비대화형 실행**: Claude Code는 대화를 표시할 수 없으므로, 전달된 설정이 승인을 요구할 때, 해당 실행에만 이를 적용합니다. 이를 승인된 것으로 기록하거나 [로컬 캐시](#fetch-and-caching-behavior)에 쓰지 않으며, 다음 대화형 세션은 대화를 표시합니다. 사용자가 대화형 세션에서 승인할 때까지, 각 비대화형 실행은 시작 시 설정을 다시 가져옵니다. v2.1.207 이전에는 비대화형 실행이 설정을 승인된 것으로 저장했으므로, 나중의 대화형 세션은 이들에 대해 대화를 표시하지 않았습니다.

sessions.md +4 −3

Details

51 51

52Claude Code가 트랜스크립트에서 대화를 로드할 때 재개된 세션은 대화와 함께 저장된 상태를 복원합니다:52Claude Code가 트랜스크립트에서 대화를 로드할 때 재개된 세션은 대화와 함께 저장된 상태를 복원합니다:

53 53

54* 대화 기록: 도구 호출 및 결과를 포함한 전체 기록입니다. 이전 프로세스가 종료될 때(예: 충돌) 여전히 실행 중이던 도구는 재개할 때 완료되거나 다시 실행되지 않습니다. [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars#variables)이 설정되지 않은 경우, Claude는 결과가 기록되기 전에 중단된 것으로 표시된 호출을 보게 되며 다시 실행하기 전에 효과가 있었는지 확인하도록 지시받습니다.54* 대화 기록: 메시지, 도구 호출 및 결과입니다. 세션이 [압축](/docs/ko/context-window#what-survives-compaction)된 경우 대화는 `Conversation compacted` 행에서 열립니다. Claude는 마지막 압축의 요약, 해당 압축이 요약하지 않고 남긴 메시지, 그리고 그 이후의 모든 메시지로 계속합니다. 마지막 압축이 요약한 메시지는 다시 로드되지 않습니다.

55* 중단된 도구 호출: 이전 프로세스가 종료될 때(예: 충돌) 여전히 실행 중이던 도구는 재개할 때 완료되거나 다시 실행되지 않습니다. [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars#variables)이 설정되지 않은 경우, Claude는 결과가 기록되기 전에 중단된 것으로 표시된 호출을 보게 되며 다시 실행하기 전에 효과가 있었는지 확인하도록 지시받습니다.

55* 모델: 세션은 사용 중이던 모델에서 계속됩니다. 단, [모델 설정](/docs/ko/model-config#setting-your-model)에 설명된 경우는 제외됩니다.56* 모델: 세션은 사용 중이던 모델에서 계속됩니다. 단, [모델 설정](/docs/ko/model-config#setting-your-model)에 설명된 경우는 제외됩니다.

56* 에이전트: [`--agent`](/docs/ko/sub-agents#invoke-subagents-explicitly) 또는 `agent` 설정으로 시작된 세션은 해당 에이전트로 계속되며 도구 제한 및 모델을 유지합니다. 재개할 때 `--agent`를 전달하여 다른 에이전트를 선택합니다. 두 경우 모두 시스템 프롬프트는 [재개된 대화의 시스템 프롬프트 플래그](/docs/ko/cli-reference#system-prompt-flags-in-resumed-conversations)를 참조하세요. Claude Code는 두 위치에서 에이전트를 찾습니다: 세션의 원본 디렉토리(해당 워크스페이스를 [신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)한 경우) 및 재개하는 디렉토리이므로 프로젝트 범위 에이전트는 다른 디렉토리에서 재개할 때도 로드됩니다. Claude Code가 두 위치 모두에서 에이전트를 찾지 못하면 세션은 기본 도구로 재개되고 [에이전트 이름을 지정하는 경고](/docs/ko/errors#session-agent-no-longer-available)를 표시합니다.57* 에이전트: [`--agent`](/docs/ko/sub-agents#invoke-subagents-explicitly) 또는 `agent` 설정으로 시작된 세션은 해당 에이전트로 계속되며 도구 제한 및 모델을 유지합니다. 재개할 때 `--agent`를 전달하여 다른 에이전트를 선택합니다. 두 경우 모두 시스템 프롬프트는 [재개된 대화의 시스템 프롬프트 플래그](/docs/ko/cli-reference#system-prompt-flags-in-resumed-conversations)를 참조하세요. Claude Code는 두 위치에서 에이전트를 찾습니다: 세션의 원본 디렉토리(해당 워크스페이스를 [신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)한 경우) 및 재개하는 디렉토리이므로 프로젝트 범위 에이전트는 다른 디렉토리에서 재개할 때도 로드됩니다. Claude Code가 두 위치 모두에서 에이전트를 찾지 못하면 세션은 기본 도구로 재개되고 [에이전트 이름을 지정하는 경고](/docs/ko/errors#session-agent-no-longer-available)를 표시합니다.

57* 권한 모드: 터미널에서 `claude --continue`, `claude --resume <session-id>` 또는 이름이 한 세션과 일치할 때 `-p` 없이 `claude --resume <name>`으로 재개하면 Claude Code는 세션이 있던 권한 모드를 복원합니다. 단, [재개 시 권한 모드](#permission-mode-on-resume)의 경우는 제외되며, 이는 세션 선택기, `/resume` 및 `claude -p`로 재개하는 경우도 포함합니다. `--permission-mode` 또는 `--dangerously-skip-permissions`를 전달하여 복원된 모드를 재정의합니다.58* 권한 모드: 터미널에서 `claude --continue`, `claude --resume <session-id>` 또는 이름이 한 세션과 일치할 때 `-p` 없이 `claude --resume <name>`으로 재개하면 Claude Code는 세션이 있던 권한 모드를 복원합니다. 단, [재개 시 권한 모드](#permission-mode-on-resume)의 경우는 제외되며, 이는 세션 선택기, `/resume` 및 `claude -p`로 재개하는 경우도 포함합니다. `--permission-mode` 또는 `--dangerously-skip-permissions`를 전달하여 복원된 모드를 재정의합니다.

163| 계획 수락 시 | [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서 계획을 수락하면 이미 이름을 지정하지 않은 경우 계획 내용에 따라 세션에 생성된 제목을 부여합니다 |164| 계획 수락 시 | [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서 계획을 수락하면 이미 이름을 지정하지 않은 경우 계획 내용에 따라 세션에 생성된 제목을 부여합니다 |

164| claude.ai 또는 Claude 앱에서 | [Remote Control 세션](/docs/ko/remote-control#connect-from-another-device)의 이름을 변경합니다. Claude Code는 CLI에서 동일한 이름을 적용합니다. Claude Code v2.1.221 이상이 필요합니다 |165| claude.ai 또는 Claude 앱에서 | [Remote Control 세션](/docs/ko/remote-control#connect-from-another-device)의 이름을 변경합니다. Claude Code는 CLI에서 동일한 이름을 적용합니다. Claude Code v2.1.221 이상이 필요합니다 |

165| 데스크톱 앱에서 | [데스크톱 앱](/docs/ko/desktop#work-in-parallel-with-sessions)에서 세션의 이름을 변경합니다 |166| 데스크톱 앱에서 | [데스크톱 앱](/docs/ko/desktop#organize-and-find-sessions)에서 세션의 이름을 변경합니다 |

166 167

167CLI 경로를 통해 또는 claude.ai에서 세션의 이름을 지정한 후 `claude --resume <name>` 또는 `/resume <name>`으로 돌아갑니다. 데스크톱 앱 세션은 [데스크톱 앱](/docs/ko/desktop#work-in-parallel-with-sessions)에서 재개됩니다. worktree 전체에서 이름 확인이 어떻게 작동하는지는 [세션 재개](#resume-a-session)를 참조합니다.168CLI 경로를 통해 또는 claude.ai에서 세션의 이름을 지정한 후 `claude --resume <name>` 또는 `/resume <name>`으로 돌아갑니다. 데스크톱 앱 세션은 [데스크톱 앱](/docs/ko/desktop#work-in-parallel-with-sessions)에서 재개됩니다. worktree 전체에서 이름 확인이 어떻게 작동하는지는 [세션 재개](#resume-a-session)를 참조합니다.

168 169

169이름을 지정하지 않은 세션도 Claude Code가 할당하는 두 가지 레이블을 받습니다. 생성된 제목만 재개 핸들로 작동합니다:170이름을 지정하지 않은 세션도 Claude Code가 할당하는 두 가지 레이블을 받습니다. 생성된 제목만 재개 핸들로 작동합니다:

170 171

171* 기본 표시 이름: 이름을 지정하지 않은 대화형 세션도 시작할 때 기본 표시 이름을 받습니다. Claude Code v2.1.196 이상이 필요합니다. 기본값은 작업 디렉터리의 이름과 두 문자 접미사를 결합합니다(예: `my-app-3f`). 이는 [에이전트 보기](/docs/ko/agent-view) 및 `claude agents --json` 출력과 같은 실행 중인 세션의 목록에서 세션을 식별합니다. 기본값은 재개 핸들이 아닙니다. `claude --resume` 또는 `/resume`에 전달하면 Claude Code는 세션을 찾지 못합니다.172* 기본 표시 이름: 이름을 지정하지 않은 대화형 세션도 시작할 때 기본 표시 이름을 받습니다. 기본값은 작업 디렉터리의 이름과 두 문자 접미사를 결합합니다(예: `my-app-3f`). 이는 [에이전트 보기](/docs/ko/agent-view) 및 `claude agents --json` 출력과 같은 실행 중인 세션의 목록에서 세션을 식별합니다. 기본값은 재개 핸들이 아닙니다. `claude --resume` 또는 `/resume`에 전달하면 Claude Code는 세션을 찾지 못합니다.

172* 생성된 제목: 세션의 이름을 지정하지 않으면 Claude Code는 세션 제목을 생성합니다. 제목은 첫 번째 프롬프트의 짧은 요약으로, 일반적으로 Haiku 클래스 모델인 소형/빠른 모델에 대한 백그라운드 요청으로 작성됩니다. 셸이나 스크립트에서 직접 시작한 `claude -p` 실행은 제목을 받지 않습니다.173* 생성된 제목: 세션의 이름을 지정하지 않으면 Claude Code는 세션 제목을 생성합니다. 제목은 첫 번째 프롬프트의 짧은 요약으로, 일반적으로 Haiku 클래스 모델인 소형/빠른 모델에 대한 백그라운드 요청으로 작성됩니다. 셸이나 스크립트에서 직접 시작한 `claude -p` 실행은 제목을 받지 않습니다.

173 174

174 계획을 수락하면 생성된 제목이 계획 기반 제목으로 바뀝니다. 두 제목 중 하나를 `claude --resume` 또는 `/resume`에 전달할 수 있으며, Claude Code는 설정한 이름과 동일한 방식으로 확인합니다.175 계획을 수락하면 생성된 제목이 계획 기반 제목으로 바뀝니다. 두 제목 중 하나를 `claude --resume` 또는 `/resume`에 전달할 수 있으며, Claude Code는 설정한 이름과 동일한 방식으로 확인합니다.

settings-reference.md +12 −5

Details

4096 `vimInsertModeRemaps`4096 `vimInsertModeRemaps`

4097</h3>4097</h3>

4098 4098

4099[vim 편집기 모드](/docs/ko/interactive-mode#vim-editor-mode)에서 두 키 INSERT 모드 시퀀스를 Escape로 매핑합니다. 각 키는 정확히 순서대로 입력된 두 개의 인쇄 가능한 문자이고, `"<Esc>"`는 유일하게 지원되는 대상입니다. Claude Code는 다른 항목을 무시합니다. Claude Code v2.1.208 이상이 필요합니다.4099[vim 편집기 모드](/docs/ko/interactive-mode#vim-editor-mode)에서 두 키로 이루어진 INSERT 모드 시퀀스를 Escape로 매핑합니다. 각 키는 순서대로 입력하는 정확히 두 개의 인쇄 가능한 문자이며, `"<Esc>"`만 유일하게 지원되는 대상입니다. Claude Code는 다른 항목을 무시합니다.

4100 4100

4101* **범위**: [`사용자 또는 관리됨`](#scopes). 저장소는 키 입력을 다시 매핑할 수 없습니다.4101* **범위**: [`사용자 또는 관리됨`](#scopes). 저장소는 키 입력을 다시 매핑할 수 없습니다.

4102* **유형**: 두 문자 시퀀스를 `"<Esc>"`로 매핑하는 객체4102* **유형**: 두 문자 시퀀스를 `"<Esc>"`로 매핑하는 객체

4110}4110}

4111```4111```

4112 4112

4113`editorMode`가 `"vim"`이 아니면 효과가 없습니다. [INSERT 모드 키 시퀀스 다시 매핑](/docs/ko/interactive-mode#remap-insert-mode-key-sequences)을 참조하세요. Claude Code v2.1.208 이상이 필요합니다.4113`editorMode`가 `"vim"`이 아니면 효과가 없습니다. [INSERT 모드 키 시퀀스 다시 매핑](/docs/ko/interactive-mode#remap-insert-mode-key-sequences)을 참조하세요.

4114 4114

4115<h3 id="voice">4115<h3 id="voice">

4116 `voice`4116 `voice`

5850 `disableDesktopLocalSessions`5850 `disableDesktopLocalSessions`

5851</h3>5851</h3>

5852 5852

5853개발자가 SSH를 통해 원격 머신에서 작업해야 하는 배포의 경우 [데스크톱 앱](/docs/ko/desktop#local-sessions-on-managed-devices)에서 실행되는 Code 세션을 끕니다. Code 탭에서 **Local** 환경은 환경 드롭다운에 남아 있지만 회색으로 표시되고 선택할 수 없으며, 조직이 이를 끄도록 했다는 도구 설명이 표시됩니다. Windows에서는 WSL 항목도 같은 방식으로 회색으로 표시되지만, WSL 세션이 관리되는 디바이스에서 실행되는지 여부는 [별도로 관리됩니다](/docs/ko/admin-setup#wsl-sessions-in-claude-code-desktop). 새 세션은 구성된 첫 번째 [SSH 연결](/docs/ko/desktop#ssh-sessions)로 기본 설정되며, 앱은 디바이스에서 세션을 시작하거나 재개하기를 거부합니다(같은 머신으로의 SSH 연결 포함). 다른 호스트로의 SSH 세션 및 클라우드 세션은 영향을 받지 않습니다. 데스크톱 앱은 이 키를 읽습니다. 터미널 CLI는 무시합니다. Claude Desktop v1.37937.0 이상이 필요합니다.5853개발자가 SSH를 통해 원격 머신에서 작업해야 하는 배포의 경우 [데스크톱 앱](/docs/ko/desktop#local-sessions-on-managed-devices)에서 디바이스에서 실행되는 Code 세션을 끕니다. 키를 `true`로 설정하면 사용자는 Code 탭에서 다음과 같이 보게 됩니다:

5854

5855* **환경 선택기**: 사용자 컴퓨터 항목이 회색으로 표시되고 선택할 수 없으며, **Disabled by your organization**이라는 도구 설명이 표시됩니다. Windows에서는 WSL 항목도 같은 방식으로 회색으로 표시되지만, WSL 세션이 관리되는 디바이스에서 실행되는지 여부는 [별도로 관리됩니다](/docs/ko/admin-setup#wsl-sessions-in-claude-code-desktop).

5856* **새 세션**: [SSH 연결](/docs/ko/desktop#ssh-sessions)이 구성되어 있으면 첫 번째 SSH 연결로 기본 설정됩니다

5857* **디바이스의 세션**: 앱은 디바이스에서 세션을 시작하거나 재개하기를 거부하며, 같은 머신으로 다시 연결하는 SSH 연결도 이에 포함됩니다

5858* **다른 호스트로의 SSH 세션 및 클라우드 세션**: 영향을 받지 않습니다

5859

5860데스크톱 앱은 이 키를 읽습니다. 터미널 CLI는 무시합니다. Claude Desktop v1.37937.0 이상이 필요합니다.

5854 5861

5855* **범위**: [`Managed`](#scopes). 기본적으로 데스크톱 앱은 [하나의 관리형 소스](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)에서 이 키를 읽습니다.5862* **범위**: [`Managed`](#scopes). 기본적으로 데스크톱 앱은 [하나의 관리형 소스](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)에서 이 키를 읽습니다.

5856* **유형**: Boolean; JSON Boolean `true`만 적용됩니다5863* **유형**: Boolean; JSON Boolean `true`만 적용됩니다

5997 `sshConfigs`6004 `sshConfigs`

5998</h3>6005</h3>

5999 6006

6000[Desktop](/docs/ko/desktop#pre-configure-ssh-connections-for-your-team) 환경 드롭다운에 SSH 연결을 추가합니다. 관리자는 이를 사용하여 팀에 공유 연결을 배포합니다. 관리형 설정에서 정의한 연결은 관리됨으로 표시됩니다. 사용자는 이를 선택하고 해당 연결에 대해 [자신의 **Worktree 폴더**를 설정](/docs/ko/desktop#choose-where-ssh-session-worktrees-go)할 수 있지만, 앱에서 그 밖의 항목을 편집하거나 연결을 삭제할 수는 없습니다.6007[Desktop](/docs/ko/desktop#pre-configure-ssh-connections-for-your-team) 환경 선택기에 SSH 연결을 추가합니다. 관리자는 `sshConfigs`를 사용하여 팀에 공유 연결을 배포합니다. 사용자는 관리되는 연결을 선택하고 해당 연결에 대해 [자신의 **Worktree 폴더**를 설정](/docs/ko/desktop#set-the-worktree-folder-on-an-existing-connection)할 수 있습니다. 앱에서 그 밖의 필드를 편집하거나 연결을 삭제할 수는 없습니다.

6001 6008

6002* **범위**: [`User or managed`](#scopes). 데스크톱 앱은 이 키를 읽습니다. 기본적으로 [하나의 관리형 소스](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)에서 관리되는 연결을 읽습니다.6009* **범위**: [`User or managed`](#scopes). 데스크톱 앱은 이 키를 읽습니다. 기본적으로 [하나의 관리형 소스](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)에서 관리되는 연결을 읽습니다.

6003* **유형**: 필수 `id`, `name` 및 `sshHost`와 선택적 `sshPort` 및 `sshIdentityFile`을 포함하는 객체 배열6010* **유형**: 필수 `id`, `name` 및 `sshHost`와 선택적 `sshPort` 및 `sshIdentityFile`을 포함하는 객체 배열

statusline.md +2 −2

Details

200| `workspace.git_worktree` | `git worktree add`로 생성된 연결된 worktree 내에 현재 디렉터리가 있을 때의 Git worktree 이름입니다. 주 작업 트리에는 없습니다. 모든 git worktree에 대해 채워지며, `worktree.*`와 달리 [worktree 세션](/docs/ko/worktrees) 중에만 존재합니다. |200| `workspace.git_worktree` | `git worktree add`로 생성된 연결된 worktree 내에 현재 디렉터리가 있을 때의 Git worktree 이름입니다. 주 작업 트리에는 없습니다. 모든 git worktree에 대해 채워지며, `worktree.*`와 달리 [worktree 세션](/docs/ko/worktrees) 중에만 존재합니다. |

201| `workspace.repo.host`, `workspace.repo.owner`, `workspace.repo.name` | `origin` 원격에서 파싱된 저장소 ID입니다. 예를 들어 `"github.com"`, `"anthropics"`, `"claude-code"`입니다. Git 저장소 외부에 있거나 `origin` 원격이 구성되지 않은 경우 없습니다. GitLab.com 프로젝트가 하위 그룹에 중첩된 경우, `owner`는 `"group/subgroup"`과 같이 슬래시가 있는 전체 네임스페이스 경로입니다. v2.1.260 이전에는 이러한 프로젝트에 대해 `workspace.repo`가 없었습니다. |201| `workspace.repo.host`, `workspace.repo.owner`, `workspace.repo.name` | `origin` 원격에서 파싱된 저장소 ID입니다. 예를 들어 `"github.com"`, `"anthropics"`, `"claude-code"`입니다. Git 저장소 외부에 있거나 `origin` 원격이 구성되지 않은 경우 없습니다. GitLab.com 프로젝트가 하위 그룹에 중첩된 경우, `owner`는 `"group/subgroup"`과 같이 슬래시가 있는 전체 네임스페이스 경로입니다. v2.1.260 이전에는 이러한 프로젝트에 대해 `workspace.repo`가 없었습니다. |

202| `cost.total_cost_usd` | USD로 계산된 예상 세션 비용이며, [`modelPricing`](/docs/ko/settings-reference#modelpricing) 테이블이 적용되지 않는 한 정가 기준으로 클라이언트 측에서 계산됩니다. 실제 청구액과 다를 수 있습니다. `/clear`가 새 세션을 시작할 때 \$0으로 재설정됩니다. v2.1.211 이전에는 `/clear` 후에도 합계가 유지되었습니다. |202| `cost.total_cost_usd` | USD로 계산된 예상 세션 비용이며, [`modelPricing`](/docs/ko/settings-reference#modelpricing) 테이블이 적용되지 않는 한 정가 기준으로 클라이언트 측에서 계산됩니다. 실제 청구액과 다를 수 있습니다. `/clear`가 새 세션을 시작할 때 \$0으로 재설정됩니다. |

1201| `effort` | string 또는 number, 선택 사항 | 서브에이전트의 [정의 frontmatter](/docs/ko/sub-agents#supported-frontmatter-fields) 또는 개별 호출에서 설정된 추론 effort로, `low`, `medium`, `high`, `xhigh`, `max` 또는 숫자 토큰 예산입니다. 이는 구성된 값이며, 모델이 해당 수준을 지원하지 않으면 Claude Code가 실제로 적용하는 effort가 다를 수 있습니다. effort가 설정되지 않으면 생략됩니다. Claude Code v2.1.213 이상이 필요합니다 |1201| `effort` | string 또는 number, 선택 사항 | 서브에이전트의 [정의 frontmatter](/docs/ko/sub-agents#supported-frontmatter-fields) 또는 개별 호출에서 설정된 추론 effort로, `low`, `medium`, `high`, `xhigh`, `max` 또는 숫자 토큰 예산입니다. 이는 구성된 값이며, 모델이 해당 수준을 지원하지 않으면 Claude Code가 실제로 적용하는 effort가 다를 수 있습니다. effort가 설정되지 않으면 생략됩니다 |

1202| `contextWindowSize` | number, 선택 사항 | `model`의 컨텍스트 윈도우(토큰 단위)로, 메인 상태줄의 [`context_window.context_window_size`](#context-window-fields)와 동일한 방식으로 계산되므로 `tokenCount`에서 행별 백분율을 렌더링할 수 있습니다. `model`이 생략되면 함께 생략됩니다 |1202| `contextWindowSize` | number, 선택 사항 | `model`의 컨텍스트 윈도우(토큰 단위)로, 메인 상태줄의 [`context_window.context_window_size`](#context-window-fields)와 동일한 방식으로 계산되므로 `tokenCount`에서 행별 백분율을 렌더링할 수 있습니다. `model`이 생략되면 함께 생략됩니다 |

sub-agents.md +53 −35

Details

287 287

288`isolation: worktree`를 가진 서브에이전트는 해당 worktree 내에서 Bash 및 PowerShell 명령을 실행합니다. 작업 디렉터리가 주 체크아웃으로 확인되는 명령(예: worktree 디렉터리가 서브에이전트 실행 중에 제거된 경우)은 오류로 실패합니다.288`isolation: worktree`를 가진 서브에이전트는 해당 worktree 내에서 Bash 및 PowerShell 명령을 실행합니다. 작업 디렉터리가 주 체크아웃으로 확인되는 명령(예: worktree 디렉터리가 서브에이전트 실행 중에 제거된 경우)은 오류로 실패합니다.

289 289

290이 작업 디렉토리 확인은 Claude Code를 시작한 디렉토리를 포함하는 전체 저장소를 다룹니다. 세션이 자체 링크된 [worktree](/docs/ko/worktrees)에서 실행될 때, 확인은 해당 worktree가 링크된 주 체크아웃도 다룹니다. v2.1.210 이전에는 확인이 시작 디렉토리 자체만 다루었습니다. 작업 디렉토리가 같은 저장소의 다른 곳(예: 모노레포 하위 디렉토리에서 Claude Code를 시작했을 때 저장소 루트)으로 확인되는 명령은 실패하지 않고 거기서 실행되었습니다.290이 작업 디렉터리 확인은 Claude Code를 시작한 디렉터리를 포함하는 전체 저장소를 다룹니다. 세션이 자체 링크된 [worktree](/docs/ko/worktrees)에서 실행될 때, 확인은 해당 worktree가 링크된 주 체크아웃도 다룹니다.

291 291

292Bash 명령의 경우, Claude Code는 두 가지 방식으로 명령 자체도 확인합니다:292Bash 명령의 경우, Claude Code는 두 가지 방식으로 명령 자체도 확인합니다:

293 293

325| `mcpServers` | 아니오 | 이 서브에이전트가 사용할 수 있는 [MCP 서버](/docs/ko/mcp). 각 항목은 이미 구성된 서버를 참조하는 서버 이름(예: `"slack"`) 또는 서버 이름을 키로 하고 전체 [MCP 서버 구성](/docs/ko/mcp#installing-mcp-servers)을 값으로 하는 인라인 정의입니다. [플러그인 서브에이전트](#choose-the-subagent-scope)에서 무시됩니다 |325| `mcpServers` | 아니오 | 이 서브에이전트가 사용할 수 있는 [MCP 서버](/docs/ko/mcp). 각 항목은 이미 구성된 서버를 참조하는 서버 이름(예: `"slack"`) 또는 서버 이름을 키로 하고 전체 [MCP 서버 구성](/docs/ko/mcp#installing-mcp-servers)을 값으로 하는 인라인 정의입니다. [플러그인 서브에이전트](#choose-the-subagent-scope)에서 무시됩니다 |

326| `hooks` | 아니오 | 이 서브에이전트로 범위가 지정된 [라이프사이클 훅](#define-hooks-for-subagents). [플러그인 서브에이전트](#choose-the-subagent-scope)에서 무시됩니다 |326| `hooks` | 아니오 | 이 서브에이전트로 범위가 지정된 [라이프사이클 훅](#define-hooks-for-subagents). [플러그인 서브에이전트](#choose-the-subagent-scope)에서 무시됩니다 |

327| `memory` | 아니오 | [지속적 메모리 범위](#enable-persistent-memory): `user`, `project`, 또는 `local`. 세션 간 학습을 활성화합니다 |327| `memory` | 아니오 | [지속적 메모리 범위](#enable-persistent-memory): `user`, `project`, 또는 `local`. 세션 간 학습을 활성화합니다 |

328| `background` | 아니오 | Claude가 포그라운드에서 실행하도록 요청할 때도 이 서브에이전트를 백그라운드에 유지하려면 `true`로 설정하세요. [포크 모드](#turn-fork-mode-on-or-off)가 켜져 있으면, Claude Code는 Claude가 생성하는 서브에이전트를 이미 [백그라운드에서 실행합니다](#run-subagents-in-foreground-or-background) |328| `background` | 아니오 | Claude가 이 서브에이전트를 기다리도록 요청할 때도 백그라운드에 유지하려면 `true`로 설정하세요. 기본적으로 Claude가 주 대화에서 생성하는 서브에이전트는 이미 [백그라운드에서 시작됩니다](#run-subagents-in-foreground-or-background) |

329| `omitClaudeMd` | 아니오 | 이 서브에이전트를 [초기 컨텍스트](#what-loads-at-startup)에 사용자, 프로젝트, 및 로컬 CLAUDE.md 파일 없이 시작하려면 `true`로 설정하세요. [관리형 정책 파일](/docs/ko/memory#how-claude-md-files-load)은 여전히 로드되지만, [관리형 서브에이전트](#choose-the-subagent-scope)는 예외입니다. 위임 프롬프트에서 필요한 모든 것을 가져오는 서브에이전트에 사용하세요. 에이전트가 `--agent` 또는 `agent` 설정을 통해 주 세션 에이전트로 실행될 때는 무시됩니다. Claude Code v2.1.271 이상이 필요합니다 |329| `omitClaudeMd` | 아니오 | 이 서브에이전트를 [초기 컨텍스트](#what-loads-at-startup)에 사용자, 프로젝트, 및 로컬 CLAUDE.md 파일 없이 시작하려면 `true`로 설정하세요. [관리형 정책 파일](/docs/ko/memory#how-claude-md-files-load)은 여전히 로드되지만, [관리형 서브에이전트](#choose-the-subagent-scope)는 예외입니다. 위임 프롬프트에서 필요한 모든 것을 가져오는 서브에이전트에 사용하세요. 에이전트가 `--agent` 또는 `agent` 설정을 통해 주 세션 에이전트로 실행될 때는 무시됩니다. Claude Code v2.1.271 이상이 필요합니다 |

330| `effort` | 아니오 | 이 서브에이전트가 활성화되어 있을 때의 effort 수준입니다. 세션 effort 수준을 재정의하지만, [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/ko/env-vars#variables) 환경 변수는 재정의하지 않습니다. 옵션: `low`, `medium`, `high`, `xhigh`, `max`. 사용 가능한 수준은 모델에 따라 다릅니다. [effort 수준 선택](#choose-an-effort-level)을 참조하세요 |330| `effort` | 아니오 | 이 서브에이전트가 활성화되어 있을 때의 effort 수준입니다. 세션 effort 수준을 재정의하지만, [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/ko/env-vars#variables) 환경 변수는 재정의하지 않습니다. 옵션: `low`, `medium`, `high`, `xhigh`, `max`. 사용 가능한 수준은 모델에 따라 다릅니다. [effort 수준 선택](#choose-an-effort-level)을 참조하세요 |

331| `isolation` | 아니오 | 서브에이전트를 임시 [git worktree](/docs/ko/worktrees)에서 실행하려면 `worktree`로 설정하여 저장소의 격리된 복사본을 제공합니다. 기본적으로 부모 세션의 `HEAD`가 아닌 [기본 분기](/docs/ko/worktrees#choose-the-base-branch)에서 분기됩니다. worktree는 서브에이전트가 변경을 하지 않으면 자동으로 정리됩니다 |331| `isolation` | 아니오 | 서브에이전트를 임시 [git worktree](/docs/ko/worktrees)에서 실행하려면 `worktree`로 설정하여 저장소의 격리된 복사본을 제공합니다. 기본적으로 부모 세션의 `HEAD`가 아닌 [기본 분기](/docs/ko/worktrees#choose-the-base-branch)에서 분기됩니다. worktree는 서브에이전트가 변경을 하지 않으면 자동으로 정리됩니다 |

405 405

406서브에이전트가 실행 중인 모델을 확인하려면 [`/tasks`](/docs/ko/commands)를 실행하세요. Claude Code는 서브에이전트의 행에 모델을 표시하며, 해당 서브에이전트에 설정된 [effort 수준](/docs/ko/model-config#adjust-effort-level)이 있으면 함께 표시합니다. Claude Code v2.1.242 이상이 필요합니다.406서브에이전트가 실행 중인 모델을 확인하려면 [`/tasks`](/docs/ko/commands)를 실행하세요. Claude Code는 서브에이전트의 행에 모델을 표시하며, 해당 서브에이전트에 설정된 [effort 수준](/docs/ko/model-config#adjust-effort-level)이 있으면 함께 표시합니다. Claude Code v2.1.242 이상이 필요합니다.

407 407

408호출별 `model` 매개변수는 서브에이전트가 [재개되거나 후속 메시지를 받을](#resume-subagents) 때도 적용되므로 서브에이전트는 해당 모델에 머물러 있습니다. v2.1.211 이전에는 재개가 호출별 값을 떨어뜨렸고 서브에이전트는 정의의 `model` 필드로 되돌아가거나, 없으면 주 대화의 모델로 되돌아갔습니다.408호출별 `model` 매개변수는 서브에이전트가 [재개되거나 후속 메시지를 받을](#resume-subagents) 때도 적용되므로 서브에이전트는 해당 모델에 머물러 있습니다.

409 409

410v2.1.198부터, 서브에이전트는 주 대화의 [확장 사고](/docs/ko/model-config#extended-thinking) 구성도 상속합니다. 세션에서 사고가 켜져 있으면 서브에이전트에서도 켜져 있고, 꺼져 있으면 꺼져 있습니다. 서브에이전트별 사고 설정은 없습니다. v2.1.198 이전에는 서브에이전트가 주 대화의 설정과 관계없이 확장 사고가 비활성화된 상태로 실행되었습니다.410v2.1.198부터, 서브에이전트는 주 대화의 [확장 사고](/docs/ko/model-config#extended-thinking) 구성도 상속합니다. 세션에서 사고가 켜져 있으면 서브에이전트에서도 켜져 있고, 꺼져 있으면 꺼져 있습니다. 서브에이전트별 사고 설정은 없습니다. v2.1.198 이전에는 서브에이전트가 주 대화의 설정과 관계없이 확장 사고가 비활성화된 상태로 실행되었습니다.

411 411

501---501---

502```502```

503 503

504`tools` 목록의 아무것도 도구로 확인되지 않을 때(예: 모든 항목이 철자가 틀렸거나 서브에이전트가 사용할 수 없는 도구를 이름 지을 때), Claude Code는 일반적으로 서브에이전트 시작을 거부하고 Agent 도구는 확인되지 않은 항목을 이름 지정하는 오류를 반환합니다. [에이전트가 0개 도구로 생성될 것입니다](/docs/ko/errors#agent-would-be-spawned-with-zero-tools)를 참조하여 메시지와 각 항목을 수정하는 방법을 확인하세요. v2.1.208 이전에는 해당 서브에이전트가 도구 없이 시작되고 빈 또는 혼란스러운 결과를 반환할 수 있었습니다.504`tools` 목록의 어떤 항목도 도구로 확인되지 않을 때(예: 모든 항목의 철자가 틀렸거나 서브에이전트가 사용할 수 없는 도구를 지정할 때), Claude Code는 일반적으로 서브에이전트 시작을 거부하고 Agent 도구는 확인되지 않은 항목을 명시하는 오류를 반환합니다. 메시지와 각 항목을 수정하는 방법은 [Agent would be spawned with zero tools](/docs/ko/errors#agent-would-be-spawned-with-zero-tools)를 참조하세요.

505 505

506`tools` 및 `disallowedTools` 필드는 MCP 서버 전체에 대한 항목도 허용합니다:506`tools` 및 `disallowedTools` 필드는 MCP 서버 전체에 대한 항목도 허용합니다:

507 507

969* **포그라운드 서브에이전트**는 완료될 때까지 메인 대화를 차단합니다. 권한 프롬프트는 나타나는 대로 전달됩니다.969* **포그라운드 서브에이전트**는 완료될 때까지 메인 대화를 차단합니다. 권한 프롬프트는 나타나는 대로 전달됩니다.

970* **백그라운드 서브에이전트**는 계속 작업하는 동안 동시에 실행됩니다. 백그라운드 서브에이전트가 권한이 필요한 도구 호출에 도달하면 Claude Code는 메인 세션에서 프롬프트를 표시하고 요청하는 서브에이전트의 이름을 지정합니다. 승인하여 서브에이전트를 계속하거나 Esc를 눌러 해당 도구 호출 하나를 거부하되 서브에이전트는 중지하지 않습니다.970* **백그라운드 서브에이전트**는 계속 작업하는 동안 동시에 실행됩니다. 백그라운드 서브에이전트가 권한이 필요한 도구 호출에 도달하면 Claude Code는 메인 세션에서 프롬프트를 표시하고 요청하는 서브에이전트의 이름을 지정합니다. 승인하여 서브에이전트를 계속하거나 Esc를 눌러 해당 도구 호출 하나를 거부하되 서브에이전트는 중지하지 않습니다.

971 971

972Claude가 Agent 도구로 생성하는 각 서브에이전트에 대해 Claude Code는 적용되는 첫 번째 경우에서 포그라운드 또는 백그라운드를 선택합니다.972<h4 id="which-subagents-run-in-the-background">

973 백그라운드에서 실행되는 서브에이전트

974</h4>

975

976아무것도 구성하지 않은 경우, Claude가 메인 대화에서 생성하는 서브에이전트는 백그라운드에서 시작됩니다.

973 977

974* 진행 중인 [에이전트 팀](/docs/ko/agent-teams#limitations) 팀원이 서브에이전트를 생성한 경우 Claude Code는 포그라운드에서 실행합니다. Claude Code는 정의가 [`background: true`](#supported-frontmatter-fields)를 설정하는 팀원의 서브에이전트를 생성하기를 거부하고 오류를 표시합니다. [포크 모드](#turn-fork-mode-on-or-off)가 꺼져 있고 [백그라운드 작업을 끄지 않은](/docs/ko/env-vars) 경우 Claude Code는 팀원이 `run_in_background: true`를 설정할 때도 오류를 표시하며 거부합니다.978* **`claude -p` 및 Agent SDK**: Claude는 자체 판단에 따라 또는 사용자가 요청할 때 기다릴 수 있습니다.

975* [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/ko/env-vars)를 `1`로 설정하면 Claude Code는 모든 종류의 세션에서 포그라운드에서 서브에이전트를 실행하며 포크 모드가 켜져 있는지 여부와 관계없이 실행합니다.979* **로컬 머신의 대화형 터미널 세션, VS Code 및 데스크톱 앱 세션**: Claude가 서브에이전트를 기다리도록 하려면 [기본적으로 켜져 있는](#turn-fork-mode-on-or-off) [포크 모드를 끄십시오](#let-claude-wait-for-a-subagent).

976* [포크 모드](#turn-fork-mode-on-or-off)가 켜져 있으면(대화형 세션에서 기본값) Claude Code는 포크 및 비포크 서브에이전트 모두 백그라운드에서 실행하며 Claude는 포그라운드를 요청할 수 없습니다.

977* 포크 모드가 꺼져 있으면 Claude는 기본적으로 서브에이전트를 백그라운드에서 실행하고 결과가 필요할 때 포그라운드에서 실행합니다. 포크 모드는 `-p`를 사용한 [비대화형 모드](/docs/ko/headless)에서 꺼져 있으며 Agent SDK에서도 꺼져 있습니다(켜지 않으면). 특정 서브에이전트를 Claude가 결과를 원할 때도 백그라운드에 유지하려면 frontmatter [`background`](#supported-frontmatter-fields) 필드를 `true`로 설정합니다.

978 980

979`context: fork`를 가진 스킬의 경우 Claude Code는 포크 모드가 켜져 있는지 여부와 관계없이 [서브에이전트에서 스킬 실행](/docs/ko/skills#run-skills-in-a-subagent)의 규칙을 따릅니다.981`context: fork`를 가진 스킬의 경우 Claude Code는 포크 모드가 켜져 있는지 여부와 관계없이 [서브에이전트에서 스킬 실행](/docs/ko/skills#run-skills-in-a-subagent)의 규칙을 따릅니다.

980 982

983<h4 id="let-claude-wait-for-a-subagent">

984 Claude가 서브에이전트를 기다리도록 하기

985</h4>

986

9871. `CLAUDE_CODE_FORK_SUBAGENT`를 `0`으로 설정하여 [포크 모드](#turn-fork-mode-on-or-off)를 끕니다. 예를 들어 [`settings.json`](/docs/ko/settings)에서 다음과 같이 설정합니다.

988

989 ```json theme={null}

990 {

991 "env": {

992 "CLAUDE_CODE_FORK_SUBAGENT": "0"

993 }

994 }

995 ```

996

9972. 셸에서 `claude`를 다시 실행하거나 새 VS Code 대화를 엽니다.

998

9993. 결과가 먼저 필요할 때 Claude에 기다리도록 요청합니다. 예: "run the reviewer subagent and wait for its report".

1000

1001Claude가 기다리는 동안 계속 작업하려면 터미널에서 **Ctrl+B**를 누르거나 VS Code에서 [**Run in background**](/docs/ko/vs-code#move-a-running-command-or-subagent-to-the-background)를 클릭합니다.

1002

1003포크 모드를 끄는 대신 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/ko/env-vars) 환경 변수를 `1`로 설정하면 Claude는 모든 서브에이전트를 기다리며 **Ctrl+B**를 포함한 백그라운드 작업이 꺼집니다.

1004

1005<h4 id="tools-permissions-and-results-of-background-subagents">

1006 백그라운드 서브에이전트의 도구, 권한 및 결과

1007</h4>

1008

981백그라운드 서브에이전트는 대화 포크 및 [재개된](#resume-subagents) 포그라운드 서브에이전트를 제외하고 포그라운드 서브에이전트보다 [더 작은 기본 제공 도구 세트](#available-tools)로 실행됩니다.1009백그라운드 서브에이전트는 대화 포크 및 [재개된](#resume-subagents) 포그라운드 서브에이전트를 제외하고 포그라운드 서브에이전트보다 [더 작은 기본 제공 도구 세트](#available-tools)로 실행됩니다.

982 1010

983백그라운드 서브에이전트는 메인 세션에서 모든 권한 프롬프트를 표시합니다. 해당 도구 호출 하나를 초과하여 지속되는 선택(예: 세션의 나머지 기간 동안 지속되는 권한 부여)으로 프롬프트 중 하나에 답하면 Claude Code는 메인 대화를 포함한 전체 세션에 답변을 적용합니다.1011백그라운드 서브에이전트는 메인 세션에서 모든 권한 프롬프트를 표시합니다. 해당 도구 호출 하나를 초과하여 지속되는 선택(예: 세션의 나머지 기간 동안 지속되는 권한 부여)으로 프롬프트 중 하나에 답하면 Claude Code는 메인 대화를 포함한 전체 세션에 답변을 적용합니다.

984 1012

985백그라운드 서브에이전트는 백그라운드 [Bash 또는 PowerShell 명령](/docs/ko/tools-reference#background-commands)을 [해당 턴의 끝을 넘어 실행](/docs/ko/interactive-mode#how-backgrounding-works)할 수 있습니다. 해당 명령이 끝나면 Claude Code는 서브에이전트에 알림을 보냅니다.1013백그라운드 서브에이전트는 백그라운드 [Bash 또는 PowerShell 명령](/docs/ko/tools-reference#background-commands)을 [해당 턴의 끝을 넘어 실행](/docs/ko/interactive-mode#how-backgrounding-works)할 수 있습니다. 해당 명령이 끝나면 Claude Code는 서브에이전트에 알림을 보냅니다.

986 1014

987백그라운드 서브에이전트의 결과는 나중 턴의 완료 알림으로 Claude에 도달합니다. Claude는 해당 알림을 기다린 후 서브에이전트의 결과를 보고하며, 먼저 진행 상황을 묻는 경우 서브에이전트가 여전히 실행 중임을 보고합니다. v2.1.211 이전에는 Claude가 완료되지 않은 백그라운드 서브에이전트의 결과를 보고하기도 했습니다.1015백그라운드 서브에이전트의 결과는 나중 턴의 완료 알림으로 Claude에 도달합니다. Claude는 해당 알림을 기다린 후 서브에이전트의 결과를 보고하며, 먼저 진행 상황을 묻는 경우 서브에이전트가 여전히 실행 중임을 보고합니다.

988 1016

989이를 직접 제어할 수도 있습니다.1017<h4 id="finished-subagents-in-the-panel-and-task-list">

~~990~~ 1018 패널 및 작업 목록의 완료된 서브에이전트

991* 포크 모드가 꺼져 있으면 Claude에 작업을 백그라운드 또는 포그라운드에서 실행하도록 요청합니다.1019</h4>

992* **Ctrl+B**를 눌러 실행 중인 작업을 백그라운드로 이동합니다.

993 1020

994Claude Code는 서브에이전트가 끝난 방식에 따라 두 가지 방법 중 하나로 프롬프트 입력 아래의 서브에이전트 패널에서 백그라운드 서브에이전트의 행을 지웁니다.1021Claude Code는 서브에이전트가 끝난 방식에 따라 두 가지 방법 중 하나로 프롬프트 입력 아래의 서브에이전트 패널에서 백그라운드 서브에이전트의 행을 지웁니다.

995 1022

1036 1063

1037[백그라운드 서브에이전트의 보고서](#run-subagents-in-foreground-or-background)는 자동화된 이벤트로 표시되는 완료 알림 내에 도착하며 사용자로부터의 메시지가 아닙니다.1064[백그라운드 서브에이전트의 보고서](#run-subagents-in-foreground-or-background)는 자동화된 이벤트로 표시되는 완료 알림 내에 도착하며 사용자로부터의 메시지가 아닙니다.

1038 1065

1039<Note>

1040 서브에이전트 출력 스캔에는 Claude Code v2.1.210 이상이 필요합니다.

1041</Note>

~~1042~~

1043<h3 id="common-patterns">1066<h3 id="common-patterns">

1044 일반적인 패턴1067 일반적인 패턴

1045</h3>1068</h3>

1109 1132

1110기본적으로 서브에이전트는 메인 대화 아래로 최대 3개 계층까지 자신의 서브에이전트를 생성할 수 있습니다. 깊이 제한에서 Claude Code는 [포크](#fork-the-current-conversation)를 제외한 모든 서브에이전트에서 `Agent` 도구를 보류하므로 제한에 있는 서브에이전트는 위임된 작업을 자체적으로 수행하고 하나의 요약을 반환합니다. 제한에 있는 포크는 상속된 도구 목록에서 `Agent`를 유지하지만 도구는 생성하는 대신 오류를 반환합니다.1133기본적으로 서브에이전트는 메인 대화 아래로 최대 3개 계층까지 자신의 서브에이전트를 생성할 수 있습니다. 깊이 제한에서 Claude Code는 [포크](#fork-the-current-conversation)를 제외한 모든 서브에이전트에서 `Agent` 도구를 보류하므로 제한에 있는 서브에이전트는 위임된 작업을 자체적으로 수행하고 하나의 요약을 반환합니다. 제한에 있는 포크는 상속된 도구 목록에서 `Agent`를 유지하지만 도구는 생성하는 대신 오류를 반환합니다.

1111 1134

1112중첩된 서브에이전트는 자체적으로 병렬 부작업으로 분할되는 위임된 작업에 적합합니다. 예를 들어 검토자 서브에이전트가 발견 사항당 검증자를 발송합니다. 대화형 세션에서는 최상위 서브에이전트의 요약만 반환되고 중간 출력은 메인 대화에서 벗어납니다. 백그라운드 서브에이전트를 시작하는 서브에이전트는 완료될 때까지 기다립니다. [비대화형 모드](/docs/ko/headless) 및 Agent SDK에서 시작 서브에이전트는 기다리지 않으므로 시작자가 종료된 후 완료되는 중첩된 백그라운드 서브에이전트는 메인 대화로 보고합니다.1135중첩된 서브에이전트는 자체적으로 병렬 부작업으로 분할되는 위임된 작업에 적합합니다. 예를 들어 검토자 서브에이전트가 발견 사항당 검증자를 발송합니다. 기본적으로 생성하는 서브에이전트는 각 중첩된 서브에이전트의 보고서를 기다립니다.

1136

1137* **대화형 터미널 세션**: 백그라운드 서브에이전트를 시작하는 서브에이전트는 완료하기 전에 그 결과를 기다리므로 최상위 서브에이전트의 요약만 사용자에게 반환됩니다.

1138* **`claude -p` 및 Agent SDK**: [포크 모드](#turn-fork-mode-on-or-off)가 켜져 있는 동안 생성하는 서브에이전트는 기다립니다. 포크 모드를 끄면 중첩된 서브에이전트는 대신 [백그라운드](#run-subagents-in-foreground-or-background)에서 시작됩니다. 생성하는 서브에이전트는 백그라운드 중첩 서브에이전트를 기다리지 않으며, 중첩 서브에이전트가 생성한 서브에이전트보다 오래 실행되면 메인 대화로 보고합니다.

1113 1139

1114제한을 변경하려면 [`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`](/docs/ko/env-vars)를 메인 대화 아래에 원하는 서브에이전트 계층 수로 설정합니다. 예를 들어 [`settings.json`](/docs/ko/settings)의 이 항목은 중첩을 2개 계층으로 제한합니다.1140제한을 변경하려면 [`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`](/docs/ko/env-vars)를 메인 대화 아래에 원하는 서브에이전트 계층 수로 설정합니다. 예를 들어 [`settings.json`](/docs/ko/settings)의 이 항목은 중첩을 2개 계층으로 제한합니다.

1115 1141

1277</h2>1303</h2>

1278 1304

1279<Note>1305<Note>

1280 `/subtask`로 포크된 subagent를 실행합니다. 이는 Claude Code v2.1.212 이상이 필요합니다. [에이전트 보기가 꺼져 있을 때](/docs/ko/agent-view#turn-off-agent-view), `/subtask`는 사용할 수 없으며 `/fork`가 포크된 subagent를 대신 시작합니다. 그렇지 않으면 `/fork`는 전체 세션을 새로운 [background 세션](/docs/ko/agent-view#from-inside-a-session)으로 복사합니다.1306 [에이전트 보기가 꺼져 있을 때](/docs/ko/agent-view#turn-off-agent-view), `/subtask`는 사용할 수 없으며 `/fork`가 포크된 서브에이전트를 대신 시작합니다. 그렇지 않으면 `/fork`는 전체 세션을 새로운 [background 세션](/docs/ko/agent-view#from-inside-a-session)으로 복사합니다.

1281</Note>1307</Note>

1282 1308

1283포크는 새로 시작하는 대신 지금까지의 전체 대화를 상속하는 subagent입니다. 이렇게 하면 subagent가 일반적으로 제공하는 입력 격리가 떨어집니다: 포크는 주 세션과 동일한 시스템 프롬프트, 도구, 모델 및 메시지 기록을 보므로 상황을 다시 설명할 필요 없이 부작업을 전달할 수 있습니다. 포크의 자체 도구 호출은 여전히 대화에서 벗어나고 최종 결과만 돌아오므로 주 컨텍스트 윈도우가 깨끗하게 유지됩니다. 다른 subagent가 유용하기에는 너무 많은 배경이 필요하거나 동일한 시작점에서 여러 접근 방식을 병렬로 시도하려는 경우 포크를 사용합니다.1309포크는 새로 시작하는 대신 지금까지의 전체 대화를 상속하는 subagent입니다. 이렇게 하면 subagent가 일반적으로 제공하는 입력 격리가 떨어집니다: 포크는 주 세션과 동일한 시스템 프롬프트, 도구, 모델 및 메시지 기록을 보므로 상황을 다시 설명할 필요 없이 부작업을 전달할 수 있습니다. 포크의 자체 도구 호출은 여전히 대화에서 벗어나고 최종 결과만 돌아오므로 주 컨텍스트 윈도우가 깨끗하게 유지됩니다. 다른 subagent가 유용하기에는 너무 많은 배경이 필요하거나 동일한 시작점에서 여러 접근 방식을 병렬로 시도하려는 경우 포크를 사용합니다.

1284 1310

1285Claude는 Agent 도구를 통해 `fork` subagent 유형을 요청하여 포크를 시작합니다. [포크 모드](#turn-fork-mode-on-or-off)로 이를 제어할 수 있으며, 이는 대화형 세션에서 기본적으로 켜져 있습니다.1311포크 모드가 켜져 있는 동안에는 Claude가 스스로 포크를 시작할 수 있으며, 포크 모드는 기본적으로 켜져 있습니다. 포크를 중지하려면 [포크 모드 끄기](#turn-fork-mode-on-or-off)를 참조하세요.

1286 1312

1287`/subtask` 다음에 작업을 입력하여 포크 모드가 켜져 있는지 여부와 관계없이 직접 포크를 시작할 수 있습니다. v2.1.161부터 v2.1.211까지는 명령이 `/fork`입니다. Claude Code는 작업의 첫 단어에서 포크의 이름을 지정합니다. 다음 예제는 주 세션에서 구현을 계속하는 동안 포크가 테스트 케이스를 작성하도록 포크합니다:1313`/subtask` 다음에 작업을 입력하여 포크 모드가 켜져 있는지 여부와 관계없이 직접 포크를 시작할 수 있습니다. Claude Code는 작업의 첫 단어에서 포크의 이름을 지정합니다. 다음 예제는 주 세션에서 구현을 계속하는 동안 포크가 테스트 케이스를 작성하도록 포크합니다:

1288 1314

1289```text wrap theme={null}1315```text wrap theme={null}

1290/subtask draft unit tests for the parser changes so far1316/subtask draft unit tests for the parser changes so far

1329| 모델 | 주 세션과 동일 | Subagent의 `model` 필드에서 |1355| 모델 | 주 세션과 동일 | Subagent의 `model` 필드에서 |

1330| 권한 | 프롬프트가 터미널에 표시됨 | [Background에서 실행 중일 때 프롬프트가 주 세션에 표시됨](#run-subagents-in-foreground-or-background) |

1332 1357

1333포크의 시스템 프롬프트 및 도구 정의가 부모와 동일하기 때문에 첫 번째 요청은 부모의 [프롬프트 캐시](/docs/ko/prompt-caching#subagents-and-the-cache)를 재사용합니다. 이렇게 하면 동일한 컨텍스트가 필요한 작업에 대해 새로운 서브에이전트를 생성하는 것보다 포크가 더 저렴합니다.1358포크의 시스템 프롬프트 및 도구 정의가 부모와 동일하기 때문에 첫 번째 요청은 부모의 [프롬프트 캐시](/docs/ko/prompt-caching#subagents-and-the-cache)를 재사용합니다. 이렇게 하면 동일한 컨텍스트가 필요한 작업에 대해 새로운 서브에이전트를 생성하는 것보다 포크가 더 저렴합니다.

1335Claude가 Agent 도구를 통해 포크를 생성할 때 `isolation: "worktree"`를 전달하여 포크의 파일 편집이 체크아웃 대신 별도의 git worktree에 기록되도록 할 수 있습니다. 포크는 추가 포크를 생성할 수 없습니다.1360Claude가 Agent 도구를 통해 포크를 생성할 때 `isolation: "worktree"`를 전달하여 포크의 파일 편집이 체크아웃 대신 별도의 git worktree에 기록되도록 할 수 있습니다. 포크는 추가 포크를 생성할 수 없습니다.

1336 1361

1337<h3 id="turn-fork-mode-on-or-off">1362<h3 id="turn-fork-mode-on-or-off">

1338 포크 모드 켜기 또는 끄기1363 포크 모드 끄기

1339</h3>1364</h3>

1340 1365

1341Claude Code는 대화형 세션에서 포크 모드를 기본적으로 켜고 `-p`를 사용한 [비대화형 모드](/docs/ko/headless) 및 Agent SDK에서는 기본적으로 끕니다. 대화형 기본값은 Claude Code v2.1.232 이상이 필요합니다. 이전 버전에서는 `CLAUDE_CODE_FORK_SUBAGENT`를 `1`로 설정하여 포크 모드를 켭니다.1366포크 모드를 사용하면 Claude가 스스로 포크를 시작할 수 있습니다. Claude가 포크를 시작하지 못하도록 하려면 다음과 같이 합니다:

~~1342~~

1343Claude Code가 Agent 도구를 처리하는 방식으로 포크 모드가 켜져 있는지 알 수 있습니다:

~~1344~~

1345* Claude는 `fork` subagent 유형을 요청하여 포크를 생성할 수 있습니다. Claude가 유형을 요청하지 않으면 세션에 여전히 해당 유형이 있는 경우 [general-purpose](#built-in-subagents) subagent를 가져옵니다. Explore와 같은 정의에서 생성된 Subagent는 평소대로 작동합니다.

1346* Claude Code는 Claude가 생성하는 subagent를 background에서 실행합니다. 포크와 비포크 subagent 모두, [foreground에 남아 있는 경우](#run-subagents-in-foreground-or-background)를 제외하고. Claude Code는 또한 Agent 도구의 `run_in_background` 매개변수를 제거하므로 Claude는 foreground를 요청할 수 없습니다.

~~1347~~

1348[`CLAUDE_CODE_FORK_SUBAGENT`](/docs/ko/env-vars) 환경 변수를 설정하여 기본값을 재정의합니다:

1349 1367

1350* `1`은 비대화형 모드 및 Agent SDK에서도 포크 모드를 켭니다1368* **포크만 중지**: [설정](#disable-specific-subagents)의 `permissions.deny`에 `"Agent(fork)"`를 추가합니다.

1351* `0`은 모든 종류의 세션에서 포크 모드를 끕니다1369* **포크 모드 끄기**: [Claude가 서브에이전트를 기다리도록 하기](#let-claude-wait-for-a-subagent)의 단계에 따라 `CLAUDE_CODE_FORK_SUBAGENT`를 `0`으로 설정합니다.

1352 1370

1353포크 모드는 켜두되 Claude가 포크를 생성하지 못하도록 하려면 `Agent(fork)` 규칙으로 [`fork` subagent 유형을 거부합니다](#disable-specific-subagents). Claude Code는 여전히 Claude가 생성하는 subagent를 background에서 실행합니다. [foreground에 남아 있는 경우](#run-subagents-in-foreground-or-background)를 제외하고.1371포크 모드가 켜져 있는 동안에는 로컬 머신의 대화형 터미널, VS Code 또는 데스크톱 세션에서 Claude가 [서브에이전트를 기다릴](#run-subagents-in-foreground-or-background) 수도 없습니다. 포크 모드는 Claude Code v2.1.302부터 기본적으로 켜져 있으며, 대화형 터미널 세션에서는 v2.1.232부터 기본적으로 켜져 있습니다.

1354 1372

1355<h2 id="example-subagents">1373<h2 id="example-subagents">

1356 예제 subagent1374 예제 subagent

terminal-config.md +1 −1

Details

58 58

59 Claude Code의 첫 실행 터미널 설정 프롬프트를 수락한 경우 이미 완료되었습니다. 해당 프롬프트는 `/terminal-setup`을 실행하여 Option을 Meta로 활성화하고 Apple Terminal 프로필에서 청각 벨을 끕니다.59 Claude Code의 첫 실행 터미널 설정 프롬프트를 수락한 경우 이미 완료되었습니다. 해당 프롬프트는 `/terminal-setup`을 실행하여 Option을 Meta로 활성화하고 Apple Terminal 프로필에서 청각 벨을 끕니다.

60 60

61 [화면 읽기 모드](/docs/ko/accessibility)에서 `/terminal-setup`은 벨 설정을 변경하지 않으므로 터미널 벨이 계속 들립니다. v2.1.211 이전에는 `/terminal-setup`이 화면 읽기 모드에서도 벨을 껐습니다. 이전 실행에서 벨을 껐다면 설정 → 프로필 → 고급 → "청각 벨"에서 다시 켭니다.61 [화면 읽기 모드](/docs/ko/accessibility)에서 `/terminal-setup`은 벨 설정을 변경하지 않으므로 터미널 벨이 계속 들립니다. 이전 실행에서 벨을 껐다면 설정 → 프로필 → 고급 → "청각 벨"에서 다시 켭니다.

62 </Tab>62 </Tab>

63 63

64 <Tab title="iTerm2">64 <Tab title="iTerm2">

tools-reference.md +25 −25

Details

26| `CronDelete` | ID로 예약된 작업을 취소합니다 | 아니오 |26| `CronDelete` | ID로 예약된 작업을 취소합니다 | 아니오 |

27| `CronList` | 세션의 모든 예약된 작업을 나열합니다 | 아니오 |27| `CronList` | 세션의 모든 예약된 작업을 나열합니다 | 아니오 |

28| `Edit` | 특정 파일에 대한 대상 편집을 수행합니다. [Edit 도구 동작](#edit-tool-behavior)을 참조하세요 | 예 |28| `Edit` | 특정 파일에 대한 대상 편집을 수행합니다. [Edit 도구 동작](#edit-tool-behavior)을 참조하세요 | 예 |

29| `EndConversation` | 지속적인 학대 입력이 있는 드문 경우 또는 Claude에게 도구를 시연하도록 요청할 때 세션을 종료합니다. Claude Code v2.1.213 이상이 필요합니다. [EndConversation 도구 동작](#endconversation-tool-behavior)을 참조하세요 | 아니오 |29| `EndConversation` | 지속적인 학대 입력이 있는 드문 경우 또는 Claude에게 도구를 시연하도록 요청할 때 세션을 종료합니다. [EndConversation 도구 동작](#endconversation-tool-behavior)을 참조하세요 | 아니오 |

30| `EnterPlanMode` | 코딩 전에 접근 방식을 설계하기 위해 계획 모드로 전환합니다 | 아니오 |30| `EnterPlanMode` | 코딩 전에 접근 방식을 설계하기 위해 계획 모드로 전환합니다 | 아니오 |

31| `EnterWorktree` | 격리된 [git worktree](/docs/ko/worktrees)를 생성하고 이를 전환합니다. 새 worktree를 생성하는 대신 기존 worktree로 전환하려면 `path`를 전달합니다. 처음 진입할 때 대상은 현재 저장소의 worktree이거나 다중 저장소 작업 공간에서 그 안에 중첩된 저장소의 worktree일 수 있습니다. v2.1.203 이전에는 중첩된 저장소의 worktree가 거부되었습니다. `.claude/worktrees/` 외부의 `path`는 세션의 작업 디렉토리와 쓰기 액세스를 해당 위치로 이동하므로 진입하기 전에 승인을 요청합니다. 새 worktree 생성 및 `.claude/worktrees/` 아래의 경로는 프롬프트하지 않습니다. v2.1.206 이전에는 Claude가 `.claude/worktrees/` 외부의 경로에 프롬프트 없이 진입했습니다. worktree 세션 내에서 또는 [`isolation: worktree`](/docs/ko/sub-agents#supported-frontmatter-fields)와 같은 고정된 작업 디렉토리가 있는 서브에이전트에서는 `path` 형식만 사용 가능하며 대상은 세션의 저장소의 `.claude/worktrees/` 아래에 있어야 합니다 | 예 |31| `EnterWorktree` | 격리된 [git worktree](/docs/ko/worktrees)를 생성하고 이를 전환합니다. 새 worktree를 생성하는 대신 기존 worktree로 전환하려면 `path`를 전달합니다. 처음 진입할 때 대상은 현재 저장소의 worktree이거나 다중 저장소 작업 공간에서 그 안에 중첩된 저장소의 worktree일 수 있습니다. v2.1.203 이전에는 중첩된 저장소의 worktree가 거부되었습니다. `.claude/worktrees/` 외부의 `path`는 세션의 작업 디렉토리와 쓰기 액세스를 해당 위치로 이동하므로 진입하기 전에 승인을 요청합니다. 새 worktree 생성 및 `.claude/worktrees/` 아래의 경로는 프롬프트하지 않습니다. v2.1.206 이전에는 Claude가 `.claude/worktrees/` 외부의 경로에 프롬프트 없이 진입했습니다. worktree 세션 내에서 또는 [`isolation: worktree`](/docs/ko/sub-agents#supported-frontmatter-fields)와 같은 고정된 작업 디렉토리가 있는 서브에이전트에서는 `path` 형식만 사용 가능하며 대상은 세션의 저장소의 `.claude/worktrees/` 아래에 있어야 합니다 | 예 |

32| `ExitPlanMode` | 승인을 위한 계획을 제시하고 계획 모드를 종료합니다 | 예 |32| `ExitPlanMode` | 승인을 위한 계획을 제시하고 계획 모드를 종료합니다 | 예 |

48| `SendFeedback` | Claude Code에 대한 피드백 보고서를 작성합니다. 제품 문제 또는 세션에서 Claude의 자체 동작을 다룹니다. 검토할 수 있도록 머신에서 대기열에 넣습니다. Claude Code는 초안을 보내도록 선택할 때까지 아무것도 보내지 않습니다. [SendFeedback 도구 동작](#sendfeedback-tool-behavior)을 참조하세요. Claude Code v2.1.238 이상이 필요합니다 | 아니오 |48| `SendFeedback` | Claude Code에 대한 피드백 보고서를 작성합니다. 제품 문제 또는 세션에서 Claude의 자체 동작을 다룹니다. 검토할 수 있도록 머신에서 대기열에 넣습니다. Claude Code는 초안을 보내도록 선택할 때까지 아무것도 보내지 않습니다. [SendFeedback 도구 동작](#sendfeedback-tool-behavior)을 참조하세요. Claude Code v2.1.238 이상이 필요합니다 | 아니오 |

49| `SendMessage` | 다른 에이전트에게 메시지를 보냅니다. [에이전트 팀](/docs/ko/agent-teams) 팀원, [에이전트 ID 또는 이름으로 재개하는](/docs/ko/sub-agents#resume-subagents) \[서브에이전트], 또는 다른 Claude Code 세션 중 하나입니다. 이 머신 또는 그 이상입니다. 다른 세션으로 메시징하려면 Claude Code v2.1.224 이상이 필요합니다. [크로스 세션 메시징](/docs/ko/cross-session-messaging)은 Claude가 도달할 수 있는 세션, [메시지가 도착할 때의 모습](/docs/ko/cross-session-messaging#what-a-message-looks-like), 및 [다른 세션이 유휴 상태가 될 때 Claude가 공지를 받는 방법](/docs/ko/cross-session-messaging#get-a-notice-when-another-session-goes-idle)을 다룹니다. Claude는 선택적 `summary` 입력을 포함할 수 있습니다. 일반적으로 5-10단어이며, Claude Code는 한 줄 미리보기로 표시합니다. Claude가 [일반 텍스트 메시지](/docs/ko/cross-session-messaging#limitations)에서 생략하면 Claude Code는 메시지의 첫 번째 줄을 요약으로 사용합니다. Claude Code는 200자보다 긴 요약을 줄임표로 자릅니다 | 아니오 |49| `SendMessage` | 다른 에이전트에게 메시지를 보냅니다. [에이전트 팀](/docs/ko/agent-teams) 팀원, [에이전트 ID 또는 이름으로 재개하는](/docs/ko/sub-agents#resume-subagents) \[서브에이전트], 또는 다른 Claude Code 세션 중 하나입니다. 이 머신 또는 그 이상입니다. 다른 세션으로 메시징하려면 Claude Code v2.1.224 이상이 필요합니다. [크로스 세션 메시징](/docs/ko/cross-session-messaging)은 Claude가 도달할 수 있는 세션, [메시지가 도착할 때의 모습](/docs/ko/cross-session-messaging#what-a-message-looks-like), 및 [다른 세션이 유휴 상태가 될 때 Claude가 공지를 받는 방법](/docs/ko/cross-session-messaging#get-a-notice-when-another-session-goes-idle)을 다룹니다. Claude는 선택적 `summary` 입력을 포함할 수 있습니다. 일반적으로 5-10단어이며, Claude Code는 한 줄 미리보기로 표시합니다. Claude가 [일반 텍스트 메시지](/docs/ko/cross-session-messaging#limitations)에서 생략하면 Claude Code는 메시지의 첫 번째 줄을 요약으로 사용합니다. Claude Code는 200자보다 긴 요약을 줄임표로 자릅니다 | 아니오 |

50| `SendUserFile` | 세션의 파일을 선택적 캡션과 함께 사용자에게 보냅니다. 생성된 보고서, 다이어그램, 스크린샷 또는 빌드된 아티팩트가 트랜스크립트에서만 언급되는 대신 장치에 도달합니다. 선택적 `display` 입력은 프레젠테이션을 제어합니다. `render`는 파일을 클라이언트에서 인라인으로 열고, `attach`는 다운로드 카드만 표시하며, 설정되지 않으면 클라이언트가 파일 유형으로 결정합니다. [Remote Control](/docs/ko/remote-control) 클라이언트가 연결되어 있거나 [클라우드 세션](/docs/ko/claude-code-on-the-web)에서 사용 가능합니다. 배달은 Anthropic 호스팅 인프라를 통해 실행되므로 도구는 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 사용할 수 없습니다 | 아니오 |50| `SendUserFile` | 세션의 파일을 선택적 캡션과 함께 사용자에게 보냅니다. 생성된 보고서, 다이어그램, 스크린샷 또는 빌드된 아티팩트가 트랜스크립트에서만 언급되는 대신 장치에 도달합니다. 선택적 `display` 입력은 프레젠테이션을 제어합니다. `render`는 파일을 클라이언트에서 인라인으로 열고, `attach`는 다운로드 카드만 표시하며, 설정되지 않으면 클라이언트가 파일 유형으로 결정합니다. [Remote Control](/docs/ko/remote-control) 클라이언트가 연결되어 있거나 [클라우드 세션](/docs/ko/claude-code-on-the-web)에서 사용 가능합니다. 배달은 Anthropic 호스팅 인프라를 통해 실행되므로 도구는 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 사용할 수 없습니다 | 아니오 |

51| `ShareOnboardingGuide` | `ONBOARDING.md`를 업로드하고 팀원이 Claude Code에서 열 수 있는 공유 링크를 반환합니다. 가이드가 작성된 후 `/team-onboarding`에서 호출됩니다. claude.ai 구독자가 Pro, Max, Team 및 Enterprise 플랜에서 사용 가능합니다 | 예 |51| `ShareOnboardingGuide` | `ONBOARDING.md`를 업로드하고 팀원이 Claude Code에서 열 수 있는 공유 링크를 반환합니다. 가이드가 작성된 후 `/team-onboarding`에서 호출됩니다. Team 및 Enterprise 플랜의 claude.ai 구독자가 사용할 수 있습니다 | 예 |

52| `Skill` | 주 대화 내에서 [스킬](/docs/ko/skills#control-who-invokes-a-skill)을 실행합니다 | 예 |52| `Skill` | 주 대화 내에서 [스킬](/docs/ko/skills#control-who-invokes-a-skill)을 실행합니다 | 예 |

53| `SubagentHandback` | 서브에이전트의 최종 보고서를 해당 서브에이전트의 결과를 받는 대화에 전달합니다. [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서만 제공되며, Agent 도구가 [포크](/docs/ko/sub-agents#fork-the-current-conversation) 이외의 로컬에서 실행하는 서브에이전트에만 제공되며, 터미널 CLI, IDE 확장, 클라우드 세션 및 Agent SDK에서 사용 가능합니다. 분류기는 보고서가 전달되기 전에 검토합니다. Claude Code v2.1.271 이상이 필요합니다 | 아니오 |53| `SubagentHandback` | 서브에이전트의 최종 보고서를 해당 서브에이전트의 결과를 받는 대화에 전달합니다. [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서만 제공되며, Agent 도구가 [포크](/docs/ko/sub-agents#fork-the-current-conversation) 이외의 로컬에서 실행하는 서브에이전트에만 제공되며, 터미널 CLI, IDE 확장, 클라우드 세션 및 Agent SDK에서 사용 가능합니다. 분류기는 보고서가 전달되기 전에 검토합니다. Claude Code v2.1.271 이상이 필요합니다 | 아니오 |

54| `TaskCreate` | 작업 목록에 새 작업을 생성합니다. [작업 도구 가용성](#task-tool-availability) 아래에 나열된 모델에서만 기본적으로 제공되며, 다른 모델에서는 옵트인할 때만 제공됩니다 | 아니오 |54| `TaskCreate` | 작업 목록에 새 작업을 생성합니다. [작업 도구 가용성](#task-tool-availability) 아래에 나열된 모델에서만 기본적으로 제공되며, 다른 모델에서는 옵트인할 때만 제공됩니다 | 아니오 |

72대부분의 경우 Claude가 이러한 도구를 사용할 시기를 결정하므로 Claude와 상호작용할 때 도구 이름을 직접 지정할 필요가 없습니다. 권한 및 기타 구성을 정의할 때 도구 이름을 직접 참조합니다:72대부분의 경우 Claude가 이러한 도구를 사용할 시기를 결정하므로 Claude와 상호작용할 때 도구 이름을 직접 지정할 필요가 없습니다. 권한 및 기타 구성을 정의할 때 도구 이름을 직접 참조합니다:

73 73

74* 설정의 [`permissions.allow`](/docs/ko/settings-reference#permissions-allow) 및 [`permissions.deny`](/docs/ko/settings-reference#permissions-deny)와 `/permissions` 인터페이스에서74* 설정의 [`permissions.allow`](/docs/ko/settings-reference#permissions-allow) 및 [`permissions.deny`](/docs/ko/settings-reference#permissions-deny)와 `/permissions` 인터페이스에서

~~75* [`CLI flags`](/docs/ko/cli-reference)의 `--allowedTools` 및 `--disallowedTools`에서~~75* [CLI 플래그](/docs/ko/cli-reference)의 `--allowedTools` 및 `--disallowedTools`에서

76* Agent SDK의 [`allowedTools` 및 `disallowedTools`](/docs/ko/agent-sdk/permissions#allow-and-deny-rules) 옵션에서76* Agent SDK의 [`allowedTools` 및 `disallowedTools`](/docs/ko/agent-sdk/permissions#allow-and-deny-rules) 옵션에서

77* [skill의 `allowed-tools`](/docs/ko/skills#frontmatter-reference) frontmatter에서77* [skill의 `allowed-tools`](/docs/ko/skills#frontmatter-reference) frontmatter에서

78* hook의 [`if` condition](/docs/ko/hooks-guide#filter-by-tool-name-and-arguments-with-the-if-field)에서78* hook의 [`if` condition](/docs/ko/hooks-guide#filter-by-tool-name-and-arguments-with-the-if-field)에서

92 92

93여기에 나열되지 않은 도구(예: `ExitPlanMode` 또는 `ShareOnboardingGuide`)는 specifier 없이 도구 이름만 허용합니다.93여기에 나열되지 않은 도구(예: `ExitPlanMode` 또는 `ShareOnboardingGuide`)는 specifier 없이 도구 이름만 허용합니다.

94 94

95`Edit(...)` allow 규칙은 동일한 경로에 대한 읽기 액세스도 부여하므로 일치하는 `Read(...)` 규칙이 필요하지 않습니다. `Read(...)` deny 규칙은 동일한 경로의 Edit 및 Write 도구도 차단하며, 새 파일을 만드는 것도 포함됩니다. 두 도구 모두 Claude가 읽을 수 있어야 하는 콘텐츠를 변경하기 때문입니다. `Read` deny 체크는 편집 시 Claude Code v2.1.208 이상이 필요하며, 쓰기 시 v2.1.228 이상이 필요합니다.95`Edit(...)` allow 규칙은 동일한 경로에 대한 읽기 액세스도 부여하므로 일치하는 `Read(...)` 규칙이 필요하지 않습니다. `Read(...)` deny 규칙은 동일한 경로의 Edit 및 Write 도구도 차단하며, 새 파일을 만드는 것도 포함됩니다. 두 도구 모두 Claude가 다시 읽을 수 있어야 하는 콘텐츠를 변경하기 때문입니다. Write 도구의 경우 `Read` deny 체크에는 Claude Code v2.1.228 이상이 필요합니다.

96 96

97Hook `matcher` 필드는 괄호로 묶인 규칙 형식이 아닌 도구 이름만 사용합니다. 매칭 규칙은 [matcher patterns](/docs/ko/hooks#matcher-patterns)을 참조하세요. 각 도구가 hook의 `tool_input`에 전달하는 필드 이름은 [PreToolUse input reference](/docs/ko/hooks#pretooluse-input)를 참조하세요.97Hook `matcher` 필드는 괄호로 묶인 규칙 형식이 아닌 도구 이름만 사용합니다. 매칭 규칙은 [matcher patterns](/docs/ko/hooks#matcher-patterns)을 참조하세요. 각 도구가 hook의 `tool_input`에 전달하는 필드 이름은 [PreToolUse input reference](/docs/ko/hooks#pretooluse-input)를 참조하세요.

98 98

100 에이전트 도구 동작100 에이전트 도구 동작

101</h2>101</h2>

102 102

103에이전트 도구는 별도의 컨텍스트 윈도우에서 서브에이전트를 생성합니다. 서브에이전트는 자율적으로 작업을 진행한 후 부모 대화에 최종 결과를 반환합니다. 부모는 서브에이전트의 중간 도구 호출이나 출력을 보지 못하고 최종 결과만 봅니다. [에이전트 팀](/docs/ko/agent-teams)이 활성화된 경우, `name`을 포함하는 호출은 [팀원](/docs/ko/agent-teams#how-claude-starts-agent-teams)을 시작할 수 있으며, 이는 결과를 반환하는 대신 팀 메시지를 통해 보고합니다.103에이전트 도구는 별도의 컨텍스트 윈도우에서 서브에이전트를 생성합니다. 서브에이전트는 자율적으로 작업을 진행한 후 부모 대화에 최종 결과를 반환합니다. 부모는 서브에이전트의 중간 도구 호출이나 출력을 보지 못하고 최종 결과만 봅니다. 동일한 도구로 팀원이나 포크를 시작할 수도 있습니다:

104 104

105서브에이전트가 실행하는 턴의 수를 제한하려면 [서브에이전트 정의](/docs/ko/sub-agents#supported-frontmatter-fields)에서 `maxTurns`를 설정합니다. 서브에이전트가 제한에 도달하면 Claude Code는 반환된 결과를 부분 출력으로 표시하며, Claude는 [서브에이전트를 재개](/docs/ko/sub-agents#resume-subagents)하여 계속할 수 있습니다.105* **팀원**: [에이전트 팀](/docs/ko/agent-teams)이 활성화된 경우, `name`을 포함하는 호출은 대신 [팀원](/docs/ko/agent-teams#how-claude-starts-agent-teams)을 시작할 수 있으며, 팀원은 결과를 반환하는 대신 팀 메시지를 통해 보고합니다

106* **포크**: [포크 모드](/docs/ko/sub-agents#turn-fork-mode-on-or-off)가 켜져 있는 곳에서는 이 도구가 [포크된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 시작할 수 있으며, 포크된 서브에이전트는 새로 시작하는 대신 전체 부모 대화를 상속합니다

106 107

107동일한 에이전트 도구는 [포크 모드](/docs/ko/sub-agents#turn-fork-mode-on-or-off)가 켜져 있는 곳에서 [포크된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)도 시작합니다. 포크는 새로 시작하는 대신 전체 부모 대화를 상속하고, [포그라운드에 유지되는 경우](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)를 제외하고 백그라운드에서 실행되며, 여전히 터미널에서 권한 프롬프트를 표시합니다. 이 섹션의 나머지 부분은 포크되지 않은 서브에이전트를 설명합니다.108서브에이전트가 실행하는 턴의 수를 제한하려면 [서브에이전트 정의](/docs/ko/sub-agents#supported-frontmatter-fields)에서 `maxTurns`를 설정합니다. 서브에이전트가 제한에 도달하면 Claude Code는 반환된 결과를 부분 출력으로 표시하며, Claude는 [서브에이전트를 재개](/docs/ko/sub-agents#resume-subagents)하여 계속할 수 있습니다.

108 109

109포크되지 않은 서브에이전트가 사용할 수 있는 도구는 [서브에이전트 정의](/docs/ko/sub-agents)의 `tools` 및 `disallowedTools` 필드에 따라 달라집니다:110포크되지 않은 서브에이전트가 사용할 수 있는 도구는 [서브에이전트 정의](/docs/ko/sub-agents)의 `tools` 및 `disallowedTools` 필드에 따라 달라집니다:

110 111

279 280

280Edit 도구는 정확한 문자열 교체를 수행합니다. `old_string`과 `new_string`을 받아 첫 번째를 두 번째로 교체합니다. 정규식이나 유사 일치를 사용하지 않습니다.281Edit 도구는 정확한 문자열 교체를 수행합니다. `old_string`과 `new_string`을 받아 첫 번째를 두 번째로 교체합니다. 정규식이나 유사 일치를 사용하지 않습니다.

281 282

282편집을 적용하기 위해 다음 검사를 통과해야 합니다. 그 전에, [`Read` 거부 규칙](/docs/ko/permissions#tool-specific-permission-rules)과 일치하는 경로는 거부되며, 여기에 새 파일을 만드는 것도 포함됩니다. 거부는 Claude Code v2.1.208 이상이 필요합니다.283편집을 적용하기 위해 다음 검사를 통과해야 합니다. 그 전에, [`Read` 거부 규칙](/docs/ko/permissions#tool-specific-permission-rules)과 일치하는 경로는 거부되며, 여기에 새 파일을 만드는 것도 포함됩니다.

283 284

284* **편집 전 읽기**: Claude는 편집하기 전에 현재 대화에서 파일을 읽으며, [`PARTIAL view` 공지](#large-files)로 단축된 읽기는 계산되지 않습니다. Claude Opus 4.6, Claude Haiku 4.5 및 이전 모델은 항상 읽기를 요구합니다. 최신 모델은 읽기가 권한 프롬프트를 필요로 하지 않고 Read 도구를 사용할 수 있을 때 읽지 않은 파일을 편집할 수 있습니다.285* **편집 전 읽기**: Claude는 편집하기 전에 현재 대화에서 파일을 읽으며, [`PARTIAL view` 공지](#large-files)로 단축된 읽기는 계산되지 않습니다. Claude Opus 4.6, Claude Haiku 4.5 및 이전 모델은 항상 읽기를 요구합니다. 최신 모델은 읽기가 권한 프롬프트를 필요로 하지 않고 Read 도구를 사용할 수 있을 때 읽지 않은 파일을 편집할 수 있습니다.

285* **일치**: `old_string`은 파일에 정확히 작성된 대로 나타나야 합니다. 공백이나 들여쓰기의 단 한 글자 차이도 일치하지 않기에 충분합니다.286* **일치**: `old_string`은 파일에 정확히 작성된 대로 나타나야 합니다. 공백이나 들여쓰기의 단 한 글자 차이도 일치하지 않기에 충분합니다.

286* **고유성**: `old_string`은 정확히 한 번 나타나야 합니다. 두 번 이상 나타날 때, Claude는 한 번의 발생을 고정하기에 충분한 주변 컨텍스트가 있는 더 긴 문자열을 제공하거나, `replace_all: true`를 설정하여 모두 교체합니다.287* **고유성**: `old_string`은 정확히 한 번 나타나야 합니다. 두 번 이상 나타날 때, Claude는 한 번의 발생을 고정하기에 충분한 주변 컨텍스트가 있는 더 긴 문자열을 제공하거나, `replace_all: true`를 설정하여 모두 교체합니다.

287 288

288Claude가 마지막으로 읽은 후 디스크에서 변경된 파일은 `old_string`이 현재 콘텐츠와 정확히 일치하고 명확하며 Claude Code가 프롬프트 없이 파일을 읽을 수 있을 때 여전히 편집할 수 있습니다. 파일의 현재 콘텐츠와 일치하면 이것이 안전하게 유지되며, 결과는 파일이 다른 변경 사항을 포함하고 있음을 기록하므로 Claude는 주변 콘텐츠에 따라 달라지는 편집 전에 다시 읽습니다. 다른 경우, 예를 들어 오래된 `old_string` 또는 `replace_all` 없이 두 번 이상 일치하는 경우, Claude는 편집하기 전에 파일을 다시 읽습니다. 읽지 않은 파일 및 변경된 파일의 완화된 처리는 Claude Code v2.1.208 이상이 필요합니다. 그 전에는 Claude Code가 대화에서 읽지 않았거나 읽은 후 디스크에서 변경된 파일에 대한 모든 편집을 거부했습니다.289Claude가 마지막으로 읽은 후 디스크에서 변경된 파일은 `old_string`이 현재 콘텐츠와 정확히 일치하고 명확하며 Claude Code가 프롬프트 없이 파일을 읽을 수 있을 때 여전히 편집할 수 있습니다. 파일의 현재 콘텐츠와 일치하면 이것이 안전하게 유지되며, 결과는 파일이 다른 변경 사항을 포함하고 있음을 기록하므로 Claude는 주변 콘텐츠에 따라 달라지는 편집 전에 다시 읽습니다. 다른 경우, 예를 들어 오래된 `old_string` 또는 `replace_all` 없이 두 번 이상 일치하는 경우, Claude는 편집하기 전에 파일을 다시 읽습니다.

289 290

290Claude는 `cat`이나 `grep` 같은 Bash 명령으로 파일을 본 후에도 별도의 Read 없이 파일을 편집할 수 있습니다. 해당 명령은 `cat`, `nl`, `bat`, `batcat`, `head`, `tail`, `sed -n 'X,Yp'`, `grep`, `egrep`, `fgrep`, `rg`이며, 각각 파이프나 리디렉션 없이 단일 파일에 대해 실행되어야 합니다. 일치 항목을 출력하지 않는 검색은 읽기로 간주되지 않으며, 이 목록에 없는 명령도 마찬가지입니다.291Claude는 `cat`이나 `grep` 같은 Bash 명령으로 파일을 본 후에도 별도의 Read 없이 파일을 편집할 수 있습니다. 해당 명령은 `cat`, `nl`, `bat`, `batcat`, `head`, `tail`, `sed -n 'X,Yp'`, `grep`, `egrep`, `fgrep`, `rg`이며, 각각 파이프나 리디렉션 없이 단일 파일에 대해 실행되어야 합니다. 일치 항목을 출력하지 않는 검색은 읽기로 간주되지 않으며, 이 목록에 없는 명령도 마찬가지입니다.

291 292

322 323

323도구는 다음의 모든 조건이 충족될 때만 나타납니다:324도구는 다음의 모든 조건이 충족될 때만 나타납니다:

324 325

325* **버전**: Claude Code v2.1.213 이상.

326* **모델**: 세션의 모델이 Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5, 또는 이들 중 하나의 최신 버전입니다.326* **모델**: 세션의 모델이 Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5, 또는 이들 중 하나의 최신 버전입니다.

327* **표면**: 대화형 터미널 세션, IDE의 통합 터미널에서의 `claude` 세션 포함, 이것이 [JetBrains 플러그인](/docs/ko/jetbrains)이 실행되는 방식입니다. 다른 표면은 도구를 포함하지 않습니다:327* **표면**: 대화형 터미널 세션, IDE의 통합 터미널에서의 `claude` 세션 포함, 이것이 [JetBrains 플러그인](/docs/ko/jetbrains)이 실행되는 방식입니다. 다른 표면은 도구를 포함하지 않습니다:

328 * 비대화형 `-p` 실행328 * 비대화형 `-p` 실행

345* 권한 [거부 규칙](/docs/ko/permissions#match-all-uses-of-a-tool), `--disallowedTools` 플래그 또는 [`--restricted`](/docs/ko/cli-reference#cli-flags)가 세션에서 `Bash`를 제거합니다.345* 권한 [거부 규칙](/docs/ko/permissions#match-all-uses-of-a-tool), `--disallowedTools` 플래그 또는 [`--restricted`](/docs/ko/cli-reference#cli-flags)가 세션에서 `Bash`를 제거합니다.

346* [서브에이전트](/docs/ko/sub-agents#available-tools)가 `tools` 필드에 `Glob` 또는 `Grep`을 나열하고 `Bash`를 제외합니다. 나열된 도구는 해당 서브에이전트에만 돌아오거나, [`--agent`](/docs/ko/sub-agents#invoke-subagents-explicitly) 또는 `agent` 설정을 통해 주 세션 에이전트로 실행될 때 전체 세션에 돌아옵니다.346* [서브에이전트](/docs/ko/sub-agents#available-tools)가 `tools` 필드에 `Glob` 또는 `Grep`을 나열하고 `Bash`를 제외합니다. 나열된 도구는 해당 서브에이전트에만 돌아오거나, [`--agent`](/docs/ko/sub-agents#invoke-subagents-explicitly) 또는 `agent` 설정을 통해 주 세션 에이전트로 실행될 때 전체 세션에 돌아옵니다.

347 347

348Glob은 재귀적 디렉토리 매칭을 위한 `**`를 포함한 표준 glob 구문을 지원합니다:348Glob은 재귀적 디렉터리 매칭을 위한 `**`를 포함한 표준 glob 구문을 지원합니다:

349 349

350* `**/*.js`는 모든 깊이의 모든 `.js` 파일과 일치합니다350* `**/*.js`는 모든 깊이의 모든 `.js` 파일과 일치합니다

351* `src/**/*.ts`는 `src/` 아래의 모든 `.ts` 파일과 일치합니다351* `src/**/*.ts`는 `src/` 아래의 모든 `.ts` 파일과 일치합니다

352* `*.{json,yaml}`은 현재 디렉토리의 `.json` 및 `.yaml` 파일과 일치합니다352* `*.{json,yaml}`은 현재 디렉터리의 `.json` 및 `.yaml` 파일과 일치합니다

353 353

354결과는 수정 시간순으로 정렬되며 100개 파일로 제한됩니다. 제한에 도달하면 Claude는 결과에서 잘림 플래그를 보고 패턴을 좁힐 수 있습니다.354결과는 수정 시간순으로 정렬되며 100개 파일로 제한됩니다. 제한에 도달하면 Claude는 결과에서 잘림 플래그를 보고 패턴을 좁힐 수 있습니다.

355 355

356Glob은 기본적으로 `.gitignore`를 존중하지 않으므로 gitignore된 파일을 추적된 파일과 함께 찾습니다. 이는 gitignore된 파일을 건너뛰는 [Grep](#grep-tool-behavior)과 다릅니다. Glob이 `.gitignore`를 존중하도록 하려면 Claude Code를 시작하기 전에 `CLAUDE_CODE_GLOB_NO_IGNORE=false`를 설정하십시오.356Glob은 기본적으로 `.gitignore`를 존중하지 않으므로 gitignore된 파일을 추적된 파일과 함께 찾습니다. 이는 gitignore된 파일을 건너뛰는 [Grep](#grep-tool-behavior)과 다릅니다. Glob이 `.gitignore`를 존중하도록 하려면 Claude Code를 시작하기 전에 `CLAUDE_CODE_GLOB_NO_IGNORE=false`를 설정하십시오.

357 357

358Claude Code는 검색 디렉토리의 존재 여부를 확인하기 전에 Glob 호출에 대한 권한을 결정합니다. 여전히 [작업 디렉토리](/docs/ko/permissions#working-directories) 외부의 누락된 `path`에 대해 읽기 권한 확인을 실행하므로 경로에 대한 권한 프롬프트가 경로가 존재한다는 의미는 아닙니다.358Claude Code는 검색 디렉터리의 존재 여부를 확인하기 전에 Glob 호출에 대한 권한을 결정합니다. 여전히 [작업 디렉터리](/docs/ko/permissions#working-directories) 외부의 누락된 `path`에 대해 읽기 권한 확인을 실행하므로 경로에 대한 권한 프롬프트가 경로가 존재한다는 의미는 아닙니다.

359 359

360null 바이트를 포함하는 `pattern` 또는 `path` 값은 Claude에 이를 제거하도록 요청하는 오류를 반환합니다. 360null 바이트를 포함하는 `pattern` 또는 `path` 값은 Claude에 이를 제거하도록 요청하는 오류를 반환합니다.

361 361

362<h2 id="grep-tool-behavior">362<h2 id="grep-tool-behavior">

363 Grep 도구 동작363 Grep 도구 동작

373 373

374* `files_with_matches`: 파일 경로만, 줄 내용 없음. 이것이 기본값입니다.374* `files_with_matches`: 파일 경로만, 줄 내용 없음. 이것이 기본값입니다.

375* `content`: 파일 및 줄 번호가 있는 일치하는 줄. 도구의 `offset` 매개변수가 일치하는 패턴의 마지막 일치를 지나가리킬 때, Grep은 `No entries at this offset`을 반환하므로 Claude는 패턴이 일치하지 않는다고 결론짓는 대신 offset을 확대하거나 재설정합니다.375* `content`: 파일 및 줄 번호가 있는 일치하는 줄. 도구의 `offset` 매개변수가 일치하는 패턴의 마지막 일치를 지나가리킬 때, Grep은 `No entries at this offset`을 반환하므로 Claude는 패턴이 일치하지 않는다고 결론짓는 대신 offset을 확대하거나 재설정합니다.

376* `count`: 파일당 일치 개수, 그 다음 모든 일치하는 파일 전체의 합계. 합계는 도구의 `head_limit` 또는 `offset` 매개변수가 나열된 파일별 항목을 자르더라도 모든 일치를 포함합니다. v2.1.208 이전에는 합계가 나열된 항목만 합산했습니다.376* `count`: 파일당 일치 개수, 그 다음 모든 일치하는 파일 전체의 합계. 합계는 도구의 `head_limit` 또는 `offset` 매개변수가 나열된 파일별 항목을 자르더라도 모든 일치를 포함합니다.

377 377

378Claude는 `glob` 매개변수(예: `**/*.tsx`)를 사용하여 파일별로 결과를 범위 지정하거나 `type` 매개변수(예: `py` 또는 `rust`)를 사용하여 언어별로 범위 지정할 수 있습니다. 기본적으로 패턴은 단일 줄 내에서 일치합니다. Claude는 `multiline: true`를 설정하여 줄 경계를 넘어 일치시킬 수 있습니다.378Claude는 `glob` 매개변수(예: `**/*.tsx`)를 사용하여 파일별로 결과를 범위 지정하거나 `type` 매개변수(예: `py` 또는 `rust`)를 사용하여 언어별로 범위 지정할 수 있습니다. 기본적으로 패턴은 단일 줄 내에서 일치합니다. Claude는 `multiline: true`를 설정하여 줄 경계를 넘어 일치시킬 수 있습니다.

379 379

536 Windows 인코딩 및 종료 코드536 Windows 인코딩 및 종료 코드

537</h3>537</h3>

538 538

539Windows에서 다음 PowerShell 인코딩 및 종료 코드 동작에는 Claude Code v2.1.214 이상이 필요합니다.

~~540~~

541* `>`와 `>>`를 사용한 리디렉션은 PowerShell 5.1에서 UTF-8 파일을 작성합니다.539* `>`와 `>>`를 사용한 리디렉션은 PowerShell 5.1에서 UTF-8 파일을 작성합니다.

542* Claude Code는 기본 명령의 표준 입력으로 파이프된 텍스트를 UTF-8로 인코딩합니다.540* Claude Code는 기본 명령의 표준 입력으로 파이프된 텍스트를 UTF-8로 인코딩합니다.

543* Claude Code는 ANSI 이스케이프 시퀀스 없이 오류 출력을 캡처합니다.541* Claude Code는 ANSI 이스케이프 시퀀스 없이 오류 출력을 캡처합니다.

544* 자식 프로세스가 표준 입력을 대기하는 명령은 행(hang)되는 대신 파일 끝을 수신합니다.542* 자식 프로세스가 표준 입력을 대기하는 명령은 행(hang)되는 대신 파일 끝을 수신합니다.

545* `where.exe`의 종료 코드 1은 일치하는 항목이 없음을 의미하고, `fc.exe` 및 `diff.exe`에서는 파일이 다름을 의미하므로, 명령이 출력을 생성할 때 Claude Code는 해당 종료 코드를 명령 오류가 아닌 유효한 부정적 답변으로 취급합니다. Claude Code는 여전히 `where.exe /Q` 또는 `$null`로의 리디렉션과 같은 침묵된 형식을 종료 코드 1에서 실패로 보고합니다.543* `where.exe`의 종료 코드 1은 일치하는 항목이 없음을 의미하고, `fc.exe` 및 `diff.exe`에서는 파일이 다름을 의미하므로, 명령이 출력을 생성할 때 Claude Code는 해당 종료 코드를 명령 오류가 아닌 유효한 부정적 답변으로 취급합니다. Claude Code는 여전히 `where.exe /Q` 또는 `$null`로의 리디렉션과 같은 침묵된 형식을 종료 코드 1에서 실패로 보고합니다.

546 544

547v2.1.214 이전에는 PowerShell 5.1의 `>`가 UTF-16LE 파일을 작성했고, 비ASCII 파이프된 입력은 `?`로 도착했으며, Python 스크립트는 비ASCII 문자를 인쇄할 때 `UnicodeEncodeError`로 충돌할 수 있었습니다.

~~548~~

549<h3 id="preview-limitations">545<h3 id="preview-limitations">

550 미리보기 제한 사항546 미리보기 제한 사항

551</h3>547</h3>

561 557

562Read 도구는 파일 경로를 받아 줄 번호와 함께 내용을 반환합니다. Claude는 항상 절대 경로를 전달하도록 지시됩니다.558Read 도구는 파일 경로를 받아 줄 번호와 함께 내용을 반환합니다. Claude는 항상 절대 경로를 전달하도록 지시됩니다.

563 559

564빈 파일을 읽으면 파일이 존재하지만 내용이 비어 있다는 공지가 반환되고, 마지막 줄을 지난 `offset`은 파일의 줄 수를 나타내는 공지를 반환합니다. v2.1.208 이전에는 빈 파일을 읽으면 끝을 지난 공지가 반환되었습니다.560빈 파일을 읽으면 파일이 존재하지만 내용이 비어 있다는 공지가 반환되고, 마지막 줄을 지난 `offset`은 파일의 줄 수를 나타내는 공지를 반환합니다.

565 561

566Read는 일반 텍스트 이상의 여러 파일 유형을 처리합니다:562Read는 일반 텍스트 이상의 여러 파일 유형을 처리합니다:

567 563

568* **이미지**: PNG, JPG 및 기타 이미지 형식은 원본 바이트가 아닌 Claude가 볼 수 있는 시각적 콘텐츠로 반환됩니다. Claude Code는 모델의 이미지 크기 제한에 맞추기 위해 큰 이미지를 크기 조정하고 재압축하므로, Claude는 큰 스크린샷의 축소된 버전을 볼 수 있습니다. 크기 조정 후에도 500KB보다 큰 이미지는 픽셀 치수는 변경하지 않고 품질을 낮춘 JPEG로 다시 인코딩됩니다. Claude가 큰 이미지에서 세밀한 픽셀 수준의 세부 정보를 놓친 경우, 예를 들어 ImageMagick을 통해 Bash로 관심 영역을 먼저 자르도록 요청하십시오.564* **이미지**: PNG, JPEG, GIF 및 WebP 파일은 원본 바이트가 아닌 Claude가 볼 수 있는 시각적 콘텐츠로 반환됩니다. Claude Code는 모델의 이미지 크기 제한에 맞추기 위해 큰 이미지를 전송 전에 크기 조정하고 재압축하므로, Claude는 큰 스크린샷의 축소된 버전을 볼 수 있습니다.

565

566 Claude가 큰 이미지에서 세밀한 픽셀 수준의 세부 정보를 놓친 경우, 예를 들어 Bash를 통해 ImageMagick으로 관심 영역을 자른 다음 잘라낸 이미지를 읽도록 요청하십시오.

569* **PDF**: Claude는 짧은 `.pdf` 파일을 전체적으로 읽습니다. 10페이지보다 긴 PDF의 경우, `pages` 매개변수(예: `"1-5"`)를 사용하여 범위로 읽으며, 한 번에 최대 20페이지까지 읽습니다. 페이지 범위 읽기는 poppler-utils의 `pdftoppm`으로 페이지를 렌더링하므로, macOS에서는 `brew install poppler`로, Debian 및 Ubuntu에서는 `apt-get install poppler-utils`로 설치하십시오. Windows 및 기타 플랫폼에서는 `pdftoppm`을 `PATH`에 배치하는 poppler 빌드를 설치하십시오. 이것이 없으면 페이지 범위 읽기가 `pdftoppm is not installed` 오류로 실패합니다.567* **PDF**: Claude는 짧은 `.pdf` 파일을 전체적으로 읽습니다. 10페이지보다 긴 PDF의 경우, `pages` 매개변수(예: `"1-5"`)를 사용하여 범위로 읽으며, 한 번에 최대 20페이지까지 읽습니다. 페이지 범위 읽기는 poppler-utils의 `pdftoppm`으로 페이지를 렌더링하므로, macOS에서는 `brew install poppler`로, Debian 및 Ubuntu에서는 `apt-get install poppler-utils`로 설치하십시오. Windows 및 기타 플랫폼에서는 `pdftoppm`을 `PATH`에 배치하는 poppler 빌드를 설치하십시오. 이것이 없으면 페이지 범위 읽기가 `pdftoppm is not installed` 오류로 실패합니다.

570* **Jupyter 노트북**: `.ipynb` 파일은 코드, 마크다운 및 시각화를 포함한 모든 셀과 해당 출력을 반환합니다. 셀의 크기가 256 KB를 초과하거나 [토큰 제한](#large-files)을 초과하는 노트북은 대신 오류를 반환합니다. Claude Code는 100MB를 초과하는 노트북 파일을 읽기를 거부합니다. 오류는 Claude에게 셀 슬라이스와 같은 노트북의 일부를 읽는 방법을 알려주며, 셸 명령을 사용합니다.568* **Jupyter 노트북**: `.ipynb` 파일은 코드, 마크다운 및 시각화를 포함한 모든 셀과 해당 출력을 반환합니다. 셀의 크기가 256 KB를 초과하거나 [토큰 제한](#large-files)을 초과하는 노트북은 대신 오류를 반환합니다. Claude Code는 100MB를 초과하는 노트북 파일을 읽기를 거부합니다. 오류는 Claude에게 셀 슬라이스와 같은 노트북의 일부를 읽는 방법을 알려주며, 셸 명령을 사용합니다.

571 569

572Read는 디렉토리가 아닌 파일만 읽습니다. Claude는 `ls`와 같은 셸 명령을 사용하여 디렉토리 내용을 나열합니다.570Read는 디렉토리가 아닌 파일만 읽습니다. Claude는 `ls`와 같은 셸 명령을 사용하여 디렉토리 내용을 나열합니다.

573 571

572Read는 `.xlsx`, `.parquet`, `.heic`, `.zip`과 같이 바이너리로 취급하는 확장자의 파일을 거부합니다. 거부된 후에도 Claude는 작업을 계속합니다. 오류는 해당 파일 유형에 사용할 수 있는 스킬이 있으면 그 스킬을 제안하고, 없으면 해당 형식을 읽는 셸 명령이나 스크립트를 제안합니다. Read가 거부하는 파일을 [`@`-멘션](/docs/ko/common-workflows#reference-files-and-directories)하면 Claude는 파일의 경로는 받지만 내용은 받지 않습니다.

573

574<h3 id="large-files">574<h3 id="large-files">

575 대용량 파일575 대용량 파일

576</h3>576</h3>

691* WebFetch는 기본적으로 각 응답을 15분 동안 캐시하므로, 동일한 URL의 반복된 가져오기가 빠르게 반환됩니다. Claude Code v2.1.233 이상에서는 [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/ko/env-vars#variables)를 설정하여 WebFetch가 각 응답을 유지하는 기간을 변경할 수 있습니다.691* WebFetch는 기본적으로 각 응답을 15분 동안 캐시하므로, 동일한 URL의 반복된 가져오기가 빠르게 반환됩니다. Claude Code v2.1.233 이상에서는 [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/ko/env-vars#variables)를 설정하여 WebFetch가 각 응답을 유지하는 기간을 변경할 수 있습니다.

692* 5분 이내에 다운로드를 완료하지 못한 페이지(WebFetch가 따라가는 모든 리디렉션 포함)는 마감 오류로 실패합니다. Claude Code v2.1.268 이상에서는 [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/ko/env-vars#variables)를 설정하여 제한을 변경하거나, `0`으로 설정하여 제거할 수 있습니다.692* 5분 이내에 다운로드를 완료하지 못한 페이지(WebFetch가 따라가는 모든 리디렉션 포함)는 마감 오류로 실패합니다. Claude Code v2.1.268 이상에서는 [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/ko/env-vars#variables)를 설정하여 제한을 변경하거나, `0`으로 설정하여 제거할 수 있습니다.

693* URL이 다른 호스트로 리디렉션될 때, WebFetch는 원본 URL과 리디렉션 대상을 이름으로 지정하는 텍스트 결과를 반환하고 따라가지 않습니다. 그러면 Claude는 두 번째 WebFetch 호출로 새 URL을 가져옵니다.693* URL이 다른 호스트로 리디렉션될 때, WebFetch는 원본 URL과 리디렉션 대상을 이름으로 지정하는 텍스트 결과를 반환하고 따라가지 않습니다. 그러면 Claude는 두 번째 WebFetch 호출로 새 URL을 가져옵니다.

694* 추출 단계가 과부하 API에 도달하면, Claude Code는 백오프로 재시도합니다. 여전히 실패하는 가져오기는 오류 결과를 반환합니다. v2.1.212 이전에는 API 오류 텍스트가 추출된 페이지 콘텐츠인 것처럼 Claude에 도달할 수 있었습니다.694* 추출 단계가 과부하 API에 도달하면, Claude Code는 백오프로 재시도합니다. 여전히 실패하는 가져오기는 오류 결과를 반환합니다.

695 695

696Manual 및 `acceptEdits` [권한 모드](/docs/ko/permission-modes)에서, WebFetch는 가져오기 전에 프롬프트를 표시합니다. 단, [권한 규칙](/docs/ko/permissions#manage-permissions)이 이미 허용하거나 거부하는 도메인과 프롬프트 없이 가져오는 사전 승인된 문서 도메인의 기본 제공 집합은 제외됩니다. 규칙이 허용하는 것이 무엇이든, 가져오기는 먼저 [WebFetch 도메인 안전 검사](/docs/ko/data-usage#webfetch-domain-safety-check)를 통과합니다. 해당 섹션에서는 검사가 전송하는 내용과 이를 건너뛰는 설정을 다룹니다. 프롬프트는 세 가지 옵션을 제공합니다:696Manual 및 `acceptEdits` [권한 모드](/docs/ko/permission-modes)에서, WebFetch는 가져오기 전에 프롬프트를 표시합니다. 단, [권한 규칙](/docs/ko/permissions#manage-permissions)이 이미 허용하거나 거부하는 도메인과 프롬프트 없이 가져오는 사전 승인된 문서 도메인의 기본 제공 집합은 제외됩니다. 규칙이 허용하는 것이 무엇이든, 가져오기는 먼저 [WebFetch 도메인 안전 검사](/docs/ko/data-usage#webfetch-domain-safety-check)를 통과합니다. 해당 섹션에서는 검사가 전송하는 내용과 이를 건너뛰는 설정을 다룹니다. 프롬프트는 세 가지 옵션을 제공합니다:

697 697

727 727

728이 도구는 호출당 최대 8개의 백엔드 검색을 실행하여 결과를 반환하기 전에 검색을 내부적으로 개선할 수 있습니다. Claude는 `allowed_domains`으로 특정 호스트만 포함하거나 `blocked_domains`으로 제외하여 결과의 범위를 지정할 수 있습니다. 두 목록은 단일 호출에서 결합할 수 없습니다.728이 도구는 호출당 최대 8개의 백엔드 검색을 실행하여 결과를 반환하기 전에 검색을 내부적으로 개선할 수 있습니다. Claude는 `allowed_domains`으로 특정 호스트만 포함하거나 `blocked_domains`으로 제외하여 결과의 범위를 지정할 수 있습니다. 두 목록은 단일 호출에서 결합할 수 없습니다.

729 729

730검색 요청이 과부하 상태의 API에 도달하면 Claude Code는 백오프를 사용하여 재시도합니다. 여전히 실패하는 호출은 오류 결과를 반환합니다. v2.1.212 이전에는 API 오류 텍스트가 검색 결과인 것처럼 Claude에 도달할 수 있었습니다.730검색 요청이 과부하 상태의 API에 도달하면 Claude Code는 백오프를 사용하여 재시도합니다. 여전히 실패하는 호출은 오류 결과를 반환합니다.

731 731

732WebSearch 권한 규칙은 지정자를 사용하지 않습니다. `allow` 또는 `deny`의 단순한 `WebSearch` 항목이 유일한 형식입니다.732WebSearch 권한 규칙은 지정자를 사용하지 않습니다. `allow` 또는 `deny`의 단순한 `WebSearch` 항목이 유일한 형식입니다.

733 733

741 세션 검색 제한741 세션 검색 제한

742</h3>742</h3>

743 743

744대화형 터미널 세션에는 200개의 WebSearch 호출 제한이 있습니다. 주 대화와 병렬 연구 팬아웃 같은 [서브에이전트](/docs/ko/sub-agents)에서 수행한 검색은 동일한 제한에 합산됩니다. 이 제한에는 Claude Code v2.1.212 이상이 필요합니다.744대화형 터미널 세션에는 200개의 WebSearch 호출 제한이 있습니다. 주 대화와 병렬 연구 팬아웃 같은 [서브에이전트](/docs/ko/sub-agents)에서 수행한 검색은 동일한 제한에 합산됩니다.

745 745

746세션이 제한에 도달한 동안에는 검색이 대화에 아무것도 하지 않은 호출로 표시됩니다. Claude는 이미 수집한 정보로 계속 진행하고, 더 많은 검색이 필요한 경우 사용자에게 제한을 높이도록 요청하라는 알림을 받습니다.746세션이 제한에 도달한 동안에는 검색이 대화에 아무것도 하지 않은 호출로 표시됩니다. Claude는 이미 수집한 정보로 계속 진행하고, 답변에서 그 사실을 밝히며, 더 많은 검색이 필요한 경우 사용자에게 제한을 높이도록 요청하라는 알림을 받습니다.

747 747

748더 많은 검색을 하려면 상한을 높이거나, 제한이 다시 채워질 때까지 기다리거나, 새 대화를 시작합니다:748더 많은 검색을 하려면 상한을 높이거나, 제한이 다시 채워질 때까지 기다리거나, 새 대화를 시작합니다:

749 749

troubleshooting.md +1 −0

Details

15| 로그인 루프, OAuth 오류, `403 Forbidden`, "organization disabled", Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry 자격 증명 | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#login-and-authentication) |15| 로그인 루프, OAuth 오류, `403 Forbidden`, "organization disabled", Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry 자격 증명 | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#login-and-authentication) |

16| 설정이 적용되지 않음, hooks가 실행되지 않음, MCP 서버가 로드되지 않음 | [구성 디버깅](/docs/ko/debug-your-config) |16| 설정이 적용되지 않음, hooks가 실행되지 않음, MCP 서버가 로드되지 않음 | [구성 디버깅](/docs/ko/debug-your-config) |

17| 세션이 자동 모드에서 시작되었거나 Claude가 묻지 않고 파일을 편집하고 명령을 실행함 | [세션이 시작되는 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in) |17| 세션이 자동 모드에서 시작되었거나 Claude가 묻지 않고 파일을 편집하고 명령을 실행함 | [세션이 시작되는 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in) |

18| Claude Code 또는 Agent SDK를 업데이트한 후 `--permission-mode`, `permissionMode` 또는 `permission_mode`를 전달하지 않는 `claude -p` 또는 SDK 실행에서 도구 호출이 거부됨 | [`claude -p` 및 Agent SDK 실행에서 거부되는 도구 호출](/docs/ko/permission-modes#which-mode-a-non-interactive-run-starts-in) |

18| `API Error: 5xx`, `529 Overloaded`, `429`, 요청 검증 오류 | [오류 참조](/docs/ko/errors) |19| `API Error: 5xx`, `529 Overloaded`, `429`, 요청 검증 오류 | [오류 참조](/docs/ko/errors) |

19| `model not found` 또는 `you may not have access to it` | [오류 참조](/docs/ko/errors#theres-an-issue-with-the-selected-model) |20| `model not found` 또는 `you may not have access to it` | [오류 참조](/docs/ko/errors#theres-an-issue-with-the-selected-model) |

20| Claude가 실행하는 명령이 `Your disk quota is full`, `is full (ENOSPC)` 또는 `Command output was lost`로 실패함 | [오류 참조](/docs/ko/errors#disk-quota-or-temp-filesystem-is-full) |21| Claude가 실행하는 명령이 `Your disk quota is full`, `is full (ENOSPC)` 또는 `Command output was lost`로 실패함 | [오류 참조](/docs/ko/errors#disk-quota-or-temp-filesystem-is-full) |

vs-code.md +24 −8

Details

268 268

269Claude Code 패널 상단의 **Session history** 버튼을 클릭하여 대화 기록에 접근합니다. 키워드로 검색하거나 시간별로 찾아볼 수 있습니다.269Claude Code 패널 상단의 **Session history** 버튼을 클릭하여 대화 기록에 접근합니다. 키워드로 검색하거나 시간별로 찾아볼 수 있습니다.

270 270

271대화를 클릭하면 전체 메시지 기록과 함께 재개됩니다. 대화가 현재 창의 다른 탭에 이미 열려 있으면 클릭 시 해당 탭으로 전환됩니다. 처음에 메시지가 비어 있다면 [비어 있는 이유와 표시되는 시점](#a-resumed-conversation-is-blank-at-first)을 참조하세요. 세션 재개에 대한 자세한 내용은 [세션 관리](/docs/ko/sessions)를 참조하세요.271대화를 클릭하면 재개됩니다. 대화가 현재 창의 다른 탭에 이미 열려 있으면 클릭 시 해당 탭으로 전환됩니다. 메시지가 표시되지 않은 채로 대화가 열리면 [재개한 대화가 처음에 비어 있는 이유](#a-resumed-conversation-is-blank-at-first)를 참조하세요. 세션 재개에 대한 자세한 내용은 [세션 관리](/docs/ko/sessions)를 참조하세요.

272 272

273* **세션 제목**: 새 세션은 첫 메시지를 기반으로 AI가 생성한 제목을 받습니다.273* **세션 제목**: 새 세션은 첫 메시지를 기반으로 AI가 생성한 제목을 받습니다.

274* **이름 변경 및 보관**: 세션 위에 마우스를 올리면 이러한 작업이 나타납니다. 이름을 변경하여 설명적인 제목을 부여하거나, 보관하여 목록 하단의 **Archived sessions** 그룹으로 이동합니다.274* **이름 변경 및 보관**: 세션 위에 마우스를 올리면 이러한 작업이 나타납니다. 이름을 변경하여 설명적인 제목을 부여하거나, 보관하여 목록 하단의 **Archived sessions** 그룹으로 이동합니다.

414 414

415대화를 로드하는 중에 패널이 충돌하거나 응답을 멈춘 경우, 또는 대화가 열린 후 약 3초 이내에 창을 다시 로드하거나 닫은 경우 열기가 완료되지 않습니다. 대화 자체는 변경되지 않으며 [세션 기록](#resume-past-conversations)에 그대로 남아 있습니다.415대화를 로드하는 중에 패널이 충돌하거나 응답을 멈춘 경우, 또는 대화가 열린 후 약 3초 이내에 창을 다시 로드하거나 닫은 경우 열기가 완료되지 않습니다. 대화 자체는 변경되지 않으며 [세션 기록](#resume-past-conversations)에 그대로 남아 있습니다.

416 416

417* **그래도 열려면**: **Open it anyway**를 클릭하거나 세션 기록에서 대화를 선택합니다. 대화가 열리고 패널이 계속 정상적으로 작동하면, 이후 다시 로드할 때 평소처럼 대화가 다시 열립니다. 패널이 다시 응답을 멈추면 창을 다시 로드하여 알림이 있는 새 채팅으로 돌아갑니다.417* **그래도 열려면**: **Open it anyway**를 클릭하거나 세션 기록에서 대화를 선택합니다. 대화가 완전히 열리면 이후 다시 로드할 때 [평소처럼 다시 열립니다](#continue-conversations-after-a-reload).

418* **대화를 로드하는 중에 패널이 응답을 멈춘 경우**: 창을 다시 로드합니다. 새 채팅이 열립니다.

418* **닫힌 상태로 두려면**: 새 채팅에서 계속 작업합니다. 프롬프트를 보내면 알림이 사라집니다.419* **닫힌 상태로 두려면**: 새 채팅에서 계속 작업합니다. 프롬프트를 보내면 알림이 사라집니다.

419 420

420<h3 id="run-multiple-conversations">421<h3 id="run-multiple-conversations">

556 패널에 그리는 플러그인557 패널에 그리는 플러그인

557</h3>558</h3>

558 559

559[mod](/docs/ko/plugins/mods/overview)를 포함하는 플러그인은 채팅 패널에 그릴 수 있습니다. 그리기 기능을 사용하려면 확장 프로그램 버전 2.1.299 이상과 [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션이 필요합니다. 이러한 플러그인에서는 다음을 볼 수 있습니다.560[mod](/docs/ko/plugins/mods/overview)를 포함하는 플러그인은 채팅 패널에 그릴 수 있습니다. 그리기 기능을 사용하려면 확장 프로그램 버전 2.1.299 이상이 필요합니다. Amazon Bedrock 세션처럼 [기능 플래그를 가져오지 않는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에는 2.1.304 이상이 필요합니다. 이러한 플러그인에서는 다음을 볼 수 있습니다.

560 561

561* 대화 옆 또는 프롬프트 상자 위의 창562* 대화 옆 또는 프롬프트 상자 위의 창

562* 프롬프트 상자 위의 토스트 또는 상태줄563* 프롬프트 상자 위의 토스트 또는 상태줄

624 625

625명령이나 [서브에이전트](/docs/ko/sub-agents) 때문에 Claude가 원하는 것보다 오래 기다리고 있다면, 대화에서 해당 도구 호출 아래에 있는 **Run in background**를 클릭합니다. Claude Code v2.1.287 이상이 필요합니다.626명령이나 [서브에이전트](/docs/ko/sub-agents) 때문에 Claude가 원하는 것보다 오래 기다리고 있다면, 대화에서 해당 도구 호출 아래에 있는 **Run in background**를 클릭합니다. Claude Code v2.1.287 이상이 필요합니다.

626 627

627* **표시 시점**: 이 동작은 명령이 약 2초 동안 실행된 후, 또는 서브에이전트가 시작되는 즉시 나타납니다.628* **표시 시점**: 이 동작은 명령이 약 2초 동안 실행된 후, 또는 Claude가 메인 대화에서 생성한 [서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)를 기다리기 시작하는 즉시 나타납니다.

628* **클릭한 후**: Claude는 기다리는 것을 멈추고 턴을 계속 진행합니다. 명령 또는 서브에이전트는 완료 시 Claude에게 알리는 [백그라운드 작업](/docs/ko/tools-reference#background-commands)으로 계속 실행됩니다.629* **클릭한 후**: Claude는 기다리는 것을 멈추고 턴을 계속 진행합니다. 명령 또는 서브에이전트는 완료 시 Claude에게 알리는 [백그라운드 작업](/docs/ko/tools-reference#background-commands)으로 계속 실행됩니다.

629 630

630그동안 작업 상태를 확인하거나 작업을 중지하려면 프롬프트 상자에 `/tasks`를 입력하여 [에이전트 맵](#use-the-prompt-box)을 엽니다. 서브에이전트는 그곳의 에이전트 트리에서 자신의 위치를 유지하며, 명령은 에이전트 아래에 나열되고 [카드에 최신 출력](#monitor-background-processes)이 표시됩니다.631그동안 작업 상태를 확인하거나 작업을 중지하려면 프롬프트 상자에 `/tasks`를 입력하여 [에이전트 맵](#use-the-prompt-box)을 엽니다. 서브에이전트는 그곳의 에이전트 트리에서 자신의 위치를 유지하며, 명령은 에이전트 아래에 나열되고 [카드에 최신 출력](#monitor-background-processes)이 표시됩니다.

631 632

633<h4 id="the-run-in-background-action-is-missing-under-a-subagent">

634 서브에이전트 아래에 Run in background 동작이 없는 경우

635</h4>

636

637VS Code에서는 기본적으로 서브에이전트에 이 동작이 표시되지 않습니다. 특정 서브에이전트에 표시되지 않는 이유를 확인하려면 [에이전트 맵](#use-the-prompt-box)에서 해당 카드를 열고 `Spawned by` 줄을 확인합니다.

638

639* **`Spawned by the main agent`**: 서브에이전트가 백그라운드에서 시작되었으므로 Claude가 이를 기다리지 않으며, 별도로 조치할 필요가 없습니다. Claude가 서브에이전트를 기다리도록 하려면 [Claude가 서브에이전트를 기다리도록 하기](/docs/ko/sub-agents#let-claude-wait-for-a-subagent)를 참조하세요.

640* **`Spawned by`에 다른 서브에이전트 이름이 표시되는 경우**: 이 동작은 메인 에이전트가 생성한 서브에이전트에만 나타나며, 다른 서브에이전트가 기다리고 있는 [중첩 서브에이전트](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)에는 나타나지 않습니다. 중첩 서브에이전트를 일찍 종료하려면 해당 카드에서 **Stop agent**를 클릭합니다. 그러면 기다리던 서브에이전트는 해당 결과 없이 계속 진행합니다.

641

632<h3 id="monitor-background-processes">642<h3 id="monitor-background-processes">

633 백그라운드 프로세스 모니터링하기643 백그라운드 프로세스 모니터링하기

634</h3>644</h3>

1028 1038

1029주변의 다른 수식은 조판되는데 특정 수식 하나만 작성된 그대로 표시된다면 다음 원인을 확인하십시오.1039주변의 다른 수식은 조판되는데 특정 수식 하나만 작성된 그대로 표시된다면 다음 원인을 확인하십시오.

1030 1040

1031* **수식이 아닌 다른 것으로 읽히는 경우**: `$O(n log n)$`처럼 단어로 읽히는 `$…$` 텍스트는 작성된 그대로 유지됩니다. `$30$`이나 `$1/N$`처럼 숫자로 시작하는 `$…$` 텍스트도 `=`, `+`, `^` 같은 문자가 수식임을 표시하지 않는 한 작성된 그대로 유지됩니다. 대신 별도의 줄에 `$$` 블록으로 작성해 달라고 Claude에게 요청하십시오. 패널은 이 검사 없이 해당 블록을 조판합니다.1041* **인라인 수식을 패널이 수식으로 처리하지 않는 경우**: 별도의 줄에 `$$` 블록으로 다시 보내 달라고 Claude에게 요청하십시오. 패널은 `$…$` 구분 기호 사이의 텍스트가 다음에 해당하면 인라인 수식을 작성된 그대로 둡니다.

1032* **공백이 있거나, 길거나, 여러 줄로 나뉜 경우**: 달러 기호 안쪽에 공백이 있는 `$ x^2 $`, 60자를 넘는 `$…$` 내용, 두 줄로 나뉜 `$…$` 또는 `$…$`는 조판되지 않습니다. 대신 별도의 줄에 `$$` 블록으로 작성해 달라고 Claude에게 요청하십시오. 해당 블록에는 이러한 제한이 없습니다.1042 * `$O(n log n)$`처럼 단순한 산술 이상이지만 `=`, `+`, `^` 같이 수식임을 표시하는 문자가 없는 경우

1033* **TeX를 조판할 수 없는 경우**: 구문 오류가 있는 수식, `\newcommand`나 `\def` 같은 매크로 정의, 이스케이프되지 않은 `%`는 작성된 그대로 표시됩니다. 오류를 수정하거나, 매크로 없이 작성하거나, 퍼센트 기호에 `\%`를 사용하여 다시 작성해 달라고 Claude에게 요청하십시오.1043 * `$30$`, `$1/N$`처럼 숫자로 시작하고 그러한 문자가 없는 경우

1034* **너무 큰 경우**: 8,192자보다 긴 수식이나 소스보다 훨씬 크게 그려지는 수식은 작성된 그대로 표시됩니다. 더 작은 수식으로 나누거나 더 간결하게 작성해 달라고 Claude에게 요청하십시오.1044 * `$ x^2 $`처럼 달러 기호 안쪽에 공백이 있는 경우

1045 * 60자보다 긴 경우

1046 * 두 줄로 나뉜 경우. 두 줄로 나뉜 `$…$` 수식도 조판되지 않습니다.

1047* **수식에 TeX 구문 오류가 있는 경우**: 오류를 수정하여 다시 작성해 달라고 Claude에게 요청하십시오.

1048* **수식이 매크로를 정의하는 경우**: `\newcommand`나 `\def` 같은 매크로 정의가 있는 수식은 작성된 그대로 표시됩니다. 매크로 없이 다시 작성해 달라고 Claude에게 요청하십시오.

1049* **수식에 이스케이프되지 않은 `%`가 포함된 경우**: 퍼센트 기호에 `\%`를 사용하여 다시 작성해 달라고 Claude에게 요청하십시오.

1050* **수식이 너무 큰 경우**: 8,192자보다 긴 수식이나 조판된 출력이 TeX 소스보다 훨씬 커지는 수식은 작성된 그대로 표시됩니다. 더 작은 수식으로 나누거나 더 간결하게 작성해 달라고 Claude에게 요청하십시오.

1035* **많은 양의 수식 뒤에 오는 경우**: 응답의 한 텍스트 블록 안에서 패널은 한도까지 수식을 순서대로 조판합니다. 한도를 넘어서는 이후 수식은 작성된 그대로 표시됩니다. 필요한 수식만 따로 다시 보내 달라고 Claude에게 요청하십시오.1051* **많은 양의 수식 뒤에 오는 경우**: 응답의 한 텍스트 블록 안에서 패널은 한도까지 수식을 순서대로 조판합니다. 한도를 넘어서는 이후 수식은 작성된 그대로 표시됩니다. 필요한 수식만 따로 다시 보내 달라고 Claude에게 요청하십시오.

1036 1052

1037<h3 id="claude-code-never-responds">1053<h3 id="claude-code-never-responds">

whats-new/2026-w20.md +2 −2

Details

78 <p className="digest-wins-title">기타 개선 사항</p>78 <p className="digest-wins-title">기타 개선 사항</p>

79 79

80 <div className="digest-wins-grid">80 <div className="digest-wins-grid">

81 <div><code>claude agents</code>는 백그라운드 세션을 구성하기 위한 발송 플래그(<code>--add-dir</code>, <code>--settings</code>, <code>--mcp-config</code>, <code>--plugin-dir</code>, <code>--permission-mode</code>, <code>--model</code>, <code>--effort</code>, <code>--dangerously-skip-permissions</code>)를 얻었으며, <code>claude agents --cwd \<path></code>는 세션 목록을 디렉토리로 범위 지정합니다</div>81 <div><code>claude agents</code>는 백그라운드 세션을 구성하기 위한 발송 플래그(`--add-dir`, `--settings`, `--mcp-config`, `--plugin-dir`, `--permission-mode`, `--model`, `--effort`, `--dangerously-skip-permissions`)를 얻었으며, `claude agents --cwd <path>`는 세션 목록을 디렉토리로 범위 지정합니다</div>

82 <div>새로운 훅 <code>args: string\[]</code> exec 형식은 셸 없이 명령을 직접 생성하므로 경로 자리 표시자는 절대 따옴표가 필요하지 않습니다</div>82 <div>새로운 훅 <code>args: string\[]</code> exec 형식은 셸 없이 명령을 직접 생성하므로 경로 자리 표시자는 절대 따옴표가 필요하지 않습니다</div>

83 <div><code>PostToolUse</code> 훅에 대한 새로운 <code>continueOnBlock</code> 구성 옵션은 훅의 거부 이유를 Claude에게 다시 피드하고 턴을 종료하는 대신 계속합니다</div>83 <div><code>PostToolUse</code> 훅에 대한 새로운 <code>continueOnBlock</code> 구성 옵션은 훅의 거부 이유를 Claude에게 다시 피드하고 턴을 종료하는 대신 계속합니다</div>

84 <div>훅 JSON 출력의 새로운 <code>terminalSequence</code> 필드를 사용하면 훅이 제어 터미널 없이 데스크톱 알림, 창 제목 및 벨을 내보낼 수 있습니다</div>84 <div>훅 JSON 출력의 새로운 <code>terminalSequence</code> 필드를 사용하면 훅이 제어 터미널 없이 데스크톱 알림, 창 제목 및 벨을 내보낼 수 있습니다</div>

85 <div>Rewind 메뉴에 "여기까지 요약"이 추가되어 최근 턴을 유지하면서 이전 컨텍스트를 압축합니다</div>85 <div>Rewind 메뉴에 "여기까지 요약"이 추가되어 최근 턴을 유지하면서 이전 컨텍스트를 압축합니다</div>

86 <div>Remote Control, <code>/schedule</code>, Claude.ai MCP 커넥터 및 알림 기본 설정은 <code>ANTHROPIC\_API\_KEY</code>, <code>apiKeyHelper</code> 또는 <code>ANTHROPIC\_AUTH\_TOKEN</code>이 설정되면 Claude.ai 로그인과 함께 비활성화됩니다. API 키를 설정 해제하여 이러한 기능을 사용합니다</div>86 <div>Remote Control, <code>/schedule</code>, claude.ai MCP 커넥터 및 알림 기본 설정은 <code>ANTHROPIC\_API\_KEY</code>, <code>apiKeyHelper</code> 또는 <code>ANTHROPIC\_AUTH\_TOKEN</code>이 설정되면 claude.ai 로그인과 함께 비활성화됩니다. API 키를 설정 해제하여 이러한 기능을 사용합니다</div>

87 <div>MCP stdio 서버는 이제 훅과 일치하는 환경에서 <code>CLAUDE\_PROJECT\_DIR</code>을 수신하며, 플러그인 구성은 명령에서 <code>\${"{"}CLAUDE\_PROJECT\_DIR{"}"}</code>을 참조할 수 있습니다</div>87 <div>MCP stdio 서버는 이제 훅과 일치하는 환경에서 <code>CLAUDE\_PROJECT\_DIR</code>을 수신하며, 플러그인 구성은 명령에서 <code>\${"{"}CLAUDE\_PROJECT\_DIR{"}"}</code>을 참조할 수 있습니다</div>

88 <div><code>claude plugin details \<name></code>은 플러그인의 구성 요소 인벤토리 및 예상 세션당 토큰 비용을 표시하며, <code>/plugin</code> 세부 정보 창은 이제 플러그인이 제공하는 LSP 서버도 나열합니다</div>88 <div><code>claude plugin details \<name></code>은 플러그인의 구성 요소 인벤토리 및 예상 세션당 토큰 비용을 표시하며, <code>/plugin</code> 세부 정보 창은 이제 플러그인이 제공하는 LSP 서버도 나열합니다</div>

89 <div>루트 수준 <code>SKILL.md</code>가 있고 <code>skills/</code> 하위 디렉토리가 없는 플러그인은 이제 기술로 표시됩니다</div>89 <div>루트 수준 <code>SKILL.md</code>가 있고 <code>skills/</code> 하위 디렉토리가 없는 플러그인은 이제 기술로 표시됩니다</div>

workflows.md +0 −4

Details

153* 예약된 작업 프롬프트153* 예약된 작업 프롬프트

154* 대화로 중계된 웹훅 페이로드 또는 풀 요청 댓글154* 대화로 중계된 웹훅 페이로드 또는 풀 요청 댓글

155 155

156<Note>

157 v2.1.210 이전에는 키워드가 웹훅 페이로드 또는 풀 요청 댓글이 대화로 중계되는 경우를 포함하여 이러한 모든 경로에서 워크플로우를 시작했습니다.

158</Note>

~~159~~

160<h3 id="let-claude-decide-with-ultracode">156<h3 id="let-claude-decide-with-ultracode">

161 ultracode로 Claude가 결정하도록 하기157 ultracode로 Claude가 결정하도록 하기

162</h3>158</h3>

worktrees.md +6 −3

Details

9[git worktree](https://git-scm.com/docs/git-worktree)는 자체 파일과 브랜치를 가진 별도의 작업 디렉터리이며, 메인 체크아웃과 동일한 저장소 히스토리 및 원격을 공유합니다. 각 Claude Code 세션을 자체 worktree에서 실행하면 세션마다 편집할 파일의 별도 사본이 주어지므로, 한 세션이 기능을 구축하는 동안 두 번째 세션이 버그를 수정할 수 있습니다.9[git worktree](https://git-scm.com/docs/git-worktree)는 자체 파일과 브랜치를 가진 별도의 작업 디렉터리이며, 메인 체크아웃과 동일한 저장소 히스토리 및 원격을 공유합니다. 각 Claude Code 세션을 자체 worktree에서 실행하면 세션마다 편집할 파일의 별도 사본이 주어지므로, 한 세션이 기능을 구축하는 동안 두 번째 세션이 버그를 수정할 수 있습니다.

10 10

11<Note>11<Note>

12 Worktree는 git 저장소가 필요합니다. 다른 버전 관리 시스템의 경우 [훅을 구성하여 git 로직을 대체](#non-git-version-control)합니다. [데스크톱 앱](/docs/ko/desktop#work-in-parallel-with-sessions)에서는 세션을 시작할 때 **worktree** 옵션을 선택하여 자체 worktree를 제공합니다.12 다른 버전 관리 시스템이나 데스크톱 앱을 사용하는 경우 해당 환경에 맞는 지침을 따릅니다.

14 * **다른 버전 관리 시스템**: worktree는 git 저장소가 필요합니다. [훅을 구성하여 git 로직을 대체](#non-git-version-control)합니다

15 * **데스크톱 앱**: [자체 worktree에서 세션 실행](/docs/ko/desktop#run-a-session-in-its-own-worktree)을 참조합니다

13</Note>16</Note>

14 17

15Worktree는 Claude를 병렬로 실행하는 여러 방법 중 하나입니다. 이들은 파일 편집을 격리합니다. [서브에이전트](/docs/ko/sub-agents)는 한 세션 내에서 작업을 분할하고, [크로스 세션 메시징](/docs/ko/cross-session-messaging)을 통해 Claude는 worktree의 세션 간에 발견 사항을 전달할 수 있습니다. [Claude를 병렬로 실행](/docs/ko/agents)을 참조하여 접근 방식을 비교하거나, [worktree로 서브에이전트 격리](#isolate-subagents-with-worktrees)로 건너뛰어 worktree와 서브에이전트를 함께 사용합니다.18Worktree는 Claude를 병렬로 실행하는 여러 방법 중 하나입니다. 이들은 파일 편집을 격리합니다. [서브에이전트](/docs/ko/sub-agents)는 한 세션 내에서 작업을 분할하고, [크로스 세션 메시징](/docs/ko/cross-session-messaging)을 통해 Claude는 worktree의 세션 간에 발견 사항을 전달할 수 있습니다. [Claude를 병렬로 실행](/docs/ko/agents)을 참조하여 접근 방식을 비교하거나, [worktree로 서브에이전트 격리](#isolate-subagents-with-worktrees)로 건너뛰어 worktree와 서브에이전트를 함께 사용합니다.

270 273

271이 모든 것들은 `--worktree`로 worktree를 생성했든, `git worktree add`로 생성했든 적용됩니다.274이 모든 것들은 `--worktree`로 worktree를 생성했든, `git worktree add`로 생성했든 적용됩니다.

272 275

273[데스크톱 앱](/docs/ko/desktop#work-in-parallel-with-sessions)에서 시작한 worktree 세션에서 Claude Code는 설정, 훅, 스킬, 에이전트, 명령, [`.mcp.json`](/docs/ko/mcp#project-scope) 서버와 같은 프로젝트 구성을 worktree가 아닌 메인 체크아웃의 루트에서 읽습니다. 훅 명령은 해당 루트에서 실행되며, `${CLAUDE_PROJECT_DIR}`는 해당 루트를 가리킵니다. Claude가 작업 중인 파일에 접근하려면 훅의 [`cwd` 입력 필드](/docs/ko/hooks#common-input-fields)에서 worktree의 경로를 읽습니다. `CLAUDE.md` 파일과 `.claude/rules/`는 여전히 worktree에서 로드됩니다.276[데스크톱 앱](/docs/ko/desktop#run-a-session-in-its-own-worktree)에서 시작한 worktree 세션에서 Claude Code는 설정, 훅, 스킬, 에이전트, 명령, [`.mcp.json`](/docs/ko/mcp#project-scope) 서버와 같은 프로젝트 구성을 메인 체크아웃의 루트에서 읽습니다. 훅 명령은 해당 루트에서 실행되며, `${CLAUDE_PROJECT_DIR}`는 해당 루트를 가리킵니다. Claude가 작업 중인 파일에 접근하려면 훅의 [`cwd` 입력 필드](/docs/ko/hooks#common-input-fields)에서 worktree의 경로를 읽습니다. `CLAUDE.md` 파일과 `.claude/rules/`는 여전히 worktree에서 로드됩니다.

274 277

275<h2 id="manage-worktrees-manually">278<h2 id="manage-worktrees-manually">

276 worktree 수동 관리279 worktree 수동 관리

434* [크로스 세션 메시징](/docs/ko/cross-session-messaging): worktree의 세션이 서로 발견 사항을 전달하도록 허용437* [크로스 세션 메시징](/docs/ko/cross-session-messaging): worktree의 세션이 서로 발견 사항을 전달하도록 허용

435* [에이전트 팀](/docs/ko/agent-teams): 여러 Claude 세션을 자동으로 조정438* [에이전트 팀](/docs/ko/agent-teams): 여러 Claude 세션을 자동으로 조정

436* [세션 관리](/docs/ko/sessions): 대화 이름 지정, 재개 및 전환439* [세션 관리](/docs/ko/sessions): 대화 이름 지정, 재개 및 전환

437* [데스크톱 병렬 세션](/docs/ko/desktop#work-in-parallel-with-sessions): 데스크톱 앱의 worktree 기반 세션440* [자체 worktree에서 데스크톱 세션 실행](/docs/ko/desktop#run-a-session-in-its-own-worktree): 데스크톱 앱의 worktree 기반 세션

Documentation 2026-10-18 22:59 UTC to 2026-10-19 23:58 UTC