Documentation — Spybara

agent-sdk/agent-loop.md +7 −1

Details

216| 옵션 | 제어 대상 | 기본값 |216| 옵션 | 제어 대상 | 기본값 |

217| :- | :- | :- |217| :- | :- | :- |

220 220

221제한 중 하나에 도달하면 SDK는 해당 오류 서브타입(`error_max_turns` 또는 `error_max_budget_usd`)이 있는 `ResultMessage`를 반환합니다. 이러한 서브타입을 확인하는 방법은 [결과 처리](#handle-the-result)를 참조하고, 구문은 [`ClaudeAgentOptions`](/docs/ko/agent-sdk/python#claudeagentoptions) / [`Options`](/docs/ko/agent-sdk/typescript#options)를 참조하세요.221제한 중 하나에 도달하면 SDK는 해당 오류 서브타입(`error_max_turns` 또는 `error_max_budget_usd`)이 있는 `ResultMessage`를 반환합니다. 이러한 서브타입을 확인하는 방법은 [결과 처리](#handle-the-result)를 참조하고, 구문은 [`ClaudeAgentOptions`](/docs/ko/agent-sdk/python#claudeagentoptions) / [`Options`](/docs/ko/agent-sdk/typescript#options)를 참조하세요.

222 222

224 224

225[스트리밍 입력](/docs/ko/agent-sdk/streaming-vs-single-mode)을 사용하면 턴이 최대 턴 제한에서 끝날 때 실행 중인 메시지는 대기열에 남아 있습니다. Claude Code는 이를 해당 턴의 마지막 모델 호출에 추가하지 않습니다. 메시지에 대해 새로운 턴을 시작하고, 해당 턴에 대해 최대 턴 수가 다시 시작됩니다. 예산 총액은 메시지 전체에 계속 누적되며, 지출이 `maxBudgetUsd`에 도달하면 같은 대화의 이후 메시지는 `error_max_budget_usd` 결과로 끝납니다. [`/clear`](/docs/ko/agent-sdk/cost-tracking)는 예산을 다시 시작합니다.225[스트리밍 입력](/docs/ko/agent-sdk/streaming-vs-single-mode)을 사용하면 턴이 최대 턴 제한에서 끝날 때 실행 중인 메시지는 대기열에 남아 있습니다. Claude Code는 이를 해당 턴의 마지막 모델 호출에 추가하지 않습니다. 메시지에 대해 새로운 턴을 시작하고, 해당 턴에 대해 최대 턴 수가 다시 시작됩니다. 예산 총액은 메시지 전체에 계속 누적되며, 지출이 `maxBudgetUsd`에 도달하면 같은 대화의 이후 메시지는 `error_max_budget_usd` 결과로 끝납니다. [`/clear`](/docs/ko/agent-sdk/cost-tracking)는 예산을 다시 시작합니다.

226 226

227<h4 id="budget-headroom">

228 예산 여유분

229</h4>

230

231Claude Code는 모델 응답이 도착한 후에 지출을 `max_budget_usd` / `maxBudgetUsd` 상한과 비교합니다. 각 응답의 비용은 API가 응답과 함께 반환하는 토큰 사용량에서 산출되기 때문입니다. 상한에 도달하게 만든 응답은 그대로 완료되며 [`total_cost_usd`](/docs/ko/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)에 포함됩니다. 따라서 지출은 해당 응답 하나의 비용에 더해, 그 시점에 아직 실행 중인 서브에이전트가 중지되기 전까지 지출한 금액만큼 상한을 초과할 수 있습니다. 상한을 설정할 때는 이를 고려하여 여유분을 두세요.

232

227<h3 id="effort-level">233<h3 id="effort-level">

228 노력 수준234 노력 수준

229</h3>235</h3>

agent-sdk/mcp.md +9 −5

Details

78 78

79`query()` 호출 시 코드에서 MCP 서버를 구성하거나, [`settingSources`](#from-a-config-file)를 통해 로드되는 `.mcp.json` 파일에서 구성할 수 있습니다.79`query()` 호출 시 코드에서 MCP 서버를 구성하거나, [`settingSources`](#from-a-config-file)를 통해 로드되는 `.mcp.json` 파일에서 구성할 수 있습니다.

80 80

~~81<h3 id="in-code">~~81<span id="in-code" />

~~82 코드에서~~82

83<h3 id="add-a-server-in-code">

84 코드에서 서버 추가

83</h3>85</h3>

84 86

85`mcpServers` 옵션에서 MCP 서버를 직접 전달합니다. 이 예제는 `/Users/me/projects`에 대한 로컬 파일시스템 MCP 서버를 시작합니다. 해당 경로를 머신의 디렉토리로 바꾸세요:87`mcpServers` 옵션에서 MCP 서버를 직접 전달합니다. 이 예제는 `/Users/me/projects`에 대한 로컬 파일시스템 MCP 서버를 시작합니다. 해당 경로를 머신의 디렉토리로 바꾸세요:

135 ```137 ```

136</CodeGroup>138</CodeGroup>

137 139

138<h3 id="from-a-config-file">140<span id="from-a-config-file" />

139 구성 파일에서141

142<h3 id="add-a-server-from-a-config-file">

143 구성 파일에서 서버 추가

140</h3>144</h3>

141 145

142프로젝트 루트에 `.mcp.json` 파일을 생성합니다. 이 파일은 `project` 설정 소스가 활성화되어 있을 때 선택되며, 기본 `query()` 옵션에서는 활성화되어 있습니다. `settingSources`를 명시적으로 설정하는 경우, 이 파일이 로드되도록 `"project"`를 포함하세요. `/Users/me/projects`를 머신의 디렉토리로 바꾸세요:146프로젝트 루트에 `.mcp.json` 파일을 생성합니다. 이 파일은 `project` 설정 소스가 활성화되어 있을 때 선택되며, 기본 `query()` 옵션에서는 활성화되어 있습니다. `settingSources`를 명시적으로 설정하는 경우, 이 파일이 로드되도록 `"project"`를 포함하세요. `/Users/me/projects`를 머신의 디렉토리로 바꾸세요:

301 stdio 서버305 stdio 서버

302</h3>306</h3>

303 307

304stdin/stdout을 통해 통신하는 로컬 프로세스입니다. 동일한 머신에서 실행하는 MCP 서버에 이를 사용하세요. `.mcp.json` 형식의 경우, [설정 파일에서](#from-a-config-file) 표시된 동일한 필드를 사용하세요. 코드에서는 명령어와 해당 인수를 전달하세요. `/Users/me/projects`를 머신의 디렉터리로 바꾸세요:308stdin/stdout을 통해 통신하는 로컬 프로세스입니다. 동일한 머신에서 실행하는 MCP 서버에 이를 사용하세요. `.mcp.json` 형식의 경우, [설정 파일에서 서버 추가](#from-a-config-file)에 표시된 동일한 필드를 사용하세요. 코드에서는 명령과 해당 인수를 전달하세요. `/Users/me/projects`를 머신의 디렉터리로 바꾸세요:

305 309

306<CodeGroup>310<CodeGroup>

307 ```typescript TypeScript hidelines={1,-1} theme={null}311 ```typescript TypeScript hidelines={1,-1} theme={null}

agent-sdk/migration-guide.md +8 −4

Details

28 마이그레이션 단계28 마이그레이션 단계

29</h2>29</h2>

30 30

~~31<h3 id="for-typescript/javascript-projects">~~31<span id="for-typescript/javascript-projects" />

~~32 TypeScript/JavaScript 프로젝트의 경우~~32

33<h3 id="migrate-a-typescript-or-javascript-project">

34 TypeScript 또는 JavaScript 프로젝트 마이그레이션

33</h3>35</h3>

34 36

35**1. 기존 패키지 제거:**37**1. 기존 패키지 제거:**

64 66

65마이그레이션을 완료하기 위해 필요한 코드 변경을 수행합니다.67마이그레이션을 완료하기 위해 필요한 코드 변경을 수행합니다.

66 68

~~67<h3 id="for-python-projects">~~69<span id="for-python-projects" />

~~68 Python 프로젝트의 경우~~70

71<h3 id="migrate-a-python-project">

72 Python 프로젝트 마이그레이션

69</h3>73</h3>

70 74

71**1. 기존 패키지 제거:**75**1. 기존 패키지 제거:**

agent-sdk/permissions.md +1 −1

Details

146| `auto` | 모델 분류 승인 | 모델 분류기가 셸 명령 및 네트워크 요청과 같은 작업을 검토하여 각각을 허용하거나 차단합니다. 가용성은 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)를 참조하고 결정 순서를 확인하세요 |146| `auto` | 모델 분류 승인 | 모델 분류기가 셸 명령 및 네트워크 요청과 같은 작업을 검토하여 각각을 허용하거나 차단합니다. 가용성은 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)를 참조하고 결정 순서를 확인하세요 |

147 147

148<Warning>148<Warning>

149 **하위 에이전트 상속:** 하위 에이전트는 부모 세션의 권한 모드에서 실행됩니다. 단, [`AgentDefinition`](/docs/ko/agent-sdk/typescript#agentdefinition)에서 `permissionMode`를 설정하고 부모 세션이 `default`, `dontAsk` 또는 `plan` 모드에 있는 경우는 예외입니다. 이 경우에도 Claude Code는 `"bypassPermissions"` 값을 적용하지 않습니다. 하위 에이전트는 부모 세션 자체가 `bypassPermissions` 모드에 있을 때만 `bypassPermissions` 모드에서 실행됩니다. `bypassPermissions` 예외는 Claude Code v2.1.267 이상이 필요합니다.149 **서브에이전트 상속:** 서브에이전트는 부모 세션의 권한 모드에서 실행됩니다. 단, [`AgentDefinition`](/docs/ko/agent-sdk/typescript#agentdefinition)에서 `permissionMode`를 설정하고 부모 세션이 `default`, `dontAsk` 또는 `plan` 모드에 있는 경우는 예외입니다. 이 경우에도 Claude Code는 `"bypassPermissions"` 값을 적용하지 않으며, `"auto"` 값은 해당 서브에이전트에 [자동 모드를 사용할 수 있는 경우](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에만 적용합니다. 서브에이전트는 부모 세션 자체가 `bypassPermissions` 모드에 있을 때만 `bypassPermissions` 모드에서 실행됩니다. `bypassPermissions` 예외는 Claude Code v2.1.267 이상이 필요합니다.

150 150

151 하위 에이전트는 주 에이전트와 다른 시스템 프롬프트를 가질 수 있으며 덜 제한된 동작을 할 수 있으므로, `bypassPermissions` 상속은 전체 자율 시스템 액세스 권한을 부여합니다. [모드가 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)은 여전히 적용됩니다.151 하위 에이전트는 주 에이전트와 다른 시스템 프롬프트를 가질 수 있으며 덜 제한된 동작을 할 수 있으므로, `bypassPermissions` 상속은 전체 자율 시스템 액세스 권한을 부여합니다. [모드가 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)은 여전히 적용됩니다.

152</Warning>152</Warning>

agent-sdk/python.md +13 −10

Details

932| `disallowed_tools` | `list[str]` | `[]` | 거부할 도구. `"Bash"`와 같은 단순 이름은 Claude의 컨텍스트에서 도구를 제거합니다. `"Bash(rm *)"` 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고, `bypassPermissions`를 포함한 모든 권한 모드에서 [작성된 대로의](/docs/ko/permissions#bash-rule-limits) 명령과 일치하는 호출을 거부합니다. [권한](/docs/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |932| `disallowed_tools` | `list[str]` | `[]` | 거부할 도구. `"Bash"`와 같은 단순 이름은 Claude의 컨텍스트에서 도구를 제거합니다. `"Bash(rm *)"` 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고, `bypassPermissions`를 포함한 모든 권한 모드에서 [작성된 대로의](/docs/ko/permissions#bash-rule-limits) 명령과 일치하는 호출을 거부합니다. [권한](/docs/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |

987```987```

988 988

989* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청당 타임아웃 (밀리초). 기본값 `600000`. 주 루프 및 모든 서브에이전트에 적용됩니다.989* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청당 타임아웃 (밀리초). 기본값 `600000`. 주 루프 및 모든 서브에이전트에 적용됩니다.

990* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도. 기본값 `10`, 최대 `15`로 제한됨. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가지므로, 최악의 경우 벽시간은 대략 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 더하기 백오프입니다. 더 긴 중단을 기다려야 하는 무인 실행의 경우, [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/ko/errors#tune-retry-behavior)을 설정하여 일시적 용량 오류를 무한정 재시도합니다. 그리고 Claude Code v2.1.199 이상에서는 다른 일시적 오류의 기본값을 `300`으로 올리고 이 변수의 상한을 제거합니다.990* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도. 기본값 `10`, 최대 `15`로 제한됨. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가집니다.

991

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

991* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: 서브에이전트의 정지 감시견. 스트림 감시견이 켜져 있는 동안 기본값은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 더하기 5분이며, 이는 해당 변수를 올리지 않으면 `600000`입니다. 스트림 감시견이 꺼져 있으면 기본값은 `600000`입니다. v2.1.257 이전에는 기본값이 항상 `600000`이었습니다.993* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: 서브에이전트의 정지 감시견. 스트림 감시견이 켜져 있는 동안 기본값은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 더하기 5분이며, 이는 해당 변수를 올리지 않으면 `600000`입니다. 스트림 감시견이 꺼져 있으면 기본값은 `600000`입니다. v2.1.257 이전에는 기본값이 항상 `600000`이었습니다.

992 994

993 타이머는 각 스트림 이벤트에서 재설정됩니다. 정지 시 Claude Code는 서브에이전트를 중단하고 정지를 부모에게 보고합니다. 백그라운드 서브에이전트의 경우 작업을 실패로 표시하고 부분 결과를 첨부합니다.995 타이머는 각 스트림 이벤트에서 재설정됩니다. 정지 시 Claude Code는 서브에이전트를 중단하고 정지를 부모에게 보고합니다. 백그라운드 서브에이전트의 경우 작업을 실패로 표시하고 부분 결과를 첨부합니다.

2877 2879

2878서브에이전트의 결과를 반환합니다. 출력은 `status` 필드에서 구분됩니다: 완료된 작업의 경우 `"completed"`, 백그라운드 작업의 경우 `"async_launched"`, Claude Code가 클라우드 세션으로 전달한 작업의 경우 `"remote_launched"`. `sessionUrl`은 해당 세션으로 연결되고 `taskId`는 이를 식별합니다. Claude Code가 [서브에이전트의 격리된 worktree를 유지](/docs/ko/worktrees#isolate-subagents-with-worktrees)한 경우, `completed` 변형의 `worktreePath`는 이를 찾을 수 있는 위치이고, `worktreeBranch`는 Claude Code가 git으로 worktree를 생성했을 때의 브랜치입니다.2880서브에이전트의 결과를 반환합니다. 출력은 `status` 필드에서 구분됩니다: 완료된 작업의 경우 `"completed"`, 백그라운드 작업의 경우 `"async_launched"`, Claude Code가 클라우드 세션으로 전달한 작업의 경우 `"remote_launched"`. `sessionUrl`은 해당 세션으로 연결되고 `taskId`는 이를 식별합니다. Claude Code가 [서브에이전트의 격리된 worktree를 유지](/docs/ko/worktrees#isolate-subagents-with-worktrees)한 경우, `completed` 변형의 `worktreePath`는 이를 찾을 수 있는 위치이고, `worktreeBranch`는 Claude Code가 git으로 worktree를 생성했을 때의 브랜치입니다.

2879 2881

2880`completed` 변형에서 `resolvedModel`은 서브에이전트가 시작한 모델을 이름 지으며, 이는 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 또는 다른 오버라이드가 적용될 때 요청된 `model` 입력과 다를 수 있습니다. 이 필드는 Claude Code v2.1.174 이상이 필요합니다. `async_launched` 변형에서 `resolvedModel`은 에이전트가 백그라운드로 이동했을 때 사용 중인 모델을 이름 지으므로, 백그라운드 전환 전에 발생한 스왑이 반영됩니다. `modelsUsed` 필드는 두 변형 모두에서 순서대로 사용된 모델을 나열하며, 연속 반복은 축소됩니다. 실행 중에 모델이 교체되었을 때만 설정됩니다. `modelsUsed`와 백그라운드 시간 `resolvedModel` 동작은 Claude Code v2.1.212 이상이 필요합니다.2882`completed` 변형에서 `resolvedModel`은 서브에이전트가 시작한 모델을 이름 지으며, 이는 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 또는 다른 재정의가 적용될 때 요청된 `model` 입력과 다를 수 있습니다. 이 필드는 Claude Code v2.1.174 이상이 필요합니다. `async_launched` 변형에서 `resolvedModel`은 에이전트가 백그라운드로 이동했을 때 사용 중인 모델을 이름 지으므로, 백그라운드 전환 전에 발생한 스왑이 반영됩니다. `modelsUsed` 필드는 두 변형 모두에서 순서대로 사용된 모델을 나열하며, 연속 반복은 축소됩니다. 실행 중에 모델이 교체되었을 때만 설정됩니다. `modelsUsed`와 백그라운드 시간 `resolvedModel` 동작은 Claude Code v2.1.212 이상이 필요합니다.

2881 2883

2882Claude Code는 전체 실행이 아닌 서브에이전트의 최종 API 요청에서 `usage`와 `totalTokens`를 채웁니다. 존재할 때, `usage`의 `output_tokens_details` 아래 `thinking_tokens`은 해당 요청의 출력 토큰 중 사고 토큰의 수입니다. `output_tokens_details` 키는 Claude Code v2.1.228을 번들로 하는 Python SDK v0.2.136 이상이 필요합니다. `fallback_credit` 키는 Claude Code v2.1.285를 번들로 하는 Python SDK v0.2.162 이상이 필요합니다.2884Claude Code는 전체 실행이 아닌 서브에이전트의 최종 API 요청에서 `usage`와 `totalTokens`를 채웁니다. 존재할 때, `usage`의 `output_tokens_details` 아래 `thinking_tokens`은 해당 요청의 출력 토큰 중 사고 토큰의 수입니다. `output_tokens_details` 키는 Claude Code v2.1.228을 번들로 하는 Python SDK v0.2.136 이상이 필요합니다. `fallback_credit` 키는 Claude Code v2.1.285를 번들로 하는 Python SDK v0.2.162 이상이 필요합니다.

2883 2885

2935 # 다중 선택 답변은 쉼표로 구분됨2937 # 다중 선택 답변은 쉼표로 구분됨

2936 "response": str | None,2938 "response": str | None,

2937 # 질문에 답하는 대신 입력한 자유 형식 답변; 설정되면,2939 # 질문에 답하는 대신 입력한 자유 형식 답변; 설정되면,

2938 # Claude는 답변 목록 대신 "사용자가 응답했습니다: ..."를 받습니다2940 # Claude는 답변 목록 대신 "The user responded: ..."를 받습니다

2939 "annotations": dict[str, dict] | None, # 사용자의 선택에서 질문별 "preview"와 "notes"2941 "annotations": dict[str, dict] | None, # 사용자의 선택에서 질문별 "preview"와 "notes"

2940 "afkTimeoutMs": int | None, # 사용자 비활성 후 이 많은 밀리초 후 대화가 자동 해결되었을 때 설정됨; 사용자가 답변했을 때는 없음2942 "afkTimeoutMs": int | None, # 사용자 비활성 후 이 많은 밀리초 후 대화가 자동 해결되었을 때 설정됨; 사용자가 답변했을 때는 없음

2941}2943}

2947 2949

2948**도구 이름:** `Bash`2950**도구 이름:** `Bash`

2949 2951

2950전경 상한선을 설정하는 것에 대해서는 [시간 초과 및 출력 제한](/docs/ko/tools-reference#timeout-and-output-limits)을 참조하십시오. 백그라운드 시간 제한에 대해서는 [백그라운드 명령의 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands)을 참조하십시오.2952전경 상한선을 설정하는 것에 대해서는 [타임아웃 및 출력 제한](/docs/ko/tools-reference#timeout-and-output-limits)을 참조하십시오. 백그라운드 시간 제한에 대해서는 [백그라운드 명령의 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands)을 참조하십시오.

2951 2953

2952**입력:**2954**입력:**

2953 2955

2989 "command": str | None, # 셸 스크립트; 각 stdout 줄은 이벤트이고, 종료는 감시를 끝냅니다2991 "command": str | None, # 셸 스크립트; 각 stdout 줄은 이벤트이고, 종료는 감시를 끝냅니다

2990 "ws": dict | None, # WebSocket 소스: {"url": str, "protocols": list[str] | None}; 각 텍스트 프레임은 이벤트입니다2992 "ws": dict | None, # WebSocket 소스: {"url": str, "protocols": list[str] | None}; 각 텍스트 프레임은 이벤트입니다

2991 "description": str, # 알림에 표시되는 짧은 설명2993 "description": str, # 알림에 표시되는 짧은 설명

2992 "timeout_ms": int | None, # 이 기한 후 종료 (기본값 300000, 최대 3600000; 유효한 기한은 최대 1800000)2994 "timeout_ms": int | None, # 밀리초 단위의 기한 (기본값 300000, 최대 3600000; 유효한 기한은 최대 1800000)

2993}2995}

2994```2996```

2995 2997

3028 "oldString": str, # 바뀐 텍스트3030 "oldString": str, # 바뀐 텍스트

3029 "newString": str, # 이를 대체한 텍스트3031 "newString": str, # 이를 대체한 텍스트

3030 "originalFile": str | None, # 편집 전 파일 내용3032 "originalFile": str | None, # 편집 전 파일 내용

3031 "structuredPatch": [ # 변경에 대한 Diff 청크3033 "structuredPatch": [ # 변경에 대한 diff 청크

3032 {3034 {

3033 "oldStart": int,3035 "oldStart": int,

3034 "oldLines": int,3036 "oldLines": int,

3152 "file": {3154 "file": {

3153 "filePath": str,3155 "filePath": str,

3154 },3156 },

3155 "source": "seeded" | None, # 이전 복사본이 시작 시 로드된 CLAUDE.md 또는 메모리 파일에서 나온 경우 표시됨3157 "source": "seeded" | None, # 이전 복사본이 Read 호출이 아닌 시작 시 로드된 CLAUDE.md 또는 메모리 파일에서 나온 경우 표시됨

3156}3158}

3157```3159```

3158 3160

3178 "type": "create" | "update", # 쓰기가 새 파일을 생성했는지 또는 기존 파일을 덮어썼는지 여부3180 "type": "create" | "update", # 쓰기가 새 파일을 생성했는지 또는 기존 파일을 덮어썼는지 여부

3179 "filePath": str, # 쓴 파일3181 "filePath": str, # 쓴 파일

3180 "content": str, # 쓴 콘텐츠3182 "content": str, # 쓴 콘텐츠

3181 "structuredPatch": [ # Diff 청크; 새 파일, 아무것도 변경되지 않음, 또는 Claude Code가 diff를 건너뛴 경우 비어 있음3183 "structuredPatch": [ # diff 청크; 새 파일, 아무것도 변경되지 않음, 또는 Claude Code가 diff를 건너뛴 경우 비어 있음

3182 {3184 {

3183 "oldStart": int,3185 "oldStart": int,

3184 "oldLines": int,3186 "oldLines": int,

3327{3329{

3328 "url": str, # 콘텐츠를 가져올 URL3330 "url": str, # 콘텐츠를 가져올 URL

3329 "prompt": str, # 가져온 콘텐츠에서 실행할 프롬프트3331 "prompt": str, # 가져온 콘텐츠에서 실행할 프롬프트

3332 "offset": int | None, # 페이지 시작 부분에서 건너뛸 문자 수. Python Agent SDK 0.2.164 이상 필요

3330}3333}

3331```3334```

3332 3335

3546 TaskOutput3549 TaskOutput

3547</h3>3550</h3>

3548 3551

3549Claude Code v2.1.277에서 제거됨. 이전에는 실행 중이거나 완료된 백그라운드 작업의 출력을 검색했으며, `BashOutput`은 별칭으로 허용되었습니다. Claude는 `Read`를 사용하여 백그라운드 작업의 출력 파일을 읽습니다.3552Claude Code v2.1.277에서 제거되었습니다. 이전에는 실행 중이거나 완료된 백그라운드 작업의 출력을 검색했으며, `BashOutput`은 별칭으로 허용되었습니다. 이제 Claude는 `Read`를 사용하여 백그라운드 작업의 출력 파일을 읽습니다.

3550 3553

3551`disallowed_tools` 항목 또는 두 이름 중 하나를 여전히 지정하는 거부 규칙은 경고 없이 무시됩니다.3554`disallowed_tools` 항목 또는 두 이름 중 하나를 여전히 지정하는 거부 규칙은 경고 없이 무시됩니다.

3552 3555

agent-sdk/subagents.md +9 −2

Details

323 서브에이전트 호출 감지323 서브에이전트 호출 감지

324</h2>324</h2>

325 325

326Claude는 Agent 도구를 통해 서브에이전트를 호출합니다. 서브에이전트가 호출되는 시점을 감지하려면 `name`이 `"Agent"`인 `tool_use` 블록을 확인하면 됩니다. 서브에이전트의 컨텍스트 내에서 생성된 메시지에는 `parent_tool_use_id` 필드가 포함됩니다.326Claude는 Agent 도구를 통해 서브에이전트를 호출합니다. 서브에이전트가 호출되는 시점을 감지하려면 `name`이 `"Agent"`인 `tool_use` 블록을 확인하면 됩니다.

327

328서브에이전트의 컨텍스트 내에서 생성된 메시지에는 `parent_tool_use_id` 필드가 포함됩니다. TypeScript에서는 서브에이전트가 생성하는 각 assistant 및 user 메시지에 [`agent_id`](/docs/ko/agent-sdk/typescript#sdkassistantmessage)도 포함되며, 이는 해당 서브에이전트의 [task 이벤트](/docs/ko/agent-sdk/typescript#sdktaskstartedmessage)의 `task_id`입니다. `agent_id`를 사용하려면 TypeScript Agent SDK v0.3.292 이상이 필요합니다.

327 329

328<Note>330<Note>

329 이 도구는 `tool_use` 블록에서는 `"Agent"`로 표시되지만 `system:init` 도구 목록에서는 `"Task"`로 표시됩니다. Claude Code v2.1.63 이전에는 `tool_use` 블록도 이를 `"Task"`로 명명했습니다. SDK 버전 간에 감지가 작동하도록 유지하려면 `block.name`에서 두 값을 모두 일치시키십시오.331 이 도구는 `tool_use` 블록에서는 `"Agent"`로 표시되지만 `system:init` 도구 목록에서는 `"Task"`로 표시됩니다. Claude Code v2.1.63 이전에는 `tool_use` 블록도 이를 `"Task"`로 명명했습니다. SDK 버전 간에 감지가 작동하도록 유지하려면 `block.name`에서 두 값을 모두 일치시키십시오.

331 333

332메시지 구조는 SDK마다 다릅니다. Python에서는 `message.content`를 통해 콘텐츠 블록에 직접 액세스합니다. TypeScript에서는 `SDKAssistantMessage`가 Claude API 메시지를 래핑하므로 `message.message.content`를 통해 콘텐츠에 액세스합니다.334메시지 구조는 SDK마다 다릅니다. Python에서는 `message.content`를 통해 콘텐츠 블록에 직접 액세스합니다. TypeScript에서는 `SDKAssistantMessage`가 Claude API 메시지를 래핑하므로 `message.message.content`를 통해 콘텐츠에 액세스합니다.

333 335

334이 예제는 스트리밍된 메시지를 반복하며 서브에이전트가 호출될 때와 후속 메시지가 해당 서브에이전트의 실행 컨텍스트 내에서 생성될 때를 기록합니다.336이 예제는 스트리밍된 메시지를 반복하며 서브에이전트가 호출될 때와 후속 메시지가 해당 서브에이전트의 실행 컨텍스트 내에서 생성될 때를 기록합니다. TypeScript 버전은 `agent_id`가 포함된 각 서브에이전트 메시지의 `agent_id`도 기록합니다.

335 337

336<CodeGroup>338<CodeGroup>

337 ```python Python theme={null}339 ```python Python theme={null}

403 // Check if this message is from within a subagent's context405 // Check if this message is from within a subagent's context

404 if (msg.parent_tool_use_id) {406 if (msg.parent_tool_use_id) {

405 console.log(" (running inside subagent)");407 console.log(" (running inside subagent)");

408 // On assistant and user messages, agent_id matches the task_id

409 // on that subagent's task_started and other task events

410 if (msg.agent_id) {

411 console.log(` agent_id: ${msg.agent_id}`);

412 }

406 }413 }

407 414

408 if ("result" in message) {415 if ("result" in message) {

agent-sdk/typescript.md +115 −5

Details

571| `managedSettings` | `Settings` | `undefined` | 호스트 프로세스가 생성된 세션에 제공하는 정책 계층 설정입니다. 관리자가 배포한 관리형 설정이 있는 머신에서는 관리자의 최우선 관리형 소스가 `parentSettingsBehavior: 'merge'`를 설정하지 않는 한 Claude Code가 이를 무시하며, [`policyHelper`](/docs/ko/settings-reference#policyhelper)가 관리형 설정을 제공하는 동안에는 절대 병합하지 않습니다. 병합된 값은 제한 전용 필터를 거칩니다. 필터가 허용하는 항목과 `allowManaged*Only` 잠금은 [상위 설정 제한](/docs/ko/claude-apps-gateway#restrict-parent-settings)에서 다룹니다. [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ko/env-vars)를 설정한 호스트는 대신 세 개의 키를 이 페이로드에서 직접 읽습니다. Claude Code v2.1.222 이상에서의 [모델 구성](/docs/ko/model-config#restrict-model-selection), v2.1.246 이상에서 관리형 소스가 설정하지 않은 경우의 [`modelPricing`](/docs/ko/settings-reference#modelpricing), v2.1.247 이상에서의 `ENABLE_TOOL_SEARCH` env 항목입니다 |571| `managedSettings` | `Settings` | `undefined` | 호스트 프로세스가 생성된 세션에 제공하는 정책 계층 설정입니다. 관리자가 배포한 관리형 설정이 있는 머신에서는 관리자의 최우선 관리형 소스가 `parentSettingsBehavior: 'merge'`를 설정하지 않는 한 Claude Code가 이를 무시하며, [`policyHelper`](/docs/ko/settings-reference#policyhelper)가 관리형 설정을 제공하는 동안에는 절대 병합하지 않습니다. 병합된 값은 제한 전용 필터를 거칩니다. 필터가 허용하는 항목과 `allowManaged*Only` 잠금은 [상위 설정 제한](/docs/ko/claude-apps-gateway#restrict-parent-settings)에서 다룹니다. [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ko/env-vars)를 설정한 호스트는 대신 세 개의 키를 이 페이로드에서 직접 읽습니다. Claude Code v2.1.222 이상에서의 [모델 구성](/docs/ko/model-config#restrict-model-selection), v2.1.246 이상에서 관리형 소스가 설정하지 않은 경우의 [`modelPricing`](/docs/ko/settings-reference#modelpricing), v2.1.247 이상에서의 `ENABLE_TOOL_SEARCH` env 항목입니다 |

572| `maxBudgetUsd` | `number` | `undefined` | 클라이언트 측 비용 추정치가 이 USD 값에 도달하면 쿼리를 중지합니다. 해당 호출 자체의 지출만 계산하며, 재개된 세션에서 복원된 합계는 계산하지 않습니다. 정확도 관련 주의 사항과 재설정 동작은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking)을 참조하세요 |572| `maxBudgetUsd` | `number` | `undefined` | 클라이언트 측 비용 추정치가 이 USD 값에 도달하면 쿼리를 중지합니다. 추정치가 이 값을 초과할 수 있으므로 [여유분을 두세요](/docs/ko/agent-sdk/agent-loop#budget-headroom). 해당 호출 자체의 지출만 집계하며, 재개된 세션에서 복원된 합계는 포함하지 않습니다. 정확도에 관한 주의 사항과 재설정 동작은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking)을 참조하세요 |

575| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 서버 구성입니다 |575| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 서버 구성입니다 |

631```631```

632 632

633* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청별 타임아웃(밀리초)입니다. 기본값은 `600000`입니다. 메인 루프와 모든 서브에이전트에 적용됩니다.633* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청별 타임아웃(밀리초)입니다. 기본값은 `600000`입니다. 메인 루프와 모든 서브에이전트에 적용됩니다.

634* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도 횟수입니다. 기본값은 `10`이며 상한은 `15`입니다. 각 재시도마다 별도의 `API_TIMEOUT_MS` 시간이 주어지므로, 최악의 경우 총 소요 시간은 대략 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)`에 백오프 시간을 더한 값입니다. 더 긴 장애를 기다려야 하는 무인 실행에는 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/ko/errors#tune-retry-behavior)을 설정하세요. 이 설정은 일시적인 용량 오류를 무기한 재시도하며, Claude Code v2.1.199 이상에서는 다른 일시적 오류의 기본값을 `300`으로 높이고 이 변수의 상한을 제거합니다.634* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도 횟수입니다. 기본값은 `10`이며 상한은 `15`입니다. 각 재시도는 자체 `API_TIMEOUT_MS` 시간 범위를 가집니다.

635

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

635* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: 서브에이전트용 멈춤 감시기입니다. 스트림 감시기가 켜져 있는 동안 기본값은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`에 5분을 더한 값이며, 해당 변수를 높이지 않는 한 `600000`이 됩니다. 스트림 감시기가 꺼져 있으면 기본값은 `600000`입니다. v2.1.257 이전에는 기본값이 항상 `600000`이었습니다.637* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: 서브에이전트용 멈춤 감시기입니다. 스트림 감시기가 켜져 있는 동안 기본값은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`에 5분을 더한 값이며, 해당 변수를 높이지 않는 한 `600000`이 됩니다. 스트림 감시기가 꺼져 있으면 기본값은 `600000`입니다. v2.1.257 이전에는 기본값이 항상 `600000`이었습니다.

636 638

637 타이머는 스트림 이벤트마다 재설정됩니다. 멈춤이 발생하면 Claude Code는 서브에이전트를 중단하고 상위 에이전트에 멈춤을 보고합니다. 백그라운드 서브에이전트의 경우 작업을 실패로 표시하고 부분 결과가 있으면 함께 첨부합니다.639 타이머는 스트림 이벤트마다 재설정됩니다. 멈춤이 발생하면 Claude Code는 서브에이전트를 중단하고 상위 에이전트에 멈춤을 보고합니다. 백그라운드 서브에이전트의 경우 작업을 실패로 표시하고 부분 결과가 있으면 함께 첨부합니다.

1561 parent_tool_use_id: string | null;1563 parent_tool_use_id: string | null;

1562 error?: SDKAssistantMessageError;1564 error?: SDKAssistantMessageError;

1563 aborted?: true;1565 aborted?: true;

1566 agent_id?: string;

1564 timestamp?: string;1567 timestamp?: string;

1565 context_usage?: SDKContextUsage;1568 context_usage?: SDKContextUsage;

1569 usage_report?: SDKUsageReport;

1566 user_message_uuid?: string;1570 user_message_uuid?: string;

1567 user_message_uuids?: string[];1571 user_message_uuids?: string[];

1568 resume_reason?: string;1572 resume_reason?: string;

1580 1584

1581`aborted`는 인터럽트 또는 중단으로 인해 스트림이 완료되기 전에 어시스턴트 메시지가 잘렸을 때 `true`입니다. 이 경우 메시지에는 `stop_reason`이 없으며 콘텐츠가 단어 중간에서 끝날 수 있습니다. 정상적으로 완료된 메시지에는 이 필드가 없습니다. Agent SDK v0.3.214 이상이 필요합니다.1585`aborted`는 인터럽트 또는 중단으로 인해 스트림이 완료되기 전에 어시스턴트 메시지가 잘렸을 때 `true`입니다. 이 경우 메시지에는 `stop_reason`이 없으며 콘텐츠가 단어 중간에서 끝날 수 있습니다. 정상적으로 완료된 메시지에는 이 필드가 없습니다. Agent SDK v0.3.214 이상이 필요합니다.

1582 1586

1587`agent_id`는 메시지를 생성한 서브에이전트를 식별하며, 메인 스레드 메시지에는 없습니다. 이 값은 해당 서브에이전트의 [`task_started`](#sdktaskstartedmessage) 및 기타 작업 이벤트의 `task_id`와 같으며, 서브에이전트가 [재개](/docs/ko/agent-sdk/subagents#resume-subagents)되어도 변경되지 않습니다. 이 필드에는 Agent SDK v0.3.292 이상이 필요합니다.

1588

1589서브에이전트의 메시지를 작업 이벤트와 매칭할 때는 메시지의 `parent_tool_use_id`를 작업 이벤트의 `tool_use_id`와 짝짓지 말고 `agent_id`를 기준으로 매칭하세요. 도구 호출이 서브에이전트를 재개하면 작업 이벤트는 해당 호출의 `tool_use_id`를 가지지만, 메시지는 서브에이전트를 처음 시작한 도구 호출의 `parent_tool_use_id`를 유지하므로 두 값이 더 이상 일치하지 않습니다.

1590

1583Claude Code는 [`user_message_uuid`](#user_message_uuid)에 설명된 조건에 따라 턴의 첫 번째 어시스턴트 메시지에 `user_message_uuid`와 `user_message_uuids`를 설정합니다. 재시작으로 중단된 턴을 Claude Code가 다시 실행할 때, 해당 필드를 가진 재실행의 어시스턴트 메시지에는 [`resume_reason`](#resume_reason)도 포함됩니다.1591Claude Code는 [`user_message_uuid`](#user_message_uuid)에 설명된 조건에 따라 턴의 첫 번째 어시스턴트 메시지에 `user_message_uuid`와 `user_message_uuids`를 설정합니다. 재시작으로 중단된 턴을 Claude Code가 다시 실행할 때, 해당 필드를 가진 재실행의 어시스턴트 메시지에는 [`resume_reason`](#resume_reason)도 포함됩니다.

1584 1592

1585`timestamp`는 메시지를 생성한 프로세스에서 메시지 콘텐츠 생성이 완료된 ISO 8601 시각입니다. 이 값은 해당 머신의 시계에서 가져오므로 표시 용도로만 사용하고 메시지 정렬에는 사용하지 마세요. 하나의 API 턴이 같은 `message.id`를 공유하는 여러 어시스턴트 메시지를 생성할 수 있으며, 각 메시지는 고유한 `timestamp`를 가집니다. 이 필드가 없으면 메시지를 수신한 시각을 대신 사용하세요.1593`timestamp`는 메시지를 생성한 프로세스에서 메시지 콘텐츠 생성이 완료된 ISO 8601 시각입니다. 이 값은 해당 머신의 시계에서 가져오므로 표시 용도로만 사용하고 메시지 정렬에는 사용하지 마세요. 하나의 API 턴이 같은 `message.id`를 공유하는 여러 어시스턴트 메시지를 생성할 수 있으며, 각 메시지는 고유한 `timestamp`를 가집니다. 이 필드가 없으면 메시지를 수신한 시각을 대신 사용하세요.

1586 1594

1587`context_usage`는 [`SDKContextUsage`](#sdkcontextusage) 타입으로 된 `/context` 보고서의 구조화된 사본이며 Agent SDK v0.3.232 이상이 필요합니다. `/context`를 프롬프트로 보내면 Claude Code는 `message.content`에 markdown 표가 담긴 어시스턴트 메시지로 보고서를 전달하고, 같은 메시지에 `context_usage`를 첨부합니다. Claude Code는 다른 어시스턴트 메시지에는 이 필드를 설정하지 않으며, 이전 버전은 이 필드 없이 `/context` 표를 전달합니다. 따라서 필드가 있으면 필드에서 세부 내역을 읽고, 없으면 markdown 텍스트를 사용하세요.1595`context_usage`는 [`SDKContextUsage`](#sdkcontextusage) 타입으로 된 `/context` 보고서의 구조화된 사본이며 Agent SDK v0.3.232 이상이 필요합니다. `/context`를 프롬프트로 보내면 Claude Code는 `message.content`에 markdown 표가 담긴 어시스턴트 메시지로 보고서를 전달하고, 같은 메시지에 `context_usage`를 첨부합니다. Claude Code는 다른 어시스턴트 메시지에는 이 필드를 설정하지 않으며, 이전 버전은 이 필드 없이 `/context` 표를 전달합니다. 따라서 필드가 있으면 필드에서 세부 내역을 읽고, 없으면 markdown 텍스트를 사용하세요.

1588 1596

1597`usage_report`는 `/usage` 보고서의 구조화된 사본으로, 타입은 [`SDKUsageReport`](#sdkusagereport)이며 Agent SDK v0.3.273 이상이 필요합니다. `/usage`를 프롬프트로 보내면 Claude Code는 `message.content`에 텍스트를 담은 어시스턴트 메시지로 보고서를 전달합니다. 세션이 다음 조건을 모두 충족할 때만 같은 메시지에 `usage_report`를 첨부합니다.

1598

1599* 세션이 claude.ai 자격 증명으로 인증됨

1600* 자격 증명이 알려진 플랜 유형을 나타내거나 `user:profile` 범위를 가짐

1601* 계정이 사용량 기반 청구를 사용하지 않음

1602

1603`CLAUDE_CODE_OAUTH_TOKEN`으로 전달된 `claude setup-token` 토큰은 `user:inference` 범위만 가지므로 기본적으로 조건을 충족하지 않습니다. API 키 세션 같은 다른 세션은 이 필드 없이 텍스트를 전달하며, 이전 버전도 마찬가지입니다. 필드가 있으면 필드에서 보고서를 읽고 없으면 텍스트를 사용하십시오.

1604

1589<h3 id="sdkusermessage">1605<h3 id="sdkusermessage">

1590 `SDKUserMessage`1606 `SDKUserMessage`

1591</h3>1607</h3>

1597 type: "user";1613 type: "user";

1598 uuid?: UUID;1614 uuid?: UUID;

1599 session_id?: string;1615 session_id?: string;

1616 agent_id?: string;

1600 message: MessageParam; // From Anthropic SDK1617 message: MessageParam; // From Anthropic SDK

1601 pasted_content?: MessageParam["content"][];1618 pasted_content?: MessageParam["content"][];

1602 parent_tool_use_id: string | null;1619 parent_tool_use_id: string | null;

1636};1653};

1637```1654```

1638 1655

1656서브에이전트가 생성하는 사용자 메시지(예: 자체 도구 호출 중 하나에 대한 `tool_result`)는 `agent_id`를 가집니다. 이 필드와 버전 요구 사항은 [`SDKAssistantMessage`](#sdkassistantmessage)에서 정의합니다.

1657

1639`tool_result` 블록을 포함한 메시지에서 `tool_use_result`는 모델에 전송된 텍스트가 아니라 도구의 구조화된 출력 객체입니다. 그 형태는 대응하는 `tool_use` 블록이 지정한 도구에 따라 달라지므로 이 필드는 `unknown` 타입입니다. 기본 제공 형태는 [도구 출력 타입](#tool-output-types)에 나열되어 있습니다. 다음 결과는 나열된 형태 이상의 처리가 필요합니다.1658`tool_result` 블록을 포함한 메시지에서 `tool_use_result`는 모델에 전송된 텍스트가 아니라 도구의 구조화된 출력 객체입니다. 그 형태는 대응하는 `tool_use` 블록이 지정한 도구에 따라 달라지므로 이 필드는 `unknown` 타입입니다. 기본 제공 형태는 [도구 출력 타입](#tool-output-types)에 나열되어 있습니다. 다음 결과는 나열된 형태 이상의 처리가 필요합니다.

1640 1659

1641* `Agent` 도구: `tool_use_result`는 [`AgentOutput`](#agent-2)입니다. `tool_result` 텍스트를 파싱하지 말고 이 값으로 렌더링하세요. `completed` 결과의 `content`에는 서브에이전트의 보고서가 담기며, 보고서를 `SubagentHandback` 도구 호출로 전달하는 서브에이전트의 경우에는 보고서 대신 해당 인계에 대한 짧은 메모가 담깁니다. Claude Code v2.1.271 이상의 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서는 [포크](/docs/ko/sub-agents#fork-the-current-conversation)가 아닌 한 `completed` 결과를 생성하는 모든 서브에이전트가 그런 방식으로 보고하며, Claude는 서브에이전트로부터 별도의 메시지로 보고서를 받습니다.1660* `Agent` 도구: `tool_use_result`는 [`AgentOutput`](#agent-2)입니다. `tool_result` 텍스트를 파싱하지 말고 이 값으로 렌더링하세요. `completed` 결과의 `content`에는 서브에이전트의 보고서가 담기며, 보고서를 `SubagentHandback` 도구 호출로 전달하는 서브에이전트의 경우에는 보고서 대신 해당 인계에 대한 짧은 메모가 담깁니다. Claude Code v2.1.271 이상의 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서는 [포크](/docs/ko/sub-agents#fork-the-current-conversation)가 아닌 한 `completed` 결과를 생성하는 모든 서브에이전트가 그런 방식으로 보고하며, Claude는 서브에이전트로부터 별도의 메시지로 보고서를 받습니다.

1992 `SDKPartialAssistantMessage`2011 `SDKPartialAssistantMessage`

1993</h3>2012</h3>

1994 2013

1995스트리밍 부분 메시지입니다(`includePartialMessages`가 true일 때만). `parent_tool_use_id` 필드는 항상 `null`입니다. 스트림 이벤트는 메인 세션에 대해서만 내보내집니다. 서브에이전트 귀속에는 `parent_tool_use_id`를 가진 완전한 메시지를 사용하거나, [`forwardSubagentText`](#options)를 활성화하여 서브에이전트 텍스트와 사고를 완전한 메시지로 받으세요.2014스트리밍 부분 메시지입니다(`includePartialMessages`가 true인 경우에만).

2015

2016`parent_tool_use_id` 필드는 항상 `null`입니다. 스트림 이벤트는 메인 세션에 대해서만 생성됩니다. 서브에이전트 귀속에는 [`agent_id`](#sdkassistantmessage)와 `parent_tool_use_id`를 가진 완전한 메시지를 사용하거나, [`forwardSubagentText`](#options)를 활성화하여 서브에이전트의 텍스트와 사고를 완전한 메시지로 받으세요.

1996 2017

1997```typescript theme={null}2018```typescript theme={null}

1998type SDKPartialAssistantMessage = {2019type SDKPartialAssistantMessage = {

2229* `buffer`: 압축 예비 공간2250* `buffer`: 압축 예비 공간

2230* `deferred`: Claude Code가 윈도우 밖에 보관하고 사용량 계산에서 제외하는 도구 스키마로, 참고용으로 나열됩니다2251* `deferred`: Claude Code가 윈도우 밖에 보관하고 사용량 계산에서 제외하는 도구 스키마로, 참고용으로 나열됩니다

2231 2252

2253<h3 id="sdkusagereport">

2254 `SDKUsageReport`

2255</h3>

2256

2257`/usage` 보고서의 구조화된 형태로, `/usage` 결과를 전달하는 [`SDKAssistantMessage`](#sdkassistantmessage)에 `usage_report`로 담깁니다. Agent SDK v0.3.273 이상에서 이 타입을 내보냅니다. 이 타입은 실험적이며 형태가 변경될 수 있습니다.

2258

2259```typescript theme={null}

2260type SDKUsageReport = {

2261 session: {

2262 total_cost_usd: number;

2263 total_api_duration_ms: number;

2264 total_duration_ms: number;

2265 total_lines_added: number;

2266 total_lines_removed: number;

2267 model_usage: { [modelName: string]: ModelUsage };

2268 };

2269 rate_limits: {

2270 limits:

2271 | {

2272 kind: string;

2273 group: string;

2274 percent: number;

2275 resets_at: string | null;

2276 scope?: {

2277 model?: { display_name: string } | null;

2278 surface?: { display_name: string } | null;

2279 } | null;

2280 severity: string;

2281 is_active: boolean;

2282 }[]

2283 | null;

2284 extra_usage?: {

2285 is_enabled: boolean;

2286 monthly_limit: number | null;

2287 used_credits: number | null;

2288 utilization: number | null;

2289 currency?: string | null;

2290 } | null;

2291 } | null;

2292};

2293```

2294

2295최상위 필드는 `session`과 `rate_limits`입니다.

2296

2297* `session`: Claude Code의 누적 비용 및 사용량 합계로, [`SDKResultMessage`](#sdkresultmessage)의 `total_cost_usd` 및 `modelUsage`와 같은 장부에서 읽습니다. 각 `model_usage` 항목은 [`ModelUsage`](#modelusage)입니다.

2298* `rate_limits`: `limits`의 플랜 사용량 행과 `extra_usage`의 사용량 크레딧 지출입니다. 세션의 OAuth 토큰에 `user:profile` 범위가 없는 경우처럼 Claude Code가 플랜의 사용량을 가져올 수 없으면 `null`입니다.

2299

2300Claude Code는 `session.total_cost_usd`를 토큰 수로부터 로컬에서 계산하므로, 이는 추정치이며 플랜에서 청구하는 금액이 아닙니다. 서버가 보고하는 사용량 크레딧 지출은 별도의 `extra_usage` 블록입니다. 정확도에 관한 주의 사항은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking)을 참조하십시오.

2301

2302`limits`는 서버가 보낸 그대로의 사용량 행을 담습니다. 어떤 미터가 적용되는지, 그 범위, 레이블, 심각도, 순서는 서버가 결정하므로 행을 그대로 렌더링하십시오.

2303

2304* 빈 배열은 서버가 미터를 보고하지 않았음을 의미합니다.

2305* `null`은 Claude Code가 보고할 행이 없음을 의미합니다.

2306

2307`limits`의 각 행은 하나의 사용량 미터를 설명합니다.

2308

2309| 필드 | 타입 | 설명 |

2310| - | - | - |

2311| `kind` | `string` | `session`, `weekly_all`, `weekly_scoped` 같은 서버의 미터 종류입니다. 행은 레이블이 아니라 항상 이 값으로 분류하십시오 |

2312| `group` | `string` | `session` 또는 `weekly` 같은 서버의 행 그룹입니다. 행은 서버의 순서대로 이 그룹 아래에 묶여 렌더링됩니다 |

2313| `percent` | `number` | 사용된 윈도우의 비율, 0-100 |

2316| `severity` | `string` | 미터 색상을 위한 행에 대한 서버의 판단으로, `normal`, `warning`, `critical` 등이 있습니다 |

2317| `is_active` | `boolean` | 단일 값 표시기가 보여 줄 행으로 서버가 선택한 행에서 `true` |

2318

2319Agent SDK v0.3.277 이전에는 타입이 `severity`와 `is_active`를 선택 사항이자 nullable로 선언했으며, 행이 이 값 없이 도착할 수 있었습니다.

2320

2321`extra_usage`는 서버가 보고하는 청구 기간의 [사용량 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 지출과 상한으로, 플랜에 사용량 크레딧이 있을 때 존재합니다. 금액은 `currency`의 보조 단위이며, USD의 경우 센트입니다.

2322

2323* 이 계정에 자체 지출 상한이 없으면 `monthly_limit`은 `null`입니다. Team 및 Enterprise 플랜에서는 `null`을 무제한으로 렌더링하지 마십시오.

2324* 사용량 크레딧으로 요청 비용을 지불할 수 없는 동안 `is_enabled`는 `false`입니다.

2325

2232<h3 id="sdkmessageorigin">2326<h3 id="sdkmessageorigin">

2233 `SDKMessageOrigin`2327 `SDKMessageOrigin`

2234</h3>2328</h3>

3414type WebFetchInput = {3508type WebFetchInput = {

3415 url: string;3509 url: string;

3416 prompt: string;3510 prompt: string;

3511 offset?: number;

3417};3512};

3418```3513```

3419 3514

3420URL에서 콘텐츠를 가져오고 AI 모델로 처리합니다.3515URL에서 콘텐츠를 가져오고 AI 모델로 처리합니다.

3421 3516

3517`offset`은 페이지 시작 부분부터 건너뛸 문자 수입니다. Claude는 긴 페이지를 계속 읽기 위해 이 값을 설정합니다. 이 필드는 Agent SDK v0.3.290 이상이 필요합니다.

3518

3422<h3 id="websearch">3519<h3 id="websearch">

3423 WebSearch3520 WebSearch

3424</h3>3521</h3>

5601 task_id: string;5698 task_id: string;

5602 tool_use_id?: string;5699 tool_use_id?: string;

5603 status: "completed" | "failed" | "stopped";5700 status: "completed" | "failed" | "stopped";

5701 reason?: "worker_restart";

5604 output_file: string;5702 output_file: string;

5605 summary: string;5703 summary: string;

5606 ambient?: boolean;5704 ambient?: boolean;

5615};5713};

5616```5714```

5617 5715

5716`reason`은 작업이 자체 완료, 실패 또는 중지가 아닌 다른 원인으로 종료될 때 설정되며, Agent SDK v0.3.273 이상이 필요합니다. Claude Code는 claude.ai를 통해 연결되는 세션에서만 이를 설정합니다. 자체 호스팅 러너의 세션을 포함한 클라우드 세션과 Remote Control 세션이 해당됩니다. 로컬 `query()` 호출은 이를 설정하지 않습니다. 유일한 값인 `worker_restart`는 작업을 실행하던 Claude Code 프로세스가 다시 시작되었음을 의미합니다. 알림은 상태 `"stopped"`를 전달하므로, 해당 작업을 완료나 실패로 취급하지 마세요.

5717

5618Claude Code가 [긴 MCP 도구 호출을 백그라운드로 이동](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls)할 때, 해당 호출에 대한 `tool_result` 블록은 자리 표시자만 보유하고 호출의 실제 결과는 이 알림에서 도착합니다. `tool_use_id`를 사용하여 알림을 호출과 일치시킵니다. `completed` 알림에서 `resource_links`는 도구가 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 항목으로 참조로 반환한 파일을 나열하며, [`tool_use_result.resourceLinks`](#sdkusermessage)와 동일한 50개 링크 및 64 KiB 제한이 있습니다. Claude Code는 결과에 링크가 없을 때 `resource_links`를 생략하고 MCP 도구 호출이 아닌 작업에 대한 알림에서 생략합니다. `resource_links`는 Agent SDK v0.3.257 이상이 필요합니다.5718Claude Code가 [긴 MCP 도구 호출을 백그라운드로 이동](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls)할 때, 해당 호출에 대한 `tool_result` 블록은 자리 표시자만 보유하고 호출의 실제 결과는 이 알림에서 도착합니다. `tool_use_id`를 사용하여 알림을 호출과 일치시킵니다. `completed` 알림에서 `resource_links`는 도구가 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 항목으로 참조로 반환한 파일을 나열하며, [`tool_use_result.resourceLinks`](#sdkusermessage)와 동일한 50개 링크 및 64 KiB 제한이 있습니다. Claude Code는 결과에 링크가 없을 때 `resource_links`를 생략하고 MCP 도구 호출이 아닌 작업에 대한 알림에서 생략합니다. `resource_links`는 Agent SDK v0.3.257 이상이 필요합니다.

5619 5719

5620Claude Code는 모델에 전송하는 모든 작업 알림 앞에 공지를 추가합니다. 단, [`scheduled-trigger` 서브종류](#task-notification-subkinds)로 스탬프된 전달은 예외이며, 이들은 대신 할당된 작업 프레이밍을 전달합니다. 공지는 사람의 입력이 발생하지 않았음을 명시하므로, 모델은 알림을 사용자 지시나 승인으로 취급하지 않습니다.5720Claude Code는 모델에 전송하는 모든 작업 알림 앞에 공지를 추가합니다. 단, [`scheduled-trigger` 서브종류](#task-notification-subkinds)로 스탬프된 전달은 예외이며, 이들은 대신 할당된 작업 프레이밍을 전달합니다. 공지는 사람의 입력이 발생하지 않았음을 명시하므로, 모델은 알림을 사용자 지시나 승인으로 취급하지 않습니다.

5773 task_type?: string;5873 task_type?: string;

5774 is_backgrounded?: boolean;5874 is_backgrounded?: boolean;

5775 spawn_depth?: number;5875 spawn_depth?: number;

5876 parent_task_id?: string;

5776 ambient?: boolean;5877 ambient?: boolean;

5777 uuid: UUID;5878 uuid: UUID;

5778 session_id: string;5879 session_id: string;

5790 5891

5791[재개된 서브에이전트](/docs/ko/agent-sdk/subagents#resume-subagents)는 항상 `is_backgrounded: true`를 보고합니다. Claude Code는 모든 재개된 서브에이전트를 백그라운드에서 실행하기 때문입니다. 포그라운드 작업이 나중에 백그라운드로 이동할 때, Claude Code는 두 번째 `task_started`를 전송하는 대신 새로운 `is_backgrounded` 값을 [`task_updated`](#sdktaskupdatedmessage) 메시지에서 보고합니다.5892[재개된 서브에이전트](/docs/ko/agent-sdk/subagents#resume-subagents)는 항상 `is_backgrounded: true`를 보고합니다. Claude Code는 모든 재개된 서브에이전트를 백그라운드에서 실행하기 때문입니다. 포그라운드 작업이 나중에 백그라운드로 이동할 때, Claude Code는 두 번째 `task_started`를 전송하는 대신 새로운 `is_backgrounded` 값을 [`task_updated`](#sdktaskupdatedmessage) 메시지에서 보고합니다.

5792 5893

5894`parent_task_id`는 이 작업을 시작한 서브에이전트의 `task_id`를 담습니다. 이를 사용하여 각 작업을 해당 작업을 시작한 서브에이전트 아래에 그룹화하세요. Claude Code는 서브에이전트, Bash 및 [Monitor](#monitor) 작업에서 이를 설정합니다. 필드는 Agent SDK v0.3.292 이상이 필요합니다. 다음 경우에는 없습니다:

5895

5896* 주 스레드가 작업을 시작한 경우

5897* Claude Code가 더 이상 부모 작업을 추적하지 않는 경우

5898* [팀원](/docs/ko/agent-teams) 또는 워크플로 내부의 에이전트가 작업을 시작한 경우

5899

5900부모는 포그라운드 작업이거나 이미 종료된 작업일 수 있으므로, 인식하지 못하는 ID는 부모가 없는 것으로 취급하세요.

5901

5793<h3 id="sdktaskprogressmessage">5902<h3 id="sdktaskprogressmessage">

5794 `SDKTaskProgressMessage`5903 `SDKTaskProgressMessage`

5795</h3>5904</h3>

5846 `SDKBackgroundTasksChangedMessage`5955 `SDKBackgroundTasksChangedMessage`

5847</h3>5956</h3>

5848 5957

5849라이브 백그라운드 작업 집합이 변경될 때마다 내보내집니다. 작업이 시작되거나, 완료되거나, 종료되거나, 포그라운드 에이전트가 백그라운드로 전환되거나, 작업의 `description` 또는 `ambient` 필드가 변경될 때입니다.5958라이브 백그라운드 작업 집합이 변경될 때마다 내보내집니다. 작업이 시작되거나, 완료되거나, 종료되거나, 포그라운드 에이전트가 백그라운드로 전환되거나, 작업의 `description`, `ambient` 또는 `parent_task_id` 필드가 변경될 때입니다. 각 항목의 `parent_task_id` 필드는 이를 정의하고 버전 요구 사항을 설명하는 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)를 참조하세요.

5850 5959

5851`tasks` 배열은 전체 라이브 집합입니다. `task_started` 및 `task_notification` 이벤트를 쌍으로 맞추는 대신 각 페이로드로 캐시된 집합을 교체하세요. 그러면 다음 멤버십 변경이 놓친 이벤트를 바로잡습니다.5960`tasks` 배열은 전체 라이브 집합입니다. `task_started` 및 `task_notification` 이벤트를 쌍으로 맞추는 대신 각 페이로드로 캐시된 집합을 교체하세요. 그러면 다음 멤버십 변경이 놓친 이벤트를 바로잡습니다.

5852 5961

5853이러한 작업별 이벤트에 대한 순서는 지정되지 않으므로, 두 스트림을 상관시키지 마세요.5962작업이 종료되면 해당 작업의 [`task_updated`](#sdktaskupdatedmessage) 및 [`task_notification`](#sdktasknotificationmessage)이 목록에서 해당 작업을 제거하는 `background_tasks_changed`보다 먼저 도착합니다. 그 외에는 작업별 이벤트에 대한 순서가 지정되지 않습니다.

5854 5963

5855시작 시 아무것도 내보내지지 않습니다. 세션의 CLI 프로세스가 시작되거나 다시 시작될 때마다 빈 집합으로 재설정하고 다음 멤버십 변경이 다시 채우도록 하세요.5964시작 시 아무것도 내보내지지 않습니다. 세션의 CLI 프로세스가 시작되거나 다시 시작될 때마다 빈 집합으로 재설정하고 다음 멤버십 변경이 다시 채우도록 하세요.

5856 5965

5867 task_type: string;5976 task_type: string;

5868 subagent_type?: string;5977 subagent_type?: string;

5869 description: string;5978 description: string;

5979 parent_task_id?: string;

5870 ambient?: boolean;5980 ambient?: boolean;

5871 }[];5981 }[];

5872 uuid: UUID;5982 uuid: UUID;

agent-sdk/user-input.md +10 −5

Details

36 ```36 ```

37 37

38 ```typescript TypeScript theme={null}38 ```typescript TypeScript theme={null}

~~39 async function handleToolRequest(toolName, input, options) {~~39 import type { CanUseTool } from "@anthropic-ai/claude-agent-sdk";

41 const handleToolRequest: CanUseTool = async (toolName, input, options) => {

40 // options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] }42 // options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] }

~~41 // 사용자에게 프롬프트하고 허용 또는 거부 반환~~43 // 여기서 사용자에게 확인을 요청한 다음 허용 또는 거부 반환

~~42 }~~44 return { behavior: "deny", message: "User declined" };

45 };

43 46

44 const options = { canUseTool: handleToolRequest };47 const options = { canUseTool: handleToolRequest };

45 ```48 ```

440 // 도구 목록에 AskUserQuestion 포함443 // 도구 목록에 AskUserQuestion 포함

441 tools: ["Read", "Glob", "Grep", "AskUserQuestion"],444 tools: ["Read", "Glob", "Grep", "AskUserQuestion"],

442 canUseTool: async (toolName, input) => {445 canUseTool: async (toolName, input) => {

443 // 명확화 질문을 여기서 처리446 // 모든 호출을 승인하는 플레이스홀더입니다. AskUserQuestion 감지 단계에서 이를 대체합니다.

447 return { behavior: "allow", updatedInput: input };

444 }448 }

445 }449 }

446 })) {450 })) {

763 767

764 ```typescript TypeScript theme={null}768 ```typescript TypeScript theme={null}

765 import { query } from "@anthropic-ai/claude-agent-sdk";769 import { query } from "@anthropic-ai/claude-agent-sdk";

770 import type { PermissionResult } from "@anthropic-ai/claude-agent-sdk";

766 import * as readline from "readline/promises";771 import * as readline from "readline/promises";

767 772

768 // 터미널에서 사용자 입력을 프롬프트하는 헬퍼773 // 터미널에서 사용자 입력을 프롬프트하는 헬퍼

783 }788 }

784 789

785 // Claude의 질문을 표시하고 사용자 답변을 수집790 // Claude의 질문을 표시하고 사용자 답변을 수집

786 async function handleAskUserQuestion(input: any) {791 async function handleAskUserQuestion(input: any): Promise<PermissionResult> {

787 const answers: Record<string, string> = {};792 const answers: Record<string, string> = {};

788 793

789 for (const q of input.questions) {794 for (const q of input.questions) {

agent-view.md +21 −12

Details

391 391

392에이전트 뷰에서 새로운 백그라운드 세션을 디스패치하거나, 기존 대화형 세션을 백그라운드로 보내거나 복사하거나, 셸에서 직접 시작할 수 있습니다.392에이전트 뷰에서 새로운 백그라운드 세션을 디스패치하거나, 기존 대화형 세션을 백그라운드로 보내거나 복사하거나, 셸에서 직접 시작할 수 있습니다.

393 393

394<h3 id="from-agent-view">394<span id="from-agent-view" />

395 에이전트 뷰에서395

396<h3 id="dispatch-an-agent-from-agent-view">

397 에이전트 뷰에서 에이전트 디스패치

396</h3>398</h3>

397 399

398에이전트 뷰 하단의 입력 필드에 프롬프트를 입력하고 `Enter`를 눌러 새로운 백그라운드 세션을 시작합니다. 세션은 프롬프트에서 자동으로 이름이 지정되며, 나중에 `Ctrl+R`로 이름을 바꿀 수 있습니다.400에이전트 뷰 하단의 입력 필드에 프롬프트를 입력하고 `Enter`를 눌러 새로운 백그라운드 세션을 시작합니다. 세션은 프롬프트에서 자동으로 이름이 지정되며, 나중에 `Ctrl+R`로 이름을 바꿀 수 있습니다.

446 448

447에이전트 뷰가 디렉터리별로 그룹화되면, 디스패치는 선택한 행의 디렉터리로 프롬프트를 보내므로, 경로를 다시 입력하지 않고도 그룹을 선택하고 그 안으로 디스패치할 수 있습니다.449에이전트 뷰가 디렉터리별로 그룹화되면, 디스패치는 선택한 행의 디렉터리로 프롬프트를 보내므로, 경로를 다시 입력하지 않고도 그룹을 선택하고 그 안으로 디스패치할 수 있습니다.

448 450

449<h3 id="from-inside-a-session">451<span id="from-inside-a-session" />

450 세션 내부에서452

453<h3 id="send-or-copy-a-session-to-the-background">

454 세션을 백그라운드로 보내기 또는 복사

451</h3>455</h3>

452 456

453두 명령은 현재 세션의 작업을 백그라운드로 이동합니다. `/background`는 현재 대화를 백그라운드로 보내고 터미널을 해제하며, `/fork`는 복사본을 보내고 사용자는 현재 위치에서 계속 작업합니다.457두 명령은 현재 세션의 작업을 백그라운드로 이동합니다. `/background`는 현재 대화를 백그라운드로 보내고 터미널을 해제하며, `/fork`는 복사본을 보내고 사용자는 현재 위치에서 계속 작업합니다.

511 515

512세션 중에 [`/add-dir`](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration)로 추가한 디렉터리도 이어집니다. `--allow-dangerously-skip-permissions`가 이어지면 백그라운드 세션에서 `bypassPermissions`에 도달할 수 있지만, 새로운 권한을 부여하지는 않습니다. 이 모드는 여전히 [권한 모드, 모델, effort](#permission-mode-model-and-effort)에 설명된 일회성 대화형 수락이 필요합니다.516세션 중에 [`/add-dir`](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration)로 추가한 디렉터리도 이어집니다. `--allow-dangerously-skip-permissions`가 이어지면 백그라운드 세션에서 `bypassPermissions`에 도달할 수 있지만, 새로운 권한을 부여하지는 않습니다. 이 모드는 여전히 [권한 모드, 모델, effort](#permission-mode-model-and-effort)에 설명된 일회성 대화형 수락이 필요합니다.

513 517

514<h3 id="from-your-shell">518<span id="from-your-shell" />

515 셸에서519

520<h3 id="dispatch-an-agent-from-your-shell">

521 셸에서 에이전트 디스패치

516</h3>522</h3>

517 523

518`--bg` 또는 그 긴 형식 `--background`를 전달하여 바로 백그라운드로 가는 세션을 시작합니다:524`--bg` 또는 그 긴 형식 `--background`를 전달하여 바로 백그라운드로 가는 세션을 시작합니다:

603 609

604git 저장소 외부에서는 세션이 작업 디렉터리에 직접 쓰고 서로 격리되지 않으므로, 동일한 파일을 편집하는 병렬 세션을 디스패치하지 않도록 합니다. 다른 버전 관리 시스템을 사용한다면 [`WorktreeCreate` 훅](/docs/ko/worktrees#non-git-version-control)을 구성하면 Claude가 git과 동일한 방식으로 편집을 격리합니다.610git 저장소 외부에서는 세션이 작업 디렉터리에 직접 쓰고 서로 격리되지 않으므로, 동일한 파일을 편집하는 병렬 세션을 디스패치하지 않도록 합니다. 다른 버전 관리 시스템을 사용한다면 [`WorktreeCreate` 훅](/docs/ko/worktrees#non-git-version-control)을 구성하면 Claude가 git과 동일한 방식으로 편집을 격리합니다.

605 611

606git 저장소가 아닌 디렉터리에서 훅이 실패하면 Claude는 해당 디렉터리의 격리를 건너뛰고 작업 디렉터리를 제자리에서 편집합니다. git 저장소 안에서는 Claude가 편집 전에 워크트리로 이동시키는 세션은 그 이동이 이루어질 때까지 공유 체크아웃의 파일을 편집할 수 없습니다.612git 저장소가 아닌 디렉터리에서 훅이 실패하면 Claude는 해당 디렉터리의 격리를 건너뛰고 작업 디렉터리를 제자리에서 편집합니다. git 저장소 안에서는 Claude가 편집 전에 워크트리로 이동시키는 세션은 그 이동이 이루어질 때까지 공유 체크아웃에서 `Edit`, `Write`, `NotebookEdit` 도구를 사용할 수 없습니다.

607 613

608세션의 워크트리 경로를 찾으려면 세션에 연결하여 작업 디렉터리를 확인합니다.614세션의 워크트리 경로를 찾으려면 세션에 연결하여 작업 디렉터리를 확인합니다.

609 615

825| `claude daemon logs` | 감독자의 로그 파일 [`~/.claude/daemon.log`](#where-state-is-stored)를 팔로우하며, `Ctrl+C`를 누를 때까지 새 줄이 도착하는 대로 인쇄 |831| `claude daemon logs` | 감독자의 로그 파일 [`~/.claude/daemon.log`](#where-state-is-stored)를 팔로우하며, `Ctrl+C`를 누를 때까지 새 줄이 도착하는 대로 인쇄 |

826| `claude daemon stop --any` | 감독자 프로세스와 이를 호스팅하는 백그라운드 세션을 중지합니다. `--keep-workers`를 전달하여 백그라운드 세션을 실행 상태로 유지하면 다음 감독자가 이들에 다시 연결됩니다. 다음 `claude agents` 또는 `claude --bg`는 새로운 감독자를 시작합니다 |832| `claude daemon stop --any` | 감독자 프로세스와 이를 호스팅하는 백그라운드 세션을 중지합니다. `--keep-workers`를 전달하여 백그라운드 세션을 실행 상태로 유지하면 다음 감독자가 이들에 다시 연결됩니다. 다음 `claude agents` 또는 `claude --bg`는 새로운 감독자를 시작합니다 |

827 833

828`claude attach`와 `claude logs`는 ID 대신 실행 중인 세션 이름의 일부를 받을 수 있습니다(예: `claude logs "auth refactor"`). 이름을 전달하려면 Claude Code v2.1.290 이상이 필요합니다.834`claude attach`와 `claude logs`는 ID 대신 세션 이름의 일부를 받을 수 있습니다(예: `claude logs "auth refactor"`). 이름을 전달하려면 Claude Code v2.1.290 이상이 필요합니다.

829 835

830<h3 id="list-sessions-as-json">836<h3 id="list-sessions-as-json">

831 세션을 JSON으로 나열837 세션을 JSON으로 나열

979 세션을 열면 저장된 트랜스크립트가 없다고 표시됨985 세션을 열면 저장된 트랜스크립트가 없다고 표시됨

980</h3>986</h3>

981 987

982[다른 대화에서 백그라운드로 이동된](#from-inside-a-session) 중지된 세션이 첫 번째 응답이 완료되기 전에 중지된 경우 다시 시작할 것이 없습니다: 첫 번째 응답이 완료될 때까지 대화는 여전히 백그라운드로 이동된 세션에만 존재합니다. `claude attach`는 `This session has no saved transcript`로 열기를 거부합니다.988[다른 대화에서 백그라운드로 이동한](#from-inside-a-session) 세션이 자체 턴을 실행하기 전에 중지된 경우, 해당 세션을 열면 Claude Code는 그 대화를 다시 시작합니다. Claude Code가 대화를 찾을 수 없으면 세션 열기를 거부합니다:

989

990* `claude attach`는 `This session has no saved transcript`를 출력합니다.

991* 에이전트 뷰는 목록 아래에 `Press enter again to restart this session fresh`를 표시합니다.

983 992

984에이전트 뷰에서 해당 행을 열면 목록 아래에 `Press enter again to restart this session fresh`가 표시됩니다. 같은 행에서 `Enter`를 다시 누르면 빈 대화로 세션을 다시 시작하거나, 셸에서 `claude respawn <id>`를 실행합니다.993같은 행에서 `Enter`를 다시 눌러 빈 대화로 세션을 다시 시작하거나, 셸에서 `claude respawn <id>`를 실행합니다.

985 994

986원래 대화는 그대로 유지됩니다; `claude --resume`으로 다시 시작하거나 계속 작업합니다. 자세한 내용은 [오류 참조](/docs/ko/errors#this-session-has-no-saved-transcript)를 참조합니다.995자세한 내용은 [오류 참조](/docs/ko/errors#this-session-has-no-saved-transcript)를 참조합니다.

987 996

988<h3 id="the-terminal-host-died-or-the-session-stopped-responding">997<h3 id="the-terminal-host-died-or-the-session-stopped-responding">

989 터미널 호스트가 죽었거나 세션이 응답하지 않음998 터미널 호스트가 죽었거나 세션이 응답하지 않음

1095 1104

1096| 버전 | 변경 사항 |1105| 버전 | 변경 사항 |

1097| - | - |1106| - | - |

1098| v2.1.290 | [`claude attach` 및 `claude logs`](#manage-sessions-from-the-shell)는 ID 대신 실행 중인 세션 이름의 일부를 받을 수 있습니다. |1107| v2.1.290 | [`claude attach` 및 `claude logs`](#manage-sessions-from-the-shell)는 ID 대신 세션 이름의 일부를 받을 수 있습니다. |

1099| v2.1.290 | 작업 중인 세션에 [엿보기 회신](#peek-and-reply)으로 보낸 `/model`, `/effort`, `/rename`, `/usage`는 즉시 실행됩니다. |1108| v2.1.290 | 작업 중인 세션에 [엿보기 회신](#peek-and-reply)으로 보낸 `/model`, `/effort`, `/rename`, `/usage`는 즉시 실행됩니다. |

1100| v2.1.290 | 전달할 수 없는 [엿보기 회신](#peek-and-reply)은 `/`로 시작하거나, 세션의 프로세스가 실행 중인 동안 미리 정의된 선택지가 있는 질문에 답하는 경우 더 이상 다음 재시작을 위해 저장되지 않습니다. |1109| v2.1.290 | 전달할 수 없는 [엿보기 회신](#peek-and-reply)은 `/`로 시작하거나, 세션의 프로세스가 실행 중인 동안 미리 정의된 선택지가 있는 질문에 답하는 경우 더 이상 다음 재시작을 위해 저장되지 않습니다. |

1101| v2.1.288 | `Ctrl+F`는 이름으로 세션을 찾고, `Alt+↑` / `Alt+↓`는 그룹 헤더 사이를 이동합니다. 이 두 가지와 `Ctrl+R`은 [다시 바인딩](/docs/ko/keybindings#agents-actions)할 수 있습니다. |1110| v2.1.288 | `Ctrl+F`는 이름으로 세션을 찾고, `Alt+↑` / `Alt+↓`는 그룹 헤더 사이를 이동합니다. 이 두 가지와 `Ctrl+R`은 [다시 바인딩](/docs/ko/keybindings#agents-actions)할 수 있습니다. |

chrome.md +39 −2

Details

202logs/session.log를 첨부해 주세요202logs/session.log를 첨부해 주세요

203```203```

204 204

205업로드에는 세 가지 제한이 적용됩니다.205Claude가 파일 첨부를 거부하거나 업로드가 실패하면 다음 원인을 확인합니다.

206 206

207* **권한**: Claude는 세션에서 읽기가 허용된 파일만 업로드할 수 있으므로, 파일에 대한 `Read` 액세스를 거부하는 [권한 규칙](/docs/ko/settings-reference#permission-settings)은 해당 파일의 업로드도 차단합니다.207* **권한**: Claude는 세션에서 읽기가 허용된 파일만 업로드할 수 있으므로, 파일에 대한 `Read` 액세스를 거부하는 [권한 규칙](/docs/ko/settings-reference#permission-settings)은 해당 파일의 업로드도 차단합니다.

208* **크기**: 한 번의 업로드에 포함할 수 있는 파일은 총 10MB까지입니다.208* **크기**: 한 번의 업로드에 포함할 수 있는 파일은 총 10MB까지입니다.

209* **하드 링크**: Claude는 하드 링크가 여러 개인 파일을 거부합니다. 이는 `node_modules`와 같은 패키지 관리자 저장소 내부에서 흔히 발생합니다. 파일을 복사한 후 복사본을 업로드합니다.209* **하드 링크**: Claude는 하드 링크가 여러 개인 파일을 거부합니다. 이는 `node_modules`와 같은 패키지 관리자 저장소 내부에서 흔히 발생합니다. 파일을 복사한 후 복사본을 업로드합니다.

210* **자격 증명 이름**: Claude는 `.env`, `.pem` 또는 `.key` 파일, `.ssh` 아래의 모든 항목처럼 자격 증명을 보관하는 데 쓰이는 이름이나 폴더를 가진 파일을 거부합니다. Claude Code v2.1.293 이상이 필요합니다.

210 211

211<h3 id="draft-content-in-google-docs">212<h3 id="draft-content-in-google-docs">

212 Google Docs에서 콘텐츠 작성213 Google Docs에서 콘텐츠 작성

309 310

310기타 Chromium 기반 브라우저는 브라우저 이름을 딴 자체 구성 디렉터리에서 동일한 파일을 읽습니다. 예를 들어 macOS의 Brave는 `~/Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts/`를 사용하며, Windows에서는 각 브라우저에 `HKCU\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\`와 같은 자체 레지스트리 키가 있습니다.311기타 Chromium 기반 브라우저는 브라우저 이름을 딴 자체 구성 디렉터리에서 동일한 파일을 읽습니다. 예를 들어 macOS의 Brave는 `~/Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts/`를 사용하며, Windows에서는 각 브라우저에 `HKCU\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\`와 같은 자체 레지스트리 키가 있습니다.

311 312

313<h3 id="project-settings-can’t-turn-on-chrome">

314 프로젝트 설정으로 Chrome을 켤 수 없음

315</h3>

316

317터미널에 다음 경고가 표시되면 작업 중인 프로젝트가 Chrome 통합을 켜려고 했지만 Claude Code가 이를 허용하지 않았다는 의미입니다.

318

319```text wrap theme={null}

320Claude Code ignored CLAUDE_CODE_ENABLE_CFC in this project's settings: a project can't turn on Claude in Chrome. To turn it on yourself, run /chrome or start with --chrome.

321```

322

323프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`이 Chrome 통합을 켜기 위해 `env` 블록에서 [`CLAUDE_CODE_ENABLE_CFC`](/docs/ko/env-vars#variables)를 `1`로 설정하고 있습니다. Claude Code가 이 설정을 적용하지 않았으므로 이 세션에서는 Chrome 통합이 꺼져 있으며 Claude에는 브라우저 도구가 없습니다.

324

325이러한 파일은 프로젝트 디렉터리에 저장되며, 체크아웃한 저장소가 Claude를 사용자의 브라우저에 연결할 수 있어서는 안 되므로 Claude Code는 이 설정을 건너뜁니다.

326

327현재 상태 그대로 계속 작업할 수 있습니다. 브라우저 도구가 필요하거나 경고를 없애려면 다음 중 하나를 수행합니다.

328

329* **지금 브라우저 도구를 사용하려면**: 종료한 후 셸에서 `claude --chrome`으로 다시 시작합니다.

330* **이후 세션에서 브라우저 도구를 사용하려면**: Claude Code 프롬프트에서 `/chrome`을 실행하고 [**Enabled by default**](#enable-chrome-by-default)를 선택합니다. 이는 실행 중인 세션이 아니라 이후에 시작하는 세션에 적용됩니다.

331* **브라우저 도구 없이 경고를 없애려면**: 프로젝트의 설정 파일에서 `CLAUDE_CODE_ENABLE_CFC` 줄을 제거합니다.

332

312<h3 id="browser-not-responding">333<h3 id="browser-not-responding">

313 브라우저가 응답하지 않음334 브라우저가 응답하지 않음

314</h3>335</h3>

325 346

326Chrome 확장 프로그램의 서비스 워커는 확장 세션 중에 유휴 상태가 될 수 있으며, 이는 연결을 끊습니다. 비활성 기간 후 브라우저 도구가 작동하지 않으면 `/chrome`을 실행하고 "확장 프로그램 다시 연결"을 선택합니다.347Chrome 확장 프로그램의 서비스 워커는 확장 세션 중에 유휴 상태가 될 수 있으며, 이는 연결을 끊습니다. 비활성 기간 후 브라우저 도구가 작동하지 않으면 `/chrome`을 실행하고 "확장 프로그램 다시 연결"을 선택합니다.

327 348

349`/chrome`을 실행하면 `Status` 줄을 확인합니다. "Not connected"로 표시되면 실행 중인 세션 자체의 Chrome 연결이 실패한 것입니다. "확장 프로그램 다시 연결"을 선택하여 해당 연결을 다시 시작합니다. 연결에 성공하면 Chrome에서 확장 프로그램의 다시 연결 페이지가 열립니다. v2.1.290 이전에는 "확장 프로그램 다시 연결"이 해당 페이지만 열 뿐 실패한 연결을 다시 시작하지 않았으므로, 이전 버전에서 브라우저 도구가 돌아오지 않으면 Claude Code를 업데이트합니다.

350

351<h3 id="extension-signed-in-to-a-different-organization">

352 다른 조직으로 로그인된 확장 프로그램

353</h3>

354

355둘 이상의 claude.ai 조직에 속해 있는 경우 확장 프로그램은 Claude Code와 동일한 조직으로 로그인되어 있어야 합니다. 두 조직이 다르면 둘 다 동일한 claude.ai 계정을 사용하더라도 Claude의 브라우저 도구가 "Browser extension is not connected"를 반환합니다.

356

357Claude Code가 어떤 조직으로 로그인되어 있는지 확인하려면 Claude Code 프롬프트에서 [`/status`](/docs/ko/commands)를 실행하고 `Organization` 행을 확인합니다.

358

359<Warning>

360 확장 프로그램에서 로그아웃하면 확장 프로그램에 저장된 바로 가기와 예약 작업이 사라집니다. 먼저 [일반적인 오류 메시지](#common-error-messages)의 다른 해결 방법을 시도합니다.

361</Warning>

362

363확장 프로그램의 조직을 변경하려면 확장 프로그램 설정에서 로그아웃한 후 다시 로그인하고 `/status`에 표시된 조직을 선택합니다.

364

328<h3 id="windows-specific-issues">365<h3 id="windows-specific-issues">

329 Windows 관련 문제366 Windows 관련 문제

330</h3>367</h3>

343 380

344| 오류 | 원인 | 해결 방법 |381| 오류 | 원인 | 해결 방법 |

345| - | - | - |382| - | - | - |

346| "브라우저 확장 프로그램이 연결되지 않음" | 네이티브 메시징 호스트가 확장 프로그램에 도달할 수 없거나, 조직의 IP 허용 목록이 `bridge.claudeusercontent.com`에 대한 연결을 거부함 | 확장 프로그램이 Claude Code와 동일한 claude.ai 계정으로 로그인되어 있는지 확인하고, Chrome과 Claude Code를 다시 시작한 후 `/chrome`을 실행하여 다시 연결합니다. 조직에서 IP 허용 목록을 사용하고 오류가 지속되면 [조직 IP 허용 목록 및 프록시 egress](/docs/ko/network-config#organization-ip-allowlists-and-proxy-egress)를 참조합니다. |383| "Browser extension is not connected" | 확장 프로그램이 Chrome에 설치되어 실행 중이지 않거나, 확장 프로그램이 Claude Code와 다른 claude.ai 계정 또는 조직으로 로그인되어 있거나, 조직의 IP 허용 목록이 `bridge.claudeusercontent.com`에 대한 연결을 거부함 | 확장 프로그램이 Claude Code와 동일한 claude.ai 계정 및 [조직](#extension-signed-in-to-a-different-organization)으로 로그인되어 있는지 확인하고, Chrome과 Claude Code를 다시 시작한 후 `/chrome`을 실행하여 다시 연결합니다. 조직에서 IP 허용 목록을 사용하고 오류가 지속되면 [조직 IP 허용 목록 및 프록시 egress](/docs/ko/network-config#organization-ip-allowlists-and-proxy-egress)를 참조합니다. |

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

Details

1237 1237

1238CLI는 메트릭, 로그, 그리고 활성화된 경우 트레이스를 게이트웨이로 전송하며, 게이트웨이는 이를 구성된 각 대상으로 그대로 중계합니다. 내보내기는 HTTP 기반 OpenTelemetry Protocol(OTLP)을 사용합니다. 중계를 건너뛰고 세션이 수집기로 직접 내보내도록 하려면 [정책에서 수집기를 지정](#export-directly-to-your-collector)합니다. CLI가 내보내는 메트릭과 이벤트는 [사용량 모니터링](/docs/ko/monitoring-usage)을 참조하세요.1238CLI는 메트릭, 로그, 그리고 활성화된 경우 트레이스를 게이트웨이로 전송하며, 게이트웨이는 이를 구성된 각 대상으로 그대로 중계합니다. 내보내기는 HTTP 기반 OpenTelemetry Protocol(OTLP)을 사용합니다. 중계를 건너뛰고 세션이 수집기로 직접 내보내도록 하려면 [정책에서 수집기를 지정](#export-directly-to-your-collector)합니다. CLI가 내보내는 메트릭과 이벤트는 [사용량 모니터링](/docs/ko/monitoring-usage)을 참조하세요.

1239 1239

1240`/login`으로 로그인한 세션에서 CLI는 게이트웨이가 발급한 JWT에서 읽은 인증된 사용자의 ID, 즉 `user.id`, `user.email` 및 `user.groups` 속성을 각 내보내기에 기록합니다. 따라서 개발자별 비용 및 사용량 귀속은 개발자 측 구성 없이 작동합니다.1240`/login`으로 로그인한 세션에서 CLI는 게이트웨이가 발급한 JWT에서 읽은 인증된 사용자의 ID, 즉 `user.id`, `user.email`, `user.groups` 속성을 각 내보내기에 기록합니다. 따라서 개발자 측 구성 없이 개발자별 비용 및 사용량 귀속이 작동합니다. 개발자가 로그인하기 전에 Claude Code가 로그에 기록하는 이벤트는 [이 ID를 포함하지 않습니다](/docs/ko/monitoring-usage#standard-attributes). 개발자 그룹 변경을 어떤 속성이 따르는지는 [열린 세션 중 그룹 변경](#group-changes-during-an-open-session)을 참조하십시오.

1241 1241

1242게이트웨이를 통해 로그인한 [Claude Desktop](#claude-desktop-overlay) 및 Cowork 세션은 `enduser.id`와 함께 `user.email` 및 `user.groups`를 텔레메트리에 기록하므로, `user.email` 또는 `user.groups`에 대한 하나의 쿼리로 터미널, Desktop 및 Cowork 사용량을 모두 다룰 수 있습니다. `user.groups`는 쉼표로 구분된 IdP 그룹 목록입니다.1242게이트웨이를 통해 로그인한 [Claude Desktop](#claude-desktop-overlay) 및 Cowork 세션은 `enduser.id`와 함께 `user.email` 및 `user.groups`를 텔레메트리에 기록하므로, `user.email` 또는 `user.groups`에 대한 하나의 쿼리로 터미널, Desktop 및 Cowork 사용량을 모두 다룰 수 있습니다. `user.groups`는 쉼표로 구분된 IdP 그룹 목록입니다.

1243 1243

1347 1347

1348Claude Code는 각 레이블을 모든 메트릭 데이터 포인트에도 복사하므로, 리소스 속성을 인덱싱하지 않는 백엔드에서도 레이블로 메트릭을 필터링할 수 있습니다. 이 복사를 끄려면 [메트릭 카디널리티 제어](/docs/ko/monitoring-usage#metrics-cardinality-control)를 참조하세요.1348Claude Code는 각 레이블을 모든 메트릭 데이터 포인트에도 복사하므로, 리소스 속성을 인덱싱하지 않는 백엔드에서도 레이블로 메트릭을 필터링할 수 있습니다. 이 복사를 끄려면 [메트릭 카디널리티 제어](/docs/ko/monitoring-usage#metrics-cardinality-control)를 참조하세요.

1349 1349

1350<h4 id="group-changes-during-an-open-session">

1351 열린 세션 중 그룹 변경

1352</h4>

1353

1354터미널 세션은 `user.groups`를 OTLP 리소스에 넣고, 각 메트릭 데이터 포인트와 이벤트에도 다시 넣습니다. 세션이 열려 있는 동안 개발자의 그룹이 변경되면, 다음 [자동 갱신](#session) 이후 사용량에 대한 데이터 포인트와 이벤트에는 새 그룹이 포함됩니다. 리소스는 개발자가 Claude Code를 재시작할 때까지 이전 그룹을 유지하므로, 데이터 포인트나 이벤트의 속성을 기준으로 그룹화하십시오.

1355

1356OpenTelemetry Collector의 Prometheus remote write 익스포터에서 `resource_to_telemetry_conversion`을 켜면, 익스포터가 각 데이터 포인트의 `user.groups`를 리소스의 값으로 대체하므로 모든 데이터 포인트에 이전 그룹이 표시됩니다. 데이터 포인트의 값을 유지하려면 해당 익스포터 앞에서 리소스의 `user.groups`를 삭제하십시오.

1357

1358다음 OpenTelemetry Collector `resource` 프로세서는 이를 나열하는 파이프라인에서 해당 속성을 삭제합니다.

1359

1360```yaml theme={null}

1361processors:

1362 resource/drop-user-groups:

1363 attributes:

1364 - key: user.groups

1365 action: delete

1366```

1367

1368메트릭 파이프라인의 `processors`에 `resource/drop-user-groups`를 추가하면, 각 시리즈는 자신의 데이터 포인트에서 가져온 `user_groups` 레이블을 갖게 됩니다.

1369

1350<h4 id="export-directly-to-your-collector">1370<h4 id="export-directly-to-your-collector">

1351 수집기로 직접 내보내기1371 수집기로 직접 내보내기

1352</h4>1372</h4>

claude-apps-gateway-on-aws.md +1 −1

Details

516 텔레메트리516 텔레메트리

517</h2>517</h2>

518 518

519게이트웨이는 머신별 OTEL 구성 없이 개발자별 사용 현황 메트릭을 제공합니다. Claude Code는 OpenTelemetry (OTLP) 메트릭, 로그 및 옵트인 추적을 내보냅니다. [모니터링 사용](/docs/ko/monitoring-usage)에서는 CLI가 보고하는 모든 내용을 다룹니다. `/login`을 통해 로그인한 세션에서 CLI는 각 내보내기에 인증된 IdP 신원 속성 `user.id`, `user.email` 및 `user.groups`을 스탬프하므로 사용 현황이 개발자별로 집계됩니다.519게이트웨이는 머신별 OTEL 구성 없이 개발자별 사용 현황 메트릭을 제공합니다. Claude Code는 OpenTelemetry (OTLP) 메트릭, 로그 및 옵트인 추적을 내보냅니다. [모니터링 사용](/docs/ko/monitoring-usage)에서는 CLI가 보고하는 모든 내용을 다룹니다. `/login`을 통해 로그인한 세션에서 CLI는 인증된 IdP 신원 속성 `user.id`, `user.email` 및 `user.groups`을 [각 내보내기에 스탬프](/docs/ko/monitoring-usage#standard-attributes)하므로 사용 현황이 개발자별로 집계됩니다.

520 520

521게이트웨이 자체는 인증된 OTLP 릴레이입니다. [`telemetry.forward_to`](/docs/ko/claude-apps-gateway-config#telemetry)를 `listen.public_url`과 함께 설정하면 OTEL 내보내기 설정을 모든 연결된 클라이언트에 푸시하고 OTLP 트래픽을 나열한 각 대상으로 그대로 전달합니다. 각 대상은 메트릭, 로그 및 추적에 독립적으로 옵트인하며 기본값은 메트릭만입니다. 신호별 필드 및 민감도 트레이드오프에 대해서는 [`telemetry` 참조](/docs/ko/claude-apps-gateway-config#telemetry)를 참조하세요. 게이트웨이는 텔레메트리를 버퍼링, 집계 또는 저장하지 않으므로 데이터가 도착하는 위치는 전적으로 수집기의 내보내기 구성에 따릅니다.521게이트웨이 자체는 인증된 OTLP 릴레이입니다. [`telemetry.forward_to`](/docs/ko/claude-apps-gateway-config#telemetry)를 `listen.public_url`과 함께 설정하면 OTEL 내보내기 설정을 모든 연결된 클라이언트에 푸시하고 OTLP 트래픽을 나열한 각 대상으로 그대로 전달합니다. 각 대상은 메트릭, 로그 및 추적에 독립적으로 옵트인하며 기본값은 메트릭만입니다. 신호별 필드 및 민감도 트레이드오프에 대해서는 [`telemetry` 참조](/docs/ko/claude-apps-gateway-config#telemetry)를 참조하세요. 게이트웨이는 텔레메트리를 버퍼링, 집계 또는 저장하지 않으므로 데이터가 도착하는 위치는 전적으로 수집기의 내보내기 구성에 따릅니다.

522 522

claude-code-on-the-web.md +9 −5

Details

91 CLI에서 세션 핸드오프는 일방향입니다. `--teleport`를 사용하여 클라우드 세션을 터미널로 가져올 수 있지만, 기존 터미널 세션을 클라우드로 푸시할 수는 없습니다. 작업 설명과 함께 `--cloud` 플래그는 현재 저장소에 대한 새로운 클라우드 세션을 생성합니다. `-p`와 세션 ID 또는 claude.ai/code URL을 사용하면 대신 [해당 기존 세션에 메시지를 큐에 넣습니다](/docs/ko/claude-code-on-the-web#send-follow-ups-from-the-cli). [Desktop 앱](/docs/ko/desktop#continue-in-another-surface)은 **Open in** 메뉴에서 Code 탭의 로컬 세션을 클라우드로 보낼 수 있습니다.91 CLI에서 세션 핸드오프는 일방향입니다. `--teleport`를 사용하여 클라우드 세션을 터미널로 가져올 수 있지만, 기존 터미널 세션을 클라우드로 푸시할 수는 없습니다. 작업 설명과 함께 `--cloud` 플래그는 현재 저장소에 대한 새로운 클라우드 세션을 생성합니다. `-p`와 세션 ID 또는 claude.ai/code URL을 사용하면 대신 [해당 기존 세션에 메시지를 큐에 넣습니다](/docs/ko/claude-code-on-the-web#send-follow-ups-from-the-cli). [Desktop 앱](/docs/ko/desktop#continue-in-another-surface)은 **Open in** 메뉴에서 Code 탭의 로컬 세션을 클라우드로 보낼 수 있습니다.

92</Note>92</Note>

93 93

~~94<h3 id="from-terminal-to-cloud">~~94<span id="from-terminal-to-cloud" />

~~95 터미널에서 클라우드로~~95

96<h3 id="start-a-cloud-session-from-your-terminal">

97 터미널에서 클라우드 세션 시작하기

96</h3>98</h3>

97 99

98`--cloud` 플래그를 사용하여 명령줄에서 클라우드 세션을 시작합니다:100`--cloud` 플래그를 사용하여 명령줄에서 클라우드 세션을 시작합니다:

215 217

216전송이 실패하면 [클라우드 세션으로 전송할 때의 오류](#errors-when-sending-to-a-cloud-session)를 참조하십시오.218전송이 실패하면 [클라우드 세션으로 전송할 때의 오류](#errors-when-sending-to-a-cloud-session)를 참조하십시오.

217 219

218<h3 id="from-cloud-to-terminal">220<span id="from-cloud-to-terminal" />

219 클라우드에서 터미널로221

222<h3 id="continue-a-cloud-session-in-your-terminal">

223 터미널에서 클라우드 세션 계속하기

220</h3>224</h3>

221 225

222다음 중 하나를 사용하여 클라우드 세션을 터미널로 가져옵니다:226다음 중 하나를 사용하여 클라우드 세션을 터미널로 가져옵니다:

483[claude.ai/code](https://claude.ai/code)에서 세션을 다시 열어 새로운 VM을 프로비저닝하세요.487[claude.ai/code](https://claude.ai/code)에서 세션을 다시 열어 새로운 VM을 프로비저닝하세요.

484 488

485* **복원됨**: 대화 기록489* **복원됨**: 대화 기록

486* **복원되지 않음**: VM이 회수되었을 때 여전히 실행 중이던 백그라운드 작업(예: 서브에이전트 및 셸 명령)490* **복원되지 않음**: VM이 회수되었을 때 여전히 실행 중이던 백그라운드 작업(예: 서브에이전트 및 셸 명령) 및 [자체 페이스 `/loop`](/docs/ko/scheduled-tasks#let-claude-choose-the-interval)의 대기 중인 웨이크업. 루프를 다시 시작하려면 `/loop`를 다시 실행하세요.

487 491

488<h2 id="limitations">492<h2 id="limitations">

489 제한 사항493 제한 사항

claude-projects.md +1 −1

Details

489* **루틴**: 프로젝트에서 예약된 작업을 요청하면 Claude는 해당 프로젝트의 스레드로 실행되고 **루틴** 탭에 표시되는 [루틴](/docs/ko/routines)을 생성합니다. 프로젝트 외부에서 생성한 루틴은 계속 독립적으로 작동합니다.489* **루틴**: 프로젝트에서 예약된 작업을 요청하면 Claude는 해당 프로젝트의 스레드로 실행되고 **루틴** 탭에 표시되는 [루틴](/docs/ko/routines)을 생성합니다. 프로젝트 외부에서 생성한 루틴은 계속 독립적으로 작동합니다.

490* **원격 제어**: [원격 제어](/docs/ko/remote-control)는 claude.ai를 머신에서 실행 중인 Claude Code 세션에 연결합니다. 프로젝트에서 Claude에게 컴퓨터에서 스레드를 실행하도록 요청하면, 프로젝트는 [원격 제어를 사용하여 이를 수행합니다](#run-a-thread-on-your-own-computer).490* **원격 제어**: [원격 제어](/docs/ko/remote-control)는 claude.ai를 머신에서 실행 중인 Claude Code 세션에 연결합니다. 프로젝트에서 Claude에게 컴퓨터에서 스레드를 실행하도록 요청하면, 프로젝트는 [원격 제어를 사용하여 이를 수행합니다](#run-a-thread-on-your-own-computer).

491* **로컬 세션 및 에이전트 뷰**: 터미널, IDE 또는 데스크톱 앱의 로컬 환경에서 직접 시작한 세션은 프로젝트에 추가할 수 없습니다. [에이전트 뷰](/docs/ko/agent-view)는 여러 로컬 세션을 나란히 추적하기 위한 화면이며, 사용자가 각 세션을 직접 시작하고 작업을 할당합니다.491* **로컬 세션 및 에이전트 뷰**: 터미널, IDE 또는 데스크톱 앱의 로컬 환경에서 직접 시작한 세션은 프로젝트에 추가할 수 없습니다. [에이전트 뷰](/docs/ko/agent-view)는 여러 로컬 세션을 나란히 추적하기 위한 화면이며, 사용자가 각 세션을 직접 시작하고 작업을 할당합니다.

492* **Worktrees**: [worktree](/docs/ko/worktrees)는 각 로컬 세션에 리포지토리의 자체 작업 복사본을 제공하므로 머신의 병렬 세션이 서로 덮어쓰지 않습니다. 클라우드 스레드는 이를 필요로 하지 않습니다: 각 스레드는 리포지토리를 자체 클라우드 샌드박스에 복제하고 자체 브랜치에서 작동합니다.492* **Worktrees**: [worktree](/docs/ko/worktrees)는 각 로컬 세션에 저장소의 자체 작업 복사본을 제공합니다. 클라우드 스레드는 이를 필요로 하지 않습니다: 각 스레드는 저장소를 자체 클라우드 샌드박스에 복제하고 자체 브랜치에서 작동합니다.

493* **에이전트 팀**: [에이전트 팀](/docs/ko/agent-teams)은 머신 또는 클라우드 세션 내에서 단일 작업을 위해 팀원 세션을 시작하고 해당 작업으로 끝나는 하나의 세션입니다.493* **에이전트 팀**: [에이전트 팀](/docs/ko/agent-teams)은 머신 또는 클라우드 세션 내에서 단일 작업을 위해 팀원 세션을 시작하고 해당 작업으로 끝나는 하나의 세션입니다.

494* **서브에이전트**: [서브에이전트](/docs/ko/sub-agents)는 하나의 세션 내에서 실행되며, 자체 컨텍스트 윈도우에서 부수적인 작업을 수행하고, 해당 세션에 요약을 반환합니다. 프로젝트의 스레드는 Claude가 시작하고 프로젝트 대화에 보고하는 전체 세션이며, 스레드는 자체 부수 작업을 위해 여전히 서브에이전트를 사용할 수 있습니다.494* **서브에이전트**: [서브에이전트](/docs/ko/sub-agents)는 하나의 세션 내에서 실행되며, 자체 컨텍스트 윈도우에서 부수적인 작업을 수행하고, 해당 세션에 요약을 반환합니다. 프로젝트의 스레드는 Claude가 시작하고 프로젝트 대화에 보고하는 전체 세션이며, 스레드는 자체 부수 작업을 위해 여전히 서브에이전트를 사용할 수 있습니다.

495* **claude.ai 채팅 및 Cowork의 프로젝트**: 스레드나 조정자 없이 대화 및 참조 파일을 그룹화하는 [이전 프로젝트 경험](https://support.claude.com/en/articles/9517075-what-are-projects)입니다. 이러한 프로젝트는 재설계된 경험이 도달할 때까지 현재대로 계속 작동합니다.495* **claude.ai 채팅 및 Cowork의 프로젝트**: 스레드나 조정자 없이 대화 및 참조 파일을 그룹화하는 [이전 프로젝트 경험](https://support.claude.com/en/articles/9517075-what-are-projects)입니다. 이러한 프로젝트는 재설계된 경험이 도달할 때까지 현재대로 계속 작동합니다.

cli-reference.md +4 −4

Details

29| `claude auth status` | 인증 상태를 JSON으로 표시합니다. 사람이 읽을 수 있는 출력을 위해 `--text`를 사용합니다. 로그인된 경우 코드 0으로 종료되고, 로그인되지 않은 경우 1로 종료됩니다. JSON에는 CLI가 사용하는 [구성 디렉토리](/docs/ko/claude-directory)의 이름을 지정하는 `configDirectory` 필드가 포함됩니다. 이 필드는 Claude Code v2.1.268 이상이 필요합니다. JSON의 `authMethod` 필드는 `none`, `claude.ai`, `oauth_token`, `api_key`, `api_key_helper` 또는 `third_party` 중 하나입니다 | `claude auth status` |29| `claude auth status` | 인증 상태를 JSON으로 표시합니다. 사람이 읽을 수 있는 출력을 위해 `--text`를 사용합니다. 로그인된 경우 코드 0으로 종료되고, 로그인되지 않은 경우 1로 종료됩니다. JSON에는 CLI가 사용하는 [구성 디렉토리](/docs/ko/claude-directory)의 이름을 지정하는 `configDirectory` 필드가 포함됩니다. 이 필드는 Claude Code v2.1.268 이상이 필요합니다. JSON의 `authMethod` 필드는 `none`, `claude.ai`, `oauth_token`, `api_key`, `api_key_helper` 또는 `third_party` 중 하나입니다 | `claude auth status` |

30| `claude agents` | [에이전트 보기](/docs/ko/agent-view)를 열어 병렬 백그라운드 세션을 모니터링하고 디스패치합니다. `--cwd <path>`를 사용하여 해당 디렉토리 아래에서 시작된 세션만 표시하거나, `--json`을 사용하여 스크립팅을 위해 활성 세션을 JSON 배열로 인쇄합니다(`--json --all`은 완료된 백그라운드 세션도 포함합니다). `--permission-mode`, `--model`, `--effort` 또는 `--agent`를 전달하여 [디스패치된 세션의 기본값](/docs/ko/agent-view#permission-mode-model-and-effort)을 설정합니다. 최상위 `claude` 명령처럼 `--settings`, `--add-dir`, `--plugin-dir` 및 `--mcp-config`를 허용합니다. 에이전트 보기를 열려면 대화형 터미널이 필요합니다 | `claude agents --json` |30| `claude agents` | [에이전트 보기](/docs/ko/agent-view)를 열어 병렬 백그라운드 세션을 모니터링하고 디스패치합니다. `--cwd <path>`를 사용하여 해당 디렉토리 아래에서 시작된 세션만 표시하거나, `--json`을 사용하여 스크립팅을 위해 활성 세션을 JSON 배열로 인쇄합니다(`--json --all`은 완료된 백그라운드 세션도 포함합니다). `--permission-mode`, `--model`, `--effort` 또는 `--agent`를 전달하여 [디스패치된 세션의 기본값](/docs/ko/agent-view#permission-mode-model-and-effort)을 설정합니다. 최상위 `claude` 명령처럼 `--settings`, `--add-dir`, `--plugin-dir` 및 `--mcp-config`를 허용합니다. 에이전트 보기를 열려면 대화형 터미널이 필요합니다 | `claude agents --json` |

32| `claude auto-mode defaults` | 기본 제공 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 규칙을 JSON으로 인쇄합니다. `claude auto-mode config`를 사용하여 설정이 적용된 유효한 구성을 확인합니다. `--label <prefix>`는 해당 접두사로 시작하는 레이블이 있는 규칙만 인쇄합니다(대소문자 구분 안 함). Claude Code v2.1.208 이상이 필요합니다 | `claude auto-mode defaults --label 'Git Destructive'` |32| `claude auto-mode defaults` | 기본 제공 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 규칙을 JSON으로 인쇄합니다. `claude auto-mode config`를 사용하여 설정이 적용된 유효한 구성을 확인합니다. `--label <prefix>`는 해당 접두사로 시작하는 레이블이 있는 규칙만 인쇄합니다(대소문자 구분 안 함). Claude Code v2.1.208 이상이 필요합니다 | `claude auto-mode defaults --label 'Git Destructive'` |

33| `claude auto-mode reset` | 사용자 설정 파일에서 `autoMode` 섹션을 제거하여 기본 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 구성을 복원합니다. 작성하기 전에 확인을 요청합니다. `-y`/`--yes`를 전달하여 프롬프트를 건너뜁니다. [관리형 설정](/docs/ko/server-managed-settings) 또는 `--settings` 플래그의 규칙은 여전히 적용됩니다. Claude Code v2.1.212 이상이 필요합니다. [기본값 및 유효한 구성 검사](/docs/ko/auto-mode-config#inspect-the-defaults-and-your-effective-config) 참조 | `claude auto-mode reset --yes` |33| `claude auto-mode reset` | 사용자 설정 파일에서 `autoMode` 섹션을 제거하여 기본 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 구성을 복원합니다. 작성하기 전에 확인을 요청합니다. `-y`/`--yes`를 전달하여 프롬프트를 건너뜁니다. [관리형 설정](/docs/ko/server-managed-settings) 또는 `--settings` 플래그의 규칙은 여전히 적용됩니다. Claude Code v2.1.212 이상이 필요합니다. [기본값 및 유효한 구성 검사](/docs/ko/auto-mode-config#inspect-the-defaults-and-your-effective-config) 참조 | `claude auto-mode reset --yes` |

34| `claude daemon logs` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)의 로그 파일 `~/.claude/daemon.log`를 팔로우하며, `Ctrl+C`를 누를 때까지 새 줄이 들어오는 대로 인쇄합니다 | `claude daemon logs` |34| `claude daemon logs` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)의 로그 파일 `~/.claude/daemon.log`를 팔로우하며, `Ctrl+C`를 누를 때까지 새 줄이 들어오는 대로 인쇄합니다 | `claude daemon logs` |

37| `claude daemon stop --any` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)와 이를 호스팅하는 세션을 중지합니다. `--keep-workers`를 전달하여 백그라운드 세션을 실행 중인 상태로 두면 다음 감독자가 이들에 다시 연결됩니다. `--any`는 기본값인 온디맨드 감독자 중지를 확인합니다. 이를 사용하여 [응답하지 않는 감독자](/docs/ko/agent-view#agent-view-says-the-background-service-did-not-respond)에서 복구합니다 | `claude daemon stop --any --keep-workers` |37| `claude daemon stop --any` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)와 이를 호스팅하는 세션을 중지합니다. `--keep-workers`를 전달하여 백그라운드 세션을 실행 중인 상태로 두면 다음 감독자가 이들에 다시 연결됩니다. `--any`는 기본값인 온디맨드 감독자 중지를 확인합니다. 이를 사용하여 [응답하지 않는 감독자](/docs/ko/agent-view#agent-view-says-the-background-service-did-not-respond)에서 복구합니다 | `claude daemon stop --any --keep-workers` |

38| `claude doctor` | 세션을 시작하지 않고 터미널에서 읽기 전용 설치 및 설정 진단을 인쇄합니다. 설치 상태, 설정 파일 검증 오류 및 Remote Control 적격성을 포함합니다. 수정을 적용할 수도 있는 세션 내 설정 점검을 위해 [`/doctor`](/docs/ko/commands#all-commands)를 실행합니다 | `claude doctor` |38| `claude doctor` | 세션을 시작하지 않고 터미널에서 읽기 전용 설치 및 설정 진단을 인쇄합니다. 설치 상태, 설정 파일 검증 오류 및 Remote Control 적격성을 포함합니다. 수정을 적용할 수도 있는 세션 내 설정 점검을 위해 [`/doctor`](/docs/ko/commands#all-commands)를 실행합니다 | `claude doctor` |

39| `claude import [source]` | 다른 코딩 에이전트의 구성을 Claude Code로 가져오기 위해 [`/import`](/docs/ko/commands#all-commands)를 실행하는 대화형 세션을 시작합니다. 명령과 동일한 `--dry-run` 및 `--yes` 옵션을 허용합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform에서는 사용할 수 없습니다. [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)를 끈 경우에도 사용할 수 없습니다. Claude Code v2.1.213 이상이 필요합니다 | `claude import codex --dry-run` |39| `claude import [source]` | 다른 코딩 에이전트의 구성을 Claude Code로 가져오기 위해 [`/import`](/docs/ko/commands#all-commands)를 실행하는 대화형 세션을 시작합니다. 명령과 동일한 `--dry-run` 및 `--yes` 옵션을 허용합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform에서는 사용할 수 없습니다. [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)를 끈 경우에도 사용할 수 없습니다. Claude Code v2.1.213 이상이 필요합니다 | `claude import codex --dry-run` |

42| `claude mcp login <name>` | 구성된 MCP 서버의 OAuth 흐름을 대화형 `/mcp` 패널을 열지 않고 실행합니다. HTTP, SSE 및 claude.ai 커넥터 서버에서 작동합니다. SSH를 통해 `--no-browser`를 추가하여 브라우저를 열지 않고 인증 URL을 인쇄한 다음 리다이렉트 URL을 프롬프트에 다시 붙여넣습니다. [명령줄에서 인증](/docs/ko/mcp#authenticate-from-the-command-line) 참조 | `claude mcp login sentry` |42| `claude mcp login <name>` | 구성된 MCP 서버의 OAuth 흐름을 대화형 `/mcp` 패널을 열지 않고 실행합니다. HTTP, SSE 및 claude.ai 커넥터 서버에서 작동합니다. SSH를 통해 접속한 경우 `--no-browser`를 추가하면 브라우저를 여는 대신 인증 URL을 인쇄합니다. HTTP 또는 SSE 서버의 경우 리다이렉트 URL을 프롬프트에 다시 붙여넣습니다. claude.ai 커넥터의 경우 [셸에서 커넥터 다시 인가](/docs/ko/remote-control#authorize-a-connector-again-from-your-shell)를 참조하세요. [명령줄에서 인증](/docs/ko/mcp#authenticate-from-the-command-line) 참조 | `claude mcp login sentry` |

44| `claude plugin` | Claude Code [플러그인](/docs/ko/plugins/overview)을 관리합니다. 별칭: `claude plugins`. 하위 명령은 [플러그인 참조](/docs/ko/plugins/cli-reference#claude-plugin-commands)를 참조하세요 | `claude plugin install code-review@claude-plugins-official` |44| `claude plugin` | Claude Code [플러그인](/docs/ko/plugins/overview)을 관리합니다. 별칭: `claude plugins`. 하위 명령은 [플러그인 참조](/docs/ko/plugins/cli-reference#claude-plugin-commands)를 참조하세요 | `claude plugin install code-review@claude-plugins-official` |

45| `claude purge [path]` | 프로젝트의 모든 로컬 Claude Code 상태를 삭제합니다: 트랜스크립트, 작업 목록, 디버그 로그, 파일 편집 기록, 프롬프트 기록 라인 및 `~/.claude.json`의 프로젝트 항목. `[path]`를 생략하면 대화형 목록에서 선택할 수 있습니다. 플래그: `--dry-run`으로 미리 보기, `-y`/`--yes`로 확인 건너뛰기, `-i`/`--interactive`로 각 항목 확인, `--all`로 모든 프로젝트. [로컬 데이터 지우기](/docs/ko/claude-directory#clear-local-data) 참조 | `claude purge ~/work/repo --dry-run` |45| `claude purge [path]` | 프로젝트의 모든 로컬 Claude Code 상태를 삭제합니다: 트랜스크립트, 작업 목록, 디버그 로그, 파일 편집 기록, 프롬프트 기록 라인 및 `~/.claude.json`의 프로젝트 항목. `[path]`를 생략하면 대화형 목록에서 선택할 수 있습니다. 플래그: `--dry-run`으로 미리 보기, `-y`/`--yes`로 확인 건너뛰기, `-i`/`--interactive`로 각 항목 확인, `--all`로 모든 프로젝트. [로컬 데이터 지우기](/docs/ko/claude-directory#clear-local-data) 참조 | `claude purge ~/work/repo --dry-run` |

107| `--json-schema` | 에이전트가 워크플로우를 완료한 후 JSON 스키마와 일치하는 검증된 JSON 출력을 가져옵니다(인쇄 모드만 해당). [구조화된 출력](/docs/ko/agent-sdk/structured-outputs)을 참조하세요. Claude Code는 잘못된 스키마에서 오류로 종료되고 클라이언트 측 검증 없이 주석으로 `format` 키워드를 허용합니다 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |107| `--json-schema` | 에이전트가 워크플로우를 완료한 후 JSON 스키마와 일치하는 검증된 JSON 출력을 가져옵니다(인쇄 모드만 해당). [구조화된 출력](/docs/ko/agent-sdk/structured-outputs)을 참조하세요. Claude Code는 잘못된 스키마에서 오류로 종료되고 클라이언트 측 검증 없이 주석으로 `format` 키워드를 허용합니다 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

109| `--max-budget-usd` | 중지하기 전에 API 호출에 지출할 최대 달러 금액입니다(인쇄 모드만 해당). Claude Code는 [클라이언트 측 비용 추정치](/docs/ko/agent-sdk/cost-tracking#estimates-not-billing)를 기준으로 한도를 확인하며, 이는 실제 청구 금액과 다를 수 있습니다. [서브에이전트](/docs/ko/sub-agents)의 지출이 한도에 포함됩니다. `--continue` 또는 `--resume`으로 대화로 돌아올 때 [이전 실행에서 복원된](/docs/ko/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls) 합계는 이에 포함되지 않습니다. 지출이 한도에 도달하면 다른 서브에이전트를 생성하면 `Budget limit reached`로 실패하고 Claude Code는 여전히 실행 중인 백그라운드 서브에이전트를 중지합니다. 한도 적용 동작에는 Claude Code v2.1.217 이상이 필요합니다 | `claude -p --max-budget-usd 5.00 "query"` |109| `--max-budget-usd` | API 호출에 대한 예상 지출이 이 금액에 도달하면 실행을 중지합니다(인쇄 모드만 해당). Claude Code는 [클라이언트 측 비용 추정치](/docs/ko/agent-sdk/cost-tracking#estimates-not-billing)를 기준으로 한도를 확인하며, 이는 실제 청구 금액과 다를 수 있습니다. [서브에이전트](/docs/ko/sub-agents)의 지출이 한도에 포함됩니다. 지출이 한도를 초과할 수 있으므로 [여유를 두세요](/docs/ko/agent-sdk/agent-loop#budget-headroom). `--continue` 또는 `--resume`으로 대화로 돌아올 때 [이전 실행에서 복원된](/docs/ko/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls) 합계는 이에 포함되지 않습니다. 지출이 한도에 도달하면 다른 서브에이전트를 생성하면 `Budget limit reached`로 실패하고 Claude Code는 여전히 실행 중인 백그라운드 서브에이전트를 중지합니다. 한도 적용 동작에는 Claude Code v2.1.217 이상이 필요합니다 | `claude -p --max-budget-usd 5.00 "query"` |

110| `--max-turns` | 에이전트 턴의 수를 제한합니다(인쇄 모드만 해당). 한도에 도달하면 오류로 종료됩니다. 기본적으로 제한이 없습니다. `--input-format stream-json`을 사용하면 한도가 턴을 끝낼 때 여전히 대기열에 있는 메시지는 대기열에 남아 있고 자체 한도로 새 턴을 시작합니다 | `claude -p --max-turns 3 "query"` |110| `--max-turns` | 에이전트 턴의 수를 제한합니다(인쇄 모드만 해당). 한도에 도달하면 오류로 종료됩니다. 기본적으로 제한이 없습니다. `--input-format stream-json`을 사용하면 한도가 턴을 끝낼 때 여전히 대기열에 있는 메시지는 대기열에 남아 있고 자체 한도로 새 턴을 시작합니다 | `claude -p --max-turns 3 "query"` |

111| `--mcp-config` | JSON 파일 또는 문자열에서 MCP 서버를 로드합니다(공백으로 구분). 이 플래그를 `-p`와 함께 전달하면 Claude Code는 첫 번째 턴을 실행하기 전에 여전히 보류 중인 서버가 연결될 때까지 기다립니다. [`MCP_TIMEOUT`](/docs/ko/env-vars) 시작 시간 초과(기본값 30초)까지입니다. [캐시된 도구 목록](/docs/ko/mcp#managing-your-servers)이 있는 서버는 대기를 건너뛰고 처음 사용할 때 연결됩니다. 대기에는 Claude Code v2.1.221 이상이 필요합니다 | `claude --mcp-config ./mcp.json` |111| `--mcp-config` | JSON 파일 또는 문자열에서 MCP 서버를 로드합니다(공백으로 구분). 이 플래그를 `-p`와 함께 전달하면 Claude Code는 첫 번째 턴을 실행하기 전에 여전히 보류 중인 서버가 연결될 때까지 기다립니다. [`MCP_TIMEOUT`](/docs/ko/env-vars) 시작 시간 초과(기본값 30초)까지입니다. [캐시된 도구 목록](/docs/ko/mcp#managing-your-servers)이 있는 서버는 대기를 건너뛰고 처음 사용할 때 연결됩니다. 대기에는 Claude Code v2.1.221 이상이 필요합니다 | `claude --mcp-config ./mcp.json` |

112| `--model` | `sonnet`, `opus`, `haiku` 또는 `fable`과 같은 [모델 별칭](/docs/ko/model-config#model-aliases) 또는 모델의 전체 이름으로 현재 세션에 대한 모델을 설정합니다. [`model`](/docs/ko/settings-reference#model) 설정 및 [`ANTHROPIC_MODEL`](/docs/ko/model-config#environment-variables)을 재정의합니다 | `claude --model claude-sonnet-5` |112| `--model` | `sonnet`, `opus`, `haiku` 또는 `fable`과 같은 [모델 별칭](/docs/ko/model-config#model-aliases) 또는 모델의 전체 이름으로 현재 세션에 대한 모델을 설정합니다. [`model`](/docs/ko/settings-reference#model) 설정 및 [`ANTHROPIC_MODEL`](/docs/ko/model-config#environment-variables)을 재정의합니다 | `claude --model claude-sonnet-5` |

cloud-environments.md +3 −3

Details

307| | 클라우드 세션에서 사용 가능 | 이유 |307| | 클라우드 세션에서 사용 가능 | 이유 |

308| :- | :- | :- |308| :- | :- | :- |

309| 저장소의 `CLAUDE.md` | 예 | 복제본의 일부 |309| 저장소의 `CLAUDE.md` | 예 | 복제본의 일부 |

310| 저장소의 `.claude/settings.json` 훅 및 권한 규칙 | 예, 하나의 저장소가 있는 세션에서 | 복제본의 일부입니다. 여러 저장소가 있는 세션([프로젝트](/docs/ko/claude-projects#what-threads-pick-up-from-your-repositories) 스레드 포함)은 복제본 위에서 시작되며 이를 읽지 않습니다 |310| 저장소의 `.claude/settings.json` 훅 및 권한 규칙 | 예, 하나의 저장소가 있는 세션에서 | 복제본의 일부입니다. 여러 저장소가 있는 세션의 경우 [읽는 설정](/docs/ko/settings#settings-in-cloud-sessions)을 참조하세요 |

312| 저장소의 `.claude/rules/` | 예 | 복제본의 일부 |312| 저장소의 `.claude/rules/` | 예 | 복제본의 일부 |

313| 저장소의 `.claude/skills/`, `.claude/agents/`, `.claude/commands/` | 예 | 복제본의 일부 |313| 저장소의 `.claude/skills/`, `.claude/agents/`, `.claude/commands/` | 예 | 복제본의 일부 |

314| 저장소의 `.claude/settings.json`에 선언된 플러그인 및 마켓플레이스 | 아니오 | 클라우드 세션은 저장소가 [`enabledPlugins`](/docs/ko/settings-reference#enabledplugins) 아래에서 켜는 플러그인을 설치하지 않으며, [`extraKnownMarketplaces`](/docs/ko/settings-reference#extraknownmarketplaces) 아래에 나열하는 마켓플레이스의 플러그인도 포함됩니다 |314| 저장소의 `.claude/settings.json`에 선언된 플러그인 및 마켓플레이스 | 아니오 | 클라우드 세션은 저장소가 [`enabledPlugins`](/docs/ko/settings-reference#enabledplugins) 아래에서 켜는 플러그인을 설치하지 않으며, [`extraKnownMarketplaces`](/docs/ko/settings-reference#extraknownmarketplaces) 아래에 나열하는 마켓플레이스의 플러그인도 포함됩니다 |

575 575

576SessionStart hook은 다음 주의사항을 제외하고 클라우드에서 로컬과 동일하게 작동합니다.576SessionStart hook은 다음 주의사항을 제외하고 클라우드에서 로컬과 동일하게 작동합니다.

577 577

578* **세션당 하나의 리포지토리**: 여러 리포지토리가 있는 세션은 리포지토리의 `.claude/settings.json`에서 hook을 로드하지 않으므로 정의한 SessionStart hook이 실행되지 않습니다. 이러한 세션의 종속성을 [설정 스크립트](#setup-scripts)로 설치합니다.578* **세션당 하나의 저장소**: Anthropic 호스팅 환경에서 여러 저장소가 있는 세션은 어떤 저장소의 `.claude/settings.json`에서도 훅을 로드하지 않으므로 그곳에 정의한 SessionStart 훅이 실행되지 않습니다. 이러한 세션의 의존성은 대신 [설정 스크립트](#setup-scripts)로 설치합니다. 자체 호스팅 환경의 경우 [어떤 저장소의 설정이 적용되는지](/docs/ko/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories)를 참조합니다.

579* **클라우드 전용 범위 없음**: hook은 로컬 및 클라우드 세션 모두에서 실행됩니다. 로컬 실행을 건너뛰려면 `CLAUDE_CODE_REMOTE` 환경 변수가 `true`가 아닌 한 조기에 종료합니다. [종속성 설치 스크립트](#install-dependencies-with-a-sessionstart-hook)가 수행하는 방식입니다.579* **클라우드 전용 범위 없음**: hook은 로컬 및 클라우드 세션 모두에서 실행됩니다. 로컬 실행을 건너뛰려면 `CLAUDE_CODE_REMOTE` 환경 변수가 `true`가 아닌 한 조기에 종료합니다. [종속성 설치 스크립트](#install-dependencies-with-a-sessionstart-hook)가 수행하는 방식입니다.

580* **네트워크 액세스 필요**: 설치 명령은 패키지 레지스트리에 도달해야 합니다. 환경이 **없음** 네트워크 액세스를 사용하면 이러한 hook이 실패합니다. **신뢰됨** 아래의 [기본 허용 목록](#default-allowed-domains)은 npm, PyPI, RubyGems 및 crates.io를 포함합니다.580* **네트워크 액세스 필요**: 설치 명령은 패키지 레지스트리에 도달해야 합니다. 환경이 **없음** 네트워크 액세스를 사용하면 이러한 hook이 실패합니다. **신뢰됨** 아래의 [기본 허용 목록](#default-allowed-domains)은 npm, PyPI, RubyGems 및 crates.io를 포함합니다.

581* **프록시 호환성**: Anthropic 호스팅 환경에서 모든 아웃바운드 트래픽은 [보안 프록시](#security-proxy)를 통과하고, 일부 패키지 관리자는 이와 올바르게 작동하지 않습니다. Bun은 알려진 예입니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments-deploy#default-deny-egress)에서 아웃바운드 트래픽은 대신 자신의 네트워크 경계를 통과합니다.581* **프록시 호환성**: Anthropic 호스팅 환경에서 모든 아웃바운드 트래픽은 [보안 프록시](#security-proxy)를 통과하고, 일부 패키지 관리자는 이와 올바르게 작동하지 않습니다. Bun은 알려진 예입니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments-deploy#default-deny-egress)에서 아웃바운드 트래픽은 대신 자신의 네트워크 경계를 통과합니다.

desktop.md +1 −1

Details

396 세션으로 병렬 작업하기396 세션으로 병렬 작업하기

397</h3>397</h3>

398 398

399사이드바에서 **+ New session**을 클릭하거나 macOS에서 **Cmd+N**을 누르거나 Windows에서 **Ctrl+N**을 눌러 여러 작업을 병렬로 작업합니다. **Ctrl+Tab** 및 **Ctrl+Shift+Tab**을 눌러 사이드바의 세션을 순환합니다. Git 저장소의 경우 브랜치 이름 옆의 **worktree** 옵션을 선택하여 세션이 [Git worktrees](/docs/ko/worktrees)를 사용하여 프로젝트의 자신의 격리된 복사본을 가지도록 하므로 한 세션의 변경 사항이 커밋할 때까지 다른 세션에 영향을 주지 않습니다.399사이드바에서 **+ New session**을 클릭하거나 macOS에서 **Cmd+N**을 누르거나 Windows에서 **Ctrl+N**을 눌러 여러 작업을 병렬로 작업합니다. **Ctrl+Tab** 및 **Ctrl+Shift+Tab**을 눌러 사이드바의 세션을 순환합니다. Git 저장소의 경우 브랜치 이름 옆의 **worktree** 옵션을 선택하면 [Git worktrees](/docs/ko/worktrees)를 사용하여 세션이 프로젝트의 자체 격리된 복사본을 가지게 됩니다.

400 400

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

402 402

env-vars.md +326 −321

Details

21 21

22셸에서 설정한 변수는 해당 터미널 세션 동안만 유지되며, 설정 파일의 변수는 `claude`가 실행될 때마다 적용됩니다.22셸에서 설정한 변수는 해당 터미널 세션 동안만 유지되며, 설정 파일의 변수는 `claude`가 실행될 때마다 적용됩니다.

23 23

~~24<h3 id="in-your-shell">~~24<span id="in-your-shell" />

~~25 셸에서~~25

26<h3 id="set-variables-in-your-shell">

27 셸에서 변수 설정

26</h3>28</h3>

27 29

28`claude`를 실행하기 전에 변수를 설정합니다:30`claude`를 실행하기 전에 변수를 설정합니다:

78 </Tab>80 </Tab>

79</Tabs>81</Tabs>

80 82

~~81<h3 id="in-settings-files">~~83<span id="in-settings-files" />

~~82 설정 파일에서~~84

85<h3 id="set-variables-in-settings-files">

86 설정 파일에서 변수 설정

83</h3>87</h3>

84 88

85`settings.json` 파일의 `env` 키 아래에 변수를 추가하고, 파일이 없으면 생성합니다. Claude Code는 파일에서 직접 읽으므로 `claude`가 어떻게 실행되었는지와 관계없이 적용됩니다. 실행 중인 세션은 파일을 저장할 때 새로운 값과 변경된 값을 환경에 적용하지만, [OpenTelemetry 모니터링](/docs/ko/monitoring-usage)과 같이 시작 시 변수를 한 번만 읽는 기능은 다시 실행할 때까지 시작 값을 유지합니다. 파일에서 변수를 제거해도 실행 중인 세션에서 설정 해제되지 않으며, 제거는 다음 번 `claude`를 실행할 때 적용됩니다.89`settings.json` 파일의 `env` 키 아래에 변수를 추가하고, 파일이 없으면 생성합니다. Claude Code는 파일에서 직접 읽으므로 `claude`가 어떻게 실행되었는지와 관계없이 적용됩니다. 실행 중인 세션은 파일을 저장할 때 새로운 값과 변경된 값을 환경에 적용하지만, [OpenTelemetry 모니터링](/docs/ko/monitoring-usage)과 같이 시작 시 변수를 한 번만 읽는 기능은 다시 실행할 때까지 시작 값을 유지합니다. 파일에서 변수를 제거해도 실행 중인 세션에서 설정 해제되지 않으며, 제거는 다음 번 `claude`를 실행할 때 적용됩니다.

120 124

121환경 변수가 CLI 플래그 및 세션 내 명령과 상호 작용하는 방식은 기능마다 다릅니다: `--model`과 `/model`은 `ANTHROPIC_MODEL`을 재정의하고, `CLAUDE_CODE_EFFORT_LEVEL`은 `--effort`와 `/effort`를 재정의합니다. 변수가 다른 구성 소스와 상호 작용할 때, [변수](#variables) 목록의 해당 행은 우선순위를 나타내거나 이를 문서화하는 페이지로 연결됩니다.125환경 변수가 CLI 플래그 및 세션 내 명령과 상호 작용하는 방식은 기능마다 다릅니다: `--model`과 `/model`은 `ANTHROPIC_MODEL`을 재정의하고, `CLAUDE_CODE_EFFORT_LEVEL`은 `--effort`와 `/effort`를 재정의합니다. 변수가 다른 구성 소스와 상호 작용할 때, [변수](#variables) 목록의 해당 행은 우선순위를 나타내거나 이를 문서화하는 페이지로 연결됩니다.

122 126

123Claude Code는 시작 시 셸 환경 변수를 읽으므로, 이에 대한 변경 사항은 다음에 `claude`를 시작할 때 적용됩니다. 설정 파일의 `env` 키 아래에 설정된 변수는 파일이 변경될 때 실행 중인 세션에 다시 적용되며, [설정 파일에서](#in-settings-files)에 설명된 시작 전용 예외가 있습니다.127Claude Code는 시작 시 셸 환경 변수를 읽으므로, 이에 대한 변경 사항은 다음에 `claude`를 시작할 때 적용됩니다. 설정 파일의 `env` 키 아래에 설정된 변수는 파일이 변경될 때 실행 중인 세션에 다시 적용되며, [설정 파일에서 변수 설정하기](#in-settings-files)에 설명된 시작 전용 예외가 있습니다.

124 128

125<h2 id="variables">129<h2 id="variables">

126 변수130 변수

127</h2>131</h2>

128 132

129타임아웃, 토큰 예산, 재시도 횟수와 같은 숫자 변수는 일반 숫자 외에도 과학적 표기법과 자릿수 구분자 표기를 허용합니다. 단, 해당 변수의 행에 일반 숫자만 허용한다고 명시된 경우는 예외입니다. 예를 들어 Claude Code는 `2e3`을 2000으로, `64_000`을 64000으로 읽습니다. v2.1.211 이전에는 `1e6`이 타임아웃을 1로 설정하는 것처럼 이러한 표기가 훨씬 작은 값을 알림 없이 설정할 수 있었습니다.133타임아웃, 토큰 예산, 재시도 횟수 같은 숫자 변수는 일반 숫자 외에도 과학적 표기법과 자릿수 구분자 표기를 허용합니다. 단, 변수 행에 일반 숫자만 허용한다고 명시된 경우는 예외입니다. 예를 들어 Claude Code는 `2e3`을 2000으로, `64_000`을 64000으로 읽습니다. v2.1.211 이전에는 `1e6`이 타임아웃을 1로 설정하는 것처럼, 이러한 표기가 아무 알림 없이 훨씬 작은 값을 설정할 수 있었습니다.

130 134

131<Note>135<Note>

132 동작을 켜거나 끄는 변수의 경우, 켜려면 대소문자와 관계없이 `1`, `true`, `yes`, `on` 중 하나를, 끄려면 `0`, `false`, `no`, `off` 중 하나를 설정합니다.136 동작을 켜거나 끄는 변수의 경우, 대소문자에 관계없이 `1`, `true`, `yes`, `on`으로 설정하면 켜지고 `0`, `false`, `no`, `off`로 설정하면 꺼집니다.

133 137

134 일부 변수는 설정 여부만 읽으므로 `0`을 포함한 비어 있지 않은 모든 값이 동작을 켜며, 동작을 끄려면 변수를 설정 해제하거나 빈 값으로 설정해야 합니다. 다음 변수가 이 방식으로 작동합니다.138 일부 변수는 설정 여부만 확인하므로 `0`을 포함해 비어 있지 않은 모든 값이 동작을 켜며, 동작을 끄려면 변수를 설정 해제하거나 빈 값으로 설정해야 합니다. 다음 변수가 이 방식으로 동작합니다:

135 139

136 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`140 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

137 * `DISABLE_TELEMETRY`141 * `DISABLE_TELEMETRY`

140 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`144 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

141 * `IS_DEMO`145 * `IS_DEMO`

142 146

143 다른 한 가지 변수는 자체 규칙을 따릅니다. `FORCE_HYPERLINK`는 숫자를 읽으므로 `0`만 이를 끕니다. 각 변수의 행에도 해당 변수의 규칙이 명시되어 있습니다.147 다른 한 변수는 자체 규칙을 따릅니다: `FORCE_HYPERLINK`는 숫자를 읽으므로 `0`만 이를 끕니다. 각 변수의 행에도 해당 변수의 규칙이 명시되어 있습니다.

144</Note>148</Note>

145 149

146| 변수 | 용도 |150| 변수 | 용도 |

147| :- | :- |151| :- | :- |

148| `ANTHROPIC_API_KEY` | `X-Api-Key` 헤더로 전송되는 API 키입니다. 설정하면 로그인한 상태라도 Claude Pro, Max, Team 또는 Enterprise 구독 대신 이 키가 사용됩니다. 비대화형 모드(`-p`)에서는 키가 있으면 항상 사용됩니다. 대화형 모드에서는 키가 구독을 재정의하기 전에 키를 한 번 승인하라는 확인 요청이 표시됩니다. 대신 구독을 사용하려면 `unset ANTHROPIC_API_KEY`를 실행합니다 |152| `ANTHROPIC_API_KEY` | `X-Api-Key` 헤더로 전송되는 API 키입니다. 설정하면 로그인한 상태라도 Claude Pro, Max, Team 또는 Enterprise 구독 대신 이 키가 사용됩니다. 비대화형 모드(`-p`)에서는 키가 있으면 항상 사용됩니다. 대화형 모드에서는 키가 구독을 재정의하기 전에 한 번 승인하라는 확인 요청이 표시됩니다. 구독을 대신 사용하려면 `unset ANTHROPIC_API_KEY`를 실행합니다 |

150| `ANTHROPIC_AWS_API_KEY` | AWS Console에서 생성한 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)용 워크스페이스 API 키입니다. `x-api-key`로 전송되며 AWS SigV4보다 우선합니다 |154| `ANTHROPIC_AWS_API_KEY` | AWS Console에서 생성한 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)용 워크스페이스 API 키입니다. `x-api-key`로 전송되며 AWS SigV4보다 우선합니다 |

151| `ANTHROPIC_AWS_BASE_URL` | [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 엔드포인트 URL을 재정의합니다. 사용자 지정 리전에 사용하거나 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. 기본값은 `https://aws-external-anthropic.{region}.api.aws`입니다. Claude Code는 [Amazon Bedrock과 동일한 우선순위](/docs/ko/amazon-bedrock#3-configure-claude-code)로 리전을 결정합니다 |155| `ANTHROPIC_AWS_BASE_URL` | [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 엔드포인트 URL을 재정의합니다. 사용자 지정 리전에서 사용하거나 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. 기본값은 `https://aws-external-anthropic.{region}.api.aws`입니다. Claude Code는 [Amazon Bedrock과 동일한 우선순위](/docs/ko/amazon-bedrock#3-configure-claude-code)로 리전을 결정합니다 |

152| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)에 필수입니다. 모든 요청에 `anthropic-workspace-id` 헤더로 전송됩니다 |156| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)에 필수입니다. 모든 요청에 `anthropic-workspace-id` 헤더로 전송됩니다 |

153| `ANTHROPIC_BASE_URL` | 요청을 프록시나 게이트웨이를 통해 라우팅하도록 API 엔드포인트를 재정의합니다. 퍼스트 파티가 아닌 호스트로 설정하면 [MCP 도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)이 기본적으로 비활성화됩니다. 프록시가 `tool_reference` 블록을 전달하는 경우 `ENABLE_TOOL_SEARCH=true`를 설정합니다. v2.1.196부터 이 값이 `api.anthropic.com` 이외의 호스트를 가리키면 [Remote Control](/docs/ko/remote-control#requirements)이 비활성화되며, 이는 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry에서의 동작과 일치합니다 |157| `ANTHROPIC_BASE_URL` | 프록시나 게이트웨이를 통해 요청을 라우팅하도록 API 엔드포인트를 재정의합니다. 퍼스트 파티가 아닌 호스트로 설정하면 [MCP 도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)이 기본적으로 비활성화됩니다. 프록시가 `tool_reference` 블록을 전달하는 경우 `ENABLE_TOOL_SEARCH=true`를 설정합니다. v2.1.196부터 이 값이 `api.anthropic.com` 이외의 호스트를 가리키면 [Remote Control](/docs/ko/remote-control#requirements)이 비활성화되며, 이는 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry에서의 동작과 동일합니다 |

154| `ANTHROPIC_BEDROCK_BASE_URL` | Amazon Bedrock 엔드포인트 URL을 재정의합니다. 사용자 지정 Amazon Bedrock 엔드포인트에 사용하거나 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock)을 참조하세요 |158| `ANTHROPIC_BEDROCK_BASE_URL` | Amazon Bedrock 엔드포인트 URL을 재정의합니다. 사용자 지정 Amazon Bedrock 엔드포인트에 사용하거나 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock)을 참조하세요 |

155| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | Amazon Bedrock Mantle 엔드포인트 URL을 재정의합니다. [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)를 참조하세요 |159| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | Amazon Bedrock Mantle 엔드포인트 URL을 재정의합니다. [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)를 참조하세요 |

156| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Claude Code가 AWS 리전에서 도출한 접두사 대신 먼저 시도하는 교차 리전 추론 프로필 접두사(`us`, `eu`, `apac`, `jp`, `au` 또는 `global`)입니다. AWS GovCloud 리전에서는 무시됩니다. Claude Code v2.1.224 이상이 필요합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock#cross-region-inference-profile-prefixes)을 참조하세요 |160| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Claude Code가 AWS 리전에서 도출한 접두사 대신 먼저 시도하는 교차 리전 추론 프로필 접두사(`us`, `eu`, `apac`, `jp`, `au` 또는 `global`)입니다. AWS GovCloud 리전에서는 무시됩니다. Claude Code v2.1.224 이상이 필요합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock#cross-region-inference-profile-prefixes)을 참조하세요 |

157| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [서비스 티어](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)(`default`, `flex` 또는 `priority`)입니다. `X-Amzn-Bedrock-Service-Tier` 헤더로 전송됩니다. [Amazon Bedrock](/docs/ko/amazon-bedrock#service-tiers)을 참조하세요 |161| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [서비스 티어](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)(`default`, `flex` 또는 `priority`)입니다. `X-Amzn-Bedrock-Service-Tier` 헤더로 전송됩니다. [Amazon Bedrock](/docs/ko/amazon-bedrock#service-tiers)을 참조하세요 |

158| `ANTHROPIC_BETAS` | API 요청에 포함할 추가 `anthropic-beta` 헤더 값의 쉼표로 구분된 목록입니다. Claude Code는 필요한 베타 헤더를 이미 전송합니다. Claude Code가 기본 지원을 추가하기 전에 [Anthropic API 베타](https://platform.claude.com/docs/en/api/beta-headers)를 사용하려면 이 변수를 사용합니다. API 키 인증이 필요한 [`--betas` 플래그](/docs/ko/cli-reference#cli-flags)와 달리, 이 변수는 Claude.ai 구독을 포함한 모든 인증 방법에서 작동합니다 |162| `ANTHROPIC_BETAS` | API 요청에 포함할 추가 `anthropic-beta` 헤더 값의 쉼표로 구분된 목록입니다. Claude Code는 필요한 베타 헤더를 이미 전송합니다. Claude Code가 기본 지원을 추가하기 전에 [Anthropic API 베타](https://platform.claude.com/docs/en/api/beta-headers)를 사용하려면 이 변수를 사용합니다. API 키 인증이 필요한 [`--betas` 플래그](/docs/ko/cli-reference#cli-flags)와 달리, 이 변수는 Claude.ai 구독을 포함한 모든 인증 방식에서 작동합니다 |

159| `ANTHROPIC_CUSTOM_HEADERS` | 요청에 추가할 사용자 지정 헤더(`Name: Value` 형식, 여러 헤더는 줄바꿈으로 구분)입니다. 이름이나 값에 둥근 따옴표나 폭이 없는 공백(zero-width space)처럼 HTTP 헤더가 전달할 수 없는 문자가 포함되면 요청이 실패하며, 오류에서 해당 쌍을 위치로 식별합니다. Claude Code v2.1.227 이상이 필요합니다. [Invalid request header value](/docs/ko/errors#invalid-request-header-value)에 정확한 문자 집합과 검사가 실행되는 위치가 나와 있습니다. `Authorization`이나 `Host`처럼 자격 증명, 조직 또는 테넌트, 라우팅, API 동작 헤더를 설정하는 값은 서버 관리형 설정이 전달하는 경우 [승인이 필요한 설정](/docs/ko/server-managed-settings#environment-variables-and-the-approval-dialog)으로 간주됩니다. 프로젝트 또는 로컬 설정에서 전달되는 이러한 값은 [`env` 값이 적용되는 시점에 대한 규칙](/docs/ko/settings-reference#when-claude-code-applies-env-values)을 따릅니다 |163| `ANTHROPIC_CUSTOM_HEADERS` | 요청에 추가할 사용자 지정 헤더입니다(`Name: Value` 형식, 여러 헤더는 줄바꿈으로 구분). 이름이나 값에 둥근 따옴표나 폭이 없는 공백처럼 HTTP 헤더가 담을 수 없는 문자가 포함되어 있으면, 요청은 해당 쌍을 위치로 식별하는 오류와 함께 실패합니다. Claude Code v2.1.227 이상이 필요합니다. [Invalid request header value](/docs/ko/errors#invalid-request-header-value)에 정확한 문자 집합과 검사가 실행되는 위치가 나와 있습니다. `Authorization`이나 `Host`처럼 자격 증명, 조직 또는 테넌트, 라우팅, API 동작 헤더를 설정하는 값은 서버 관리형 설정이 전달할 때 [승인이 필요한 설정](/docs/ko/server-managed-settings#environment-variables-and-the-approval-dialog)으로 간주됩니다. 프로젝트 또는 로컬 설정에서 오는 이러한 값은 [`env` 값이 적용되는 시점에 대한 규칙](/docs/ko/settings-reference#when-claude-code-applies-env-values)을 따릅니다 |

160| `ANTHROPIC_CUSTOM_MODEL_OPTION` | `/model` 선택기에 사용자 지정 항목으로 추가할 모델 ID입니다. 기본 제공 별칭을 대체하지 않고 비표준 모델이나 게이트웨이 전용 모델을 선택할 수 있게 하려면 이 변수를 사용합니다. [모델 구성](/docs/ko/model-config#add-a-custom-model-option)을 참조하세요 |164| `ANTHROPIC_CUSTOM_MODEL_OPTION` | `/model` 선택기에 사용자 지정 항목으로 추가할 모델 ID입니다. 기본 제공 별칭을 대체하지 않고 비표준 모델이나 게이트웨이 전용 모델을 선택할 수 있게 하려면 이 변수를 사용합니다. [모델 구성](/docs/ko/model-config#add-a-custom-model-option)을 참조하세요 |

161| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | `/model` 선택기의 사용자 지정 모델 항목에 표시되는 설명입니다. 설정하지 않으면 기본값은 `Custom model (<model-id>)`입니다 |165| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | `/model` 선택기에 표시되는 사용자 지정 모델 항목의 설명입니다. 설정하지 않으면 기본값은 `Custom model (<model-id>)`입니다 |

162| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 선택기의 사용자 지정 모델 항목에 표시되는 이름입니다. 설정하지 않으면 Claude Code가 [ID를 인식하는](/docs/ko/model-config#customize-pinned-model-display-and-capabilities) 경우 모델 이름이, 그렇지 않으면 모델 ID가 표시됩니다 |166| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 선택기에 표시되는 사용자 지정 모델 항목의 이름입니다. 설정하지 않으면 Claude Code가 [ID를 인식](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)하는 경우 모델 이름을, 그렇지 않으면 모델 ID를 표시합니다 |

163| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 사용자 지정 모델이 지원하는 [기능](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)의 쉼표로 구분된 목록입니다(예: `effort,thinking`). [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |167| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 사용자 지정 모델이 지원하는 [기능](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)의 쉼표로 구분된 목록입니다(예: `effort,thinking`). [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |

164| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 별칭이 가리키는 모델 ID이자, 서드파티 공급자에서 [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)을 위해 Claude Code가 Fable 모델로 인식하는 ID입니다. [모델 구성](/docs/ko/model-config#environment-variables)을 참조하세요 |168| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 별칭이 가리키는 모델 ID이자, 서드파티 제공자에서 [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)을 위해 Claude Code가 Fable 모델로 인식하는 ID입니다. [모델 구성](/docs/ko/model-config#environment-variables)을 참조하세요 |

165| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 선택기에서 고정된 Fable 모델에 표시되는 설명입니다. 설정하지 않으면 해당 행에 `Custom Fable model`로 시작하는 기본 설명이 표시됩니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |169| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 선택기에 표시되는 고정된 Fable 모델의 설명입니다. 설정하지 않으면 해당 행에 `Custom Fable model`로 시작하는 기본 설명이 표시됩니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |

166| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 선택기에서 고정된 Fable 모델에 표시되는 이름입니다. 설정하지 않으면 Claude Code가 고정된 ID를 인식하는 경우 해당 행에 모델 이름이, 그렇지 않으면 고정된 ID가 표시됩니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |170| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 선택기에 표시되는 고정된 Fable 모델의 이름입니다. 설정하지 않으면 Claude Code가 고정된 ID를 인식하는 경우 해당 행에 모델 이름을, 그렇지 않으면 고정된 ID를 표시합니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |

167| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 고정된 Fable 모델이 지원하는 [기능](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)의 쉼표로 구분된 목록입니다(예: `effort,thinking`). [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |171| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 고정된 Fable 모델이 지원하는 [기능](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)의 쉼표로 구분된 목록입니다(예: `effort,thinking`). [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |

168| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 별칭이 가리키는 모델 ID로, [백그라운드 기능](/docs/ko/costs#background-token-usage)에도 사용됩니다. [모델 구성](/docs/ko/model-config#environment-variables)을 참조하세요 |172| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 별칭이 가리키는 모델 ID이며, [백그라운드 기능](/docs/ko/costs#background-token-usage)에도 사용됩니다. [모델 구성](/docs/ko/model-config#environment-variables)을 참조하세요 |

169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 선택기에서 고정된 Haiku 모델에 표시되는 설명입니다. 설정하지 않으면 해당 행에 `Custom Haiku model`로 시작하는 기본 설명이 표시됩니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |173| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 선택기에 표시되는 고정된 Haiku 모델의 설명입니다. 설정하지 않으면 해당 행에 `Custom Haiku model`로 시작하는 기본 설명이 표시됩니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |

170| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 선택기에서 고정된 Haiku 모델에 표시되는 이름입니다. 설정하지 않으면 Claude Code가 고정된 ID를 인식하는 경우 해당 행에 모델 이름이, 그렇지 않으면 고정된 ID가 표시됩니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |174| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 선택기에 표시되는 고정된 Haiku 모델의 이름입니다. 설정하지 않으면 Claude Code가 고정된 ID를 인식하는 경우 해당 행에 모델 이름을, 그렇지 않으면 고정된 ID를 표시합니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |

171| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 고정된 Haiku 모델이 지원하는 [기능](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)의 쉼표로 구분된 목록입니다(예: `effort,thinking`). [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |175| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 고정된 Haiku 모델이 지원하는 [기능](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)의 쉼표로 구분된 목록입니다(예: `effort,thinking`). [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |

172| `ANTHROPIC_DEFAULT_MODEL` | 새 세션이 기본적으로 시작하는 모델입니다. Claude Code v2.1.236 이상이 필요합니다. [새 세션의 기본 모델 설정](/docs/ko/model-config#set-a-default-model-for-new-sessions)을 참조하세요 |176| `ANTHROPIC_DEFAULT_MODEL` | 새 세션이 기본적으로 시작하는 모델입니다. Claude Code v2.1.236 이상이 필요합니다. [새 세션의 기본 모델 설정](/docs/ko/model-config#set-a-default-model-for-new-sessions)을 참조하세요 |

173| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 별칭이 가리키는 모델 ID이자, 플랜 모드가 활성화된 동안 `opusplan`이 사용하는 모델 ID입니다. [모델 구성](/docs/ko/model-config#environment-variables)을 참조하세요 |177| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 별칭이 가리키는 모델 ID이자, 플랜 모드가 활성화된 동안 `opusplan`이 사용하는 모델 ID입니다. [모델 구성](/docs/ko/model-config#environment-variables)을 참조하세요 |

174| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 선택기에서 고정된 Opus 모델에 표시되는 설명입니다. 설정하지 않으면 해당 행에 `Custom Opus model`로 시작하는 기본 설명이 표시됩니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |178| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 선택기에 표시되는 고정된 Opus 모델의 설명입니다. 설정하지 않으면 해당 행에 `Custom Opus model`로 시작하는 기본 설명이 표시됩니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |

175| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 선택기에서 고정된 Opus 모델에 표시되는 이름입니다. 설정하지 않으면 Claude Code가 고정된 ID를 인식하는 경우 해당 행에 모델 이름이, 그렇지 않으면 고정된 ID가 표시됩니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |179| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 선택기에 표시되는 고정된 Opus 모델의 이름입니다. 설정하지 않으면 Claude Code가 고정된 ID를 인식하는 경우 해당 행에 모델 이름을, 그렇지 않으면 고정된 ID를 표시합니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |

176| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 고정된 Opus 모델이 지원하는 [기능](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)의 쉼표로 구분된 목록입니다(예: `effort,thinking`). [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |180| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 고정된 Opus 모델이 지원하는 [기능](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)의 쉼표로 구분된 목록입니다(예: `effort,thinking`). [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |

177| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 별칭이 가리키는 모델 ID이자, 플랜 모드가 활성화되지 않았을 때 `opusplan`이 사용하는 모델 ID입니다. [모델 구성](/docs/ko/model-config#environment-variables)을 참조하세요 |181| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 별칭이 가리키는 모델 ID이자, 플랜 모드가 활성화되지 않았을 때 `opusplan`이 사용하는 모델 ID입니다. [모델 구성](/docs/ko/model-config#environment-variables)을 참조하세요 |

178| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 선택기에서 고정된 Sonnet 모델에 표시되는 설명입니다. 설정하지 않으면 해당 행에 `Custom Sonnet model`로 시작하는 기본 설명이 표시됩니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |182| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 선택기에 표시되는 고정된 Sonnet 모델의 설명입니다. 설정하지 않으면 해당 행에 `Custom Sonnet model`로 시작하는 기본 설명이 표시됩니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |

179| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 선택기에서 고정된 Sonnet 모델에 표시되는 이름입니다. 설정하지 않으면 Claude Code가 고정된 ID를 인식하는 경우 해당 행에 모델 이름이, 그렇지 않으면 고정된 ID가 표시됩니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |183| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 선택기에 표시되는 고정된 Sonnet 모델의 이름입니다. 설정하지 않으면 Claude Code가 고정된 ID를 인식하는 경우 해당 행에 모델 이름을, 그렇지 않으면 고정된 ID를 표시합니다. [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |

180| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 고정된 Sonnet 모델이 지원하는 [기능](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)의 쉼표로 구분된 목록입니다(예: `effort,thinking`). [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |184| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 고정된 Sonnet 모델이 지원하는 [기능](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)의 쉼표로 구분된 목록입니다(예: `effort,thinking`). [모델 구성](/docs/ko/model-config#customize-pinned-model-display-and-capabilities)을 참조하세요 |

181| `ANTHROPIC_FEDERATION_RULE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)의 페더레이션 규칙 ID입니다. `ANTHROPIC_ORGANIZATION_ID`와 함께 설정하면 Claude Code는 페더레이션 자격 증명을 선택하며, 이는 `/login` 자격 증명보다 우선순위가 높습니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하세요 |185| `ANTHROPIC_FEDERATION_RULE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)용 페더레이션 규칙 ID입니다. `ANTHROPIC_ORGANIZATION_ID`와 함께 설정하면 Claude Code는 페더레이션 자격 증명을 선택하며, 이는 `/login` 자격 증명보다 우선순위가 높습니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하세요 |

183| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | Microsoft Entra 액세스 토큰과 같은 Microsoft Foundry 인증용 Bearer 토큰입니다. Claude Code는 이를 `Authorization: Bearer` 헤더로 전송합니다. `ANTHROPIC_FOUNDRY_API_KEY`와 Azure 기본 자격 증명 체인보다 우선합니다. [Microsoft Foundry](/docs/ko/microsoft-foundry)를 참조하세요. Claude Code v2.1.203 이상이 필요합니다 |187| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | Microsoft Entra 액세스 토큰과 같은 Microsoft Foundry 인증용 Bearer 토큰입니다. Claude Code는 이를 `Authorization: Bearer` 헤더로 전송합니다. `ANTHROPIC_FOUNDRY_API_KEY`와 Azure 기본 자격 증명 체인보다 우선합니다. [Microsoft Foundry](/docs/ko/microsoft-foundry)를 참조하세요. Claude Code v2.1.203 이상이 필요합니다 |

184| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 리소스의 전체 기본 URL(예: `https://my-resource.services.ai.azure.com/anthropic`)입니다. `ANTHROPIC_FOUNDRY_RESOURCE`의 대안입니다([Microsoft Foundry](/docs/ko/microsoft-foundry) 참조) |188| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 리소스의 전체 기본 URL입니다(예: `https://my-resource.services.ai.azure.com/anthropic`). `ANTHROPIC_FOUNDRY_RESOURCE`의 대안입니다([Microsoft Foundry](/docs/ko/microsoft-foundry) 참조) |

185| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 리소스 이름(예: `my-resource`)입니다. Claude Code는 [URL이나 호스트 이름을 거부합니다](/docs/ko/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name). `ANTHROPIC_FOUNDRY_BASE_URL`이 설정되지 않은 경우 필수입니다([Microsoft Foundry](/docs/ko/microsoft-foundry) 참조) |189| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 리소스 이름입니다(예: `my-resource`). Claude Code는 [URL이나 호스트 이름을 거부](/docs/ko/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name)합니다. `ANTHROPIC_FOUNDRY_BASE_URL`이 설정되지 않은 경우 필수입니다([Microsoft Foundry](/docs/ko/microsoft-foundry) 참조) |

187| `ANTHROPIC_ORGANIZATION_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)의 조직 ID입니다. `ANTHROPIC_FEDERATION_RULE_ID`와 함께 설정합니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하세요 |191| `ANTHROPIC_ORGANIZATION_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)용 조직 ID입니다. `ANTHROPIC_FEDERATION_RULE_ID`와 함께 설정합니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하세요 |

188| `ANTHROPIC_PROFILE` | 인증에 사용할 Anthropic 프로필의 이름으로, [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication)이나 [API 키 없이 Console 계정에 로그인](/docs/ko/authentication#sign-in-without-an-api-key)하여 생성한 프로필 등이 있습니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하세요 |192| `ANTHROPIC_PROFILE` | [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication)으로 만들었거나 [API 키 없이 Console 계정에 로그인](/docs/ko/authentication#sign-in-without-an-api-key)하여 만든 프로필처럼, 인증에 사용할 Anthropic 프로필의 이름입니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하세요 |

190| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Amazon Bedrock 또는 Amazon Bedrock Mantle 사용 시 Haiku급 모델의 AWS 리전을 재정의합니다. Amazon Bedrock에서는 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 또는 deprecated된 `ANTHROPIC_SMALL_FAST_MODEL`도 설정된 경우에만 적용됩니다. 그렇지 않으면 Amazon Bedrock은 세션 리전에서 [기본 Sonnet 모델 또는 주 모델](/docs/ko/amazon-bedrock#4-pin-model-versions)로 백그라운드 작업을 실행하기 때문입니다 |194| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Amazon Bedrock 또는 Amazon Bedrock Mantle을 사용할 때 Haiku급 모델의 AWS 리전을 재정의합니다. Amazon Bedrock에서는 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 또는 deprecated된 `ANTHROPIC_SMALL_FAST_MODEL`도 설정된 경우에만 적용됩니다. 그렇지 않으면 Amazon Bedrock은 세션 리전에서 [기본 Sonnet 모델 또는 주 모델](/docs/ko/amazon-bedrock#4-pin-model-versions)로 백그라운드 작업을 실행하기 때문입니다 |

191| `ANTHROPIC_VERTEX_BASE_URL` | Google Cloud's Agent Platform 엔드포인트 URL을 재정의합니다. 사용자 지정 Google Cloud's Agent Platform 엔드포인트에 사용하거나 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai)을 참조하세요 |195| `ANTHROPIC_VERTEX_BASE_URL` | Google Cloud's Agent Platform 엔드포인트 URL을 재정의합니다. 사용자 지정 Google Cloud's Agent Platform 엔드포인트에 사용하거나 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai)을 참조하세요 |

192| `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)을 참조하세요 |

193| `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입니다. 페더레이션 규칙의 범위가 둘 이상의 워크스페이스로 지정된 경우, 토큰 교환이 대상 워크스페이스를 알 수 있도록 이 값을 설정합니다 |

194| `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`으로 설정하더라도 오랫동안 아무 응답이 없는 일시 중지를 중단합니다 |

195| `API_TIMEOUT_MS` | API 요청의 타임아웃(밀리초)입니다(기본값: 600000, 즉 10분, 최댓값: 2147483647). 느린 네트워크에서 요청이 시간 초과되거나 프록시를 통해 라우팅할 때 이 값을 늘립니다. 최댓값을 초과하는 값은 기본 타이머를 오버플로시켜 요청이 즉시 실패합니다 |199| `API_TIMEOUT_MS` | API 요청의 타임아웃(밀리초)입니다(기본값: 600000, 즉 10분, 최댓값: 2147483647). 느린 네트워크에서 요청이 시간 초과되거나 프록시를 통해 라우팅할 때 이 값을 늘립니다. 최댓값을 초과하는 값은 내부 타이머를 오버플로시켜 요청이 즉시 실패하게 만듭니다 |

196| `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/) 참조) |

197| `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 이상이 필요합니다 |

198| `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)을 참조하세요 |

199| `BASH_MAX_TIMEOUT_MS` | 모델이 포그라운드 Bash 또는 PowerShell 도구 명령에 설정할 수 있는 최대 타임아웃(밀리초)입니다(기본값: 600000, 즉 10분). 실제 상한은 이 값과 `BASH_DEFAULT_TIMEOUT_MS` 중 더 큰 값입니다. 실제 상한이 2시간보다 길면 무인 세션에서 [백그라운드 명령의 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands) 최댓값도 됩니다. 백그라운드 시간 제한에는 Claude Code v2.1.285 이상이 필요합니다 |203| `BASH_MAX_TIMEOUT_MS` | 모델이 포그라운드 Bash 또는 PowerShell 도구 명령에 설정할 수 있는 최대 타임아웃(밀리초)입니다(기본값: 600000, 즉 10분). 실제 상한은 이 값과 `BASH_DEFAULT_TIMEOUT_MS` 중 더 큰 값입니다. 실제 상한이 2시간보다 길면 무인 세션에서 [백그라운드 명령의 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands) 최댓값도 됩니다. 백그라운드 시간 제한에는 Claude Code v2.1.285 이상이 필요합니다 |

200| `BETA_TRACING_ENDPOINT` | [상세 베타 트레이싱](/docs/ko/monitoring-usage#traces-beta)용 OTLP/HTTP 엔드포인트입니다. `ENABLE_BETA_TRACING_DETAILED=1`과 함께 사용하면 로그와 트레이스가 구성된 익스포터 대신 이곳으로 전송됩니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |204| `BETA_TRACING_ENDPOINT` | [상세 베타 트레이싱](/docs/ko/monitoring-usage#traces-beta)용 OTLP/HTTP 엔드포인트입니다. `ENABLE_BETA_TRACING_DETAILED=1`과 함께 사용하면 로그와 트레이스가 구성된 익스포터 대신 이 엔드포인트로 전송됩니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |

201| `CCR_FORCE_BUNDLE` | `1`로 설정하면 [`claude --cloud`](/docs/ko/claude-code-on-the-web#send-local-repositories-without-github)가 원격에서 클론하는 대신 로컬 저장소를 번들로 묶어 업로드하도록 강제합니다 |205| `CCR_FORCE_BUNDLE` | `1`로 설정하면 [`claude --cloud`](/docs/ko/claude-code-on-the-web#send-local-repositories-without-github)가 원격에서 클론하는 대신 로컬 저장소를 번들로 묶어 업로드하도록 강제합니다 |

202| `CLAUDECODE` | Claude Code가 생성하는 하위 프로세스(Bash 및 PowerShell 도구, tmux 세션, [훅](/docs/ko/hooks) 명령, [상태줄](/docs/ko/statusline) 명령, stdio [MCP 서버](/docs/ko/mcp) 하위 프로세스)에서 `1`로 설정됩니다. IDE 확장 프로그램도 통합 터미널에서 이 변수를 설정합니다. 스크립트가 Claude Code가 생성한 하위 프로세스 안에서 실행 중인지 감지하는 데 사용합니다. Claude Code가 시작한 stdio MCP 서버 내부가 아니라 도구 호출이나 훅에 의해 현재 프로세스가 직접 생성되었는지 확인하려면 대신 `CLAUDE_CODE_CHILD_SESSION`을 사용합니다 |206| `CLAUDECODE` | Claude Code가 생성하는 하위 프로세스(Bash 및 PowerShell 도구, tmux 세션, [훅](/docs/ko/hooks) 명령, [상태줄](/docs/ko/statusline) 명령, stdio [MCP 서버](/docs/ko/mcp) 하위 프로세스)에서 `1`로 설정됩니다. IDE 확장 프로그램도 통합 터미널에서 이 값을 설정합니다. 스크립트가 Claude Code가 생성한 하위 프로세스 안에서 실행 중인지 감지하는 데 사용합니다. 현재 프로세스가 Claude Code가 시작한 stdio MCP 서버 내부가 아니라 도구 호출이나 훅에 의해 직접 생성되었는지 확인하려면 대신 `CLAUDE_CODE_CHILD_SESSION`을 사용합니다 |

203| `CLAUDE_AFK_COUNTDOWN_MS` | 응답하지 않은 [`AskUserQuestion`](/docs/ko/tools-reference) 대화 상자에서 자동 계속되기 몇 밀리초 전에 화면 카운트다운이 나타나는지 지정합니다. 기본값은 `20000`(20초)이며 자동 계속 타임아웃을 상한으로 합니다. 자동 계속이 켜져 있지 않으면 효과가 없습니다. [`askUserQuestionTimeout`](/docs/ko/settings-reference#askuserquestiontimeout) 설정과 `CLAUDE_AFK_TIMEOUT_MS`를 참조하세요. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. Claude Code v2.1.198 이상이 필요합니다 |207| `CLAUDE_AFK_COUNTDOWN_MS` | 응답하지 않은 [`AskUserQuestion`](/docs/ko/tools-reference) 대화 상자에서 자동 계속 몇 밀리초 전에 화면 카운트다운이 나타나는지 지정합니다. 기본값은 `20000`(20초)이며, 자동 계속 타임아웃을 넘을 수 없습니다. 자동 계속이 켜져 있지 않으면 효과가 없습니다. [`askUserQuestionTimeout`](/docs/ko/settings-reference#askuserquestiontimeout) 설정과 `CLAUDE_AFK_TIMEOUT_MS`를 참조하세요. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. Claude Code v2.1.198 이상이 필요합니다 |

204| `CLAUDE_AFK_TIMEOUT_MS` | 응답하지 않은 [`AskUserQuestion`](/docs/ko/tools-reference) 대화 상자가 사용자 없이 자동으로 계속되기까지의 유휴 시간(밀리초)입니다. 자동 계속은 기본적으로 꺼져 있으며, [`askUserQuestionTimeout`](/docs/ko/settings-reference#askuserquestiontimeout) 설정으로 사용하도록 선택할 수 있습니다. 이 변수는 데모와 자동화된 테스트를 위한 재정의 값으로, 설정하면 해당 설정보다 우선하며 설정이 지정되지 않았거나 `never`인 경우에도 자동 계속을 켭니다. `0`으로 설정해도 타임아웃이 꺼지지 않으며, 대화 상자가 즉시 닫힙니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. v2.1.200 이전에는 자동 계속이 기본적으로 켜져 있었으며 타임아웃은 `60000`(60초)이었습니다. Claude Code v2.1.198 이상이 필요합니다 |208| `CLAUDE_AFK_TIMEOUT_MS` | 응답하지 않은 [`AskUserQuestion`](/docs/ko/tools-reference) 대화 상자가 사용자 응답 없이 자동으로 계속되기까지의 유휴 시간(밀리초)입니다. 자동 계속은 기본적으로 꺼져 있으며, [`askUserQuestionTimeout`](/docs/ko/settings-reference#askuserquestiontimeout) 설정으로 사용하도록 선택할 수 있습니다. 이 변수는 데모와 자동화된 테스트를 위한 재정의로, 설정하면 해당 설정보다 우선하며 설정이 지정되지 않았거나 `never`인 경우에도 자동 계속을 켭니다. `0`으로 설정해도 타임아웃이 꺼지지 않고 대화 상자가 즉시 닫힙니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. v2.1.200 이전에는 자동 계속이 `60000`(60초) 타임아웃으로 기본적으로 켜져 있었습니다. Claude Code v2.1.198 이상이 필요합니다 |

205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | `1`로 설정하면 Explore, Plan 같은 모든 기본 제공 [서브에이전트](/docs/ko/sub-agents) 유형을 비활성화합니다. 비대화형 모드(`-p` 플래그)에서만 적용됩니다. 빈 상태에서 시작하려는 SDK 사용자에게 유용합니다. 이렇게 하면 Agent 도구 호출에서 `subagent_type`을 생략했을 때 Claude Code가 실행하는 서브에이전트인 `general-purpose`도 제거됩니다. 그러면 이러한 호출은 [`subagent_type is required`](/docs/ko/errors#subagent-type-is-required)로 실패합니다 |209| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | `1`로 설정하면 Explore, Plan 같은 모든 기본 제공 [서브에이전트](/docs/ko/sub-agents) 유형을 비활성화합니다. 비대화형 모드(`-p` 플래그)에서만 적용됩니다. 빈 상태에서 시작하려는 SDK 사용자에게 유용합니다. 이 설정은 Agent 도구 호출에서 `subagent_type`을 생략할 때 Claude Code가 실행하는 서브에이전트인 `general-purpose`도 제거합니다. 그러면 이러한 호출은 [`subagent_type is required`](/docs/ko/errors#subagent-type-is-required) 오류로 실패합니다 |

206| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | `1`로 설정하면 SDK로 생성한 MCP 서버의 도구 이름에서 `mcp__<server>__` 접두사를 생략합니다. 도구는 원래 이름을 사용합니다. SDK 사용 시에만 해당됩니다 |210| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | `1`로 설정하면 SDK에서 생성한 MCP 서버의 도구 이름에 `mcp__<server>__` 접두사를 붙이지 않습니다. 도구는 원래 이름을 사용합니다. SDK 사용 시에만 해당됩니다 |

207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 서브에이전트의 정체 타임아웃(밀리초)입니다. 기본값은 `600000`(10분)이며, 스트림 워치독이 켜져 있는 동안 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`를 늘리면 [느리거나 정체된 API 응답 처리](/docs/ko/agent-sdk/typescript#handle-slow-or-stalled-api-responses)에 설명된 대로 기본값도 함께 늘어납니다. 타이머는 스트리밍 진행 이벤트마다 재설정되며, 해당 시간 내에 진행이 없으면 Claude Code는 서브에이전트를 중단하고 상위 에이전트에 정체를 보고합니다 |211| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 서브에이전트의 정체 타임아웃(밀리초)입니다. Claude Code v2.1.286 이상에서는 [워크플로 에이전트](/docs/ko/workflows#when-an-agent-stalls-and-restarts)에도 적용됩니다. 기본값은 `600000`(10분)이며, 스트림 워치독이 켜진 상태에서 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`를 높이면 [느리거나 정체된 API 응답 처리](/docs/ko/agent-sdk/typescript#handle-slow-or-stalled-api-responses)에 설명된 대로 기본값도 함께 높아집니다 |

208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 자동 압축이 트리거되는 자동 압축 윈도우의 비율(1-100)을 설정합니다. 더 일찍 압축하려면 `50`과 같은 낮은 값을 사용합니다. 이 변수는 임계값을 높일 수 없으므로 기본 비율보다 큰 값은 무시됩니다. [모델의 컨텍스트 한도 전에 압축하는](/docs/ko/model-config#context-window-and-auto-compaction) 세션에서만 적용됩니다. 메인 대화와 서브에이전트 모두에 적용됩니다 |212| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 자동 압축이 트리거되는 자동 압축 윈도우의 백분율(1-100)을 설정합니다. 더 일찍 압축하려면 `50` 같은 낮은 값을 사용합니다. 이 변수로 임계값을 높일 수는 없으므로 기본 백분율보다 큰 값은 무시됩니다. [모델의 컨텍스트 한도 전에 압축하는](/docs/ko/model-config#context-window-and-auto-compaction) 세션에만 적용됩니다. 메인 대화와 서브에이전트 모두에 적용됩니다 |

209| `CLAUDE_AUTO_BACKGROUND_TASKS` | `1`로 설정하면 오래 실행되는 에이전트 작업의 자동 백그라운드 전환을 강제로 활성화합니다. 활성화하면 서브에이전트는 약 2분간 실행된 후 백그라운드로 이동합니다. Claude Code v2.1.212 이상에서는 비대화형 모드에서 [긴 MCP 도구 호출의 자동 백그라운드 전환](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls)도 활성화합니다 |213| `CLAUDE_AUTO_BACKGROUND_TASKS` | `1`로 설정하면 장기 실행 에이전트 작업의 자동 백그라운드 전환을 강제로 활성화합니다. 활성화하면 서브에이전트가 약 2분간 실행된 후 백그라운드로 이동합니다. Claude Code v2.1.212 이상에서는 비대화형 모드에서 [긴 MCP 도구 호출의 자동 백그라운드 전환](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls)도 활성화합니다 |

210| `CLAUDE_AX_PREPARK_MS` | [스크린 리더 모드](/docs/ko/accessibility)에서 Claude Code가 새 줄이나 변경된 줄을 쓰기 전에 기다리는 시간(밀리초)입니다. 기본값은 `0`이므로 Claude Code는 기다리지 않습니다. v2.1.287 이전에는 기본값이 `50`이었습니다. Claude Code는 대기 시간의 상한을 `5000`으로 제한합니다. Claude Code v2.1.233 이상이 필요합니다 |214| `CLAUDE_AX_PREPARK_MS` | [스크린 리더 모드](/docs/ko/accessibility)에서 Claude Code가 새 줄이나 변경된 줄을 쓰기 전에 기다리는 시간(밀리초)입니다. 기본값은 `0`이므로 Claude Code는 기다리지 않습니다. v2.1.287 이전에는 기본값이 `50`이었습니다. Claude Code는 대기 시간을 최대 `5000`으로 제한합니다. Claude Code v2.1.233 이상이 필요합니다 |

211| `CLAUDE_AX_SCREEN_READER` | `1`로 설정하면 장식용 테두리나 애니메이션 없는 평면 텍스트로 스크린 리더 친화적인 출력을 렌더링합니다. `0`으로 설정하면 [`axScreenReader`](/docs/ko/settings-reference#axscreenreader)가 `true`인 경우에도 스크린 리더 모드를 강제로 끕니다. [`--ax-screen-reader`](/docs/ko/cli-reference#cli-flags) 플래그가 우선합니다. Claude Code v2.1.181 이상이 필요합니다 |215| `CLAUDE_AX_SCREEN_READER` | `1`로 설정하면 장식용 테두리나 애니메이션이 없는 평면 텍스트로 스크린 리더 친화적인 출력을 렌더링합니다. `0`으로 설정하면 [`axScreenReader`](/docs/ko/settings-reference#axscreenreader)가 `true`인 경우에도 스크린 리더 모드를 강제로 끕니다. [`--ax-screen-reader`](/docs/ko/cli-reference#cli-flags) 플래그가 우선합니다. Claude Code v2.1.181 이상이 필요합니다 |

212| `CLAUDE_AX_STARTUP_QUIET_MS` | [스크린 리더 모드](/docs/ko/accessibility)에서 시작 확인 줄 이후 Claude Code가 첫 인터페이스 렌더링을 보류하는 시간(밀리초)으로, 새 출력이 끼어들기 전에 스크린 리더가 해당 줄을 끝까지 읽을 수 있도록 합니다. 기본값은 `3000`입니다. 즉시 렌더링하려면 `0`으로 설정합니다. Claude Code는 보류 시간의 상한을 `600000`(10분)으로 제한합니다. 첫 번째 키 입력 시 보류가 조기에 종료됩니다. Claude Code v2.1.217 이상이 필요합니다 |216| `CLAUDE_AX_STARTUP_QUIET_MS` | [스크린 리더 모드](/docs/ko/accessibility)에서 시작 확인 줄 이후 Claude Code가 첫 인터페이스 렌더링을 보류하는 시간(밀리초)으로, 새 출력이 끼어들기 전에 스크린 리더가 해당 줄을 끝까지 읽을 수 있게 합니다. 기본값은 `3000`입니다. 즉시 렌더링하려면 `0`으로 설정합니다. Claude Code는 보류 시간을 최대 `600000`(10분)으로 제한합니다. 첫 키 입력 시 보류가 조기에 종료됩니다. Claude Code v2.1.217 이상이 필요합니다 |

214| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 바이트 수준 스트리밍 유휴 워치독의 타임아웃(밀리초)입니다. 설정하면 해당 워치독에 대해 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`보다 우선하며, 이벤트 수준 워치독은 변경하지 않습니다. Claude Code는 이 변수를 10초에서 30분 사이로 제한합니다. Claude Code v2.1.210 이상이 필요합니다 |218| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 바이트 수준 스트리밍 유휴 워치독의 타임아웃(밀리초)입니다. 설정하면 해당 워치독에 대해 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`보다 우선하며, 이벤트 수준 워치독은 변경하지 않습니다. Claude Code는 이 변수를 10초에서 30분 사이로 제한합니다. Claude Code v2.1.210 이상이 필요합니다 |

215| `CLAUDE_CLIENT_PRESENCE_FILE` | 화면 잠금 리스너와 같은 외부 도구가 화면 잠금을 해제할 때 생성하고 잠글 때 삭제하는 파일의 경로입니다. 파일이 존재하는 동안 Claude Code는 [Remote Control 모바일 푸시 알림](/docs/ko/remote-control#mobile-push-notifications)을 건너뛰므로, 컴퓨터를 활발히 사용하는 동안에는 푸시를 받지 않습니다. 파일이 없거나 읽을 수 없으면 알림이 평소대로 전송됩니다. Claude Code는 파일을 폴링하지 않고 푸시를 트리거하는 이벤트마다 한 번 확인합니다. Claude Code v2.1.181 이상이 필요합니다 |219| `CLAUDE_CLIENT_PRESENCE_FILE` | 화면 잠금 리스너 같은 외부 도구가 화면 잠금을 해제할 때 생성하고 잠글 때 삭제하는 파일의 경로입니다. 파일이 존재하는 동안 Claude Code는 [Remote Control 모바일 푸시 알림](/docs/ko/remote-control#mobile-push-notifications)을 건너뛰므로, 컴퓨터를 활발히 사용하는 동안에는 푸시를 받지 않습니다. 파일이 없거나 읽을 수 없으면 알림이 평소대로 전송됩니다. Claude Code는 파일을 폴링하지 않고 푸시를 트리거하는 이벤트마다 한 번씩 확인합니다. Claude Code v2.1.181 이상이 필요합니다 |

216| `CLAUDE_CODE_ACCESSIBILITY` | `1`로 설정하면 기본 터미널 커서를 계속 표시하고 반전 텍스트 커서 표시를 비활성화합니다. macOS Zoom과 같은 화면 돋보기가 커서 위치를 추적할 수 있게 합니다 |220| `CLAUDE_CODE_ACCESSIBILITY` | `1`로 설정하면 네이티브 터미널 커서를 표시된 상태로 유지하고 반전 텍스트 커서 표시기를 비활성화합니다. macOS 확대/축소(Zoom) 같은 화면 확대 도구가 커서 위치를 추적할 수 있게 합니다 |

217| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | `1`로 설정하면 `--add-dir`로 지정한 디렉터리에서 메모리 파일을 로드합니다. `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md`, `CLAUDE.local.md`를 로드합니다. 기본적으로 추가 디렉터리는 메모리 파일을 로드하지 않습니다 |221| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | `1`로 설정하면 `--add-dir`로 지정한 디렉터리에서 메모리 파일을 로드합니다. `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md`, `CLAUDE.local.md`를 로드합니다. 기본적으로 추가 디렉터리에서는 메모리 파일을 로드하지 않습니다 |

218| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 증분 업데이트를 보내는 대신 매 프레임마다 전체 화면을 다시 그립니다. 전체 화면 모드에서 오래되었거나 잘못 배치된 텍스트 조각이 표시되는 경우 사용합니다. Claude Code는 Windows의 백그라운드 세션과 [에이전트 뷰](/docs/ko/agent-view)에서 이 기능을 자동으로 활성화합니다 |222| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 증분 업데이트를 보내는 대신 매 프레임마다 전체 화면을 다시 그립니다. 전체 화면 모드에서 오래되었거나 잘못 배치된 텍스트 조각이 표시되면 이 변수를 사용합니다. Claude Code는 Windows의 백그라운드 세션과 [에이전트 뷰](/docs/ko/agent-view)에서 이 설정을 자동으로 활성화합니다 |

219| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | `1`로 설정하면 Claude Code가 모델 ID를 effort 지원 모델로 인식하지 못하는 경우에도 모든 요청에 [effort](/docs/ko/model-config#adjust-effort-level) 매개변수를 전송합니다. 사용자 지정 식별자로 모델을 제공하는 [LLM 게이트웨이](/docs/ko/llm-gateway)나 서드파티 공급자를 통해 라우팅할 때 사용합니다. Claude 3 모델, Sonnet 4.0 및 4.5, Opus 4.0 및 4.1, Haiku 4.5 등 API에서 effort 매개변수를 거부하는 모델은 요청이 실패하지 않도록 여전히 제외됩니다 |223| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | `1`로 설정하면 Claude Code가 모델 ID를 effort 지원 모델로 인식하지 못하는 경우에도 모든 요청에 [effort](/docs/ko/model-config#adjust-effort-level) 매개변수를 전송합니다. 사용자 지정 식별자로 모델을 제공하는 [LLM 게이트웨이](/docs/ko/llm-gateway)나 서드파티 제공자를 통해 라우팅할 때 사용합니다. Claude 3 모델, Sonnet 4.0 및 4.5, Opus 4.0 및 4.1, Haiku 4.5 등 API에서 effort 매개변수를 거부하는 모델은 요청이 실패하지 않도록 계속 제외됩니다 |

220| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 자격 증명을 새로 고치는 간격(밀리초)입니다([`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 사용 시) |224| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 자격 증명을 갱신해야 하는 간격(밀리초)입니다([`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 사용 시) |

221| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | `0`으로 설정하면 새 [아티팩트](/docs/ko/artifacts#create-an-artifact)가 게시될 때 Claude Code가 브라우저를 자동으로 열지 않습니다 |225| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | `0`으로 설정하면 새 [아티팩트](/docs/ko/artifacts#create-an-artifact)가 게시될 때 Claude Code가 브라우저를 자동으로 열지 않습니다 |

222| `CLAUDE_CODE_ARTIFACT_COMMENTS` | `0`으로 설정하면 Claude가 [아티팩트의 댓글](/docs/ko/artifacts#collect-comments-on-an-artifact)을 읽고 답글을 다는 것을 중단합니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 [아티팩트를 끈](/docs/ko/artifacts#availability) 경우에는 효과가 없습니다. Claude Code v2.1.221 이상이 필요합니다 |226| `CLAUDE_CODE_ARTIFACT_COMMENTS` | `0`으로 설정하면 Claude가 [아티팩트의 댓글](/docs/ko/artifacts#collect-comments-on-an-artifact)을 읽고 답하지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 [아티팩트를 끈](/docs/ko/artifacts#availability) 경우에는 효과가 없습니다. Claude Code v2.1.221 이상이 필요합니다 |

223| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | `0`으로 설정하면 Claude가 [자신에게 전송된 댓글에 스스로 답글을 다는 것](/docs/ko/artifacts#let-claude-reply-to-comments-on-its-own)을 중단합니다. Claude Code v2.1.228 이상이 필요합니다 |227| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | `0`으로 설정하면 Claude가 [자신에게 전송된 댓글에 스스로 답하지](/docs/ko/artifacts#let-claude-reply-to-comments-on-its-own) 않습니다. Claude Code v2.1.228 이상이 필요합니다 |

224| `CLAUDE_CODE_ATTRIBUTION_HEADER` | `0`으로 설정하면 클라이언트 버전과 프롬프트 지문을 담은 [attribution 블록](/docs/ko/llm-gateway-protocol#system-prompt-attribution-block)을 시스템 프롬프트 시작 부분에서 생략합니다. Anthropic API에 직접 연결할 때의 캐싱은 어느 쪽이든 영향을 받지 않습니다. 일부 직접 연결 설정에서는 `0`으로 설정해도 Claude Code가 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 요청에 해당 블록을 유지합니다. [시스템 프롬프트 attribution 블록](/docs/ko/llm-gateway-protocol#system-prompt-attribution-block)에서 이것이 적용되는 연결과 자격 증명을 확인하세요. v2.1.181 이전에는 사용자 지정 기본 URL 및 Microsoft Foundry 연결에서 블록에 요청별 토큰이 포함되었으므로, 해당 버전에서는 LLM 게이트웨이가 요청 본문을 기준으로 캐싱하거나 서드파티 공급자로 요청을 전달하는 경우, 또는 Microsoft Foundry에 직접 연결하는 경우 `0`으로 설정합니다 |228| `CLAUDE_CODE_ATTRIBUTION_HEADER` | `0`으로 설정하면 클라이언트 버전과 프롬프트 지문을 담은 [출처 표시 블록](/docs/ko/llm-gateway-protocol#system-prompt-attribution-block)을 시스템 프롬프트 시작 부분에서 생략합니다. Anthropic API에 직접 연결할 때의 캐싱은 어느 쪽이든 영향을 받지 않습니다. 일부 직접 연결 구성에서는 `0`으로 설정하더라도 Claude Code가 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 요청에 이 블록을 유지합니다. 이것이 적용되는 연결과 자격 증명은 [시스템 프롬프트 출처 표시 블록](/docs/ko/llm-gateway-protocol#system-prompt-attribution-block)에서 확인하세요. v2.1.181 이전에는 사용자 지정 기본 URL과 Microsoft Foundry 연결에서 이 블록에 요청별 토큰이 포함되었으므로, 해당 버전에서는 LLM 게이트웨이가 요청 본문을 기준으로 캐시하거나 서드파티 제공자로 요청을 전달하는 경우, 또는 Microsoft Foundry에 직접 연결하는 경우 `0`으로 설정합니다 |

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

226| `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`는 항상 모델의 전체 컨텍스트 윈도우를 기준으로 측정하므로, 이 변수를 설정하면 해당 비율은 더 이상 압축이 실행되는 시점을 나타내지 않습니다 |230| `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`는 항상 모델의 전체 컨텍스트 윈도우를 기준으로 측정하므로, 이 변수를 설정하면 해당 백분율은 더 이상 압축이 실행될 시점을 나타내지 않습니다 |

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

228| `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 이상이 필요합니다 |232| `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 이상이 필요합니다 |

229| `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 이상이 필요합니다 |233| `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 이상이 필요합니다 |

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

231| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | `0`으로 설정하면 백그라운드 작업이 아직 실행 중이더라도 비대화형 세션이 매 턴 종료 시 호스트에 유휴 상태를 보고합니다. 기본적으로 백그라운드 에이전트나 [워크플로](/docs/ko/workflows) 실행과 같은 백그라운드 작업이 아직 실행 중이면 세션은 턴 종료 후에도 실행 중 상태를 계속 보고합니다. 이를 통해 원격 세션 목록처럼 상태를 감시하는 호스트가 작업 도중에 Claude가 사용자 입력을 기다리고 있다고 알리는 것을 방지합니다. 개발 서버와 같은 백그라운드 셸 명령은 실행 중 상태를 유지하지 않습니다. 실행 중 상태 기본값과 `0` 옵트아웃에는 Claude Code v2.1.269 이상이 필요합니다. 이전 버전에서는 실행 중 상태를 유지하려면 `1`로 설정합니다 |235| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | `0`으로 설정하면 백그라운드 작업이 아직 실행 중이더라도 비대화형 세션이 매 턴이 끝날 때마다 호스트에 유휴 상태를 보고합니다. 기본적으로 세션은 백그라운드 에이전트나 [워크플로](/docs/ko/workflows) 실행 같은 백그라운드 작업이 아직 진행 중이면 턴이 끝난 후에도 실행 중 상태를 계속 보고합니다. 이렇게 하면 원격 세션 목록처럼 상태를 감시하는 호스트가 작업 도중에 Claude가 사용자 입력을 기다리고 있다고 알리는 것을 방지할 수 있습니다. 개발 서버 같은 백그라운드 셸 명령은 실행 중 상태를 유지하지 않습니다. 실행 중 상태 기본값과 `0` 옵트아웃에는 Claude Code v2.1.269 이상이 필요하며, 이전 버전에서는 실행 중 상태를 유지하려면 `1`로 설정합니다 |

232| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 세션에 활성 [Remote Control](/docs/ko/remote-control) 연결이 있는 동안 Bash 도구 및 [훅 명령](/docs/ko/hooks) 하위 프로세스에서 자동으로 설정되며, 연결이 종료되면 제거됩니다. 값은 `session_` 형식의 세션 ID로, 세션의 `claude.ai/code` URL에 나타나는 것과 동일한 식별자이므로 스크립트가 자신을 실행한 세션으로 다시 연결할 수 있습니다. Claude Code v2.1.199 이상이 필요합니다. [클라우드 세션](/docs/ko/claude-code-on-the-web)에서는 대신 `CLAUDE_CODE_REMOTE_SESSION_ID`를 읽습니다 |236| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 세션에 활성 [Remote Control](/docs/ko/remote-control) 연결이 있는 동안 Bash 도구 및 [훅 명령](/docs/ko/hooks) 하위 프로세스에서 자동으로 설정되며, 연결이 끝나면 제거됩니다. 값은 `session_` 형식의 세션 ID로, 세션의 `claude.ai/code` URL에 나타나는 것과 동일한 식별자이므로 스크립트가 자신을 실행한 세션으로 다시 연결할 수 있습니다. Claude Code v2.1.199 이상이 필요합니다. [클라우드 세션](/docs/ko/claude-code-on-the-web)에서는 대신 `CLAUDE_CODE_REMOTE_SESSION_ID`를 읽습니다 |

233| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | `0`으로 설정하면 Claude Code가 `^H`로도 표기되는 `0x08` 바이트를 일반 Backspace로 읽고, `1`로 설정하면 Ctrl+Backspace로 읽습니다. 어느 값이든 플랫폼 기본값을 대체합니다. 기본적으로 Claude Code는 Windows에서는 `TERM_PROGRAM`이 `mintty`이거나 `TERM`이 `cygwin`인 경우를 제외하고 이를 Ctrl+Backspace로 읽으며, macOS와 Linux에서는 일반 Backspace로 읽습니다. [Backspace가 단어 전체를 삭제하는](/docs/ko/terminal-config#fix-backspace-deleting-a-whole-word-on-windows) Windows 터미널에서는 `0`으로 설정합니다 |237| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | `0`으로 설정하면 Claude Code가 `^H`로도 표기되는 `0x08` 바이트를 일반 Backspace로 읽고, `1`로 설정하면 Ctrl+Backspace로 읽습니다. 어느 값이든 플랫폼 기본값을 대체합니다. 기본적으로 Claude Code는 Windows에서 이를 Ctrl+Backspace로 읽되 `TERM_PROGRAM`이 `mintty`이거나 `TERM`이 `cygwin`인 경우는 예외이며, macOS와 Linux에서는 일반 Backspace로 읽습니다. [Backspace가 단어 전체를 삭제하는](/docs/ko/terminal-config#fix-backspace-deleting-a-whole-word-on-windows) Windows 터미널에서는 `0`으로 설정합니다 |

234| `CLAUDE_CODE_CERT_STORE` | TLS 연결을 위한 CA 인증서 소스의 쉼표로 구분된 목록입니다. `bundled`는 Claude Code와 함께 제공되는 Mozilla CA 세트입니다. `system`은 운영 체제 신뢰 저장소로, `tls.getCACertificates`가 있는 런타임(네이티브 바이너리 또는 npm 설치의 경우 Node 22.15 이상)에서만 읽습니다. [CA 인증서 저장소](/docs/ko/network-config#ca-certificate-store)를 참조하세요. 기본값은 `bundled,system`입니다 |238| `CLAUDE_CODE_CERT_STORE` | TLS 연결을 위한 CA 인증서 소스의 쉼표로 구분된 목록입니다. `bundled`는 Claude Code와 함께 제공되는 Mozilla CA 세트입니다. `system`은 운영 체제 신뢰 저장소로, `tls.getCACertificates`가 있는 런타임, 즉 네이티브 바이너리 또는 npm 설치의 경우 Node 22.15 이상에서만 읽습니다. [CA 인증서 저장소](/docs/ko/network-config#ca-certificate-store)를 참조하세요. 기본값은 `bundled,system`입니다 |

235| `CLAUDE_CODE_CHILD_SESSION` | Claude Code가 Bash, PowerShell, Monitor 도구, [훅](/docs/ko/hooks) 명령, [상태줄](/docs/ko/statusline) 명령을 통해 생성하는 하위 프로세스에서 `1`로 설정됩니다. stdio [MCP 서버](/docs/ko/mcp) 하위 프로세스에는 설정되지 않는데, 이들은 오래 실행되며 자신을 생성한 세션보다 오래 유지되기 때문입니다. `CLAUDECODE`와 달리 이 변수는 Claude Code가 하위 프로세스를 시작할 때만 Claude Code 자체가 설정하며 IDE 확장 프로그램은 설정하지 않으므로, 중첩된 세션과 IDE 통합 터미널에서 실행된 최상위 `claude`를 확실하게 구분합니다. 이렇게 시작된 중첩 대화형 `claude` TUI는 `--resume`, `--continue`, 위쪽 화살표 기록, `claude agents` 목록에서 자동으로 제외됩니다. 비대화형 `claude -p` 세션은 여전히 유지됩니다. 이 제외를 재정의하려면 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1`을 설정합니다. Claude Code v2.1.172 이상이 필요합니다 |239| `CLAUDE_CODE_CHILD_SESSION` | Claude Code가 Bash, PowerShell, Monitor 도구, [훅](/docs/ko/hooks) 명령, [상태줄](/docs/ko/statusline) 명령을 통해 생성하는 하위 프로세스에서 `1`로 설정됩니다. 수명이 길어 자신을 생성한 세션보다 오래 유지되는 stdio [MCP 서버](/docs/ko/mcp) 하위 프로세스에는 설정되지 않습니다. `CLAUDECODE`와 달리 이 변수는 Claude Code 자체가 하위 프로세스를 시작할 때만 설정되고 IDE 확장 프로그램은 설정하지 않으므로, 중첩된 세션과 IDE 통합 터미널에서 시작한 최상위 `claude`를 확실하게 구분합니다. 이런 방식으로 시작된 중첩된 대화형 `claude` TUI는 `--resume`, `--continue`, 위쪽 화살표 기록, `claude agents` 목록에서 자동으로 제외됩니다. 비대화형 `claude -p` 세션은 계속 저장됩니다. 이 제외를 재정의하려면 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1`을 설정합니다. Claude Code v2.1.172 이상이 필요합니다 |

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

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

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

242| `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)을 참조하세요 |246| `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)을 참조하세요 |

243| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | `1`로 설정하면 Opus 4.6 및 Sonnet 4.6에서 [적응형 추론](/docs/ko/model-config#adjust-effort-level)을 비활성화하고 `MAX_THINKING_TOKENS`로 제어되는 고정 사고 예산으로 폴백합니다. 항상 적응형 추론을 사용하는 [Fable 모델](/docs/ko/model-config#extended-thinking), Sonnet 5 이상, Haiku 5.5, Opus 4.7 이상에는 효과가 없습니다 |247| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | `1`로 설정하면 Opus 4.6 및 Sonnet 4.6에서 [적응형 추론](/docs/ko/model-config#adjust-effort-level)을 비활성화하고 `MAX_THINKING_TOKENS`로 제어되는 고정 사고 예산으로 폴백합니다. 항상 적응형 추론을 사용하는 [Fable 모델](/docs/ko/model-config#extended-thinking), Sonnet 5 이상, Haiku 5.5, Opus 4.7 이상에는 효과가 없습니다 |

244| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | `1`로 설정하면 Claude Code가 관리자 소스 전반에서 [관리형 설정](/docs/ko/managed-settings#precedence-within-the-managed-tier) `env` 블록을 키별로 병합하지 않으므로, v2.1.223 이전처럼 우선순위가 가장 높은 소스의 `env` 블록 전체만 적용됩니다. Claude Code는 설정의 `env` 블록을 통해 전달된 값을 무시하므로 Claude Code를 실행하는 환경에서 설정합니다. Claude Code v2.1.223 이상이 필요합니다 |248| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | `1`로 설정하면 Claude Code가 관리자 소스 전반에서 [관리형 설정](/docs/ko/managed-settings#precedence-within-the-managed-tier) `env` 블록을 키별로 병합하지 않으므로, v2.1.223 이전처럼 우선순위가 가장 높은 소스의 `env` 블록 전체만 적용됩니다. Claude Code는 설정 `env` 블록을 통해 전달된 값을 무시하므로 Claude Code를 실행하는 환경에서 설정합니다. Claude Code v2.1.223 이상이 필요합니다 |

245| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | `1`로 설정하면 [advisor 도구](/docs/ko/advisor)를 비활성화합니다. `/advisor` 명령을 사용할 수 없게 되고, 구성된 `advisorModel`은 무시되며, `--advisor` 플래그는 허용되지만 효과가 없으므로 이 플래그를 전달하는 기존 스크립트는 오류 없이 계속 작동합니다 |249| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | `1`로 설정하면 [advisor 도구](/docs/ko/advisor)를 비활성화합니다. `/advisor` 명령을 사용할 수 없게 되고, 구성된 `advisorModel`은 무시되며, `--advisor` 플래그는 허용되지만 효과가 없으므로 이를 전달하는 기존 스크립트는 오류 없이 계속 작동합니다 |

246| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | `1`로 설정하면 [백그라운드 에이전트와 에이전트 뷰](/docs/ko/agent-view)(`claude agents`, `--bg`, `/background`, 온디맨드 슈퍼바이저)를 끕니다. [`disableAgentView`](/docs/ko/settings-reference#disableagentview) 설정과 동일합니다 |250| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | `1`로 설정하면 [백그라운드 에이전트와 에이전트 뷰](/docs/ko/agent-view)를 끕니다: `claude agents`, `--bg`, `/background`, 그리고 온디맨드 슈퍼바이저. [`disableAgentView`](/docs/ko/settings-reference#disableagentview) 설정과 동일합니다 |

247| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)을 비활성화하고 클래식 메인 화면 렌더러를 사용합니다. 대화가 터미널의 기본 스크롤백에 남으므로 `Cmd+f`와 tmux 복사 모드가 평소처럼 작동합니다. `CLAUDE_CODE_NO_FLICKER`와 [`tui`](/docs/ko/settings-reference#tui) 설정보다 우선합니다. `/tui default`로도 전환할 수 있습니다. 항상 전체 화면 렌더링을 사용하는 [에이전트 뷰](/docs/ko/agent-view)에서 연 백그라운드 세션에는 적용되지 않습니다 |251| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)을 비활성화하고 기존 메인 화면 렌더러를 사용합니다. 대화가 터미널의 기본 스크롤백에 남으므로 `Cmd+f`와 tmux 복사 모드가 평소대로 작동합니다. `CLAUDE_CODE_NO_FLICKER`와 [`tui`](/docs/ko/settings-reference#tui) 설정보다 우선합니다. `/tui default`로 전환할 수도 있습니다. 항상 전체 화면 렌더링을 사용하는 [에이전트 뷰](/docs/ko/agent-view)에서 연 백그라운드 세션에는 적용되지 않습니다 |

248| `CLAUDE_CODE_DISABLE_ARTIFACT` | `1`로 설정하면 세션 출력을 claude.ai의 비공개 웹 페이지로 게시하는 [Artifact](/docs/ko/artifacts) 도구를 끕니다. 이 변수를 설정하면 어떤 설정 파일로도 도구를 다시 켤 수 없습니다. 대신 설정 파일에서 도구를 끄려면 [`enableArtifact`](/docs/ko/settings-reference#enableartifact)를 `false`로 설정합니다. deprecated된 [`disableArtifact`](/docs/ko/settings-reference#disableartifact) 키로도 끌 수 있습니다 |252| `CLAUDE_CODE_DISABLE_ARTIFACT` | `1`로 설정하면 세션 출력을 claude.ai의 비공개 웹 페이지로 게시하는 [Artifact](/docs/ko/artifacts) 도구를 끕니다. 이 값을 설정하면 어떤 설정 파일로도 도구를 다시 켤 수 없습니다. 대신 설정 파일에서 도구를 끄려면 [`enableArtifact`](/docs/ko/settings-reference#enableartifact)를 `false`로 설정합니다. deprecated된 [`disableArtifact`](/docs/ko/settings-reference#disableartifact) 키로도 끌 수 있습니다 |

249| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | `1`로 설정하면 첨부 파일 처리를 비활성화합니다. `@` 구문을 사용한 파일 멘션이 파일 내용으로 확장되지 않고 일반 텍스트로 전송됩니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |253| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | `1`로 설정하면 첨부 파일 처리를 비활성화합니다. `@` 구문을 사용한 파일 멘션이 파일 내용으로 확장되지 않고 일반 텍스트로 전송됩니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |

250| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | `1`로 설정하면 Claude Code 프로세스가 다른 프로세스가 실행하는 동안 기다리지 않고 [`gcpAuthRefresh`](/docs/ko/settings-reference#gcpauthrefresh) 또는 [`awsAuthRefresh`](/docs/ko/settings-reference#awsauthrefresh) 명령을 직접 실행합니다. Claude Code v2.1.286 이상이 필요합니다 |254| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | `1`로 설정하면 Claude Code 프로세스가 다른 프로세스가 [`gcpAuthRefresh`](/docs/ko/settings-reference#gcpauthrefresh) 또는 [`awsAuthRefresh`](/docs/ko/settings-reference#awsauthrefresh) 명령을 실행하는 동안 기다리지 않고 해당 명령을 직접 실행합니다. Claude Code v2.1.286 이상이 필요합니다 |

251| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | `1`로 설정하면 [자동 메모리](/docs/ko/memory#auto-memory)를 비활성화합니다. `0`으로 설정하면 `--bare` 모드나 [`autoMemoryEnabled: false`](/docs/ko/settings-reference#automemoryenabled)로 인해 비활성화되는 경우에도 자동 메모리를 강제로 켭니다. 비활성화되면 Claude는 자동 메모리 파일을 생성하거나 로드하지 않습니다 |255| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | `1`로 설정하면 [자동 메모리](/docs/ko/memory#auto-memory)를 비활성화합니다. `0`으로 설정하면 `--bare` 모드나 [`autoMemoryEnabled: false`](/docs/ko/settings-reference#automemoryenabled)로 인해 비활성화되는 경우에도 자동 메모리를 강제로 켭니다. 비활성화되면 Claude는 자동 메모리 파일을 생성하거나 로드하지 않습니다 |

252| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | `1`로 설정하면 Bash 및 서브에이전트 도구의 `run_in_background` 매개변수, 자동 백그라운드 전환, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화합니다 |256| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | `1`로 설정하면 Bash 및 서브에이전트 도구의 `run_in_background` 매개변수, 자동 백그라운드 전환, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화합니다 |

253| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | `1`로 설정하면 Claude Code가 `Content-Type` 헤더가 없거나 비어 있는 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답을 Amazon Bedrock의 바이너리 이벤트 스트림으로 취급하지 않습니다. 기본적으로 Claude Code는 게이트웨이가 달리 수정되지 않은 응답에서 헤더만 누락했다고 가정하므로, 본문을 디코딩하고 스트리밍이 계속 작동합니다. 스트림을 server-sent events로 다시 내보내기도 하는 게이트웨이에서만 설정하세요. 그러면 Claude Code는 헤더가 없는 본문을 대신 server-sent events로 읽습니다. Claude Code v2.1.239 이상이 필요합니다 |257| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | `1`로 설정하면 Claude Code가 `Content-Type` 헤더가 없거나 비어 있는 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답을 Amazon Bedrock의 바이너리 이벤트 스트림으로 처리하지 않습니다. 기본적으로 Claude Code는 게이트웨이가 그 외에는 수정되지 않은 응답에서 헤더만 제거했다고 가정하므로, 본문을 디코딩하고 스트리밍이 계속 작동합니다. 스트림을 server-sent events로 다시 내보내기도 하는 게이트웨이에만 이 변수를 설정합니다. 그러면 Claude Code는 헤더가 없는 본문을 server-sent events로 읽습니다. Claude Code v2.1.239 이상이 필요합니다 |

254| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | `1`로 설정하면 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답이 `application/vnd.amazon.eventstream` content-type을 포함하는지 확인하는 검사를 건너뜁니다. 이 변수가 없으면 응답이 다른 content-type을 포함할 때 Claude Code는 해당 유형을 명시한 오류로 요청을 실패시키며, 이는 [게이트웨이나 프록시가 응답을 변환하고 있음](/docs/ko/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)을 의미합니다. 이 변수를 설정하기보다는 `Content-Type` 헤더와 본문을 수정 없이 전달하도록 게이트웨이를 구성하세요. Claude Code v2.1.208 이상이 필요합니다 |258| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | `1`로 설정하면 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답이 `application/vnd.amazon.eventstream` content-type을 포함하는지 확인하는 검사를 건너뜁니다. 이 변수가 없으면 응답에 다른 content-type이 있을 때 Claude Code는 해당 유형을 명시한 오류와 함께 요청을 실패 처리하며, 이는 [게이트웨이나 프록시가 응답을 변환하고 있음](/docs/ko/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)을 의미합니다. 이 변수를 설정하는 대신 `Content-Type` 헤더와 본문을 수정 없이 전달하도록 게이트웨이를 구성합니다. Claude Code v2.1.208 이상이 필요합니다 |

255| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | `1`로 설정하면 [supervisor](/docs/ko/agent-view#the-supervisor-process)가 [백그라운드 세션](/docs/ko/agent-view)의 프로세스를 중지, 재시작 또는 업데이트할 때 해당 세션의 실행 중인 백그라운드 셸 명령, 동적 워크플로, 그리고 v2.1.198부터는 백그라운드 서브에이전트를 세션의 다음 프로세스로 넘기지 않고 중지합니다. 이 인계에만 영향을 미칩니다. `←` 또는 [`/background`](/docs/ko/agent-view#from-inside-a-session)로 세션을 백그라운드로 전환하면 진행 중인 작업이 여전히 이어지며, `CLAUDE_DISABLE_ADOPT`는 두 가지를 모두 끕니다. Claude Code v2.1.196 이상이 필요합니다 |259| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | `1`로 설정하면 [슈퍼바이저](/docs/ko/agent-view#the-supervisor-process)가 [백그라운드 세션](/docs/ko/agent-view)의 프로세스를 중지, 재시작 또는 업데이트할 때, 해당 세션에서 실행 중인 백그라운드 셸 명령, 동적 워크플로, 그리고 v2.1.198부터는 백그라운드 서브에이전트를 세션의 다음 프로세스로 넘기는 대신 중지합니다. 이 인계에만 영향을 줍니다: `←` 또는 [`/background`](/docs/ko/agent-view#from-inside-a-session)로 세션을 백그라운드로 전환하면 진행 중인 작업이 여전히 이어지며, `CLAUDE_DISABLE_ADOPT`는 둘 다 끕니다. Claude Code v2.1.196 이상이 필요합니다 |

256| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | `1`로 설정하면 메모리 압박 상황에서 Claude Code가 [백그라운드 셸 명령](/docs/ko/interactive-mode#background-bash-commands)을 종료하지 않습니다. 기본적으로 macOS와 Linux에서 Claude Code는 운영 체제가 심각한 메모리 압박을 보고하고 세션이 실행 중인 턴이나 서브에이전트 없이 30분 동안 유휴 상태였을 때 백그라운드 셸을 종료합니다. Windows에는 메모리 압박 신호가 없으므로 이 변수는 효과가 없습니다. Claude Code v2.1.193 이상이 필요합니다 |260| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | `1`로 설정하면 Claude Code가 시스템 메모리 부족 상황에서 [백그라운드 셸 명령](/docs/ko/interactive-mode#background-bash-commands)을 종료하지 않습니다. 기본적으로 macOS와 Linux에서 Claude Code는 운영 체제가 심각한 메모리 부족을 보고하고 세션이 실행 중인 턴이나 서브에이전트 없이 30분 동안 유휴 상태였을 때 백그라운드 셸을 종료합니다. Windows에는 메모리 부족 신호가 없으므로 이 변수는 효과가 없습니다. Claude Code v2.1.193 이상이 필요합니다 |

257| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | `1`로 설정하면 Claude Code에 포함된 [스킬](/docs/ko/skills)과 워크플로를 비활성화합니다. 번들 스킬과 워크플로는 완전히 제거되며, `/init` 같은 기본 제공 명령은 계속 입력할 수 있지만 모델에는 숨겨집니다. `/doctor`는 기본 제공 명령처럼 계속 입력할 수 있으며, 숨기려면 대신 `DISABLE_DOCTOR_COMMAND`를 사용합니다. 플러그인, `.claude/skills/`, `.claude/commands/`의 스킬은 영향을 받지 않습니다. [`disableBundledSkills`](/docs/ko/settings-reference#disablebundledskills) 설정과 동일합니다 |261| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | `1`로 설정하면 Claude Code에 포함된 [스킬](/docs/ko/skills)과 워크플로를 비활성화합니다: 번들 스킬과 워크플로는 완전히 제거되며, `/init` 같은 기본 제공 명령은 계속 입력할 수 있지만 모델에게는 숨겨집니다. `/doctor`는 기본 제공 명령처럼 계속 입력할 수 있으며, 숨기려면 대신 `DISABLE_DOCTOR_COMMAND`를 사용합니다. 플러그인, `.claude/skills/`, `.claude/commands/`의 스킬은 영향을 받지 않습니다. [`disableBundledSkills`](/docs/ko/settings-reference#disablebundledskills) 설정과 동일합니다 |

258| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | `1`로 설정하면 [Claude in Chrome](/docs/ko/chrome) 브라우저 도구를 계속 사용할 수 있게 유지하면서 시스템 프롬프트의 Chrome 섹션과 `/claude-in-chrome` [번들 스킬](/docs/ko/skills#bundled-skills)을 생략합니다. Claude Code를 내장하고 자체 브라우저 지침을 제공하는 호스트를 위한 변수입니다. Claude Code v2.1.257 이상이 필요합니다 |262| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | `1`로 설정하면 [Claude in Chrome](/docs/ko/chrome) 브라우저 도구는 계속 사용할 수 있게 유지하면서 시스템 프롬프트의 Chrome 섹션과 `/claude-in-chrome` [번들 스킬](/docs/ko/skills#bundled-skills)을 생략합니다. Claude Code를 임베드하고 자체 브라우저 지침을 제공하는 호스트를 위한 것입니다. Claude Code v2.1.257 이상이 필요합니다 |

260| `CLAUDE_CODE_DISABLE_CRON` | `1`로 설정하면 [예약 작업](/docs/ko/scheduled-tasks)을 비활성화합니다. `/loop` 스킬과 cron 도구를 사용할 수 없게 되며, 세션 도중 이미 실행 중인 작업을 포함해 이미 예약된 작업도 더 이상 실행되지 않습니다 |264| `CLAUDE_CODE_DISABLE_CRON` | `1`로 설정하면 [예약 작업](/docs/ko/scheduled-tasks)을 비활성화합니다. `/loop` 스킬과 cron 도구를 사용할 수 없게 되며, 세션 도중 이미 실행 중인 작업을 포함해 이미 예약된 모든 작업이 더 이상 실행되지 않습니다 |

261| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | `1`로 설정하면 [중요 경로 삭제](/docs/ko/permission-modes#critical-paths) 프롬프트의 시간 제한을 끕니다. 그러면 `auto` 모드에서는 Claude Code가 이러한 삭제를 대신 분류기로 보내고, `bypassPermissions` 모드에서는 프롬프트가 사용자의 응답을 기다립니다. Claude Code는 설정의 `env` 블록을 통해 전달된 값을 무시하므로 Claude Code를 실행하는 환경에서 설정합니다. Claude Code v2.1.281 이상이 필요합니다 |265| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | `1`로 설정하면 [중요 경로 삭제](/docs/ko/permission-modes#critical-paths) 프롬프트의 시간 제한을 끕니다. 그러면 `auto` 모드에서 Claude Code는 이러한 삭제를 대신 분류기로 보내고, `bypassPermissions` 모드에서는 프롬프트가 사용자의 응답을 기다립니다. Claude Code는 설정 `env` 블록을 통해 전달된 값을 무시하므로 Claude Code를 실행하는 환경에서 설정합니다. Claude Code v2.1.281 이상이 필요합니다 |

262| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | `1`로 설정하면 API 요청에서 출시 전 `anthropic-beta` 요청 헤더, 이와 짝을 이루는 본문 필드, `defer_loading` 및 `eager_input_streaming` 같은 베타 도구 스키마 필드를 제거합니다. 프록시 게이트웨이가 `anthropic-beta` 헤더에 대한 `Unexpected value(s)` 오류나 `Extra inputs are not permitted` 오류로 요청을 거부할 때 사용합니다. [출시 전 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)에 [MCP 도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)을 포함해 이 변수가 제거하는 항목과 Claude Code가 계속 전송하는 항목이 나와 있습니다 |266| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | `1`로 설정하면 API 요청에서 프리릴리스 `anthropic-beta` 요청 헤더, 이와 짝을 이루는 본문 필드, `defer_loading` 및 `eager_input_streaming` 같은 베타 도구 스키마 필드를 제거합니다. 프록시 게이트웨이가 `anthropic-beta` 헤더에 대해 `Unexpected value(s)` 오류나 `Extra inputs are not permitted` 오류로 요청을 거부할 때 사용합니다. [프리릴리스 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)에 [MCP 도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)을 포함해 이 변수가 제거하는 항목과 Claude Code가 계속 전송하는 항목이 나와 있습니다 |

263| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | `1`로 설정하면 기본 제공 [Explore 및 Plan 서브에이전트](/docs/ko/sub-agents#built-in-subagents)를 비활성화합니다. Claude는 대신 검색 도구나 general-purpose 서브에이전트로 탐색하며, [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)는 Explore 및 Plan 에이전트를 실행하지 않고 파일을 직접 읽습니다. 이름이 `Explore` 또는 `Plan`인 사용자 지정 서브에이전트는 영향을 받지 않습니다. Agent SDK 또는 비대화형 모드에서 모든 기본 제공 서브에이전트 유형을 제거하려면 대신 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`를 사용합니다. Claude Code v2.1.198 이상이 필요합니다 |267| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | `1`로 설정하면 기본 제공 [Explore 및 Plan 서브에이전트](/docs/ko/sub-agents#built-in-subagents)를 비활성화합니다. Claude는 대신 검색 도구나 general-purpose 서브에이전트로 탐색하며, [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)는 Explore 및 Plan 에이전트를 실행하지 않고 파일을 직접 읽습니다. 이름이 `Explore` 또는 `Plan`인 사용자 지정 서브에이전트는 영향을 받지 않습니다. Agent SDK나 비대화형 모드에서 모든 기본 제공 서브에이전트 유형을 제거하려면 대신 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`를 사용합니다. Claude Code v2.1.198 이상이 필요합니다 |

265| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | `1`로 설정하면 "How is Claude doing?" 세션 품질 설문을 비활성화합니다. `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`로 다시 사용하도록 선택하지 않는 한, `DISABLE_TELEMETRY`, `DO_NOT_TRACK` 또는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 설정된 경우에도 설문이 비활성화됩니다. 완전히 비활성화하는 대신 샘플링 비율을 설정하려면 [`feedbackSurveyRate`](/docs/ko/settings-reference#feedbacksurveyrate) 설정을 사용합니다. [세션 품질 설문](/docs/ko/data-usage#session-quality-surveys)을 참조하세요 |269| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | `1`로 설정하면 "How is Claude doing?" 세션 품질 설문을 비활성화합니다. `DISABLE_TELEMETRY`, `DO_NOT_TRACK` 또는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 설정된 경우에도 설문이 비활성화되며, 단 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`로 다시 사용하도록 선택한 경우는 예외입니다. 완전히 비활성화하는 대신 샘플링 비율을 설정하려면 [`feedbackSurveyRate`](/docs/ko/settings-reference#feedbacksurveyrate) 설정을 사용합니다. [세션 품질 설문](/docs/ko/data-usage#session-quality-surveys)을 참조하세요 |

266| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | `1`로 설정하면 파일 [체크포인트](/docs/ko/checkpointing)를 비활성화합니다. `/rewind` 명령으로 코드 변경 사항을 복원할 수 없게 됩니다. [`fileCheckpointingEnabled`](/docs/ko/settings-reference#filecheckpointingenabled) 설정을 재정의합니다 |270| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | `1`로 설정하면 파일 [체크포인트](/docs/ko/checkpointing) 기능을 비활성화합니다. `/rewind` 명령으로 코드 변경 사항을 복원할 수 없게 됩니다. [`fileCheckpointingEnabled`](/docs/ko/settings-reference#filecheckpointingenabled) 설정을 재정의합니다 |

267| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | `1`로 설정하면 기본 제공 커밋 및 PR 워크플로 지침과 git 상태 스냅샷을 Claude의 컨텍스트에서 제거합니다. 자체 git 워크플로 스킬을 사용할 때 유용합니다. 설정된 경우 [`includeGitInstructions`](/docs/ko/settings-reference#includegitinstructions) 설정보다 우선합니다 |271| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | `1`로 설정하면 Claude의 컨텍스트에서 기본 제공 커밋 및 PR 워크플로 지침과 git 상태 스냅샷을 제거합니다. 자체 git 워크플로 스킬을 사용할 때 유용합니다. 설정된 경우 [`includeGitInstructions`](/docs/ko/settings-reference#includegitinstructions) 설정보다 우선합니다 |

268| `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` | `1`로 설정하면 Claude Code가 `bash -c 'rm -rf ~'`처럼 `-c`로 셸에 전달된 스크립트에서 [중요 경로](/docs/ko/permission-modes#removals-inside-nested-commands-and-inline-scripts) 삭제를 읽지 않습니다. Claude Code는 여전히 해당 스크립트의 셸 변수 및 위치 매개변수 대상을 검사하며, 다른 중요 경로 검사도 계속 실행됩니다. Claude Code는 설정의 `env` 블록을 통해 전달된 값을 무시하므로 Claude Code를 실행하는 환경에서 설정합니다. Claude Code v2.1.288 이상이 필요합니다 |272| `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` | `1`로 설정하면 Claude Code가 `bash -c 'rm -rf ~'`처럼 `-c`로 셸에 전달된 스크립트를 읽어 [중요 경로](/docs/ko/permission-modes#removals-inside-nested-commands-and-inline-scripts) 삭제 여부를 확인하지 않습니다. Claude Code는 해당 스크립트의 셸 변수 및 위치 매개변수 대상은 계속 검사하며, 다른 중요 경로 검사도 계속 실행됩니다. Claude Code는 설정 `env` 블록을 통해 전달된 값을 무시하므로 Claude Code를 실행하는 환경에서 설정합니다. Claude Code v2.1.288 이상이 필요합니다 |

269| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | `1`로 설정하면 Anthropic API에서 Opus 4.0 및 4.1이 현재 Opus 버전으로 자동 재매핑되지 않도록 합니다. 의도적으로 이전 모델을 고정하려는 경우에 사용합니다. 재매핑은 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry에서는 실행되지 않습니다 |273| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | `1`로 설정하면 Anthropic API에서 Opus 4.0 및 4.1이 현재 Opus 버전으로 자동 재매핑되지 않습니다. 의도적으로 이전 모델을 고정하려는 경우 사용합니다. 재매핑은 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry에서는 실행되지 않습니다 |

270| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | `1`로 설정하면 세션 도중 계정이 세션 모델에 대한 액세스 권한을 잃었을 때 [Amazon Bedrock](/docs/ko/amazon-bedrock#when-a-model-is-disabled-mid-session) 및 [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai#when-a-model-is-disabled-mid-session)의 Claude Code가 이전 모델로 전환하지 않으며, 대신 거부된 요청이 즉시 실패합니다. 구성한 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)은 해당 거부 시 여전히 전환되며, [시작 시 모델 검사](/docs/ko/amazon-bedrock#startup-model-checks)도 실행 시점에 여전히 폴백합니다. Claude Code v2.1.285 이상이 필요합니다 |274| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | `1`로 설정하면 [Amazon Bedrock](/docs/ko/amazon-bedrock#when-a-model-is-disabled-mid-session)과 [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai#when-a-model-is-disabled-mid-session)에서 계정이 세션 도중 세션 모델에 대한 액세스 권한을 잃을 때 Claude Code가 이전 모델로 전환하지 않으며, 대신 거부된 요청이 즉시 실패합니다. 구성한 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)은 이러한 거부 시에도 여전히 전환되며, [시작 시 모델 검사](/docs/ko/amazon-bedrock#startup-model-checks)도 실행 시점에 여전히 폴백합니다. Claude Code v2.1.285 이상이 필요합니다 |

271| `CLAUDE_CODE_DISABLE_MOUSE` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 마우스 추적을 비활성화합니다. `PgUp`과 `PgDn`을 사용한 키보드 스크롤은 계속 작동합니다. 터미널의 기본 선택 시 복사 동작을 유지하려면 이 변수를 사용합니다 |275| `CLAUDE_CODE_DISABLE_MOUSE` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 마우스 추적을 비활성화합니다. `PgUp`과 `PgDn`을 사용한 키보드 스크롤은 계속 작동합니다. 터미널의 기본 선택 시 복사 동작을 유지하려면 이 변수를 사용합니다 |

272| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 마우스 휠 스크롤은 유지하면서 클릭, 드래그, 호버 처리를 비활성화합니다. Claude Code 안에서 휠 스크롤은 작동하되 클릭으로 커서를 배치하거나 도구 출력을 펼치거나 링크를 열지 않기를 원할 때 사용합니다. 둘 다 설정된 경우 `CLAUDE_CODE_DISABLE_MOUSE`가 우선합니다. Claude Code v2.1.195 이상이 필요합니다 |276| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | `1`로 설정하면 마우스 휠 스크롤은 유지하면서 [전체 화면 렌더링](/docs/ko/fullscreen)에서 클릭, 드래그, 호버 처리를 비활성화합니다. Claude Code 안에서 휠 스크롤은 작동하되 클릭으로 커서를 배치하거나 도구 출력을 펼치거나 링크를 열지 않게 하려면 이 변수를 사용합니다. 둘 다 설정된 경우 `CLAUDE_CODE_DISABLE_MOUSE`가 우선합니다. Claude Code v2.1.195 이상이 필요합니다 |

273| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | `1`로 설정하면 연결 재설정이나 TLS 핸드셰이크 오류 같은 연결 수준 오류로 API 요청이 실패할 때 Claude Code가 [mTLS 클라이언트 인증서와 키](/docs/ko/network-config#mtls-authentication)를 다시 읽지 않습니다. 다시 로드가 비활성화되면 Claude Code는 다음에 설정을 적용할 때나 다음 시작 시에만 교체된 파일을 로드합니다. Claude Code v2.1.232 이상이 필요합니다 |277| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | `1`로 설정하면 API 요청이 연결 재설정이나 TLS 핸드셰이크 오류 같은 연결 수준 오류로 실패할 때 Claude Code가 [mTLS 클라이언트 인증서와 키](/docs/ko/network-config#mtls-authentication)를 다시 읽지 않습니다. 다시 로드를 비활성화하면 Claude Code는 다음에 설정을 적용할 때나 다음 시작 시에만 교체된 파일을 로드합니다. Claude Code v2.1.232 이상이 필요합니다 |

274| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | `1`과 같이 비어 있지 않은 값으로 설정하면 필수적이지 않은 네트워크 트래픽을 비활성화합니다. 자동 업데이트, 텔레메트리, 오류 보고, `/feedback` 명령, [Claude가 작성한 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior), 릴리스 노트, [PR 및 MR 상태 배지](/docs/ko/interactive-mode#pr-review-status) 검사, [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 검사와 같은 가용성 검사가 해당됩니다. 또한 [플러그인 `command` 소스의 백그라운드 실행](/docs/ko/plugins/loading#when-a-command-source-re-runs)도 중지합니다. 이는 네트워크 트래픽이 아닌 로컬 명령이지만 의존성 설치를 트리거할 수 있기 때문입니다. **대부분의 켜기/끄기 변수와 달리 `0`이나 `false`로 설정해도 이 트래픽은 비활성화됩니다**. 다시 허용하려면 변수를 설정 해제하세요. 기능 플래그 가져오기도 비활성화되므로 [Remote Control](/docs/ko/remote-control#requirements)과 기타 [기능 플래그 가져오기가 필요한 기능](#features-that-need-feature-flag-fetching)을 사용할 수 없게 됩니다. 공식 플러그인 마켓플레이스 자동 설치는 해당되지 않으므로 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`로 비활성화합니다. 자체 옵트인이 있는 [게이트웨이 모델 검색](/docs/ko/llm-gateway-connect#add-gateway-models-to-the-model-picker)에는 영향을 주지 않습니다 |278| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | `1`과 같이 비어 있지 않은 값으로 설정하면 필수적이지 않은 네트워크 트래픽을 비활성화합니다: 자동 업데이트, 텔레메트리, 오류 보고, `/feedback` 명령, [Claude가 작성한 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior), 릴리스 노트, [PR 및 MR 상태 배지](/docs/ko/interactive-mode#pr-review-status) 검사, 그리고 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 검사 같은 가용성 검사. 또한 [플러그인 `command` 소스의 백그라운드 실행](/docs/ko/plugins/loading#when-a-command-source-re-runs)도 중지합니다. 이는 네트워크 트래픽이 아닌 로컬 명령이지만 의존성 설치를 트리거할 수 있기 때문입니다. **`0`이나 `false`로 설정해도 이 트래픽은 여전히 비활성화되며**, 이는 대부분의 켜기/끄기 변수와 다릅니다. 다시 허용하려면 변수를 설정 해제합니다. 기능 플래그 가져오기도 비활성화하므로 [Remote Control](/docs/ko/remote-control#requirements) 및 기타 [기능 플래그 가져오기가 필요한 기능](#features-that-need-feature-flag-fetching)을 사용할 수 없게 됩니다. 공식 플러그인 마켓플레이스 자동 설치는 해당되지 않으므로 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`로 비활성화합니다. 자체 옵트인이 있는 [게이트웨이 모델 검색](/docs/ko/llm-gateway-connect#add-gateway-models-to-the-model-picker)에는 영향을 주지 않습니다 |

275| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | `1`로 설정하면 스트리밍 요청이 스트림 도중 실패할 때 비스트리밍 폴백을 비활성화합니다. 대신 스트리밍 오류가 재시도 계층으로 전파됩니다. 프록시나 게이트웨이로 인해 폴백이 중복 도구 실행을 일으키는 경우 유용합니다 |279| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | `1`로 설정하면 스트리밍 요청이 스트림 도중 실패할 때 비스트리밍 폴백을 비활성화합니다. 대신 스트리밍 오류가 재시도 계층으로 전파됩니다. 프록시나 게이트웨이로 인해 폴백이 도구 실행을 중복시키는 경우에 유용합니다 |

276| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | `1`로 설정하면 사용자가 터미널에서 입력 중이거나 터미널에 포커스가 있는 동안에도 `PushNotification` 도구의 데스크톱 알림을 전송합니다. 기본적으로 이 도구는 최근 키보드 활동이나 터미널 포커스를 감지하면 데스크톱 알림과 [모바일 푸시](/docs/ko/remote-control#mobile-push-notifications)를 모두 건너뜁니다. 이 변수는 해당 로컬 검사만 비활성화하므로, 서버는 사용자가 활동 중임을 감지하면 여전히 모바일 푸시를 억제할 수 있습니다. Claude Code v2.1.193 이상이 필요합니다 |280| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | `1`로 설정하면 터미널에서 입력 중이거나 터미널에 포커스가 있는 동안에도 `PushNotification` 도구의 데스크톱 알림을 전송합니다. 기본적으로 이 도구는 최근 키보드 활동이나 터미널 포커스를 감지하면 데스크톱 알림과 [모바일 푸시](/docs/ko/remote-control#mobile-push-notifications)를 모두 건너뜁니다. 이 변수는 해당 로컬 검사만 비활성화하므로, 서버는 사용자가 활동 중임을 감지하면 여전히 모바일 푸시를 억제할 수 있습니다. Claude Code v2.1.193 이상이 필요합니다 |

277| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | `1`로 설정하면 공식 플러그인 마켓플레이스의 자동 등록을 비활성화합니다. Claude Code는 마켓플레이스를 등록하려는 시점, 보통 머신의 첫 대화형 실행 중에 이 변수를 읽습니다. 그 시점에 변수가 설정되어 있으면 Claude Code는 등록을 영구적으로 건너뜁니다. 나중에 변수를 설정 해제해도 건너뛴 등록이 되돌려지지 않습니다. 언제든지 마켓플레이스를 등록하려면 `claude plugin marketplace add anthropics/claude-plugins-official`을 실행합니다 |281| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | `1`로 설정하면 공식 플러그인 마켓플레이스의 자동 등록을 비활성화합니다. Claude Code는 마켓플레이스를 등록하려는 시점, 보통 머신의 첫 대화형 실행 중에 이 변수를 읽습니다. 그 시점에 변수가 설정되어 있으면 Claude Code는 등록을 영구적으로 건너뜁니다. 나중에 변수를 설정 해제해도 건너뛴 등록은 되돌려지지 않습니다. 언제든지 `claude plugin marketplace add anthropics/claude-plugins-official`을 실행하여 마켓플레이스를 등록할 수 있습니다 |

278| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | `1`로 설정하면 Claude Code가 응답하지 않은 권한 요청을 Agent SDK의 `canUseTool` 콜백으로 보내는 세션(Claude Desktop과 VS Code 확장 프로그램이 Claude Code를 호스팅하는 방식)에서 [응답하지 않은 권한 요청에 대한 `Notification` 훅](/docs/ko/hooks#notification)을 실행하지 않습니다. 터미널 세션에서는 효과가 없습니다. Claude Code v2.1.233 이상이 필요합니다 |282| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | `1`로 설정하면 Claude Code가 권한 요청을 Agent SDK의 `canUseTool` 콜백으로 보내는 세션에서 [응답하지 않은 권한 요청에 대한 `Notification` 훅](/docs/ko/hooks#notification)을 실행하지 않습니다. 이는 Claude Desktop과 VS Code 확장 프로그램이 Claude Code를 호스팅하는 방식입니다. 터미널 세션에서는 효과가 없습니다. Claude Code v2.1.233 이상이 필요합니다 |

279| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | `1`로 설정하면 시스템 전체 관리형 스킬 디렉터리에서 스킬을 로드하지 않습니다. 운영자가 프로비저닝한 스킬을 로드하지 않아야 하는 컨테이너 또는 CI 세션에 유용합니다 |283| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | `1`로 설정하면 시스템 전체 관리형 스킬 디렉터리에서 스킬을 로드하지 않습니다. 운영자가 프로비저닝한 스킬을 로드하지 않아야 하는 컨테이너 또는 CI 세션에 유용합니다 |

280| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | `1`로 설정하면 드라이브 루트나 홈 디렉터리 같은 [시스템 경로](/docs/ko/permission-modes#remove-item-in-powershell)에서 `cmd` 기본 제공 명령인 `rd`, `rmdir`, `del`, `erase`를 거부하는 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 검사를 끕니다. Claude Code는 설정 파일의 `env` 블록에 있는 이 변수를 무시합니다. Claude Code v2.1.283 이상이 필요합니다 |284| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | `1`로 설정하면 드라이브 루트나 홈 디렉터리 같은 [시스템 경로](/docs/ko/permission-modes#remove-item-in-powershell)에서 `cmd` 기본 제공 명령 `rd`, `rmdir`, `del`, `erase`를 거부하는 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 검사를 끕니다. Claude Code는 설정 파일의 `env` 블록에 있는 이 변수를 무시합니다. Claude Code v2.1.283 이상이 필요합니다 |

281| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | `1`로 설정하면 [`switchModelsOnFlag`](/docs/ko/settings-reference#switchmodelsonflag) 설정이 제어하는 동작인 [안전 분류기가 요청에 플래그를 지정할 때의 자동 모델 전환](/docs/ko/model-config#automatic-model-fallback)을 끕니다 |285| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | `1`로 설정하면 [안전 분류기가 요청을 플래그 지정할 때의 자동 모델 전환](/docs/ko/model-config#automatic-model-fallback)을 끕니다. 이는 [`switchModelsOnFlag`](/docs/ko/settings-reference#switchmodelsonflag) 설정이 제어하는 동작입니다 |

282| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | `1`로 설정하면 업스트림이 구조화된 출력 `output_config.format` 필드와 이와 짝을 이루는 `anthropic-beta` 값을 거부하는 [LLM 게이트웨이](/docs/ko/llm-gateway-protocol#feature-pass-through)를 위해 Claude Code가 이들을 전송하지 않습니다. [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)가 끄는 다른 출시 전 기능은 켜진 상태로 유지됩니다. Claude Code v2.1.288 이상이 필요합니다 |286| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | `1`로 설정하면 업스트림이 구조화된 출력 `output_config.format` 필드와 이와 짝을 이루는 `anthropic-beta` 값을 거부하는 [LLM 게이트웨이](/docs/ko/llm-gateway-protocol#feature-pass-through)를 위해 Claude Code가 이를 전송하지 않습니다. [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)가 끄는 다른 프리릴리스 기능은 켜진 상태로 유지됩니다. Claude Code v2.1.288 이상이 필요합니다 |

283| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | `1`로 설정하면 `rm -rf "$(pwd)"`처럼 대상이 전적으로 명령 치환의 출력인 재귀 `rm`에 대한 [중요 경로](/docs/ko/permission-modes#critical-paths) 검사를 끕니다. 다른 중요 경로 검사는 계속 실행됩니다. Claude Code는 설정의 `env` 블록을 통해 전달된 값을 무시하므로 Claude Code를 실행하는 환경에서 설정합니다. Claude Code v2.1.281 이상이 필요합니다 |287| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | `1`로 설정하면 `rm -rf "$(pwd)"`처럼 대상이 전적으로 명령 치환의 출력인 재귀적 `rm`에 대한 [중요 경로](/docs/ko/permission-modes#critical-paths) 검사를 끕니다. 다른 중요 경로 검사는 계속 실행됩니다. Claude Code는 설정 `env` 블록을 통해 전달된 값을 무시하므로 Claude Code를 실행하는 환경에서 설정합니다. Claude Code v2.1.281 이상이 필요합니다 |

284| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | `1`로 설정하면 대화 컨텍스트에 기반한 자동 터미널 제목 업데이트를 비활성화합니다. 또한 [세션 제목을 생성하는](/docs/ko/sessions#name-your-sessions) 백그라운드 소형/고속 모델 요청도 건너뜁니다 |288| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | `1`로 설정하면 대화 컨텍스트에 기반한 자동 터미널 제목 업데이트를 비활성화합니다. 또한 [세션 제목을 생성하는](/docs/ko/sessions#name-your-sessions) 백그라운드 small/fast 모델 요청도 건너뜁니다 |

285| `CLAUDE_CODE_DISABLE_THINKING` | `1`로 설정하면 API 요청에서 `thinking` 매개변수를 완전히 생략합니다. 이는 해당 매개변수를 거부하는 프록시와 게이트웨이를 위한 호환성 옵션입니다. 기본적으로 사고하는 모델에서는 매개변수를 생략해도 모델이 여전히 사고할 수 있습니다. Anthropic API에서 [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)를 명시적으로 비활성화하려면 대신 `MAX_THINKING_TOKENS=0`을 사용합니다. 두 변수 모두 사고를 끌 수 없는 모델인 Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 모델에서는 사고를 끄지 못합니다. [서드파티 공급자](/docs/ko/third-party-integrations)에서는 `MAX_THINKING_TOKENS=0`도 마찬가지로 매개변수를 생략하므로 두 변수가 동일하게 동작합니다 |289| `CLAUDE_CODE_DISABLE_THINKING` | `1`로 설정하면 API 요청에서 `thinking` 매개변수를 완전히 생략합니다. 이는 해당 매개변수를 거부하는 프록시와 게이트웨이를 위한 호환성 옵션입니다. 기본적으로 사고하는 모델에서는 매개변수를 생략해도 모델이 여전히 사고할 수 있습니다. Anthropic API에서 [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)를 명시적으로 비활성화하려면 대신 `MAX_THINKING_TOKENS=0`을 사용합니다. 두 변수 모두 사고를 끌 수 없는 Opus 5.5, Sonnet 5.5, Haiku 5.5 또는 Fable 모델에서는 사고를 끄지 않습니다. [서드파티 제공자](/docs/ko/third-party-integrations)에서는 `MAX_THINKING_TOKENS=0`도 마찬가지로 매개변수를 생략하므로 두 변수가 동일하게 동작합니다 |

286| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | `1`로 설정하면 Claude Code가 [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭처럼 모델 ID를 인식하지 못할 때 사전 [자동 압축](/docs/ko/costs#reduce-token-usage)을 건너뜁니다. 이 변수가 없으면 Claude Code는 해당 ID에 대해 가정한 컨텍스트 윈도우에서 압축합니다. 대신 `CLAUDE_CODE_MAX_CONTEXT_TOKENS`로 가정된 윈도우를 보정할 수 있습니다. 각 변수가 적용되는 경우는 [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 보정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요. Claude Code v2.1.223 이상이 필요합니다 |290| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | `1`로 설정하면 Claude Code가 [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭처럼 모델 ID를 인식하지 못할 때 사전 [자동 압축](/docs/ko/costs#reduce-token-usage)을 건너뜁니다. 이 변수가 없으면 Claude Code는 해당 ID에 대해 가정한 컨텍스트 윈도우에서 압축합니다. 대신 `CLAUDE_CODE_MAX_CONTEXT_TOKENS`로 가정된 윈도우를 보정할 수 있으며, 각 변수가 적용되는 경우는 [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 보정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요. Claude Code v2.1.223 이상이 필요합니다 |

287| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 가상 스크롤을 비활성화하고 트랜스크립트의 모든 메시지를 렌더링합니다. 전체 화면 모드에서 스크롤할 때 메시지가 표시되어야 할 곳에 빈 영역이 나타나는 경우 사용합니다 |291| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 가상 스크롤을 비활성화하고 트랜스크립트의 모든 메시지를 렌더링합니다. 전체 화면 모드에서 스크롤할 때 메시지가 나타나야 할 곳에 빈 영역이 표시되면 이 변수를 사용합니다 |

288| `CLAUDE_CODE_DISABLE_WEB_FETCH` | `1`로 설정하면 [WebFetch](/docs/ko/tools-reference#webfetch-tool-behavior) 도구를 끕니다. [WebSearch](/docs/ko/tools-reference#websearch-tool-behavior) 도구는 계속 사용할 수 있습니다. Claude Code v2.1.285 이상이 필요합니다 |292| `CLAUDE_CODE_DISABLE_WEB_FETCH` | `1`로 설정하면 [WebFetch](/docs/ko/tools-reference#webfetch-tool-behavior) 도구를 끕니다. [WebSearch](/docs/ko/tools-reference#websearch-tool-behavior) 도구는 계속 사용할 수 있습니다. Claude Code v2.1.285 이상이 필요합니다 |

289| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | `1`로 설정하면 Windows에서 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 명령을 `cmd.exe` 런처를 거치지 않고 직접 시작합니다. 기본적으로 런처는 [세션을 백그라운드로 전환](/docs/ko/agent-view#from-inside-a-session)할 때처럼 [백그라운드에서 실행 중인](/docs/ko/tools-reference#background-commands) PowerShell 명령이 [세션의 다음 프로세스로 이어지도록](/docs/ko/agent-view#the-supervisor-process) 합니다. 변수를 설정하면 백그라운드로 전환된 PowerShell 명령은 세션의 프로세스가 종료될 때 중지됩니다. Bash 명령은 영향을 받지 않습니다. Claude Code v2.1.269 이상이 필요합니다 |293| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | `1`로 설정하면 Windows에서 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 명령을 `cmd.exe` 런처를 거치지 않고 직접 시작합니다. 기본적으로 런처는 [백그라운드에서 실행 중인](/docs/ko/tools-reference#background-commands) PowerShell 명령이 [세션의 다음 프로세스로 이어지도록](/docs/ko/agent-view#the-supervisor-process) 하며, 예를 들어 [세션을 백그라운드로 전환](/docs/ko/agent-view#from-inside-a-session)할 때가 이에 해당합니다. 변수를 설정하면 백그라운드로 전환된 PowerShell 명령은 세션의 프로세스가 종료될 때 중지됩니다. Bash 명령은 영향을 받지 않습니다. Claude Code v2.1.269 이상이 필요합니다 |

290| `CLAUDE_CODE_DISABLE_WORKFLOWS` | `1`로 설정하면 [워크플로](/docs/ko/workflows#turn-workflows-off)를 비활성화합니다. [`disableWorkflows`](/docs/ko/settings-reference#disableworkflows) 설정과 동일합니다 |294| `CLAUDE_CODE_DISABLE_WORKFLOWS` | `1`로 설정하면 [워크플로](/docs/ko/workflows#turn-workflows-off)를 비활성화합니다. [`disableWorkflows`](/docs/ko/settings-reference#disableworkflows) 설정과 동일합니다 |

291| `CLAUDE_CODE_EFFORT_LEVEL` | 지원되는 모델의 effort 수준을 설정합니다. 값: `low`, `medium`, `high`, `xhigh`, `max` 또는 모델 기본값을 사용하는 `auto`. 사용 가능한 수준은 모델에 따라 다릅니다. `--effort`, `/effort`, `modelSettings` 및 `effortLevel` 설정보다 우선합니다. [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel) 상한은 여전히 적용됩니다. [effort 수준 조정](/docs/ko/model-config#adjust-effort-level)을 참조하세요 |295| `CLAUDE_CODE_EFFORT_LEVEL` | 지원되는 모델의 effort 수준을 설정합니다. 값: `low`, `medium`, `high`, `xhigh`, `max`, 또는 모델 기본값을 사용하는 `auto`. 사용 가능한 수준은 모델에 따라 다릅니다. `--effort`, `/effort`, `modelSettings` 및 `effortLevel` 설정보다 우선합니다. [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel) 상한은 여전히 적용됩니다. [effort 수준 조정](/docs/ko/model-config#adjust-effort-level)을 참조하세요 |

292| `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS` | `1`로 설정하면 세션 상태를 담은 [`session_state_changed`](/docs/ko/agent-sdk/typescript#sdksessionstatechangedmessage) 메시지를 메시지 스트림에 추가합니다. [Agent SDK](/docs/ko/agent-sdk/overview)를 사용하거나 `--print`, `--output-format stream-json`, `--verbose`를 함께 지정해야 합니다 |296| `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS` | 세션 상태를 담은 [`session_state_changed`](/docs/ko/agent-sdk/typescript#sdksessionstatechangedmessage) 메시지를 메시지 스트림에 추가하려면 `1`로 설정합니다. [Agent SDK](/docs/ko/agent-sdk/overview)가 필요하거나, `--print`, `--output-format stream-json`, `--verbose`가 모두 필요합니다 |

293| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 이전 릴리스와의 호환성을 위해 허용되며 효과는 없습니다. 자동 모드는 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, 로그인된 [Claude apps gateway](/docs/ko/claude-apps-gateway) 세션을 포함한 모든 공급자에서 기본적으로 사용할 수 있습니다. v2.1.158부터 v2.1.206까지는 해당 공급자에서 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용하려면 이 값을 `1`로 설정해야 했습니다 |297| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 이전 릴리스와의 호환성을 위해 허용되며 아무 효과가 없습니다. 자동 모드는 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, 로그인한 [Claude apps gateway](/docs/ko/claude-apps-gateway) 세션을 포함한 모든 제공업체에서 기본적으로 사용할 수 있습니다. v2.1.158부터 v2.1.206까지는 해당 제공업체에서 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용하려면 이 변수를 `1`로 설정해야 했습니다 |

294| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | [세션 요약](/docs/ko/interactive-mode#session-recap) 사용 여부를 재정의합니다. `0`으로 설정하면 `/config` 토글과 관계없이 요약을 강제로 끕니다. `1`로 설정하면 [`awaySummaryEnabled`](/docs/ko/settings-reference#awaysummaryenabled)가 `false`일 때 요약을 강제로 켭니다. 설정과 `/config` 토글보다 우선합니다 |298| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | [세션 요약](/docs/ko/interactive-mode#session-recap) 사용 여부를 재정의합니다. `/config` 토글과 관계없이 요약을 강제로 끄려면 `0`으로 설정합니다. [`awaySummaryEnabled`](/docs/ko/settings-reference#awaysummaryenabled)가 `false`일 때 요약을 강제로 켜려면 `1`로 설정합니다. 설정과 `/config` 토글보다 우선합니다 |

295| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | `1`로 설정하면 백그라운드 설치가 완료된 후 [비대화형 모드](/docs/ko/headless)에서 턴 경계마다 플러그인 상태를 새로 고칩니다. 새로 고침은 세션 도중 시스템 프롬프트를 변경하여 해당 턴의 [프롬프트 캐싱](/docs/ko/prompt-caching)을 무효화하므로 기본적으로 꺼져 있습니다 |299| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 백그라운드 설치가 완료된 후 [비대화형 모드](/docs/ko/headless)에서 턴 경계마다 플러그인 상태를 새로 고치려면 `1`로 설정합니다. 새로 고침은 세션 도중 시스템 프롬프트를 변경하여 해당 턴의 [프롬프트 캐싱](/docs/ko/prompt-caching)을 무효화하므로 기본적으로 꺼져 있습니다 |

296| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | `1`로 설정하면 Anthropic으로 향하는 필수적이지 않은 트래픽이 차단된 경우 "How is Claude doing?" 세션 품질 설문을 자체 [OpenTelemetry 컬렉터](/docs/ko/monitoring-usage)로 라우팅합니다. 설문 평가는 구성된 컬렉터에 OTEL 이벤트로만 내보내집니다. 이 모드에서는 설문 데이터가 Anthropic으로 전송되지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY` 또는 `DO_NOT_TRACK`이 설정된 경우에 적용되며, 그 외에는 효과가 없습니다. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`와 조직의 제품 피드백 정책이 우선합니다 |300| `CLAUDE_CODE_ENABLE_CFC` | [Chrome 통합](/docs/ko/chrome)을 켠 상태로 CLI 세션을 시작하려면 `1`로, 끈 상태로 시작하려면 `0`으로 설정합니다. [`claudeInChromeDefaultEnabled`](/docs/ko/settings-reference#claudeinchromedefaultenabled) 설정보다 우선합니다. `--chrome` 및 `--no-chrome` 플래그는 둘 모두보다 우선합니다. Claude Code는 [프로젝트 및 로컬 설정의 `1`을 무시합니다](/docs/ko/chrome#project-settings-can’t-turn-on-chrome) |

297| `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) 연결에서는 기본적으로 꺼져 있습니다 |301| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Anthropic으로 향하는 비필수 트래픽이 차단된 경우 "How is Claude doing?" 세션 품질 설문을 자체 [OpenTelemetry 컬렉터](/docs/ko/monitoring-usage)로 전달하려면 `1`로 설정합니다. 설문 평가는 구성된 컬렉터에 OTEL 이벤트로만 전송됩니다. 이 모드에서는 설문 데이터가 Anthropic으로 전송되지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY` 또는 `DO_NOT_TRACK`이 설정된 경우에 적용되며, 그렇지 않으면 아무 효과가 없습니다. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`와 조직의 제품 피드백 정책이 우선합니다 |

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

303| `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)을 통해 전달합니다 |

300| `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)을 참조하세요 |305| `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)을 참조하세요 |

301| `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)을 참조하세요 |306| `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)을 참조하세요 |

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

303| `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 이상이 필요합니다 |308| `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 이상이 필요합니다 |

304| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | 쿼리 루프가 유휴 상태가 된 후 자동으로 종료하기 전까지 대기할 시간(밀리초)입니다. SDK 모드를 사용하는 자동화된 워크플로와 스크립트에 유용합니다 |309| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | 쿼리 루프가 유휴 상태가 된 후 자동으로 종료하기 전까지 기다리는 시간(밀리초)입니다. SDK 모드를 사용하는 자동화된 워크플로와 스크립트에 유용합니다 |

305| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | `1`로 설정하면 [에이전트 팀](/docs/ko/agent-teams)을 활성화합니다. 에이전트 팀은 실험적 기능이며 기본적으로 비활성화되어 있습니다 |310| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | [에이전트 팀](/docs/ko/agent-teams)을 활성화하려면 `1`로 설정합니다. 에이전트 팀은 실험적 기능이며 기본적으로 비활성화되어 있습니다 |

306| `CLAUDE_CODE_EXTRA_BODY` | 모든 API 요청 본문의 최상위 수준에 병합할 JSON 객체입니다. Claude Code가 직접 노출하지 않는 공급자별 매개변수를 전달할 때 유용합니다. 셸에서 export한 값은 `claude agents` 또는 `--bg`로 디스패치하는 [백그라운드 세션](/docs/ko/agent-view)에도 적용됩니다. v2.1.206 이전에는 백그라운드 세션이 셸에서 export한 값을 무시하고 백그라운드 supervisor 프로세스가 상속한 값을 사용했습니다 |311| `CLAUDE_CODE_EXTRA_BODY` | 모든 API 요청 본문의 최상위 수준에 병합할 JSON 객체입니다. Claude Code가 직접 노출하지 않는 제공업체별 매개변수를 전달할 때 유용합니다. 셸에서 export한 값은 `claude agents` 또는 `--bg`로 실행하는 [백그라운드 세션](/docs/ko/agent-view)에도 적용됩니다. v2.1.206 이전에는 백그라운드 세션이 셸에서 export한 값을 무시하고 백그라운드 수퍼바이저 프로세스가 상속한 값을 사용했습니다 |

308| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | `1`로 설정하면 이 `claude`가 다른 Claude Code 세션 내부에서 시작된 경우에도 트랜스크립트 저장, 프롬프트 기록, `claude agents` 등록을 강제합니다. 예를 들어 `screen` 세션이나 Claude Code의 Bash 도구가 처음 시작한 백그라운드 런처에서 상속된 `CLAUDE_CODE_CHILD_SESSION` 값 때문에 실제 최상위 세션이 중첩된 세션으로 잘못 분류될 때 사용합니다. v2.1.178부터 Claude Code는 tmux의 경우를 자동으로 감지하고 상속된 마커를 무시하므로 tmux에서는 더 이상 이 변수가 필요하지 않습니다. v2.1.169 이하에서도 적용되며, 이 변수가 재정의하는 중첩 세션 감지가 제거된 v2.1.170과 v2.1.171에서는 효과가 없습니다 |313| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 이 `claude`가 다른 Claude Code 세션 내부에서 실행된 경우에도 트랜스크립트 저장, 프롬프트 기록, `claude agents` 등록을 강제하려면 `1`로 설정합니다. 예를 들어 `screen` 세션이나 Claude Code의 Bash 도구로 처음 시작된 백그라운드 런처에서 상속된 `CLAUDE_CODE_CHILD_SESSION` 값으로 인해 실제 최상위 세션이 중첩된 세션으로 잘못 분류될 때 사용합니다. v2.1.178부터 Claude Code는 tmux의 경우를 자동으로 감지하여 상속된 마커를 무시하므로 tmux에서는 더 이상 이 변수가 필요하지 않습니다. v2.1.169 이하에서도 적용되며, 이 변수가 재정의하는 중첩 세션 감지가 제거된 v2.1.170과 v2.1.171에서는 아무 효과가 없습니다 |

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

310| `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`와 달리 렌더러를 변경하지 않습니다 |315| `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`와 달리 렌더러를 변경하지 않습니다 |

311| `CLAUDE_CODE_FORCE_TERMINAL_IMAGES` | 터미널이 Unicode 플레이스홀더를 사용해 kitty 그래픽 프로토콜 이미지를 그리지만 자동 감지되지 않는 경우, `1`로 설정하면 [mod `Image` 요소](/docs/ko/plugins/mods/reference#elements)를 그림으로 그립니다. [Claude Code가 감지하는 터미널](/docs/ko/plugins/mods/gallery#image-and-client)과 tmux 또는 screen 내부에서 도움이 되지 않는 이유를 참조하세요 |316| `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 내부에서는 도움이 되지 않는 이유를 참조하세요 |

312| `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`로 설정합니다 |317| `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`로 설정합니다 |

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

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

315| `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 이상이 필요합니다 |320| `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 이상이 필요합니다 |

316| `CLAUDE_CODE_GIT_BASH_PATH` | Windows 전용: Git Bash 실행 파일(`bash.exe`)의 경로입니다. Git Bash가 설치되어 있지만 PATH에 없을 때 사용합니다. 경로가 존재하지 않거나 파일 이름이 `bash.exe`, `sh.exe`, `bash`, `sh`가 아닌 경우 Claude Code는 변수를 무시하고 설정되지 않은 것처럼 Git Bash를 자동 감지하며, `--debug`로 확인할 수 있는 경고를 로그에 기록합니다. v2.1.219 이전에는 경로가 존재하지 않으면 Claude Code가 시작 시 종료되었고, bash 또는 sh인지 확인하지 않고 존재하는 모든 파일을 셸로 사용했습니다. [Windows 설정](/docs/ko/setup#set-up-on-windows)을 참조하세요 |321| `CLAUDE_CODE_GIT_BASH_PATH` | Windows 전용: Git Bash 실행 파일(`bash.exe`)의 경로입니다. Git Bash가 설치되어 있지만 PATH에 없는 경우 사용합니다. 경로가 존재하지 않거나 파일 이름이 `bash.exe`, `sh.exe`, `bash`, `sh`가 아닌 경우 Claude Code는 변수를 무시하고 설정되지 않은 것처럼 Git Bash를 자동 감지하며, `--debug`로 확인할 수 있는 경고를 로그에 기록합니다. v2.1.219 이전에는 경로가 존재하지 않으면 Claude Code가 시작 시 종료되었고, bash나 sh인지 확인하지 않고 존재하는 모든 파일을 셸로 사용했습니다. [Windows 설정](/docs/ko/setup#set-up-on-windows)을 참조하세요 |

317| `CLAUDE_CODE_GLOB_HIDDEN` | `false`로 설정하면 Claude가 [Glob 도구](/docs/ko/tools-reference#glob-tool-behavior)를 호출할 때 결과에서 dotfile을 제외합니다. 기본적으로 포함됩니다. `@` 파일 자동 완성, `ls`, Grep, Read에는 영향을 주지 않습니다 |322| `CLAUDE_CODE_GLOB_HIDDEN` | Claude가 [Glob 도구](/docs/ko/tools-reference#glob-tool-behavior)를 호출할 때 결과에서 dotfile을 제외하려면 `false`로 설정합니다. 기본적으로 포함됩니다. `@` 파일 자동 완성, `ls`, Grep, Read에는 영향을 주지 않습니다 |

318| `CLAUDE_CODE_GLOB_NO_IGNORE` | `false`로 설정하면 [Glob 도구](/docs/ko/tools-reference#glob-tool-behavior)가 `.gitignore` 패턴을 따릅니다. 기본적으로 Glob은 gitignore된 파일을 포함해 일치하는 모든 파일을 반환합니다. 자체 [`respectGitignore` 설정](/docs/ko/settings-reference#respectgitignore)이 있는 `@` 파일 자동 완성에는 영향을 주지 않습니다 |323| `CLAUDE_CODE_GLOB_NO_IGNORE` | [Glob 도구](/docs/ko/tools-reference#glob-tool-behavior)가 `.gitignore` 패턴을 따르도록 하려면 `false`로 설정합니다. 기본적으로 Glob은 gitignore된 파일을 포함한 모든 일치하는 파일을 반환합니다. 자체 [`respectGitignore` 설정](/docs/ko/settings-reference#respectgitignore)이 있는 `@` 파일 자동 완성에는 영향을 주지 않습니다 |

320| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 백그라운드 작업이 활성 목표를 대기시킬 수 있는 시간(분)으로, 이 시간이 지나면 Claude Code가 [Claude에게 확인을 요청합니다](/docs/ko/goal#background-work-defers-evaluation). 기본값은 `30`입니다. 확인을 끄려면 `0`으로 설정합니다. 최대 `10080`(1주일)까지의 정수 분 값을 숫자로만 지정합니다. Claude Code는 그 외의 값을 설정되지 않은 것으로 간주하고 기본값을 사용합니다. Claude Code v2.1.234 이상이 필요합니다 |325| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 백그라운드 작업이 활성 목표를 몇 분 동안 대기시킬 수 있는지 지정하며, 이 시간이 지나면 Claude Code가 [Claude에게 확인을 요청합니다](/docs/ko/goal#background-work-defers-evaluation). 기본값은 `30`입니다. 확인을 끄려면 `0`으로 설정합니다. 정수 분을 숫자로만 지정하며, 최대값은 1주에 해당하는 `10080`입니다. Claude Code는 그 밖의 값을 설정되지 않은 것으로 간주하고 기본값을 사용합니다. Claude Code v2.1.234 이상이 필요합니다 |

321| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | `0`으로 설정하면 `api.anthropic.com`으로 전송되는 Claude API, 텔레메트리, [아티팩트](/docs/ko/artifacts) 게시 요청 본문의 gzip 압축을 끕니다. 기본적으로 Claude Code는 직접 연결에서 큰 요청 본문을 압축하며, 프록시를 통해 요청을 보내거나 클라이언트 인증서를 구성하거나 `NODE_EXTRA_CA_CERTS`를 설정한 경우에는 압축을 건너뜁니다. Claude Code가 감지할 수 없는 [TLS 검사 프록시](/docs/ko/network-config#ca-certificate-store)가 압축된 요청을 잘못 처리하는 경우 `0`을 사용합니다 |326| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | `api.anthropic.com`으로 전송되는 Claude API, 텔레메트리, [아티팩트](/docs/ko/artifacts) 게시 요청 본문의 gzip 압축을 끄려면 `0`으로 설정합니다. 기본적으로 Claude Code는 직접 연결에서 큰 요청 본문을 압축하며, 프록시를 통해 요청을 보내거나, 클라이언트 인증서를 구성하거나, `NODE_EXTRA_CA_CERTS`를 설정한 경우에는 압축을 건너뜁니다. Claude Code가 감지할 수 없는 [TLS 검사 프록시](/docs/ko/network-config#ca-certificate-store)가 압축된 요청을 잘못 처리하는 경우 `0`을 사용합니다 |

323| `CLAUDE_CODE_IDE_HOST_OVERRIDE` | IDE 확장에 연결하는 데 사용되는 호스트 주소를 재정의합니다. 기본적으로 Claude Code는 WSL에서 Windows로의 라우팅을 포함해 올바른 주소를 자동 감지합니다 |328| `CLAUDE_CODE_IDE_HOST_OVERRIDE` | IDE 확장에 연결하는 데 사용되는 호스트 주소를 재정의합니다. 기본적으로 Claude Code는 WSL에서 Windows로의 라우팅을 포함하여 올바른 주소를 자동으로 감지합니다 |

324| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | `1`로 설정하면 IDE 확장 자동 설치를 건너뜁니다. [`autoInstallIdeExtension`](/docs/ko/settings-reference#autoinstallideextension)을 `false`로 설정하는 것과 같습니다 |329| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | IDE 확장의 자동 설치를 건너뛰려면 `1`로 설정합니다. [`autoInstallIdeExtension`](/docs/ko/settings-reference#autoinstallideextension)을 `false`로 설정하는 것과 같습니다 |

325| `CLAUDE_CODE_IDE_SKIP_VALID_CHECK` | `1`로 설정하면 연결 중 IDE 잠금 파일 항목의 유효성 검사를 건너뜁니다. IDE가 실행 중인데도 자동 연결이 IDE를 찾지 못할 때 사용합니다 |330| `CLAUDE_CODE_IDE_SKIP_VALID_CHECK` | 연결 중 IDE 잠금 파일 항목의 유효성 검사를 건너뛰려면 `1`로 설정합니다. IDE가 실행 중인데도 자동 연결이 IDE를 찾지 못할 때 사용합니다 |

326| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | Agent 도구가 추가 생성을 거부하기 전까지 한 세션에서 동시에 실행할 수 있는 [서브에이전트](/docs/ko/sub-agents#concurrent-subagent-limit) 수입니다(기본값: 20). 숫자로만 된 양의 정수를 허용하며, 그 외의 값은 무시되므로 이 변수로 상한을 조정할 수는 있지만 비활성화할 수는 없습니다. Claude Code v2.1.217 이상이 필요합니다 |331| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | Agent 도구가 추가 생성을 거부하기 전까지 한 세션에서 동시에 실행할 수 있는 [서브에이전트](/docs/ko/sub-agents#concurrent-subagent-limit) 수입니다(기본값: 20). 숫자로만 된 양의 정수를 허용하며 그 밖의 값은 무시되므로, 이 변수로 상한을 조정할 수는 있지만 비활성화할 수는 없습니다. Claude Code v2.1.217 이상이 필요합니다 |

327| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Claude Code가 활성 모델에 대해 가정하는 컨텍스트 윈도우 크기를 재정의합니다. v2.1.193부터는 Claude Code가 모델 ID를 확인하는 방식에 따라 적용 방법이 달라집니다. [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요. 컨텍스트 윈도우가 이름에 해당하는 기본 제공 크기와 일치하지 않는 모델로 `ANTHROPIC_BASE_URL`을 통해 라우팅할 때 사용합니다 |332| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Claude Code가 활성 모델에 대해 가정하는 컨텍스트 윈도우 크기를 재정의합니다. v2.1.193부터는 Claude Code가 모델 ID를 확인하는 방식에 따라 적용 방식이 달라집니다. [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요. `ANTHROPIC_BASE_URL`을 통해 라우팅하는 모델의 컨텍스트 윈도우가 해당 이름에 대한 기본 제공 크기와 일치하지 않을 때 사용합니다 |

328| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code가 모델에 보내는 각 MCP 도구 설명과 각 MCP 서버 지침의 최대 길이(문자 수)입니다(기본값: 2048). Claude Code는 [더 긴 텍스트를 잘라냅니다](/docs/ko/mcp#for-mcp-server-authors). 숫자로만 된 양의 정수를 허용합니다. 그 외의 값은 무시되고 기본값이 적용됩니다. Claude Code v2.1.280 이상이 필요합니다 |333| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code가 모델에 보내는 각 MCP 도구 설명과 각 MCP 서버 지침의 최대 길이(문자 수)입니다(기본값: 2048). Claude Code는 [더 긴 텍스트를 잘라냅니다](/docs/ko/mcp#for-mcp-server-authors). 숫자로만 된 양의 정수를 허용합니다. 그 밖의 값은 무시되고 기본값이 적용됩니다. Claude Code v2.1.280 이상이 필요합니다 |

329| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 대부분의 요청에 대한 최대 출력 토큰 수를 설정합니다. 기본값과 상한은 모델마다 다릅니다. [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)을 참조하세요. 모델의 상한을 초과하는 값은 Claude Code가 상한으로 낮춥니다. Claude Code가 알고 있는 모델로 확인할 수 없는 모델 ID의 경우 기본값은 32000이고 상한은 128000입니다. 이 값을 늘리면 [자동 압축](/docs/ko/costs#reduce-token-usage)이 트리거되기 전에 사용할 수 있는 유효 컨텍스트 윈도우가 줄어듭니다 |334| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 대부분의 요청에 대한 최대 출력 토큰 수를 설정합니다. 기본값과 상한은 모델마다 다릅니다. [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)을 참조하세요. 모델의 상한을 초과하는 값은 Claude Code가 상한으로 낮춥니다. Claude Code가 알려진 모델로 확인할 수 없는 모델 ID의 경우 기본값은 32000이고 상한은 128000입니다. 이 값을 늘리면 [자동 압축](/docs/ko/costs#reduce-token-usage)이 트리거되기 전에 사용할 수 있는 유효 컨텍스트 윈도우가 줄어듭니다 |

330| `CLAUDE_CODE_MAX_RETRIES` | 실패한 API 요청을 재시도하는 횟수를 재정의합니다(기본값: 10). v2.1.186부터 15로 제한됩니다. v2.1.199부터는 `CLAUDE_CODE_RETRY_WATCHDOG`가 기본값을 높이고 상한을 제거합니다. 더 긴 장애 동안 기다려야 하는 무인 세션에서는 대신 `CLAUDE_CODE_RETRY_WATCHDOG`를 설정합니다 |335| `CLAUDE_CODE_MAX_RETRIES` | 실패한 API 요청의 재시도 횟수를 재정의합니다(기본값: 10). v2.1.186부터 상한은 15입니다. v2.1.199부터 `CLAUDE_CODE_RETRY_WATCHDOG`가 기본값을 늘리고 상한을 제거합니다. 더 긴 장애를 기다려야 하는 무인 세션에는 대신 `CLAUDE_CODE_RETRY_WATCHDOG`를 설정합니다 |

331| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | v2.1.224에서 제거되어 현재는 아무 동작도 하지 않습니다. 이전에는 한 세션에서 Claude가 Agent 도구로 생성할 수 있는 [서브에이전트](/docs/ko/sub-agents)의 총수를 제한했으며(기본값: 200), 상한을 넘어 생성하면 `Subagent spawn limit reached`와 함께 실패했습니다. [동시 서브에이전트 제한](/docs/ko/sub-agents#concurrent-subagent-limit)과 [깊이 제한](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)은 여전히 적용됩니다 |336| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | v2.1.224에서 제거되었으며 이제 아무 작업도 하지 않습니다. 이전에는 한 세션에서 Claude가 Agent 도구로 생성할 수 있는 [서브에이전트](/docs/ko/sub-agents)의 총수를 제한했으며(기본값: 200), 상한을 넘어 생성하면 `Subagent spawn limit reached`와 함께 실패했습니다. [동시 서브에이전트 제한](/docs/ko/sub-agents#concurrent-subagent-limit)과 [깊이 제한](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)은 여전히 적용됩니다 |

332| `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 이상이 필요합니다 |337| `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 이상이 필요합니다 |

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

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

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

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

338| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [비대화형](/docs/ko/headless) 세션의 첫 번째 턴이 아직 연결 중인 MCP 서버를 기다리는 시간(밀리초)으로, 기본 [첫 번째 턴 대기](/docs/ko/agent-sdk/mcp#connection-timing)를 대신합니다. 설정하면 대기가 보류 중인 모든 서버에 적용됩니다. 대기를 건너뛰려면 `0`으로 설정합니다. [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 서버는 값과 관계없이 자체 `MCP_TIMEOUT` 대기를 유지합니다. Claude Code v2.1.274 이상이 필요합니다 |343| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [비대화형](/docs/ko/headless) 세션의 첫 번째 턴이 아직 연결 중인 MCP 서버를 기다리는 시간(밀리초)으로, 기본 [첫 번째 턴 대기](/docs/ko/agent-sdk/mcp#connection-timing)를 대체합니다. 설정하면 대기가 보류 중인 모든 서버에 적용됩니다. 대기를 건너뛰려면 `0`으로 설정합니다. [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 서버는 값과 관계없이 자체 `MCP_TIMEOUT` 대기를 유지합니다. Claude Code v2.1.274 이상이 필요합니다 |

339| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 도구 호출의 유휴 타임아웃(밀리초)입니다. stdio, HTTP, SSE, WebSocket 또는 [claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai) MCP 서버가 이 시간 동안 응답이나 진행 알림을 보내지 않으면, 도구 호출은 전체 `MCP_TOOL_TIMEOUT`을 기다리지 않고 오류와 함께 중단됩니다. 네트워크 서버의 경우 300000(5분), stdio 서버의 경우 1800000(30분)인 전송 방식별 기본값을 재정의합니다. 유휴 검사를 비활성화하려면 `0`으로 설정합니다. 1000 미만의 값은 1초로 올려지며, 값은 유효 `MCP_TOOL_TIMEOUT`으로 제한됩니다. `.mcp.json`에서 서버별 `timeout`이 1000 이상이면 해당 서버의 유휴 기간이 최소 `timeout` 값으로 늘어납니다. IDE 서버나 SDK 인프로세스 서버에는 적용되지 않습니다. Claude Code v2.1.187 이상이 필요합니다. v2.1.203 이전에는 stdio 서버가 유휴 타임아웃에서 제외되었습니다 |344| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 도구 호출의 유휴 타임아웃(밀리초)입니다. stdio, HTTP, SSE, WebSocket 또는 [claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai) MCP 서버가 이 시간 동안 응답이나 진행 알림을 보내지 않으면, 전체 `MCP_TOOL_TIMEOUT`을 기다리는 대신 도구 호출이 오류와 함께 중단됩니다. 네트워크 서버의 300000(5분), stdio 서버의 1800000(30분)이라는 전송 방식별 기본값을 재정의합니다. 유휴 검사를 비활성화하려면 `0`으로 설정합니다. 1000 미만의 값은 1초로 올라가며, 값은 유효 `MCP_TOOL_TIMEOUT`으로 제한됩니다. `.mcp.json`에서 서버별 `timeout`이 1000 이상이면 해당 서버의 유휴 시간이 최소 `timeout` 값으로 올라갑니다. IDE 서버나 SDK 인프로세스 서버에는 적용되지 않습니다. Claude Code v2.1.187 이상이 필요합니다. v2.1.203 이전에는 stdio 서버가 유휴 타임아웃에서 제외되었습니다 |

340| `CLAUDE_CODE_MESSAGING_SOCKET` | 사용자가 아닌 Claude Code가 설정합니다. [받은 편지함 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 소켓을 바인딩할 때 해당 소켓의 경로를 훅과 Bash 명령에 내보냅니다. 메시징이 켜진 상태로 시작하는 세션에서는 Claude Code가 훅이 실행되기 전에 소켓을 바인딩합니다. 머신의 다른 세션은 이 경로로 메시지를 전달합니다. 각 세션은 부모에게서 상속된 소켓이 아닌 자체 소켓을 내보내며, 이 소켓으로 도착하는 메시지는 세션의 [수신 제어](/docs/ko/cross-session-messaging#control-inbound-messages)를 거칩니다. 설정의 `env` 블록으로는 설정할 수 없습니다. Claude Code v2.1.224 이상이 필요합니다 |345| `CLAUDE_CODE_MESSAGING_SOCKET` | 사용자가 아닌 Claude Code가 설정합니다. [inbox 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 소켓을 바인딩할 때 해당 소켓의 경로를 훅과 Bash 명령에 export합니다. 메시징이 켜진 상태로 시작하는 세션에서는 Claude Code가 훅이 실행되기 전에 소켓을 바인딩합니다. 머신의 다른 세션은 이 경로로 메시지를 전달합니다. 각 세션은 부모로부터 상속된 소켓이 아닌 자체 소켓을 export하며, 이 소켓으로 도착하는 메시지는 세션의 [인바운드 제어](/docs/ko/cross-session-messaging#control-inbound-messages)를 거칩니다. 설정의 `env` 블록으로는 설정할 수 없습니다. Claude Code v2.1.224 이상이 필요합니다 |

341| `CLAUDE_CODE_MESSAGING_TOKEN` | 사용자가 아닌 Claude Code가 설정합니다. [받은 편지함 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 `CLAUDE_CODE_MESSAGING_SOCKET`과 함께 이 세션별 토큰을 훅과 Bash 명령에 내보냅니다. 소켓에 게시하는 스크립트는 첫 줄로 `{"type":"auth","token":"<token>"}`을 보내 해당 세션에 속해 있음을 증명할 수 있습니다. 네이티브 Windows에서는 Claude Code가 이 줄을 요구하며, 유효한 줄로 시작하지 않는 연결은 닫습니다. Claude Code가 토큰을 참조하는 시점은 [자체 자식 규칙](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)에서 설명합니다. 각 세션은 부모 세션에서 상속된 토큰이 아닌 자체 토큰을 내보냅니다. 설정의 `env` 블록으로는 설정할 수 없습니다. Claude Code v2.1.228 이상이 필요합니다 |346| `CLAUDE_CODE_MESSAGING_TOKEN` | 사용자가 아닌 Claude Code가 설정합니다. [inbox 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 `CLAUDE_CODE_MESSAGING_SOCKET`과 함께 이 세션별 토큰을 훅과 Bash 명령에 export합니다. 소켓에 게시하는 스크립트는 첫 줄로 `{"type":"auth","token":"<token>"}`를 보내 해당 세션에 속함을 증명할 수 있습니다. 네이티브 Windows에서는 Claude Code가 이 줄을 요구하며, 유효한 줄로 시작하지 않는 연결은 모두 닫습니다. Claude Code가 토큰을 확인하는 시점은 [자체 자식 규칙](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)에 설명되어 있습니다. 각 세션은 부모 세션에서 상속된 토큰이 아닌 자체 토큰을 export합니다. 설정의 `env` 블록으로는 설정할 수 없습니다. Claude Code v2.1.228 이상이 필요합니다 |

342| `CLAUDE_CODE_NATIVE_CURSOR` | `1`로 설정하면 그려진 블록 대신 입력 캐럿 위치에 터미널 자체 커서를 표시합니다. 커서는 터미널의 깜박임, 모양, 포커스 설정을 따릅니다. `0`으로 설정하는 것은 변수를 설정하지 않은 것과 같게 해석되므로, 터미널 자체 커서가 이미 켜져 있는 세션에서 그려진 블록을 다시 표시하지는 않습니다 |347| `CLAUDE_CODE_NATIVE_CURSOR` | 그려진 블록 대신 입력 캐럿 위치에 터미널 자체 커서를 표시하려면 `1`로 설정합니다. 커서는 터미널의 깜박임, 모양, 포커스 설정을 따릅니다. `0`으로 설정하는 것은 변수를 설정하지 않은 것과 같으므로, 터미널 자체 커서가 이미 켜진 세션에서 그려진 블록을 다시 표시하지는 않습니다 |

343| `CLAUDE_CODE_NEW_INIT` | `1`로 설정하면 `/init`이 대화형 설정 흐름을 실행합니다. 이 흐름은 코드베이스를 탐색하고 파일을 작성하기 전에 CLAUDE.md, 스킬, 훅을 포함해 생성할 파일을 묻습니다. 이 변수가 없으면 `/init`은 묻지 않고 CLAUDE.md를 자동으로 생성합니다 |348| `CLAUDE_CODE_NEW_INIT` | `/init`이 대화형 설정 흐름을 실행하도록 하려면 `1`로 설정합니다. 이 흐름은 코드베이스를 탐색하고 파일을 작성하기 전에 CLAUDE.md, 스킬, 훅 등 어떤 파일을 생성할지 묻습니다. 이 변수가 없으면 `/init`은 묻지 않고 CLAUDE.md를 자동으로 생성합니다 |

344| `CLAUDE_CODE_NONBLOCKING_STDOUT` | `1`로 설정하면 두 번째 논블로킹 파일 디스크립터를 통해 터미널 출력을 기록하므로, 일시 중지된 tmux control-mode 창이나 멈춘 SSH 연결처럼 읽기를 멈춘 터미널이 세션 도중 Claude Code를 멈추게 할 수 없습니다. stdout이 터미널인 경우 macOS, Linux, WSL에서 적용됩니다. Claude Code v2.1.261 이상이 필요합니다 |349| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 두 번째 논블로킹 파일 디스크립터를 통해 터미널 출력을 쓰려면 `1`로 설정합니다. 이렇게 하면 일시 중지된 tmux 컨트롤 모드 창이나 멈춘 SSH 연결처럼 읽기를 중단한 터미널이 세션 도중 Claude Code를 멈추게 할 수 없습니다. stdout이 터미널인 경우 macOS, Linux, WSL에서 적용됩니다. Claude Code v2.1.261 이상이 필요합니다 |

345| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 시간 초과된 [비스트리밍 요청](/docs/ko/errors#streaming-response-ended-before-any-complete-data-was-received)을 Claude Code가 다시 보내는 횟수를 제한합니다. `0`이면 첫 번째 타임아웃에서 요청이 실패합니다. 타임아웃에 대해서는 [재시도 동작 조정](/docs/ko/errors#tune-retry-behavior)을 참조하세요. Claude Code v2.1.285 이상이 필요합니다 |350| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 시간 초과된 [비스트리밍 요청](/docs/ko/errors#streaming-response-ended-before-any-complete-data-was-received)을 Claude Code가 다시 보내는 횟수를 제한합니다. `0`이면 첫 번째 시간 초과에서 요청이 실패합니다. 타임아웃에 대해서는 [재시도 동작 조정](/docs/ko/errors#tune-retry-behavior)을 참조하세요. Claude Code v2.1.285 이상이 필요합니다 |

346| `CLAUDE_CODE_NO_FLICKER` | `1`로 설정하면 깜박임을 줄이고 긴 대화에서 메모리 사용량을 일정하게 유지하는 리서치 프리뷰인 [전체 화면 렌더링](/docs/ko/fullscreen)을 활성화합니다. [`tui`](/docs/ko/settings-reference#tui) 설정을 재정의합니다. `/tui fullscreen`으로 전환할 수도 있습니다 |351| `CLAUDE_CODE_NO_FLICKER` | 깜박임을 줄이고 긴 대화에서 메모리 사용량을 일정하게 유지하는 리서치 프리뷰인 [전체 화면 렌더링](/docs/ko/fullscreen)을 활성화하려면 `1`로 설정합니다. [`tui`](/docs/ko/settings-reference#tui) 설정을 재정의하며, `/tui fullscreen`으로도 전환할 수 있습니다 |

347| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증을 위한 OAuth 새로 고침 토큰입니다. 설정하면 `claude auth login`이 브라우저를 여는 대신 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝할 때 유용합니다 |352| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증을 위한 OAuth 갱신 토큰입니다. 설정하면 `claude auth login`이 브라우저를 여는 대신 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝할 때 유용합니다 |

348| `CLAUDE_CODE_OAUTH_SCOPES` | 새로 고침 토큰이 발급될 때 사용된, 공백으로 구분된 OAuth 범위입니다(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정된 경우 필요합니다 |353| `CLAUDE_CODE_OAUTH_SCOPES` | 갱신 토큰이 발급될 때의 OAuth 범위를 공백으로 구분한 목록입니다(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정된 경우 필수입니다 |

349| `CLAUDE_CODE_OAUTH_TOKEN` | claude.ai 인증을 위한 OAuth 액세스 토큰입니다. SDK 및 자동화된 환경에서 `/login`의 대안입니다. 키체인에 저장된 자격 증명보다 우선합니다. [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 생성합니다. [`/login`](/docs/ko/authentication#authentication-precedence)을 실행하지 않는 한 Claude Code는 세션 전체에서 설정한 토큰을 사용합니다. 만료된 토큰을 교체하려면 새 토큰을 생성하고 다시 시작합니다 |354| `CLAUDE_CODE_OAUTH_TOKEN` | claude.ai 인증을 위한 OAuth 액세스 토큰입니다. SDK 및 자동화된 환경에서 `/login`의 대안입니다. 키체인에 저장된 자격 증명보다 우선합니다. [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 생성합니다. [`/login`](/docs/ko/authentication#authentication-precedence)을 실행하지 않는 한 Claude Code는 세션 전체에서 설정한 토큰을 사용합니다. 만료된 토큰을 교체하려면 새 토큰을 생성하고 다시 시작합니다 |

350| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | v2.1.160에서 제거되어 현재는 아무 동작도 하지 않습니다. 이전에는 현재 기본값 대신 [빠른 모드](/docs/ko/fast-mode)를 Claude Opus 4.6으로 고정했습니다. Opus 4.6은 더 이상 빠른 모드를 지원하지 않습니다 |355| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | v2.1.160에서 제거되었으며 이제 아무 작업도 하지 않습니다. 이전에는 [빠른 모드](/docs/ko/fast-mode)를 현재 기본값 대신 Claude Opus 4.6으로 고정했습니다. Opus 4.6은 더 이상 빠른 모드를 지원하지 않습니다 |

351| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 콘텐츠를 담는 OpenTelemetry 속성(모델 응답, 도구 콘텐츠, 시스템 프롬프트, 원시 API 본문)의 최대 길이로, 잘림 표시를 포함하며 UTF-16 코드 단위로 측정합니다(기본값: 61440, 즉 60 KB). 텔레메트리 백엔드가 64 KB보다 큰 속성 값을 허용하는 경우에만 값을 높이고, 텔레메트리 양을 줄이려면 값을 낮춥니다. Claude Code v2.1.214 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |356| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 콘텐츠를 담는 OpenTelemetry 속성(모델 응답, 도구 콘텐츠, 시스템 프롬프트, 원시 API 본문)의 최대 길이로, 잘림 표시를 포함하며 UTF-16 코드 단위로 계산합니다(기본값: 61440, 즉 60 KB). 텔레메트리 백엔드가 64 KB보다 큰 속성 값을 허용하는 경우에만 늘리고, 텔레메트리 양을 줄이려면 낮춥니다. Claude Code v2.1.214 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

352| `CLAUDE_CODE_OTEL_DIAG_STDERR` | `1`로 설정하면 OpenTelemetry 익스포터의 진단 오류를 stderr에 기록합니다. 기본적으로 이러한 오류는 `--debug`에서만 표시되므로, Prometheus 포트 충돌처럼 잘못 구성된 익스포터는 조용히 실패합니다. Claude Code v2.1.179 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |357| `CLAUDE_CODE_OTEL_DIAG_STDERR` | OpenTelemetry 익스포터 진단 오류를 stderr에 쓰려면 `1`로 설정합니다. 기본적으로 이러한 오류는 `--debug`에서만 표시되므로, 그렇지 않으면 Prometheus 포트 충돌과 같이 잘못 구성된 익스포터가 조용히 실패합니다. Claude Code v2.1.179 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

353| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 보류 중인 OpenTelemetry 스팬을 플러시하는 타임아웃(밀리초)입니다(기본값: 5000). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |358| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 보류 중인 OpenTelemetry 스팬을 플러시하는 타임아웃(밀리초)입니다(기본값: 5000). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

354| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 동적 OpenTelemetry 헤더를 새로 고치는 간격(밀리초)입니다(기본값: 1740000 / 29분). [동적 헤더](/docs/ko/monitoring-usage#dynamic-headers)를 참조하세요 |359| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 동적 OpenTelemetry 헤더를 새로 고치는 간격(밀리초)입니다(기본값: 1740000 / 29분). [동적 헤더](/docs/ko/monitoring-usage#dynamic-headers)를 참조하세요 |

355| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | 종료 시 OpenTelemetry 익스포터가 완료되기까지의 타임아웃(밀리초)입니다(기본값: 2000). 종료 시 메트릭이 누락되면 값을 늘립니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |360| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | 종료 시 OpenTelemetry 익스포터가 완료되기까지의 타임아웃(밀리초)입니다(기본값: 2000). 종료 시 메트릭이 누락되면 값을 늘립니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

356| `CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS` | API가 `529` 과부하 오류로 거부한 요청의 [자동 재시도](/docs/ko/errors#tune-retry-behavior) 사이 지수 백오프의 시작 지연 시간(밀리초)으로, 기본값 500을 대신합니다. API 용량이 가득 찬 경우 재시도를 더 긴 기간에 걸쳐 분산하려면 값을 높입니다. 500에서 32000 사이의 정수 밀리초 값을 숫자로만 지정합니다. Claude Code는 그 외의 값을 설정되지 않은 것으로 간주합니다. `CLAUDE_CODE_RETRY_WATCHDOG`가 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](/docs/ko/fast-mode#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.292 이상이 필요합니다 |361| `CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS` | API가 `529` overloaded 오류로 거부한 요청의 [자동 재시도](/docs/ko/errors#tune-retry-behavior) 사이에 적용되는 지수 백오프의 시작 지연 시간(밀리초)으로, 기본값 500을 대체합니다. API가 용량에 도달했을 때 재시도를 더 긴 기간에 걸쳐 분산하려면 값을 늘립니다. 500부터 32000까지의 정수 밀리초를 숫자로만 지정하며, Claude Code는 그 밖의 값을 설정되지 않은 것으로 간주합니다. `CLAUDE_CODE_RETRY_WATCHDOG`가 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](/docs/ko/fast-mode#handle-rate-limits)로 전송된 경우에는 아무 효과가 없습니다. Claude Code v2.1.292 이상이 필요합니다 |

357| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | `1`로 설정하면 새 버전이 있을 때 Claude Code가 백그라운드에서 패키지 관리자의 업그레이드 명령을 실행합니다. Homebrew와 WinGet 설치에 적용됩니다. 다른 패키지 관리자는 계속해서 업그레이드 명령을 실행하지 않고 표시만 합니다. [자동 업데이트](/docs/ko/setup#auto-updates)를 참조하세요 |362| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 새 버전을 사용할 수 있을 때 Claude Code가 패키지 관리자의 업그레이드 명령을 백그라운드에서 실행하도록 하려면 `1`로 설정합니다. Homebrew 및 WinGet 설치에 적용됩니다. 다른 패키지 관리자는 계속해서 업그레이드 명령을 실행하지 않고 표시만 합니다. [자동 업데이트](/docs/ko/setup#auto-updates)를 참조하세요 |

358| `CLAUDE_CODE_PERFORCE_MODE` | `1`로 설정하면 Perforce 인식 쓰기 보호를 활성화합니다. 설정하면 대상 파일에 소유자 쓰기 비트가 없는 경우 Edit, Write, NotebookEdit가 `p4 edit <file>` 힌트와 함께 실패합니다. Perforce는 `p4 edit`로 파일을 열 때까지 동기화된 파일에서 이 비트를 해제합니다. 이를 통해 Claude Code가 Perforce 변경 추적을 우회하지 못하게 합니다 |363| `CLAUDE_CODE_PERFORCE_MODE` | Perforce 인식 쓰기 보호를 활성화하려면 `1`로 설정합니다. 설정하면 대상 파일에 소유자 쓰기 비트가 없을 때 Edit, Write, NotebookEdit이 `p4 edit <file>` 힌트와 함께 실패합니다. Perforce는 동기화된 파일에서 `p4 edit`으로 열기 전까지 이 비트를 해제합니다. 이를 통해 Claude Code가 Perforce 변경 추적을 우회하는 것을 방지합니다 |

359| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 플러그인 루트 디렉터리를 재정의합니다. 이름과 달리 캐시 자체가 아닌 상위 디렉터리를 설정합니다. 마켓플레이스와 플러그인 캐시는 이 경로 아래의 하위 디렉터리에 있습니다. 기본값은 `~/.claude/plugins`입니다 |364| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 플러그인 루트 디렉터리를 재정의합니다. 이름과 달리 캐시 자체가 아닌 상위 디렉터리를 설정하며, 마켓플레이스와 플러그인 캐시는 이 경로 아래의 하위 디렉터리에 위치합니다. 기본값은 `~/.claude/plugins`입니다 |

360| `CLAUDE_CODE_PLUGIN_DIRS` | 세션에 로드할 플러그인 디렉터리로, 각각 [`--plugin-dir`](/docs/ko/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 플래그와 같은 방식으로 로드됩니다. 여러 경로는 Unix에서는 `:`, Windows에서는 `;`로 구분합니다. Claude Code는 상대 경로를 건너뛰므로 각 경로는 절대 경로로 지정하거나 `~`로 시작해야 합니다. Claude Code v2.1.280 이상이 필요합니다. [한 세션에 플러그인 로드](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session)를 참조하세요 |365| `CLAUDE_CODE_PLUGIN_DIRS` | 세션에 로드할 플러그인 디렉터리로, 각각 [`--plugin-dir`](/docs/ko/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 플래그와 같은 방식으로 로드됩니다. 여러 경로는 Unix에서는 `:`, Windows에서는 `;`로 구분합니다. Claude Code는 상대 경로를 건너뛰므로 각 경로를 절대 경로로 지정하거나 `~`로 시작합니다. Claude Code v2.1.280 이상이 필요합니다. [한 세션에 플러그인 로드](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session)를 참조하세요 |

361| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | mod의 파일이 변경될 때 Claude Code가 [mod](/docs/ko/plugins/mods/overview)를 다시 로드할지 여부를 제어합니다. 다시 로드는 `--plugin-dir`로 디렉터리에서 로드한 mod에 적용되며, 대화형 세션에서는 기본적으로 켜져 있습니다. 비대화형 세션에서도 켜려면 `1`로, 모든 세션에서 끄려면 `0`으로 설정합니다. Claude Code v2.1.287 이상이 필요합니다. [mod 설정 및 환경 변수](/docs/ko/plugins/mods/reference#settings-and-environment-variables)를 참조하세요 |366| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | [mod](/docs/ko/plugins/mods/overview)의 파일이 변경될 때 Claude Code가 해당 mod를 다시 로드할지 여부를 제어합니다. 다시 로드는 `--plugin-dir`로 디렉터리에서 로드한 mod에 적용되며, 대화형 세션에서는 기본적으로 켜져 있습니다. 비대화형 세션에서도 켜려면 `1`로, 모든 세션에서 끄려면 `0`으로 설정합니다. Claude Code v2.1.287 이상이 필요합니다. [mod 설정 및 환경 변수](/docs/ko/plugins/mods/reference#settings-and-environment-variables)를 참조하세요 |

362| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인 마켓플레이스를 복제하거나 새로 고치는 타임아웃(밀리초)입니다(기본값: 120000). 큰 저장소나 느린 네트워크 연결의 경우 이 값을 늘립니다. [Git clone timed out](/docs/ko/plugins/troubleshooting#git-clone-timed-out-after-120s)을 참조하세요 |367| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인 마켓플레이스를 복제하거나 새로 고치는 타임아웃(밀리초)입니다(기본값: 120000). 큰 저장소나 느린 네트워크 연결에서는 이 값을 늘립니다. [Git clone timed out](/docs/ko/plugins/troubleshooting#git-clone-timed-out-after-120s)을 참조하세요 |

363| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | `1`로 설정하면 마켓플레이스 새로 고침이 원격에 연결하거나 인증하지 못할 때 재복제 시도를 건너뛰고 기존 마켓플레이스 체크아웃을 계속 사용합니다. 재복제도 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](/docs/ko/plugins/troubleshooting#marketplace-updates-keep-failing-offline)를 참조하세요 |368| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 마켓플레이스 새로 고침이 원격에 연결하거나 인증할 수 없을 때 재복제 시도를 건너뛰고 기존 마켓플레이스 체크아웃을 계속 사용하려면 `1`로 설정합니다. 재복제가 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](/docs/ko/plugins/troubleshooting#marketplace-updates-keep-failing-offline)를 참조하세요 |

364| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | `1`로 설정하면 GitHub `owner/repo` 축약형 소스를 SSH 대신 HTTPS로 복제합니다. 플러그인 설치 및 업데이트와 `/plugin marketplace add` 및 `update`에 적용됩니다. CI 러너, 컨테이너 또는 `github.com`용 SSH 키가 구성되지 않은 환경에서 유용합니다 |369| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 약식 소스를 SSH 대신 HTTPS로 복제하려면 `1`로 설정합니다. 플러그인 설치 및 업데이트와 `/plugin marketplace add` 및 `update`에 적용됩니다. CI 러너, 컨테이너 또는 `github.com`용 SSH 키가 구성되지 않은 환경에서 유용합니다 |

365| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉터리 경로로, Unix에서는 `:`, Windows에서는 `;`로 구분합니다. 미리 채워진 플러그인 디렉터리를 컨테이너 이미지에 번들로 포함할 때 사용합니다. Claude Code는 시작 시 이 디렉터리에서 마켓플레이스를 등록하고, 미리 캐시된 플러그인을 재복제하지 않고 사용합니다. [컨테이너용 플러그인 미리 채우기](/docs/ko/plugins/org#seed-containers-and-ci)를 참조하세요 |370| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉터리 경로로, Unix에서는 `:`, Windows에서는 `;`로 구분합니다. 미리 채워진 플러그인 디렉터리를 컨테이너 이미지에 번들로 포함할 때 사용합니다. Claude Code는 시작 시 이 디렉터리에서 마켓플레이스를 등록하고 재복제 없이 미리 캐시된 플러그인을 사용합니다. [컨테이너용 플러그인 미리 채우기](/docs/ko/plugins/org#seed-containers-and-ci)를 참조하세요 |

366| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | `1`로 설정하면 도구 호출, 훅, 상태줄 명령을 위해 PowerShell을 생성할 때 Claude Code가 `-ExecutionPolicy Bypass`를 전달하지 않고, 대신 머신의 유효 실행 정책을 따릅니다. 기본적으로 Claude Code는 기본값이 Restricted인 Windows 설치에서도 `.ps1` 스크립트와 모듈 가져오기가 동작하도록 프로세스 범위에서 실행 정책을 우회합니다. 프로세스 범위 우회는 이 설정과 관계없이 그룹 정책 `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않습니다 |371| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 도구 호출, 훅, 상태줄 명령을 위해 PowerShell을 생성할 때 Claude Code가 `-ExecutionPolicy Bypass`를 전달하지 않고 대신 머신의 유효 실행 정책을 따르도록 하려면 `1`로 설정합니다. 기본적으로 Claude Code는 기본값이 Restricted인 Windows 설치에서 `.ps1` 스크립트와 모듈 가져오기가 작동하도록 프로세스 범위에서 실행 정책을 우회합니다. 프로세스 범위 우회는 이 설정과 관계없이 그룹 정책 `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않습니다 |

367| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless#background-tasks-at-exit)에서 마지막 턴 이후 서브에이전트와 워크플로 같은 백그라운드 작업을 유휴 상태로 기다리는 시간의 상한(밀리초)입니다. Claude가 백그라운드 결과를 처리하기 위해 턴을 진행할 때마다 유휴 대기가 다시 시작됩니다. 기본값: `600000`, 즉 10분. 유휴 대기가 상한에 도달하면 Claude Code는 남은 백그라운드 작업을 더 이상 기다리지 않습니다. 메인 대화가 시작한 실행 중인 백그라운드 명령은 상한을 넘어서도 실행을 유지합니다. 무기한 기다리려면 `0`으로 설정합니다. Claude Code v2.1.182 이상이 필요합니다 |372| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless#background-tasks-at-exit)에서 마지막 턴 이후 서브에이전트, 워크플로 등 백그라운드 작업을 유휴 상태로 기다리는 시간의 상한(밀리초)입니다. Claude가 백그라운드 결과를 처리하기 위해 턴을 진행할 때마다 유휴 대기가 다시 시작됩니다. 기본값: `600000`, 즉 10분입니다. 유휴 대기가 상한에 도달하면 Claude Code는 남은 백그라운드 작업을 더 이상 기다리지 않습니다. 메인 대화가 시작한 백그라운드 명령이 실행 중이면 상한을 넘어서도 실행이 유지됩니다. 무기한 기다리려면 `0`으로 설정합니다. Claude Code v2.1.182 이상이 필요합니다 |

368| `CLAUDE_CODE_PROCESS_WRAPPER` | [에이전트 뷰](/docs/ko/agent-view) 세션을 호스팅하는 백그라운드 서비스처럼 Claude Code가 자체 바이너리에서 시작하는 프로세스를 `/opt/corp/launcher`와 같은 argv 접두사로 지정한 회사 런처를 통해 실행합니다. 분리된 백그라운드 서비스가 상속할 수 있도록 셸 export가 아닌 사용자 설정 또는 [관리형 설정](/docs/ko/managed-settings)의 `env` 블록에서 설정합니다. 프로젝트 및 로컬 설정에서는 설정할 수 없습니다. Claude Code v2.1.210 이상이 필요한 [`processWrapper` 설정](/docs/ko/settings-reference#processwrapper)과 동일하며, 둘 다 설정된 경우 이 변수가 우선합니다. VS Code 확장은 자체 `claudeProcessWrapper` 설정을 통해 별도로 런처를 구성합니다. Windows에서는 무시됩니다. 값 형식, 런처가 적용되는 범위, 런처가 충족해야 하는 계약은 [회사 런처 뒤에서 Claude Code 실행](/docs/ko/corporate-launcher)을 참조하세요. Claude Code v2.1.208 이상이 필요합니다 |373| `CLAUDE_CODE_PROCESS_WRAPPER` | [에이전트 뷰](/docs/ko/agent-view) 세션을 호스팅하는 백그라운드 서비스처럼 Claude Code가 자체 바이너리에서 시작하는 프로세스를, `/opt/corp/launcher`와 같은 argv 접두사로 지정한 기업용 런처를 통해 실행합니다. 분리된 백그라운드 서비스가 상속할 수 있도록 셸 export가 아닌 사용자 또는 [관리형 설정](/docs/ko/managed-settings)의 `env` 블록에서 설정합니다. 프로젝트 및 로컬 설정으로는 설정할 수 없습니다. Claude Code v2.1.210 이상이 필요한 [`processWrapper` 설정](/docs/ko/settings-reference#processwrapper)과 같으며, 둘 다 설정된 경우 이 변수가 우선합니다. VS Code 확장은 자체 `claudeProcessWrapper` 설정을 통해 별도로 런처를 구성합니다. Windows에서는 무시됩니다. 값 형식, 런처가 적용되는 범위, 런처가 충족해야 하는 조건은 [기업용 런처 뒤에서 Claude Code 실행](/docs/ko/corporate-launcher)을 참조하세요. Claude Code v2.1.208 이상이 필요합니다 |

369| `CLAUDE_CODE_PROJECT_DIR_NAME` | `CLAUDE_CONFIG_DIR`과 함께 설정하면 작업 디렉터리 경로에서 파생된 이름 대신, Claude Code가 해당 세션의 트랜스크립트와 자동 메모리를 저장할 `projects/` 디렉터리 이름을 선택합니다. 예를 들어 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude`로 Claude Code를 시작하면 `/srv/tenant-a/projects/work/` 아래에 저장됩니다. `CLAUDE_CONFIG_DIR`이 설정되지 않은 경우 Claude Code는 이 변수를 무시하며, `claude`를 시작한 환경에서만 읽고 [설정 파일 `env` 블록](#in-settings-files)에서는 읽지 않습니다. [프로젝트 디렉터리 이름 직접 지정](/docs/ko/sessions#name-the-project-directory-yourself)을 참조하세요. Claude Code v2.1.234 이상이 필요합니다 |374| `CLAUDE_CODE_PROJECT_DIR_NAME` | `CLAUDE_CONFIG_DIR`과 함께 설정하여, 작업 디렉터리 경로에서 파생된 이름 대신 Claude Code가 해당 세션의 트랜스크립트와 자동 메모리를 저장할 `projects/` 디렉터리 이름을 선택합니다. 예를 들어 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude`로 Claude Code를 시작하면 `/srv/tenant-a/projects/work/` 아래에 저장됩니다. `CLAUDE_CONFIG_DIR`이 설정되지 않은 경우 Claude Code는 이 변수를 무시하며, `claude`를 시작하는 환경에서만 읽고 [설정 파일의 `env` 블록](#in-settings-files)에서는 절대 읽지 않습니다. [프로젝트 디렉터리 이름 직접 지정](/docs/ko/sessions#name-the-project-directory-yourself)을 참조하세요. Claude Code v2.1.234 이상이 필요합니다 |

370| `CLAUDE_CODE_PROMPT_CACHE_TTL` | Claude Code가 허용하는 유일한 값인 `5m` 또는 `1h`로 설정하여 메인 대화의 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다. 메인 대화에는 대화형, `-p`, SDK 턴과 이와 함께 인라인으로 실행되는 도우미가 포함됩니다. `promptCacheTtl` 설정과 `ENABLE_PROMPT_CACHING_1H`보다 우선하며, `FORCE_PROMPT_CACHING_5M`이 이 값을 재정의합니다. API는 1시간 캐시 쓰기에 더 높은 요율을 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |375| `CLAUDE_CODE_PROMPT_CACHE_TTL` | Claude Code가 허용하는 유일한 값인 `5m` 또는 `1h`로 설정하여 메인 대화의 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다. 메인 대화에는 대화형, `-p`, SDK 턴과 이와 함께 인라인으로 실행되는 헬퍼가 포함됩니다. `promptCacheTtl` 설정과 `ENABLE_PROMPT_CACHING_1H`보다 우선하며, `FORCE_PROMPT_CACHING_5M`이 이 변수를 재정의합니다. API는 1시간 캐시 쓰기에 더 높은 요금을 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |

371| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | `ANTHROPIC_BASE_URL`이 사용자 지정 프록시를 가리킬 때 `1`로 설정하면 W3C 트레이스 컨텍스트를 전파합니다. 전파 대상은 모델 및 HTTP MCP 요청의 `traceparent` 헤더와 Bash, PowerShell, 훅 하위 프로세스의 `TRACEPARENT` 환경 변수입니다. 기본적으로 전파는 Anthropic API에 직접 연결된 경우에만 활성화됩니다. v2.1.152에서 추가되었습니다. [트레이스(베타)](/docs/ko/monitoring-usage#traces-beta)를 참조하세요 |376| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | `ANTHROPIC_BASE_URL`이 사용자 지정 프록시를 가리킬 때 W3C 트레이스 컨텍스트를 전파하려면 `1`로 설정합니다. 전파 대상은 모델 및 HTTP MCP 요청의 `traceparent` 헤더와 Bash, PowerShell, 훅 하위 프로세스의 `TRACEPARENT` 환경 변수입니다. 기본적으로 Anthropic API에 직접 연결된 경우에만 전파가 활성화됩니다. v2.1.152에서 추가되었습니다. [트레이스(베타)](/docs/ko/monitoring-usage#traces-beta)를 참조하세요 |

372| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Claude Code를 내장하고 이를 대신해 모델 공급자 라우팅을 관리하는 호스트 플랫폼이 설정합니다. 설정되면 Claude Code는 설정 파일의 `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY` 같은 공급자 선택, 엔드포인트, 인증 변수를 무시하므로 사용자 설정이 호스트의 라우팅을 재정의할 수 없습니다. 또한 Claude Code는 [관리형 설정](/docs/ko/managed-settings)의 `model`, `fallbackModel`, `modelOverrides` 같은 모델 선택 키를 어떤 관리형 소스가 전달하든 무시하므로, 호스트의 모델 구성이 오래된 관리형 모델 고정보다 우선합니다. 또한 Claude Code는 관리형 `env` 블록의 `ANTHROPIC_MODEL` 및 `ANTHROPIC_DEFAULT_*_MODEL` 계열 같은 모델 선택 변수도 무시합니다. 관리형 설정의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록은 호스트가 자체 목록을 제공하지 않는 한 계속 적용됩니다. 또한 Claude Code는 Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, Microsoft Foundry 같은 타사 공급자에서 적용하던 자동 텔레메트리 옵트아웃을 건너뛰므로, 텔레메트리는 표준 `DISABLE_TELEMETRY` 옵트아웃을 따릅니다. [API 공급자별 기본 동작](/docs/ko/data-usage#default-behaviors-by-api-provider)을 참조하세요 |377| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Claude Code를 내장하고 모델 제공업체 라우팅을 대신 관리하는 호스트 플랫폼이 설정합니다. 설정하면 Claude Code는 설정 파일의 `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY` 등 제공업체 선택, 엔드포인트, 인증 변수를 무시하므로 사용자 설정이 호스트의 라우팅을 재정의할 수 없습니다. Claude Code는 또한 어떤 관리형 소스가 전달하든 [관리형 설정](/docs/ko/managed-settings)의 `model`, `fallbackModel`, `modelOverrides` 등 모델 선택 키를 무시하므로, 호스트의 모델 구성이 오래된 관리형 모델 고정보다 우선합니다. Claude Code는 또한 관리형 `env` 블록의 `ANTHROPIC_MODEL` 및 `ANTHROPIC_DEFAULT_*_MODEL` 계열 등 모델 선택 변수를 무시합니다. 관리형 설정의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록은 호스트가 자체 목록을 제공하지 않는 한 계속 적용됩니다. Claude Code는 또한 Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, Microsoft Foundry 등 타사 제공업체에서 적용하던 자동 텔레메트리 옵트아웃을 건너뛰므로, 텔레메트리는 표준 `DISABLE_TELEMETRY` 옵트아웃을 따릅니다. [API 제공업체별 기본 동작](/docs/ko/data-usage#default-behaviors-by-api-provider)을 참조하세요 |

373| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | `1`로 설정하면 호출자 대신 프록시가 DNS 확인을 수행하도록 허용합니다. 프록시가 호스트 이름 확인을 처리해야 하는 환경을 위한 옵트인 설정입니다 |378| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 호출자 대신 프록시가 DNS 확인을 수행하도록 허용하려면 `1`로 설정합니다. 프록시가 호스트 이름 확인을 처리해야 하는 환경을 위한 옵트인 설정입니다 |

374| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/docs/ko/claude-code-on-the-web)으로 실행될 때 자동으로 `true`로 설정됩니다. 훅이나 설정 스크립트에서 이 값을 읽어 클라우드 세션 여부를 감지합니다 |379| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/docs/ko/claude-code-on-the-web)으로 실행될 때 자동으로 `true`로 설정됩니다. 훅이나 설정 스크립트에서 이 값을 읽어 클라우드 세션인지 감지합니다 |

375| `CLAUDE_CODE_REMOTE_SESSION_ID` | [클라우드 세션](/docs/ko/claude-code-on-the-web)에서 현재 세션의 ID로 자동 설정됩니다. 세션 트랜스크립트로 돌아가는 링크를 구성할 때 이 값을 읽습니다. [출력을 세션에 다시 연결](/docs/ko/cloud-environments#link-output-back-to-the-session)을 참조하세요 |380| `CLAUDE_CODE_REMOTE_SESSION_ID` | [클라우드 세션](/docs/ko/claude-code-on-the-web)에서 현재 세션의 ID로 자동 설정됩니다. 세션 트랜스크립트로 돌아가는 링크를 구성할 때 읽습니다. [출력을 세션에 다시 연결](/docs/ko/cloud-environments#link-output-back-to-the-session)을 참조하세요 |

376| `CLAUDE_CODE_RESTRICTED` | `1`로 설정하면 [`--restricted`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 마찬가지로 제한 모드로 세션을 시작합니다. Claude Code는 설정 파일의 `env` 블록에 있는 이 변수를 무시합니다. Claude Code v2.1.248 이상이 필요합니다 |381| `CLAUDE_CODE_RESTRICTED` | [`--restricted`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 같이 제한 모드로 세션을 시작하려면 `1`로 설정합니다. Claude Code는 설정 파일의 `env` 블록에서 이 변수를 무시합니다. Claude Code v2.1.248 이상이 필요합니다 |

377| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | `1`로 설정하면 이전 세션이 턴 도중에 종료된 경우 자동으로 재개합니다. SDK 모드에서 SDK가 프롬프트를 다시 보내지 않아도 모델이 계속 진행하도록 사용됩니다. 끄려면 변수를 설정 해제하거나 `0`으로 설정합니다. VS Code 채팅 패널의 경우 [다시 로드 후 대화 계속하기](/docs/ko/vs-code#continue-conversations-after-a-reload)를 참조하세요 |382| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 이전 세션이 턴 도중에 종료된 경우 자동으로 재개하려면 `1`로 설정합니다. SDK 모드에서 SDK가 프롬프트를 다시 보내지 않아도 모델이 계속 진행하도록 사용됩니다. 끄려면 변수 설정을 해제하거나 `0`으로 설정합니다. VS Code 채팅 패널의 경우 [다시 로드 후 대화 계속하기](/docs/ko/vs-code#continue-conversations-after-a-reload)를 참조하세요 |

378| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 턴 도중 종료된 세션이 재개 시 자동으로 계속되기 위한 마지막 트랜스크립트 메시지의 최대 경과 시간(밀리초)입니다. 마지막 메시지가 이 기준보다 오래된 경우 Claude Code는 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 자동 재개와 `CLAUDE_CODE_RESUME_PROMPT` 계속 메시지를 건너뛰고, 세션이 유휴 상태로 시작되므로 사용자가 명시적으로 계속해야 합니다. 설정하지 않거나 `0`이면 제한이 없습니다. 단, 마지막 요청이 API 오류로 실패한 턴은 해당 오류가 발생한 지 6시간이 지나지 않은 경우에만 재개됩니다. 양수 값은 이러한 턴을 포함해 모든 턴을 제한하며, 음수 또는 숫자가 아닌 값은 1시간 제한을 적용합니다. 장기 실행 에이전트의 생성 스크립트에서 이 값을 설정하면 오래된 트랜스크립트로 다시 시작할 때 오래된 프롬프트가 다시 실행되지 않습니다. Claude Code는 대화형 세션에서 대화를 상속한 [에이전트 뷰](/docs/ko/agent-view) 세션이 충돌 후 다시 시작될 때 자체적으로 1시간 제한을 설정합니다. Claude Code v2.1.211 이상이 필요합니다 |383| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 턴 도중에 종료된 세션이 재개 시 자동으로 계속되기 위한 마지막 트랜스크립트 메시지의 최대 경과 시간(밀리초)입니다. 마지막 메시지가 이 한계보다 오래되면 Claude Code는 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 자동 재개와 `CLAUDE_CODE_RESUME_PROMPT` 계속 메시지를 건너뛰며, 세션이 유휴 상태로 시작되어 사용자가 명시적으로 계속해야 합니다. 설정하지 않거나 `0`이면 한계가 없습니다. 단, 마지막 요청이 API 오류로 실패한 턴은 해당 오류가 6시간이 지나지 않은 경우에만 재개됩니다. 양수 값은 이러한 턴을 포함한 모든 턴에 한계를 적용하며, 음수나 숫자가 아닌 값은 1시간 한계를 적용합니다. 장기 실행 에이전트의 생성 스크립트는 이 변수를 설정하여 오래된 트랜스크립트로 다시 시작할 때 오래된 프롬프트가 다시 실행되지 않도록 할 수 있습니다. 대화형 세션에서 대화를 상속한 [에이전트 뷰](/docs/ko/agent-view) 세션이 충돌하여 다시 시작할 때는 Claude Code가 직접 1시간 한계를 설정합니다. Claude Code v2.1.211 이상이 필요합니다 |

379| `CLAUDE_CODE_RESUME_PROMPT` | `CLAUDE_CODE_RESUME_INTERRUPTED_TURN`이 프롬프트를 다시 보내는 대신 중단된 턴을 계속할 때, 또는 `-p`로 [지연된 도구 호출](/docs/ko/hooks#defer-a-tool-call-for-later)을 재개할 때 Claude Code가 Claude에게 보내는 계속 메시지를 재정의합니다. 기본값은 `Continue from where you left off.`입니다. 빈 문자열은 기본값을 사용합니다 |384| `CLAUDE_CODE_RESUME_PROMPT` | `CLAUDE_CODE_RESUME_INTERRUPTED_TURN`이 중단된 턴을 프롬프트를 다시 보내는 대신 계속할 때, 또는 `-p`로 [지연된 도구 호출](/docs/ko/hooks#defer-a-tool-call-for-later)을 재개할 때 Claude Code가 Claude에게 보내는 계속 메시지를 재정의합니다. 기본값은 `Continue from where you left off.`입니다. 빈 문자열은 기본값을 사용합니다 |

380| `CLAUDE_CODE_RETRY_WATCHDOG` | eval 하네스, CI 작업 또는 원격 워커 같은 무인 세션에서는 `1`로 설정합니다. `CLAUDE_CODE_MAX_RETRIES`회 시도 후 실패하는 대신 `429` 및 `529` 용량 오류를 무기한 재시도합니다. 표준 속도 요청이 지출 한도나 소진된 사용량 크레딧을 보고하는 `429`를 받으면, 일정에 따라 재설정되는 [게이트웨이 지출 상한](/docs/ko/errors#spend-limit-reached)에서 온 것이더라도 Claude Code는 즉시 실패합니다. v2.1.239 이전에는 워치독이 이러한 오류를 무기한 재시도했습니다. 빠른 모드 요청의 경우 [속도 제한 처리](/docs/ko/fast-mode#handle-rate-limits)를 참조하세요. 워치독은 시도 사이에 최대 5분까지 백오프하며, 응답에 속도 제한 재설정 시간이 포함된 경우에는 한도가 재설정될 때까지 대기하므로 사용 한도에 도달한 세션은 남은 기간이 지날 때까지 기다립니다. v2.1.199 이상에서는 서버 오류, 타임아웃, 연결 끊김 같은 기타 일시적 오류의 기본 재시도 횟수도 약 3시간의 백오프에 해당하는 300으로 높이고, `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정한 경우 15의 상한을 제거합니다. Claude Code v2.1.186 이상이 필요합니다 |385| `CLAUDE_CODE_RETRY_WATCHDOG` | eval 하네스, CI 작업, 원격 워커 등 무인 세션에서는 `1`로 설정합니다. `CLAUDE_CODE_MAX_RETRIES`회 시도 후 실패하는 대신 `429` 및 `529` 용량 오류를 무기한 재시도합니다. 표준 속도 요청이 지출 한도나 소진된 사용량 크레딧을 알리는 `429`를 받으면, 일정에 따라 재설정되는 [게이트웨이 지출 상한](/docs/ko/errors#spend-limit-reached)에서 온 경우라도 Claude Code는 즉시 실패합니다. v2.1.239 이전에는 watchdog이 이러한 오류를 무기한 재시도했습니다. 빠른 모드 요청의 경우 [속도 제한 처리](/docs/ko/fast-mode#handle-rate-limits)를 참조하세요. watchdog은 시도 사이에 최대 5분까지 백오프하거나, 응답에 속도 제한 재설정 시간이 포함된 경우 한도가 재설정될 때까지 대기하므로, 사용 한도에 도달한 세션은 남은 기간 동안 기다립니다. v2.1.199 이상에서는 서버 오류, 타임아웃, 끊긴 연결 등 다른 일시적 오류의 기본 재시도 횟수도 약 3시간의 백오프에 해당하는 300으로 늘리며, `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정한 경우 15라는 상한을 제거합니다. Claude Code v2.1.186 이상이 필요합니다 |

381| `CLAUDE_CODE_SAFE_MODE` | `1`로 설정하면 손상된 구성의 문제 해결을 위해 안전 모드로 시작합니다. 안전 모드에서는 CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 사용자 지정 명령과 에이전트, 출력 스타일, 워크플로, 사용자 지정 테마, 사용자 지정 키보드 단축키, 상태줄 및 파일 제안 명령, LSP 서버, 자동 메모리가 로드되지 않습니다. 정책으로 구성된 훅, 상태줄, 파일 제안 명령을 포함해 관리형 설정 정책은 계속 적용되지만, 관리형 플러그인, 관리형 스킬, 관리형 CLAUDE.md, 정책으로 구성된 MCP 서버는 적용되지 않습니다. [`--safe-mode`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 같습니다. 직접 생성된 자식 프로세스는 이 변수를 상속합니다 |386| `CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS` | `CLAUDE_CODE_RETRY_WATCHDOG`가 설정된 경우 각 API 요청이 `429` 및 `529` 오류를 기다리며 보내는 최대 시간(밀리초)입니다. 이 시간이 지나면 다음 해당 오류에서 요청이 종료됩니다. 30분에 해당하는 `1800000`처럼 숫자로만 된 양의 정수를 지정합니다. 설정하지 않으면 대기 시간에 제한이 없습니다. Claude Code v2.1.295 이상이 필요합니다 |

382| `CLAUDE_CODE_SCRIPT_CAPS` | `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`이 설정된 경우 세션당 특정 스크립트를 호출할 수 있는 횟수를 제한하는 JSON 객체입니다. 키는 명령 텍스트와 비교되는 부분 문자열이고, 값은 정수 호출 제한입니다. 예를 들어 `{"deploy.sh": 2}`는 `deploy.sh`를 최대 두 번까지 호출할 수 있게 합니다. 부분 문자열 기반으로 일치하므로 `./scripts/deploy.sh $(evil)` 같은 셸 확장 기법도 상한에 포함됩니다. `xargs`나 `find -exec`를 통한 런타임 팬아웃은 감지되지 않습니다. 이는 심층 방어 제어입니다 |387| `CLAUDE_CODE_SAFE_MODE` | 손상된 구성의 문제 해결을 위해 안전 모드로 시작하려면 `1`로 설정합니다. 안전 모드에서는 CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 사용자 지정 명령 및 에이전트, 출력 스타일, 워크플로, 사용자 지정 테마, 사용자 지정 키보드 단축키, 상태줄 및 파일 제안 명령, LSP 서버, 자동 메모리가 로드되지 않습니다. 정책으로 구성된 훅, 상태줄, 파일 제안 명령을 포함한 관리형 설정 정책은 계속 적용되지만, 관리형 플러그인, 관리형 스킬, 관리형 CLAUDE.md, 정책으로 구성된 MCP 서버는 적용되지 않습니다. [`--safe-mode`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 같습니다. 직접 생성된 자식 프로세스는 이 변수를 상속합니다 |

383| `CLAUDE_CODE_SCROLL_SPEED` | [전체 화면 렌더링](/docs/ko/fullscreen#mouse-wheel-scrolling)에서 마우스 휠 스크롤 배율을 설정합니다. 최대 20까지의 모든 양수 값을 허용하며, 이미 휠 이벤트를 증폭하는 터미널에서 가속된 트랙패드 및 휠 스크롤을 늦추기 위한 `0.5` 같은 1 미만의 소수 값도 허용합니다. 터미널이 증폭 없이 노치당 하나의 휠 이벤트를 보내는 경우 `vim`과 맞추려면 `3`으로 설정합니다. Claude Code가 자체 스크롤 처리를 사용하는 JetBrains IDE 터미널에서는 무시됩니다 |388| `CLAUDE_CODE_SCRIPT_CAPS` | `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`이 설정된 경우 특정 스크립트를 세션당 호출할 수 있는 횟수를 제한하는 JSON 객체입니다. 키는 명령 텍스트와 대조되는 부분 문자열이고, 값은 정수 호출 제한입니다. 예를 들어 `{"deploy.sh": 2}`는 `deploy.sh`를 최대 두 번까지 호출할 수 있도록 허용합니다. 부분 문자열 기반으로 일치시키므로 `./scripts/deploy.sh $(evil)`과 같은 셸 확장 기법도 상한에 포함됩니다. `xargs`나 `find -exec`를 통한 런타임 팬아웃은 감지되지 않으며, 이는 심층 방어 제어입니다 |

384| `CLAUDE_CODE_SEND_FEEDBACK` | `0`으로 설정하면 세션에서 [Claude가 작성하는 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior)을 끕니다. 계정에 이미 액세스 권한이 있는 경우 `1`로 설정하면 켭니다. 이 변수 자체로는 액세스 권한을 부여할 수 없으며, `DISABLE_FEEDBACK_COMMAND`와 [`feedbackDrafts`](/docs/ko/settings-reference#feedbackdrafts) 설정의 `off` 값처럼 피드백을 끄는 다른 스위치는 계속 적용됩니다 |389| `CLAUDE_CODE_SCROLL_SPEED` | [전체 화면 렌더링](/docs/ko/fullscreen#mouse-wheel-scrolling)에서 마우스 휠 스크롤 배율을 설정합니다. 이미 휠 이벤트를 증폭하는 터미널에서 가속된 트랙패드 및 휠 스크롤을 늦추기 위한 `0.5`와 같은 1 미만의 소수 값을 포함하여 20 이하의 모든 양수 값을 허용합니다. 터미널이 증폭 없이 휠 눈금당 하나의 휠 이벤트를 보내는 경우 `vim`과 맞추려면 `3`으로 설정합니다. Claude Code가 자체 스크롤 처리를 사용하는 JetBrains IDE 터미널에서는 무시됩니다 |

385| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | [SessionEnd](/docs/ko/hooks#sessionend) 훅의 시간 예산(밀리초)을 재정의합니다. 이 값은 자체 `timeout`을 설정하지 않은 각 훅의 타임아웃이기도 합니다. 세션 종료, `/clear`, 대화형 `/resume`을 통한 세션 전환에 적용됩니다. 기본 예산은 1.5초이며, 설정 파일에 구성된 가장 높은 훅별 `timeout`으로 최대 60초까지 자동으로 늘어납니다. 플러그인이 제공하는 훅의 타임아웃은 예산을 늘리지 않습니다 |390| `CLAUDE_CODE_SEND_FEEDBACK` | 세션에서 [Claude가 작성한 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior)을 끄려면 `0`으로 설정합니다. 계정에 이미 액세스 권한이 있는 경우 켜려면 `1`로 설정합니다. 이 변수로 액세스 권한을 부여할 수는 없으며, `DISABLE_FEEDBACK_COMMAND`와 [`feedbackDrafts`](/docs/ko/settings-reference#feedbackdrafts) 설정의 `off` 값 등 피드백을 끄는 다른 스위치는 계속 적용됩니다 |

391| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | [SessionEnd](/docs/ko/hooks#sessionend) 훅의 시간 예산(밀리초)을 재정의합니다. 이 값은 자체 `timeout`을 설정하지 않은 각 훅의 타임아웃이기도 합니다. 세션 종료, `/clear`, 대화형 `/resume`을 통한 세션 전환에 적용됩니다. 기본 예산은 1.5초이며, 설정 파일에 구성된 가장 높은 훅별 `timeout`으로 최대 60초까지 자동으로 올라갑니다. 플러그인이 제공하는 훅의 타임아웃은 예산을 올리지 않습니다 |

386| `CLAUDE_CODE_SESSION_ID` | Bash 및 PowerShell 도구 하위 프로세스, [훅 명령](/docs/ko/hooks) 하위 프로세스, stdio [MCP 서버](/docs/ko/mcp) 하위 프로세스에서 현재 세션 ID로 자동 설정됩니다. Bash, PowerShell, 훅의 경우 이 값은 훅 JSON 입력의 `session_id` 필드와 일치하며 `/clear` 시 업데이트됩니다. MCP 서버 하위 프로세스는 생성될 때의 ID를 유지합니다. `--resume <session-id>`에서는 재개된 ID를 받아 훅 및 Bash와 일치합니다. 명시적 ID 없이 `--continue` 또는 `--resume`을 사용하면 대신 초기 시작 ID를 받을 수 있습니다. 스크립트와 외부 도구를 이를 실행한 Claude Code 세션과 연관시킬 때 사용합니다 |392| `CLAUDE_CODE_SESSION_ID` | Bash 및 PowerShell 도구 하위 프로세스, [훅 명령](/docs/ko/hooks) 하위 프로세스, stdio [MCP 서버](/docs/ko/mcp) 하위 프로세스에서 현재 세션 ID로 자동 설정됩니다. Bash, PowerShell, 훅의 경우 이 값은 훅 JSON 입력의 `session_id` 필드와 일치하며 `/clear` 시 업데이트됩니다. MCP 서버 하위 프로세스는 생성될 때의 ID를 유지합니다. `--resume <session-id>`에서는 재개된 ID를 받아 훅 및 Bash와 일치합니다. 명시적 ID 없이 `--continue` 또는 `--resume`을 사용하면 대신 초기 시작 ID를 받을 수 있습니다. 스크립트와 외부 도구를 이를 실행한 Claude Code 세션과 연관시킬 때 사용합니다 |

387| `CLAUDE_CODE_SHELL` | Claude Code가 Bash 도구 명령을 실행하는 데 사용하는 셸을 설정합니다. `/opt/homebrew/bin/bash`처럼 `bash` 또는 `zsh` 바이너리 경로를 허용합니다. `fish` 같은 다른 셸은 지원되지 않습니다. 값이 동작하는 `bash` 또는 `zsh` 경로가 아니면 Claude Code는 이를 무시하고 자동 감지로 폴백합니다. 자동 감지는 `$SHELL`이 `bash` 또는 `zsh`를 가리키면 이를 사용하고, 그렇지 않으면 `PATH`와 표준 설치 위치에서 찾은 첫 번째 동작하는 `zsh`, 그다음 `bash`를 선택합니다 |393| `CLAUDE_CODE_SHELL` | Claude Code가 Bash 도구 명령을 실행하는 데 사용하는 셸을 설정합니다. `/opt/homebrew/bin/bash`처럼 `bash` 또는 `zsh` 바이너리의 경로를 허용합니다. `fish` 등 다른 셸은 지원되지 않습니다. 값이 작동하는 `bash` 또는 `zsh` 경로가 아니면 Claude Code는 이를 무시하고 자동 감지로 폴백합니다. 자동 감지는 `$SHELL`이 `bash` 또는 `zsh`를 가리키면 이를 사용하고, 그렇지 않으면 `PATH`와 표준 설치 위치에서 처음 발견되는 작동하는 `zsh`, 그다음 `bash`를 선택합니다 |

388| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 셸 명령을 감싸는 명령 접두사입니다. 대상은 Bash 도구 호출, [훅](/docs/ko/hooks) 명령, [상태줄](/docs/ko/statusline) 명령, stdio [MCP 서버](/docs/ko/mcp) 시작 명령입니다. PowerShell 훅과 exec 형식 훅은 접두사 없이 실행됩니다. 로깅이나 감사에 유용합니다. `/path/to/logger.sh` 같은 실행 파일 경로만 설정하면 각 명령이 `/path/to/logger.sh '<command>'`로 실행됩니다. 래퍼는 명령줄을 `$1`에 셸 인용된 단일 인수로 받으므로, 래퍼는 `exec bash -c "$1"`처럼 셸로 `$1`을 다시 평가해야 합니다. `$1`을 단순 실행 파일 경로로 취급하면 `npx -y <package>`처럼 인수를 전달하는 stdio MCP 서버가 동작하지 않습니다. Bash 도구 호출의 경우 `$1`에는 Claude가 실행한 명령뿐 아니라 환경 설정을 포함해 Claude Code가 조합한 전체 셸 호출이 들어 있습니다 |394| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 셸 명령, 즉 Bash 도구 호출, [훅](/docs/ko/hooks) 명령, [상태줄](/docs/ko/statusline) 명령, stdio [MCP 서버](/docs/ko/mcp) 시작 명령을 감싸는 명령 접두사입니다. PowerShell 훅과 exec 형식 훅은 접두사 없이 실행됩니다. 로깅이나 감사에 유용합니다. `/path/to/logger.sh`와 같은 실행 파일 경로만 설정하면 각 명령이 `/path/to/logger.sh '<command>'`로 실행됩니다. 래퍼는 명령줄을 `$1`에 셸 인용된 단일 인수로 받으므로, 래퍼는 `exec bash -c "$1"`처럼 셸로 `$1`을 다시 평가해야 합니다. `$1`을 실행 파일 경로로만 취급하면 `npx -y <package>`와 같은 인수를 전달하는 stdio MCP 서버가 작동하지 않습니다. Bash 도구 호출의 경우 `$1`에는 Claude가 실행한 명령만이 아니라 환경 설정을 포함하여 Claude Code가 조합한 전체 셸 호출이 들어 있습니다 |

389| `CLAUDE_CODE_SIMPLE` | `1`로 설정하면 최소한의 시스템 프롬프트와 Bash, 파일 읽기, 파일 편집 도구만으로 실행합니다. `--mcp-config`의 MCP 도구는 계속 사용할 수 있습니다. 훅, 스킬, 사용자 지정 명령, 서브에이전트, 설치된 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. `--add-dir`로 전달한 디렉터리의 스킬은 계속 로드됩니다. OAuth 토큰과 키체인 자격 증명을 읽지 않으므로 Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`의 `apiKeyHelper`에서 제공되어야 합니다. [`--bare`](/docs/ko/headless#start-faster-with-bare-mode)를 전달하는 것과 같습니다 |395| `CLAUDE_CODE_SIMPLE` | 최소한의 시스템 프롬프트와 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정합니다. `--mcp-config`의 MCP 도구는 계속 사용할 수 있습니다. 훅, 스킬, 사용자 지정 명령, 서브에이전트, 설치된 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. `--add-dir`로 전달한 디렉터리의 스킬은 계속 로드됩니다. OAuth 토큰과 키체인 자격 증명을 읽지 않으므로, Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`의 `apiKeyHelper`에서 제공되어야 합니다. [`--bare`](/docs/ko/headless#start-faster-with-bare-mode)를 전달하는 것과 같습니다 |

390| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | Claude Code의 전체 시스템 프롬프트와 도구 설명이 축약된 더 짧은 프롬프트 중에서 선택합니다. 설정하지 않으면 Haiku 4.5, Sonnet 5, Opus 4.7 및 해당 제품군의 이전 모델은 기본적으로 전체 프롬프트를 사용하고, 더 새로운 모델은 짧은 프롬프트를 사용합니다. 모든 모델에서 짧은 프롬프트를 사용하려면 `1`로 설정합니다. 실험이나 서버 구성이 짧은 프롬프트를 선택하는 경우에도 모든 모델에서 전체 프롬프트를 사용하려면 `0`, `false`, `no` 또는 `off`로 설정합니다. 어느 프롬프트든 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색을 유지합니다 |396| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | Claude Code의 전체 시스템 프롬프트와 도구 설명이 축약된 더 짧은 시스템 프롬프트 중에서 선택합니다. 설정하지 않으면 Haiku 4.5, Sonnet 5, Opus 4.7과 해당 제품군의 이전 모델은 기본적으로 전체 프롬프트를 사용하고, 더 새로운 모델은 짧은 프롬프트를 사용합니다. 모든 모델에서 짧은 프롬프트를 사용하려면 `1`로 설정합니다. 실험이나 서버 구성이 짧은 프롬프트를 선택하는 경우에도 모든 모델에서 전체 프롬프트를 사용하려면 `0`, `false`, `no` 또는 `off`로 설정합니다. 어느 프롬프트든 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색을 유지합니다 |

391| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 요청에 직접 서명하는 게이트웨이를 위해 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)의 클라이언트 측 인증을 건너뜁니다 |397| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 요청에 직접 서명하는 게이트웨이를 위해 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)의 클라이언트 측 인증을 건너뜁니다 |

392| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | `1`로 설정하면 AWS 기본 자격 증명 공급자 체인에서 확인한 자격 증명의 프로세스 내 캐시를 끄므로, Claude Code가 모든 API 요청마다 체인을 확인합니다. 캐시를 끄면 SSO 기반 프로필은 모든 요청마다 IAM Identity Center에 자격 증명을 요청합니다. [자격 증명 캐싱 및 확인 타임아웃](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout)을 참조하세요. Claude Code v2.1.207 이상이 필요합니다 |398| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | AWS 기본 자격 증명 공급자 체인에서 확인된 자격 증명의 인프로세스 캐시를 끄려면 `1`로 설정합니다. 그러면 Claude Code는 모든 API 요청마다 체인을 확인합니다. 캐시가 꺼져 있으면 SSO 기반 프로필은 모든 요청마다 IAM Identity Center에 자격 증명을 요청합니다. [자격 증명 캐싱 및 확인 타임아웃](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout)을 참조하세요. Claude Code v2.1.207 이상이 필요합니다 |

394| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | `1`로 설정하면 `api.anthropic.com`으로의 직접 요청을 차단하는 네트워크에서 실패한 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 가용성 확인을 사용 가능으로 처리합니다. Claude Code는 "disabled by your organization" 응답은 계속 따릅니다 |400| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 확인 작업의 `api.anthropic.com` 직접 요청을 차단하는 네트워크를 위해, 실패한 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 사용 가능 여부 확인을 사용 가능으로 처리하려면 `1`로 설정합니다. Claude Code는 "disabled by your organization" 응답은 계속 따릅니다 |

395| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | `1`로 설정하면 확인 요청을 거부하지 않고 가로채는 프록시를 위해 클라이언트 측 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 가용성 확인을 건너뜁니다. 조직에서 빠른 모드를 비활성화한 경우 API는 여전히 빠른 모드 요청을 거부합니다 |401| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 확인 요청을 거부하지 않고 가로채는 프록시를 위해 클라이언트 측 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 사용 가능 여부 확인을 건너뛰려면 `1`로 설정합니다. 조직에서 빠른 모드를 비활성화한 경우 API는 여전히 빠른 모드 요청을 거부합니다 |

396| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 자체 `Authorization` 헤더를 주입하는 프록시나 게이트웨이를 위해 Microsoft Foundry의 Azure 인증을 건너뜁니다. Claude Code는 Azure 자격 증명 없이 요청을 보내며, 예를 들어 `ANTHROPIC_CUSTOM_HEADERS`를 통해 제공한 `Authorization` 헤더를 유지합니다. `ANTHROPIC_FOUNDRY_API_KEY` 또는 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`이 설정된 경우 무시됩니다. v2.1.203 이전에는 API 키도 함께 설정하지 않으면 이 변수로 인해 Microsoft Foundry 클라이언트가 요청을 보낼 수 없었습니다 |402| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 자체 `Authorization` 헤더를 삽입하는 프록시나 게이트웨이를 위해 Microsoft Foundry의 Azure 인증을 건너뜁니다. Claude Code는 Azure 자격 증명 없이 요청을 보내고, 예를 들어 `ANTHROPIC_CUSTOM_HEADERS`를 통해 제공한 `Authorization` 헤더를 유지합니다. `ANTHROPIC_FOUNDRY_API_KEY` 또는 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`이 설정된 경우 무시됩니다. v2.1.203 이전에는 API 키도 함께 설정하지 않으면 이 변수로 인해 Microsoft Foundry 클라이언트가 요청을 보낼 수 없었습니다 |

398| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/ko/amazon-bedrock)과 [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai)의 [시작 시 모델 확인](/docs/ko/amazon-bedrock#startup-model-checks)은 계정이 호출할 수 없는 것으로 확인된 모델을 이 머신에 최대 하루 동안 기억합니다. 이 기억 기능을 끄려면 `1`로 설정합니다. Claude Code v2.1.285 이상이 필요합니다 |404| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/ko/amazon-bedrock)과 [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai)의 [시작 시 모델 확인](/docs/ko/amazon-bedrock#startup-model-checks)은 계정에서 호출할 수 없는 것으로 확인된 모델을 이 머신에 최대 하루 동안 기억합니다. 이 기억 기능을 끄려면 `1`로 설정합니다. Claude Code v2.1.285 이상이 필요합니다 |

399| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | `1`로 설정하면 프롬프트 기록과 세션 트랜스크립트를 디스크에 기록하지 않습니다. 이 변수를 설정한 상태로 시작한 세션은 `--resume`, `--continue` 또는 위쪽 화살표 기록에 나타나지 않습니다. 일회성 스크립트 세션에 유용합니다 |405| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 프롬프트 기록과 세션 트랜스크립트를 디스크에 쓰지 않으려면 `1`로 설정합니다. 이 변수를 설정한 상태로 시작한 세션은 `--resume`, `--continue` 또는 위쪽 화살표 기록에 나타나지 않습니다. 일회성 스크립트 세션에 유용합니다 |

401| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | `1`로 설정하면 `--output-format stream-json`으로 시작한 세션이 stderr 출력만으로 끝나던 시작 실패에 대해 [Claude Code가 시작을 거부한 이유를 명시하는 result 메시지](/docs/ko/agent-sdk/typescript#startup_failure_reason)를 기록합니다. Claude Code v2.1.274 이상이 필요합니다 |407| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | `--output-format stream-json`으로 시작한 세션이, 평소라면 stderr만 남기고 끝나는 시작 실패에 대해 [Claude Code가 시작을 거부한 이유를 명시하는 결과 메시지](/docs/ko/agent-sdk/typescript#startup_failure_reason)를 쓰도록 하려면 `1`로 설정합니다. Claude Code v2.1.274 이상이 필요합니다 |

402| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | Claude Code가 이를 재정의하고 턴을 종료하기 전까지 [Stop](/docs/ko/hooks#stop) 또는 [SubagentStop](/docs/ko/hooks#subagentstop) 훅이 턴 종료를 연속으로 차단할 수 있는 최대 횟수입니다(기본값: 8). 상한을 비활성화하려면 `0`으로 설정합니다. 훅이 해결을 위해 실제로 더 많은 반복이 필요한 경우 값을 높입니다 |408| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/ko/hooks#stop) 또는 [SubagentStop](/docs/ko/hooks#subagentstop) 훅이 턴 종료를 연속으로 차단할 수 있는 최대 횟수로, 이 횟수를 넘으면 Claude Code가 이를 재정의하고 턴을 종료합니다(기본값: 8). 상한을 비활성화하려면 `0`으로 설정합니다. 훅이 해결하는 데 정당하게 더 많은 반복이 필요한 경우 값을 늘립니다 |

403| `CLAUDE_CODE_SUBAGENT_MODEL` | 다른 방식으로 모델이 할당되지 않은 [서브에이전트](/docs/ko/sub-agents#choose-a-model), [에이전트 팀](/docs/ko/agent-teams#specify-teammates-and-models) 팀원, [워크플로](/docs/ko/workflows) 에이전트의 기본 모델입니다. `haiku` 같은 별칭이나 전체 모델 이름을 허용합니다. 두 가지 소스가 이보다 우선합니다. 하나는 Claude가 에이전트를 생성할 때 전달하는 모델이고, 다른 하나는 `inherit`를 포함한 에이전트 정의의 `model` 필드입니다. 이를 변경하려면 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/ko/sub-agents#run-every-subagent-on-one-model)를 설정합니다. 전체 순서는 [모델 선택](/docs/ko/sub-agents#choose-a-model)을 참조하세요. `inherit`로 설정하는 것은 설정하지 않은 것과 같습니다. v2.1.251 이전에는 이 변수가 호출별 모델과 정의의 `model` 필드를 모두 재정의했습니다 |409| `CLAUDE_CODE_SUBAGENT_MODEL` | 다른 방식으로 모델이 지정되지 않은 [서브에이전트](/docs/ko/sub-agents#choose-a-model), [에이전트 팀](/docs/ko/agent-teams#specify-teammates-and-models) 팀원, [워크플로](/docs/ko/workflows) 에이전트의 기본 모델입니다. `haiku`와 같은 별칭이나 전체 모델 이름을 허용합니다. 두 가지 소스가 이보다 우선합니다. 하나는 Claude가 에이전트를 생성할 때 전달하는 모델이고, 다른 하나는 `inherit`를 포함한 에이전트 정의의 `model` 필드입니다. 이를 변경하려면 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/ko/sub-agents#run-every-subagent-on-one-model)를 설정합니다. 전체 순서는 [모델 선택](/docs/ko/sub-agents#choose-a-model)을 참조하세요. `inherit`로 설정하는 것은 설정하지 않는 것과 같습니다. v2.1.251 이전에는 이 변수가 호출별 모델과 정의의 `model` 필드를 모두 재정의했습니다 |

404| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | `1`로 설정하면 서브에이전트, 팀원, 워크플로 에이전트에 하나의 모델을 강제합니다. 어떤 모델인지는 [모든 서브에이전트를 하나의 모델로 실행](/docs/ko/sub-agents#run-every-subagent-on-one-model)에서 설명합니다. Claude Code v2.1.257 이상이 필요합니다 |410| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 서브에이전트, 팀원, 워크플로 에이전트에 하나의 모델을 강제로 적용하려면 `1`로 설정합니다. 어떤 모델인지는 [모든 서브에이전트를 하나의 모델로 실행](/docs/ko/sub-agents#run-every-subagent-on-one-model)에 설명되어 있습니다. Claude Code v2.1.257 이상이 필요합니다 |

405| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | Claude Code가 허용하는 유일한 값인 `5m` 또는 `1h`로 설정하여 [서브에이전트](/docs/ko/sub-agents), 워크플로, 백그라운드 작업처럼 메인 대화 외부의 요청에 대한 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다. `subagentPromptCacheTtl` 설정과 `ENABLE_PROMPT_CACHING_1H`보다 우선하며, `FORCE_PROMPT_CACHING_5M`이 이 값을 재정의합니다. API는 1시간 캐시 쓰기에 더 높은 요율을 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |411| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | Claude Code가 허용하는 유일한 값인 `5m` 또는 `1h`로 설정하여 [서브에이전트](/docs/ko/sub-agents), 워크플로, 백그라운드 작업 등 메인 대화 외부 요청의 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다. `subagentPromptCacheTtl` 설정과 `ENABLE_PROMPT_CACHING_1H`보다 우선하며, `FORCE_PROMPT_CACHING_5M`이 이 변수를 재정의합니다. API는 1시간 캐시 쓰기에 더 높은 요금을 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |

406| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | `1`로 설정하면 Bash 명령, 훅, stdio MCP 서버처럼 Claude Code가 시작하는 하위 프로세스의 환경에서 자격 증명을 제거합니다. 정리 기능은 변수 이름이나 값으로 자격 증명을 인식하며, GitHub 토큰과 프록시 설정은 그대로 둡니다. [하위 프로세스 환경 정리가 제거하는 항목](#what-the-subprocess-environment-scrub-removes)을 참조하세요. `claude-code-action`은 `allowed_non_write_users`가 구성된 경우 이 값을 자동으로 설정합니다 |412| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Bash 명령, 훅, stdio MCP 서버 등 Claude Code가 시작하는 하위 프로세스의 환경에서 자격 증명을 제거하려면 `1`로 설정합니다. 제거 기능은 변수 이름이나 값으로 자격 증명을 인식하며, GitHub 토큰과 프록시 설정은 그대로 둡니다. [하위 프로세스 환경 정리가 제거하는 항목](#what-the-subprocess-environment-scrub-removes)을 참조하세요. `allowed_non_write_users`가 구성되면 `claude-code-action`이 이 변수를 자동으로 설정합니다 |

407| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 비대화형 모드(`-p` 플래그)에서 `1`로 설정하면 첫 번째 쿼리 전에 플러그인 설치가 완료될 때까지 기다립니다. 이 설정이 없으면 플러그인이 백그라운드에서 설치되어 첫 번째 턴에서 사용하지 못할 수 있습니다. 대기 시간을 제한하려면 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS`와 함께 사용합니다 |413| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 비대화형 모드(`-p` 플래그)에서 첫 번째 쿼리 전에 플러그인 설치가 완료될 때까지 기다리려면 `1`로 설정합니다. 이 변수가 없으면 플러그인이 백그라운드에서 설치되어 첫 번째 턴에서 사용할 수 없을 수 있습니다. 대기 시간을 제한하려면 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS`와 함께 사용합니다 |

408| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 동기식 플러그인 설치의 타임아웃(밀리초)입니다. 초과하면 Claude Code는 플러그인 없이 진행하고 오류를 로그에 기록합니다. 기본값은 없으며, 이 변수가 없으면 동기식 설치는 완료될 때까지 기다립니다 |414| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 동기식 플러그인 설치의 타임아웃(밀리초)입니다. 초과하면 Claude Code는 플러그인 없이 진행하고 오류를 로그에 기록합니다. 기본값은 없으며, 이 변수가 없으면 동기식 설치는 완료될 때까지 기다립니다 |

409| `CLAUDE_CODE_SYNC_SKILLS` | `-p` 플래그를 사용하는 비대화형 모드에서 `1`로 설정하면, Claude Code가 첫 번째 쿼리를 실행하기 전에 해당 실행에서 claude.ai 계정에 활성화된 스킬을 다운로드하고 최대 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`까지 스킬 목록을 기다립니다. claude.ai 인증이 필요합니다. claude.ai 계정으로 로그인하는 터미널 세션은 이 변수 없이도 [이러한 스킬을 동기화](/docs/ko/skills#where-synced-skills-load)하므로, `-p` 실행의 첫 번째 쿼리에 현재 스킬이 필요한 경우에만 설정합니다 |415| `CLAUDE_CODE_SYNC_SKILLS` | `-p` 플래그를 사용하는 비대화형 모드에서 `1`로 설정하면, Claude Code가 해당 실행에서 claude.ai 계정에 활성화된 스킬을 다운로드하고 첫 번째 쿼리를 실행하기 전에 최대 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` 동안 스킬 목록을 기다립니다. claude.ai 인증이 필요합니다. claude.ai 계정으로 로그인한 터미널 세션은 이 변수 없이도 [이러한 스킬을 동기화](/docs/ko/skills#where-synced-skills-load)하므로, `-p` 실행의 첫 번째 쿼리에 현재 스킬이 필요한 경우에만 설정합니다 |

410| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | [Agent SDK](/docs/ko/agent-sdk/typescript#query-object) 기반 앱이 스킬을 다시 로드할 때 세션 도중 실행되는 스킬 재동기화의 타임아웃(밀리초)입니다(기본값: 30000). 초과하면 도착한 스킬로 다시 로드를 계속하고, 나머지 다운로드는 백그라운드에서 완료됩니다 |416| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | [Agent SDK](/docs/ko/agent-sdk/typescript#query-object)로 빌드된 앱이 스킬을 다시 로드할 때 세션 도중 실행되는 스킬 재동기화의 타임아웃(밀리초)입니다(기본값: 30000). 초과하면 도착한 스킬로 다시 로드를 계속하며, 나머지 다운로드는 백그라운드에서 완료됩니다 |

411| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | `CLAUDE_CODE_SYNC_SKILLS`가 설정된 경우 첫 번째 쿼리가 초기 스킬 목록을 기다리는 타임아웃(밀리초)입니다(기본값: 5000). 초과하면 첫 번째 쿼리는 도착한 스킬로 실행됩니다. 어느 경우든 다운로드는 백그라운드에서 완료되며, Claude가 스킬을 호출하면 해당 스킬의 다운로드를 기다립니다 |417| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | `CLAUDE_CODE_SYNC_SKILLS`가 설정된 경우 첫 번째 쿼리가 초기 스킬 목록을 기다리는 타임아웃(밀리초)입니다(기본값: 5000). 초과하면 첫 번째 쿼리는 도착한 스킬로 실행됩니다. 어느 쪽이든 다운로드는 백그라운드에서 완료되며, Claude는 스킬을 호출할 때 해당 스킬의 다운로드를 기다립니다 |

412| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | `false`로 설정하면 diff 출력에서 구문 강조를 비활성화합니다. 색상이 터미널 설정과 충돌할 때 유용합니다. 코드 블록과 파일 미리 보기에서도 강조를 비활성화하려면 [`syntaxHighlightingDisabled`](/docs/ko/settings-reference#syntaxhighlightingdisabled) 설정을 사용합니다 |418| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | diff 출력에서 구문 강조를 비활성화하려면 `false`로 설정합니다. 색상이 터미널 설정과 충돌할 때 유용합니다. 코드 블록과 파일 미리보기에서도 강조를 비활성화하려면 [`syntaxHighlightingDisabled`](/docs/ko/settings-reference#syntaxhighlightingdisabled) 설정을 사용합니다 |

413| `CLAUDE_CODE_TASK_LIST_ID` | 세션 간에 작업 목록을 공유합니다. [Task 도구가 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 여러 Claude Code 인스턴스에 같은 ID를 설정하면 공유 작업 목록으로 협업할 수 있습니다. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하세요 |419| `CLAUDE_CODE_TASK_LIST_ID` | 세션 간에 작업 목록을 공유합니다. [Task 도구가 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 여러 Claude Code 인스턴스에 같은 ID를 설정하여 공유 작업 목록으로 협업합니다. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하세요 |

414| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 비대화형 세션이 종료 시 [에이전트 팀](/docs/ko/agent-teams)의 해체가 완료될 때까지 기다리는 시간을 밀리초 단위로 재정의합니다. 1000에서 60000까지 허용합니다. 범위를 벗어난 값은 무시되고 기본값 10000이 적용됩니다. Claude Code v2.1.206 이상이 필요합니다 |420| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 비대화형 세션이 종료 시 [에이전트 팀](/docs/ko/agent-teams)의 해체가 완료될 때까지 기다리는 시간을 밀리초 단위로 재정의합니다. 1000부터 60000까지 허용하며, 범위를 벗어난 값은 무시되고 기본값 10000이 적용됩니다. Claude Code v2.1.206 이상이 필요합니다 |

415| `CLAUDE_CODE_TMPDIR` | 내부 임시 파일에 사용되는 임시 디렉터리를 재정의합니다. Claude Code는 Unix에서는 이 경로에 `/claude-{uid}/`를, Windows에서는 `/claude/`를 추가합니다. 기본값: macOS에서는 `/tmp`, Linux와 Windows에서는 `os.tmpdir()`. macOS와 Linux에서 재정의 값이 긴 경로인 경우, 일부 도구는 임시 경로가 너무 길면 실패하므로 [샌드박스](/docs/ko/sandboxing)된 Bash 하위 프로세스는 시스템 기본값 아래의 짧은 대체 `$TMPDIR`을 받습니다. 샌드박스되지 않은 Bash 명령은 셸의 `$TMPDIR`이 설정되어 있으면 이를 상속합니다. 네이티브 Windows에서 셸이 `$TMPDIR`을 설정하지 않은 경우, `$TMPDIR`을 참조하는 Bash 명령은 재정의 값을 받거나, 재정의 값을 설정하지 않았다면 `%TEMP%`를 받습니다. Claude Code 자체 임시 파일은 항상 재정의 값을 사용합니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |421| `CLAUDE_CODE_TMPDIR` | 내부 임시 파일에 사용되는 임시 디렉터리를 재정의합니다. Claude Code는 Unix에서는 이 경로에 `/claude-{uid}/`를, Windows에서는 `/claude/`를 추가합니다. 기본값: macOS에서는 `/tmp`, Linux와 Windows에서는 `os.tmpdir()`입니다. macOS와 Linux에서 재정의한 경로가 긴 경우, 임시 경로가 너무 길면 일부 도구가 실패하므로 [샌드박스](/docs/ko/sandboxing)된 Bash 하위 프로세스는 시스템 기본값 아래의 짧은 대체 `$TMPDIR`을 받습니다. 샌드박스되지 않은 Bash 명령은 셸의 `$TMPDIR`이 설정되어 있으면 이를 상속합니다. 네이티브 Windows에서 셸이 `$TMPDIR`을 설정하지 않은 경우, `$TMPDIR`을 참조하는 Bash 명령은 재정의한 값을 받거나, 재정의하지 않았다면 `%TEMP%`를 받습니다. Claude Code 자체 임시 파일은 항상 재정의한 값을 사용합니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |

416| `CLAUDE_CODE_TMUX_TRUECOLOR` | `1` 같은 비어 있지 않은 값으로 설정하면 tmux 내부에서 24비트 트루컬러 출력을 허용합니다. 대부분의 켜기/끄기 변수와 달리 **`0` 또는 `false`로 설정해도 트루컬러가 허용됩니다**. 256색 제한을 복원하려면 변수를 설정 해제합니다. tmux는 별도로 구성하지 않으면 트루컬러 이스케이프 시퀀스를 전달하지 않으므로, 기본적으로 Claude Code는 `$TMUX`가 설정되어 있으면 256색으로 제한합니다. `~/.tmux.conf`에 `set -ga terminal-overrides ',*:Tc'`를 추가한 후 이 값을 설정합니다. 다른 tmux 설정은 [터미널 구성](/docs/ko/terminal-config)을 참조하세요 |422| `CLAUDE_CODE_TMUX_TRUECOLOR` | tmux 내부에서 24비트 트루컬러 출력을 허용하려면 `1`과 같은 비어 있지 않은 값으로 설정합니다. 대부분의 켜기/끄기 변수와 달리 **`0` 또는 `false`로 설정해도 트루컬러가 허용되므로**, 256색 제한을 복원하려면 변수 설정을 해제합니다. tmux는 구성되지 않는 한 트루컬러 이스케이프 시퀀스를 전달하지 않으므로, 기본적으로 Claude Code는 `$TMUX`가 설정되어 있으면 256색으로 제한합니다. `~/.tmux.conf`에 `set -ga terminal-overrides ',*:Tc'`를 추가한 후 이 변수를 설정합니다. 다른 tmux 설정은 [터미널 구성](/docs/ko/terminal-config)을 참조하세요 |

417| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | Linux와 WSL에서 Claude Code가 [도구 메모리 상한에서 제외](/docs/ko/tools-reference#memory-limit-on-linux-and-wsl)하는 프로세스 종류를 `mcp` 또는 `lsp`처럼 쉼표로 구분된 목록으로 설정합니다. 모든 종류에 상한을 적용하려면 `none`을, Bash, PowerShell, Monitor 도구 명령에만 상한을 적용하려면 `all-new`를 설정합니다. 무엇을 나열하든 Claude Code는 Bash, PowerShell, Monitor 도구 명령에 상한을 유지합니다. Claude Code v2.1.246 이상이 필요합니다 |423| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | Linux와 WSL에서 Claude Code가 [도구 메모리 상한에서 제외](/docs/ko/tools-reference#memory-limit-on-linux-and-wsl)하는 프로세스 종류를 `mcp` 또는 `lsp`처럼 쉼표로 구분한 목록으로 설정합니다. 모든 종류에 상한을 적용하려면 `none`으로, Bash, PowerShell, Monitor 도구 명령에만 상한을 적용하려면 `all-new`로 설정합니다. 목록에 무엇을 지정하든 Claude Code는 Bash, PowerShell, Monitor 도구 명령을 상한 아래에 둡니다. Claude Code v2.1.246 이상이 필요합니다 |

418| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | Linux와 WSL에서 `4G` 같은 크기로 설정하면 [Bash 및 PowerShell 도구 명령이 사용할 수 있는 메모리를 제한](/docs/ko/tools-reference#memory-limit-on-linux-and-wsl)하며, v2.1.246 이상에서는 Monitor 도구 명령도 제한합니다. 크기는 숫자로만 작성하며, 바이트 수는 숫자만으로, 또는 `K`, `M`, `G`, `T` 접미사를 붙여 작성합니다. 상한을 끄려면 `0` 또는 `off`로 설정합니다. Claude Code가 시작한 첫 번째 프로세스가 상한을 켜거나 끈 후에는 변경된 값이 다음에 `claude`를 실행할 때 적용됩니다. Claude Code v2.1.233 이상이 필요합니다 |424| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | Linux와 WSL에서 `4G`와 같은 크기로 설정하여 [Bash 및 PowerShell 도구 명령이 사용할 수 있는 메모리를 제한](/docs/ko/tools-reference#memory-limit-on-linux-and-wsl)하며, v2.1.246 이상에서는 Monitor 도구 명령도 제한합니다. 크기는 숫자로만 쓰며, 바이트 수만 쓰거나 `K`, `M`, `G`, `T` 접미사를 붙입니다. 상한을 끄려면 `0` 또는 `off`로 설정합니다. Claude Code가 시작하는 첫 번째 프로세스가 상한을 켜거나 끈 후에는 변경된 값이 다음에 `claude`를 실행할 때 적용됩니다. Claude Code v2.1.233 이상이 필요합니다 |

419| `CLAUDE_CODE_TRANSCRIPT_LOCAL_GC` | `1`로 설정하면 긴 `-p` 또는 Agent SDK 세션의 [트랜스크립트 파일](/docs/ko/sessions#where-transcripts-are-stored)이 커지는 크기를 제한합니다. 각 압축 후 파일이 5 MB보다 크면 Claude Code는 해당 압축 이전의 기록을 제거합니다. 세션을 재개하면 파일이 잘렸는지와 관계없이 같은 대화가 복원됩니다. 설정 `env` 블록으로는 켤 수 없으므로 Claude Code를 시작하는 환경에서 설정합니다. Claude Code v2.1.287 이상이 필요합니다 |425| `CLAUDE_CODE_TRANSCRIPT_LOCAL_GC` | 긴 `-p` 또는 Agent SDK 세션의 [트랜스크립트 파일](/docs/ko/sessions#where-transcripts-are-stored)이 커지는 크기를 제한하려면 `1`로 설정합니다. 각 압축 후 파일이 5 MB보다 크면 Claude Code는 해당 압축 이전의 기록을 제거합니다. 세션을 재개하면 파일이 잘렸는지와 관계없이 같은 대화가 복원됩니다. 설정의 `env` 블록으로는 켤 수 없으므로 Claude Code를 시작하는 환경에서 설정합니다. Claude Code v2.1.287 이상이 필요합니다 |

420| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code가 [Remote Control](/docs/ko/remote-control) 또는 SDK 호스트 같은 원격 클라이언트에 전달하는 대화 상자, 또는 [보류된 세션 간 메시지](/docs/ko/cross-session-messaging#control-inbound-messages)의 승인 대화 상자를 취소하기 전까지의 기한(밀리초)입니다. 권한 프롬프트와 `AskUserQuestion` 질문은 자체 흐름을 사용하며 이 값의 적용을 받지 않습니다. Claude Code v2.1.236 이상에서는 무인으로 실행 중일 수 있는 세션에서 세션 도중 표시되는 [Fable 사용량 크레딧 동의 프롬프트](/docs/ko/model-config#fable-and-usage-credits)에도 기한을 적용합니다. 기한이 적용되지 않는 경우를 포함한 보류 메시지 만료 규칙 전체는 [수신 메시지 제어](/docs/ko/cross-session-messaging#control-inbound-messages)와 [비대화형 세션](/docs/ko/cross-session-messaging#non-interactive-sessions)에서 다룹니다. [`dialogExpiry`](/docs/ko/settings-reference#dialogexpiry) 설정을 재정의합니다. `0` 또는 음수 값은 기한을 비활성화합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |426| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code가 [Remote Control](/docs/ko/remote-control) 또는 SDK 호스트 같은 원격 클라이언트로 전달하는 대화 상자, 또는 [보류된 세션 간 메시지](/docs/ko/cross-session-messaging#control-inbound-messages)에 대한 승인 대화 상자를 취소하기 전까지의 기한(밀리초)입니다. 권한 프롬프트와 `AskUserQuestion` 질문은 자체 흐름을 사용하며 이 변수의 적용을 받지 않습니다. Claude Code v2.1.236 이상에서는 무인으로 실행 중일 수 있는 세션에서 세션 도중에 표시되는 [Fable 사용량 크레딧 동의 프롬프트](/docs/ko/model-config#fable-and-usage-credits)에도 이 기한이 적용됩니다. 기한이 적용되지 않는 경우를 포함한 보류 메시지 만료 규칙 전체는 [인바운드 메시지 제어](/docs/ko/cross-session-messaging#control-inbound-messages) 및 [비대화형 세션](/docs/ko/cross-session-messaging#non-interactive-sessions)에서 다룹니다. [`dialogExpiry`](/docs/ko/settings-reference#dialogexpiry) 설정을 재정의합니다. `0` 또는 음수 값을 지정하면 기한이 비활성화됩니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |

425| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | `1`로 설정하면 ripgrep 대신 Node.js 파일 API를 사용하여 사용자 지정 명령, 서브에이전트, 출력 스타일을 검색합니다. 번들된 ripgrep 바이너리를 사용할 수 없거나 사용 환경에서 차단된 경우 설정합니다. Grep 또는 파일 검색 도구에는 영향을 주지 않습니다 |431| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | `1`로 설정하면 ripgrep 대신 Node.js 파일 API를 사용하여 사용자 지정 명령, 서브에이전트, 출력 스타일을 검색합니다. 번들된 ripgrep 바이너리를 사용할 수 없거나 환경에서 차단된 경우 설정합니다. Grep 또는 파일 검색 도구에는 영향을 주지 않습니다 |

426| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | PowerShell 도구를 제어합니다. Git Bash가 없는 Windows에서는 도구가 자동으로 활성화되며, 비활성화하려면 `0`으로 설정합니다. Git Bash가 설치된 Windows에서는 claude.ai 및 Console 계정에서 도구가 기본적으로 켜져 있으며, Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry 세션에서 활성화하려면 `1`로, 끄려면 `0`으로 설정합니다. Linux, macOS, WSL에서는 `1`로 설정하면 활성화되며, 이 경우 `PATH`에 `pwsh`가 있어야 합니다. Windows에서 활성화하면 Claude는 Git Bash를 거치지 않고 PowerShell 명령을 네이티브로 실행할 수 있습니다. [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)를 참조하세요 |432| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | PowerShell 도구를 제어합니다. Git Bash가 없는 Windows에서는 도구가 자동으로 활성화되며, `0`으로 설정하면 비활성화됩니다. Git Bash가 설치된 Windows에서는 claude.ai 및 Console 계정의 경우 도구가 기본적으로 켜져 있습니다. Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry 세션에서 활성화하려면 `1`로, 끄려면 `0`으로 설정합니다. Linux, macOS, WSL에서는 `1`로 설정하여 활성화하며, 이 경우 `PATH`에 `pwsh`가 있어야 합니다. Windows에서 활성화하면 Claude가 Git Bash를 거치지 않고 PowerShell 명령을 네이티브로 실행할 수 있습니다. [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)를 참조하세요 |

428| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | [WebFetch](/docs/ko/tools-reference#webfetch-tool-behavior)가 가져온 각 URL의 응답을 캐시에 보관하는 시간(밀리초)을 설정합니다. 기본값은 `900000`으로, 15분입니다. 숫자만 허용되며, `0`, 소수 또는 다른 표기는 기본값을 유지합니다. Claude Code는 실행할 때마다 값을 한 번만 읽으므로, 설정의 `env` 블록에서 변경한 내용은 다음에 `claude`를 실행할 때 적용됩니다. Claude Code v2.1.233 이상이 필요합니다 |434| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | [WebFetch](/docs/ko/tools-reference#webfetch-tool-behavior)가 가져온 각 URL의 응답을 캐시에 유지하는 시간(밀리초)으로 설정합니다. 기본값은 `900000`이며, 이는 15분입니다. 숫자만 허용되며, `0`, 소수 또는 기타 표기는 기본값을 유지합니다. Claude Code는 실행할 때마다 이 값을 한 번 읽으므로, 설정 `env` 블록의 변경 사항은 다음에 `claude`를 실행할 때 적용됩니다. Claude Code v2.1.233 이상이 필요합니다 |

429| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/ko/tools-reference#webfetch-tool-behavior)가 따라가는 리디렉션을 포함하여 페이지 다운로드를 기다리는 시간의 상한(밀리초)입니다. 이 시간까지 완료되지 않은 다운로드는 기한 오류로 실패합니다. 기본값은 `300000`으로, 5분입니다. 제한을 없애려면 `0`으로 설정합니다. 숫자만 허용되며, 소수 또는 다른 표기는 기본값을 유지합니다. Claude Code v2.1.268 이상이 필요합니다 |435| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/ko/tools-reference#webfetch-tool-behavior)가 따라가는 리디렉션을 포함하여 페이지 다운로드를 기다리는 시간의 상한(밀리초)입니다. 그때까지 완료되지 않은 다운로드는 기한 오류로 실패합니다. 기본값은 `300000`이며, 이는 5분입니다. `0`으로 설정하면 제한이 해제됩니다. 숫자만 허용되며, 소수 또는 기타 표기는 기본값을 유지합니다. Claude Code v2.1.268 이상이 필요합니다 |

430| `CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR` | 세션의 [WebSearch 한도](/docs/ko/tools-reference#session-search-limit)가 다시 채워지는 속도로, 시간당 호출 수 단위입니다. 대화형 터미널 세션에서 기본값은 `100`입니다. [비대화형](/docs/ko/headless) 세션에서는 기본값이 `0`이며, 이 경우 다시 채워지지 않습니다. 숫자만 허용되며, 다른 표기는 설정되지 않은 것으로 간주됩니다. Claude Code v2.1.290 이상이 필요합니다 |436| `CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR` | 세션의 [WebSearch 한도](/docs/ko/tools-reference#session-search-limit)가 다시 채워지는 속도(시간당 호출 수)입니다. 대화형 터미널 세션에서 기본값은 `100`입니다. [비대화형](/docs/ko/headless) 세션에서는 기본값이 `0`이며, 이 경우 다시 채워지지 않습니다. 숫자만 허용되며, 기타 표기는 설정되지 않은 것으로 간주됩니다. Claude Code v2.1.290 이상이 필요합니다 |

431| `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` | `CLAUDE_AUTO_BACKGROUND_TASKS`가 `1`로 설정된 경우, 아직 실행 중인 [백그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)를 확인하도록 Claude에게 알림을 보내기 전에 Claude Code가 매번 기다리는 시간입니다. `600` 또는 `600,1800,3600`처럼 `1`부터 `86400`까지의 정수 초 단위 대기 시간을 하나 이상 쉼표로 구분하여 지정합니다. 각 값은 다음 알림까지의 대기 시간이며, 마지막 값이 반복됩니다. 숫자만 허용되며, 다른 값이나 표기는 설정되지 않은 것으로 간주됩니다. 설정하지 않으면 알림이 없습니다. Claude Code v2.1.283 이상이 필요합니다 |437| `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` | `CLAUDE_AUTO_BACKGROUND_TASKS`가 `1`로 설정된 경우, 아직 실행 중인 [백그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)를 확인하도록 Claude에게 알림을 보내기 전에 Claude Code가 매번 대기하는 시간입니다. `600` 또는 `600,1800,3600`처럼 `1`부터 `86400`까지의 정수 초 단위 대기 시간을 쉼표로 구분하여 하나 이상 지정합니다. 각 값은 다음 알림 전까지의 대기 시간이며, 마지막 값이 반복됩니다. 숫자만 허용되며, 기타 값이나 표기는 설정되지 않은 것으로 간주됩니다. 설정하지 않으면 알림이 없습니다. Claude Code v2.1.283 이상이 필요합니다 |

432| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 단일 [워크플로](/docs/ko/workflows) 실행이 동시에 실행하는 에이전트 수로, `1`부터 `256`까지 지정할 수 있습니다. 기본적으로 한 실행은 최대 16개의 에이전트를 동시에 실행하며, Claude Code가 사용할 수 있는 CPU가 적으면 그보다 적게 실행합니다. 대기열에 있는 `agent()` 호출은 빈 슬롯이 생길 때까지 기다립니다. 실행 중인 각 에이전트의 트랜스크립트는 Claude Code의 메모리에 유지되므로, 값이 클수록 메모리 사용량이 늘어납니다. 숫자만 허용되며, 범위를 벗어난 값과 다른 표기는 기본값을 유지합니다. Claude Code v2.1.269 이상이 필요합니다 |438| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 단일 [워크플로](/docs/ko/workflows) 실행이 동시에 실행하는 에이전트 수로, `1`부터 `256`까지입니다. 기본적으로 실행당 최대 16개의 에이전트를 동시에 실행하며, Claude Code가 사용할 수 있는 CPU가 적으면 더 적게 실행합니다. 대기열에 있는 `agent()` 호출은 빈 슬롯을 기다립니다. 실행 중인 각 에이전트의 트랜스크립트는 Claude Code의 메모리에 유지되므로, 값이 높을수록 메모리 사용량이 늘어납니다. 숫자만 허용되며, 범위를 벗어난 값이나 기타 표기는 기본값을 유지합니다. Claude Code v2.1.269 이상이 필요합니다 |

433| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [워크플로](/docs/ko/workflows) 에이전트가 자신의 첫 요청을 보내기 전에, 같은 접두사를 가진 형제 에이전트의 첫 응답이 시작되기를 기다리는 시간의 상한(밀리초)입니다. 팬아웃이 [프롬프트 캐시 접두사](/docs/ko/workflows#prompt-caching-in-a-fan-out)를 공유하는 여러 에이전트를 시작하면, Claude Code는 첫 번째 에이전트를 제외한 나머지를 최대 이 시간 동안 대기시켜 각 에이전트가 접두사를 캐시 없이 처리하는 대신 캐시된 접두사를 읽도록 합니다. 기본값은 `5000`입니다. 대기를 비활성화하려면 `0`으로 설정합니다. `DISABLE_PROMPT_CACHING`이 설정된 경우 에이전트는 대기하지 않습니다. Claude Code v2.1.229 이상이 필요합니다 |439| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [워크플로](/docs/ko/workflows) 에이전트가 자신의 첫 요청을 보내기 전에 동일한 접두사를 가진 형제 에이전트의 첫 응답이 시작되기를 기다리는 시간의 상한(밀리초)입니다. 팬아웃이 [프롬프트 캐시 접두사](/docs/ko/workflows#prompt-caching-in-a-fan-out)를 공유하는 여러 에이전트를 시작하면, Claude Code는 첫 번째 에이전트를 제외한 나머지를 최대 이 시간만큼 대기시켜 각각 캐시되지 않은 접두사를 처리하는 대신 캐시된 접두사를 읽도록 합니다. 기본값은 `5000`입니다. `0`으로 설정하면 대기를 비활성화합니다. `DISABLE_PROMPT_CACHING`이 설정된 경우 에이전트는 대기하지 않습니다. Claude Code v2.1.229 이상이 필요합니다 |

434| `CLAUDE_CONFIG_DIR` | 구성 디렉터리를 재정의합니다(기본값: `~/.claude`). 모든 설정, 세션 기록, 플러그인이 이 경로 아래에 저장됩니다. 자격 증명에 대해서는 [Claude Code가 자격 증명을 저장하는 위치](/docs/ko/authentication#credential-management)를 참조하세요. 여러 계정을 나란히 실행할 때 유용합니다. 예: `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 설정 파일에서는 [절대 경로](#in-settings-files)를 작성합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |440| `CLAUDE_CONFIG_DIR` | 구성 디렉터리를 재정의합니다(기본값: `~/.claude`). 모든 설정, 세션 기록, 플러그인이 이 경로 아래에 저장됩니다. 자격 증명에 대해서는 [Claude Code가 자격 증명을 저장하는 위치](/docs/ko/authentication#credential-management)를 참조하세요. 여러 계정을 나란히 실행할 때 유용합니다. 예: `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 설정 파일에서는 [절대 경로](#in-settings-files)를 작성합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |

435| `CLAUDE_DISABLE_ADOPT` | `1`로 설정하면 `←`를 누르거나 [`/background`](/docs/ko/agent-view#from-inside-a-session)로 세션을 백그라운드로 보낼 때 진행 중인 백그라운드 작업을 이어받지 않고 중지합니다. Claude Code는 백그라운드로 보내기 전에 확인을 요청한 다음, 이어받았을 작업을 중지합니다. Claude Code v2.1.195 이상이 필요합니다 |441| `CLAUDE_DISABLE_ADOPT` | `←`를 누르거나 [`/background`](/docs/ko/agent-view#from-inside-a-session)로 세션을 백그라운드로 전환할 때, 진행 중인 백그라운드 작업을 이어가는 대신 중지하려면 `1`로 설정합니다. Claude Code는 백그라운드로 전환하기 전에 확인을 요청한 다음, 그렇지 않으면 이어졌을 작업을 중지합니다. Claude Code v2.1.195 이상이 필요합니다 |

436| `CLAUDE_EFFORT` | Bash 도구 하위 프로세스와 훅 명령에서, 하위 프로세스가 시작될 때 적용 중인 [effort 수준](/docs/ko/model-config#adjust-effort-level)(`low`, `medium`, `high`, `xhigh`, `max`)으로 자동 설정됩니다. [훅](/docs/ko/hooks)에 전달되는 `effort.level` 필드와 일치합니다. 현재 모델이 effort 매개변수를 지원하는 경우에만 설정됩니다 |442| `CLAUDE_EFFORT` | Bash 도구 하위 프로세스와 훅 명령에서 하위 프로세스가 시작될 때 적용 중인 [effort 수준](/docs/ko/model-config#adjust-effort-level)(`low`, `medium`, `high`, `xhigh` 또는 `max`)으로 자동 설정됩니다. [훅](/docs/ko/hooks)에 전달되는 `effort.level` 필드와 일치합니다. 현재 모델이 effort 매개변수를 지원하는 경우에만 설정됩니다 |

437| `CLAUDE_ENABLE_BYTE_WATCHDOG` | `1`로 설정하면 바이트 수준 스트리밍 유휴 워치독을 강제로 활성화하고, `0`으로 설정하면 강제로 비활성화합니다. `0`은 해당 기한이 적용되는 연결에서 [첫 바이트 기한](/docs/ko/network-config#streaming-idle-watchdogs)도 끕니다. 설정하지 않으면 직접 Anthropic API 및 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 연결과, `ANTHROPIC_BASE_URL` 또는 `ANTHROPIC_AWS_BASE_URL`을 통해 연결되는 [게이트웨이](/docs/ko/gateways) 연결의 스트리밍 응답에서 워치독이 기본적으로 활성화됩니다. v2.1.222 이전에는 이러한 게이트웨이 연결에서 워치독이 실행되지 않았기 때문에, keep-alive ping이 도착하는 중에도 이벤트 수준 워치독이 중단을 보고할 수 있었습니다. 타임아웃과 타이머 간의 상호 작용에 대해서는 [스트리밍 유휴 워치독](/docs/ko/network-config#streaming-idle-watchdogs)을 참조하세요 |443| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 바이트 수준 스트리밍 유휴 워치독을 강제로 활성화하려면 `1`로, 강제로 비활성화하려면 `0`으로 설정합니다. `0`은 해당 기한이 실행되는 연결에서 [첫 바이트 기한](/docs/ko/network-config#streaming-idle-watchdogs)도 끕니다. 설정하지 않으면 직접 Anthropic API 및 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 연결과, `ANTHROPIC_BASE_URL` 또는 `ANTHROPIC_AWS_BASE_URL`을 통해 연결되는 [게이트웨이](/docs/ko/gateways) 연결의 스트리밍 응답에 대해 워치독이 기본적으로 활성화됩니다. v2.1.222 이전에는 해당 게이트웨이 연결에서 실행되지 않았기 때문에, keep-alive 핑이 도착하는 중에도 이벤트 수준 워치독이 정체를 보고할 수 있었습니다. 타임아웃과 타이머 간 상호작용에 대해서는 [스트리밍 유휴 워치독](/docs/ko/network-config#streaming-idle-watchdogs)을 참조하세요 |

438| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | `1`로 설정하면 Amazon Bedrock `vnd.amazon.eventstream` 응답에서 바이트 수준 스트리밍 유휴 워치독을 활성화하며, Bedrock 스트리밍 요청에서 [첫 바이트 기한](/docs/ko/network-config#streaming-idle-watchdogs)도 함께 활성화됩니다. 기본적으로 꺼져 있습니다. 타임아웃은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 구성합니다 |444| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | Amazon Bedrock `vnd.amazon.eventstream` 응답에서 바이트 수준 스트리밍 유휴 워치독을 활성화하려면 `1`로 설정합니다. 이렇게 하면 Bedrock 스트리밍 요청에서 [첫 바이트 기한](/docs/ko/network-config#streaming-idle-watchdogs)도 활성화됩니다. 기본적으로 꺼져 있습니다. 타임아웃은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 구성합니다 |

439| `CLAUDE_ENABLE_STREAM_WATCHDOG` | `0`으로 설정하면 이벤트 수준 스트리밍 유휴 워치독을 강제로 비활성화하고, `1`로 설정하면 강제로 활성화합니다. 설정하지 않으면 모든 공급자에서 워치독이 기본적으로 켜져 있습니다. v2.1.196 이전에는 설정하지 않은 경우의 기본값이 직접 Anthropic API에서는 서버에 의해 제어되었고 다른 공급자에서는 꺼져 있었습니다. 타임아웃은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 구성합니다. 이 워치독과 함께 실행되는 다른 중단 타이머에 대해서는 [스트리밍 유휴 워치독](/docs/ko/network-config#streaming-idle-watchdogs)을 참조하세요 |445| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 이벤트 수준 스트리밍 유휴 워치독을 강제로 비활성화하려면 `0`으로, 강제로 활성화하려면 `1`로 설정합니다. 설정하지 않으면 모든 공급자에서 워치독이 기본적으로 켜져 있습니다. v2.1.196 이전에는 설정하지 않았을 때의 기본값이 직접 Anthropic API에서는 서버에서 제어되었고 다른 공급자에서는 꺼져 있었습니다. 타임아웃은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 구성합니다. 이 워치독과 함께 실행되는 다른 정체 타이머에 대해서는 [스트리밍 유휴 워치독](/docs/ko/network-config#streaming-idle-watchdogs)을 참조하세요 |

440| `CLAUDE_ENV_FILE` | Claude Code가 각 Bash 명령 전에 같은 셸 프로세스에서 실행하는 셸 스크립트의 경로로, 파일 안의 export가 명령에서 보이게 됩니다. 명령 간에 virtualenv 또는 conda 활성화를 유지하는 데 사용합니다. [SessionStart](/docs/ko/hooks#persist-environment-variables), [Setup](/docs/ko/hooks#setup), [CwdChanged](/docs/ko/hooks#cwdchanged), [FileChanged](/docs/ko/hooks#filechanged) 훅에 의해 동적으로 채워지기도 합니다 |446| `CLAUDE_ENV_FILE` | Claude Code가 각 Bash 명령 전에 동일한 셸 프로세스에서 내용을 실행하는 셸 스크립트의 경로로, 파일의 export가 명령에 표시됩니다. virtualenv 또는 conda 활성화를 명령 간에 유지하는 데 사용합니다. [SessionStart](/docs/ko/hooks#persist-environment-variables), [Setup](/docs/ko/hooks#setup), [CwdChanged](/docs/ko/hooks#cwdchanged), [FileChanged](/docs/ko/hooks#filechanged) 훅에 의해 동적으로 채워지기도 합니다 |

441| `CLAUDE_JOB_DIR` | Claude Code가 각 [백그라운드 세션](/docs/ko/agent-view)에서 해당 세션의 `~/.claude/jobs/<id>` 디렉터리로 설정합니다. 세션이 실행하는 셸 명령이 이를 상속합니다. 임시 파일은 [`$CLAUDE_JOB_DIR/tmp`](/docs/ko/agent-view#where-state-is-stored)에 작성합니다. 이 위치에 대한 Claude의 `Write` 및 `Edit` 호출은 권한을 묻지 않으며, 세션이 삭제되면 디렉터리도 제거됩니다 |447| `CLAUDE_JOB_DIR` | 각 [백그라운드 세션](/docs/ko/agent-view)에서 Claude Code가 해당 세션의 `~/.claude/jobs/<id>` 디렉터리로 설정합니다. 세션이 실행하는 셸 명령이 이를 상속합니다. 임시 파일은 [`$CLAUDE_JOB_DIR/tmp`](/docs/ko/agent-view#where-state-is-stored)에 작성합니다. 그곳에 대한 Claude의 `Write` 및 `Edit` 호출은 권한을 묻지 않으며, 세션이 삭제되면 디렉터리가 제거됩니다 |

442| `CLAUDE_PID` | Claude Code가 생성하는 하위 프로세스(Bash 및 PowerShell 도구 명령과 훅 명령)에서 자신의 프로세스 ID로 설정합니다. Linux에서 Bash 도구의 셸 통합은 이 값을 사용하여 Claude Code 프로세스 자체와 일치하는 `pkill` 패턴을 거부합니다. [오류 참조](/docs/ko/errors#pkill-pattern-matches-the-claude-code-process)를 참조하세요. 사용자 스크립트에서 이 값을 읽어 부모 Claude Code 프로세스를 의도적으로 식별하거나 시그널을 보낼 수 있습니다. Claude Code v2.1.214 이상이 필요합니다 |448| `CLAUDE_PID` | Claude Code가 생성하는 하위 프로세스(Bash 및 PowerShell 도구 명령과 훅 명령)에서 자신의 프로세스 ID로 설정합니다. Linux에서 Bash 도구의 셸 통합은 이를 사용하여 Claude Code 프로세스 자체와 일치하는 `pkill` 패턴을 거부합니다. [오류 참조](/docs/ko/errors#pkill-pattern-matches-the-claude-code-process)를 참조하세요. 자체 스크립트에서 이 값을 읽어 상위 Claude Code 프로세스를 의도적으로 식별하거나 신호를 보낼 수 있습니다. Claude Code v2.1.214 이상이 필요합니다 |

443| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 명시적인 이름이 제공되지 않은 경우 자동 생성되는 [Remote Control](/docs/ko/remote-control) 세션 이름의 접두사입니다. 기본값은 머신의 호스트 이름이며, `myhost-graceful-unicorn`과 같은 이름이 생성됩니다. `--remote-control-session-name-prefix` CLI 플래그는 단일 실행에 대해 같은 값을 설정합니다 |449| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 명시적인 이름이 제공되지 않을 때 자동 생성되는 [Remote Control](/docs/ko/remote-control) 세션 이름의 접두사입니다. 기본값은 머신의 호스트 이름이며, `myhost-graceful-unicorn` 같은 이름이 생성됩니다. `--remote-control-session-name-prefix` CLI 플래그는 단일 호출에 대해 동일한 값을 설정합니다 |

444| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | [첫 바이트 기한](/docs/ko/network-config#streaming-idle-watchdogs)이 적용되는 연결에서 스트리밍 요청의 첫 응답 바이트에 대한 기한(밀리초)입니다. Claude Code가 이 값을 제한하는 방식, 큰 요청 본문에 추가하는 시간, 이 값을 설정하지 않았을 때 기한을 선택하는 방식에 대해서는 [No response from API](/docs/ko/errors#no-response-from-api)를 참조하세요. Claude Code v2.1.242 이상이 필요합니다 |450| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | [첫 바이트 기한](/docs/ko/network-config#streaming-idle-watchdogs)이 실행되는 연결에서 스트리밍 요청의 첫 응답 바이트에 대한 기한(밀리초)입니다. Claude Code가 이 값을 제한하는 방식, 큰 요청 본문에 대해 추가하는 시간, 이 값을 설정하지 않았을 때 기한을 선택하는 방식은 [No response from API](/docs/ko/errors#no-response-from-api)를 참조하세요. Claude Code v2.1.242 이상이 필요합니다 |

445| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 이벤트 수준 및 바이트 수준 스트리밍 유휴 워치독이 중단된 연결을 닫기 전까지의 타임아웃(밀리초)입니다. 이 변수를 명시적으로 설정하는 경우 최솟값은 `300000`(5분)입니다. 확장 사고로 인한 멈춤과 프록시 버퍼링을 흡수하기 위해 더 낮은 값은 별도 알림 없이 최솟값으로 조정되며, 바이트 수준 워치독은 값을 최대 30분으로 제한합니다. 바이트 수준 워치독에서는 `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS`가 이 변수보다 우선합니다. 워치독별로 설정하지 않았을 때의 기본값은 [스트리밍 유휴 워치독](/docs/ko/network-config#streaming-idle-watchdogs)을 참조하세요 |451| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 이벤트 수준 및 바이트 수준 스트리밍 유휴 워치독이 정체된 연결을 닫기 전까지의 타임아웃(밀리초)입니다. 이 변수를 명시적으로 설정하면 최솟값은 `300000`(5분)입니다. 확장 사고 일시 중지와 프록시 버퍼링을 흡수하기 위해 더 낮은 값은 자동으로 조정되며, 바이트 수준 워치독은 값을 30분으로 제한합니다. 바이트 수준 워치독에 대해서는 `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS`가 이 변수보다 우선합니다. 워치독별 미설정 시 기본값은 [스트리밍 유휴 워치독](/docs/ko/network-config#streaming-idle-watchdogs)을 참조하세요 |

446| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | v2.1.260에서 제거되어 이제 아무 효과가 없습니다. 이전에는 [서브에이전트](/docs/ko/sub-agents)가 시작한 [백그라운드 셸 명령](/docs/ko/interactive-mode#background-bash-commands)이 실행될 수 있는 시간을 밀리초 단위로 제한했으며, 기본값은 60분이었습니다. [백그라운드 명령 수명 규칙](/docs/ko/tools-reference#background-commands)을 참조하세요 |452| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | v2.1.260에서 제거되었으며 이제 아무 작업도 수행하지 않습니다. 이전에는 [서브에이전트](/docs/ko/sub-agents)가 시작한 [백그라운드 셸 명령](/docs/ko/interactive-mode#background-bash-commands)이 실행될 수 있는 시간을 밀리초 단위로 제한했으며, 기본값은 60분이었습니다. [백그라운드 명령 수명 규칙](/docs/ko/tools-reference#background-commands)을 참조하세요 |

447| `DEBUG` | `1`로 설정하면 디버그 모드를 활성화하며, [`--debug`](/docs/ko/cli-reference#cli-flags)로 실행하는 것과 같습니다. 디버그 로그는 `~/.claude/debug/<session-id>.txt` 또는 `CLAUDE_CODE_DEBUG_LOGS_DIR`로 설정한 경로에 기록됩니다. 참 값인 `1`, `true`, `yes`, `on`만 디버그 모드를 활성화하므로, 다른 도구를 위해 설정한 `DEBUG=express:*` 같은 네임스페이스 패턴은 디버그 모드를 트리거하지 않습니다 |453| `DEBUG` | `1`로 설정하면 디버그 모드가 활성화되며, [`--debug`](/docs/ko/cli-reference#cli-flags)로 실행하는 것과 같습니다. 디버그 로그는 `~/.claude/debug/<session-id>.txt` 또는 `CLAUDE_CODE_DEBUG_LOGS_DIR`로 설정된 경로에 기록됩니다. 참 값인 `1`, `true`, `yes`, `on`만 디버그 모드를 활성화하므로, 다른 도구를 위해 설정한 `DEBUG=express:*` 같은 네임스페이스 패턴은 이를 트리거하지 않습니다 |

448| `DISABLE_AUTOUPDATER` | `1`로 설정하면 자동 백그라운드 업데이트를 비활성화합니다. 수동 `claude update`는 계속 작동합니다. 둘 다 차단하려면 `DISABLE_UPDATES`를 사용합니다 |454| `DISABLE_AUTOUPDATER` | 자동 백그라운드 업데이트를 비활성화하려면 `1`로 설정합니다. 수동 `claude update`는 계속 작동합니다. 둘 다 차단하려면 `DISABLE_UPDATES`를 사용합니다 |

449| `DISABLE_AUTO_COMPACT` | `1`로 설정하면 컨텍스트 한도에 가까워질 때의 자동 압축을 비활성화합니다. 수동 `/compact` 명령은 계속 사용할 수 있습니다. 압축 시점을 명시적으로 제어하려는 경우 사용합니다. [`autoCompactEnabled`](/docs/ko/settings-reference#autocompactenabled) 설정을 재정의합니다 |455| `DISABLE_AUTO_COMPACT` | 컨텍스트 한도에 가까워질 때 자동 압축을 비활성화하려면 `1`로 설정합니다. 수동 `/compact` 명령은 계속 사용할 수 있습니다. 압축 시점을 명시적으로 제어하려는 경우에 사용합니다. [`autoCompactEnabled`](/docs/ko/settings-reference#autocompactenabled) 설정을 재정의합니다 |

452| `DISABLE_DOCTOR_COMMAND` | `1`로 설정하면 [`/doctor`](/docs/ko/commands#all-commands) 설정 점검 스킬과 그 별칭인 `/checkup`을 숨깁니다. 사용자가 세션에서 설정 진단을 실행하지 않아야 하는 관리형 배포에서 유용합니다. `claude doctor` 터미널 명령에는 영향을 주지 않습니다. v2.1.205 이전에는 이 변수가 `/doctor` 진단 화면 명령을 숨겼습니다 |458| `DISABLE_DOCTOR_COMMAND` | [`/doctor`](/docs/ko/commands#all-commands) 설정 점검 스킬과 그 별칭인 `/checkup`을 숨기려면 `1`로 설정합니다. 사용자가 세션에서 설정 진단을 실행해서는 안 되는 관리형 배포에 유용합니다. `claude doctor` 터미널 명령에는 영향을 주지 않습니다. v2.1.205 이전에는 이 변수가 `/doctor` 진단 화면 명령을 숨겼습니다 |

453| `DISABLE_ERROR_REPORTING` | `1`과 같이 비어 있지 않은 값으로 설정하면 오류 보고를 거부합니다. 대부분의 켜기/끄기 변수와 달리 **`0` 또는 `false`로 설정해도 여전히 거부됩니다**. 오류 보고를 다시 켜려면 변수 설정을 해제합니다 |459| `DISABLE_ERROR_REPORTING` | 오류 보고를 거부하려면 `1`과 같이 비어 있지 않은 아무 값으로 설정합니다. 대부분의 켜기/끄기 변수와 달리 **`0` 또는 `false`로 설정해도 여전히 거부됩니다**. 오류 보고를 다시 켜려면 변수를 설정 해제합니다 |

455| `DISABLE_FEEDBACK_COMMAND` | `1`로 설정하면 `/feedback` 명령과 [Claude가 작성하는 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior)을 비활성화합니다. 같은 경로로 보고하는 `/bug`와 `/share`도 비활성화합니다. v2.1.212 이전에는 이들이 `/feedback`의 별칭이었으므로 모든 이름의 명령이 비활성화되었습니다. 이전 이름인 `DISABLE_BUG_COMMAND`도 허용됩니다 |461| `DISABLE_FEEDBACK_COMMAND` | `/feedback` 명령과 [Claude가 작성한 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior)을 비활성화하려면 `1`로 설정합니다. 동일한 경로로 보고하는 `/bug` 및 `/share`도 비활성화합니다. v2.1.212 이전에는 이들이 `/feedback`의 별칭이었으므로 모든 이름에서 명령이 비활성화되었습니다. 이전 이름인 `DISABLE_BUG_COMMAND`도 허용됩니다 |

456| `DISABLE_GROWTHBOOK` | `1` 또는 `true`로 설정하면 GrowthBook 기능 플래그 가져오기를 비활성화하고 모든 플래그에 코드 기본값을 사용합니다. 이로 인해 [Remote Control](/docs/ko/remote-control#requirements) 및 기타 [기능 플래그 가져오기가 필요한 기능](#features-that-need-feature-flag-fetching)을 사용할 수 없게 됩니다. `0` 또는 `false`로 설정하면 가져오기가 켜진 상태로 유지됩니다. `DISABLE_TELEMETRY`도 설정하지 않는 한 텔레메트리 이벤트 로깅은 켜진 상태로 유지됩니다 |462| `DISABLE_GROWTHBOOK` | GrowthBook 기능 플래그 가져오기를 비활성화하고 모든 플래그에 코드 기본값을 사용하려면 `1` 또는 `true`로 설정합니다. 이렇게 하면 [Remote Control](/docs/ko/remote-control#requirements) 및 기타 [기능 플래그 가져오기가 필요한 기능](#features-that-need-feature-flag-fetching)을 사용할 수 없게 됩니다. `0` 또는 `false`로 설정하면 가져오기가 켜진 상태로 유지됩니다. `DISABLE_TELEMETRY`도 설정하지 않는 한 텔레메트리 이벤트 로깅은 켜진 상태로 유지됩니다 |

458| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | `1`로 설정하면 `/install-github-app` 명령을 숨깁니다. 서드파티 공급자(Amazon Bedrock, Google Cloud's Agent Platform 또는 Microsoft Foundry)를 사용하는 경우에는 이미 숨겨져 있습니다 |464| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | `/install-github-app` 명령을 숨기려면 `1`로 설정합니다. 서드 파티 공급자(Amazon Bedrock, Google Cloud's Agent Platform 또는 Microsoft Foundry)를 사용할 때는 이미 숨겨져 있습니다 |

459| `DISABLE_INTERLEAVED_THINKING` | `1`로 설정하면 interleaved-thinking 베타 헤더를 보내지 않습니다. LLM 게이트웨이 또는 공급자가 [인터리브드 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)를 지원하지 않는 경우 유용합니다 |465| `DISABLE_INTERLEAVED_THINKING` | interleaved-thinking 베타 헤더 전송을 방지하려면 `1`로 설정합니다. LLM 게이트웨이 또는 공급자가 [인터리브드 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)를 지원하지 않을 때 유용합니다 |

462| `DISABLE_PROMPT_CACHING` | `1`로 설정하면 모든 모델에 대해 [프롬프트 캐싱](/docs/ko/prompt-caching#disable-prompt-caching)을 비활성화합니다(모델별 설정보다 우선함) |468| `DISABLE_PROMPT_CACHING` | 모든 모델에 대해 [프롬프트 캐싱](/docs/ko/prompt-caching#disable-prompt-caching)을 비활성화하려면 `1`로 설정합니다(모델별 설정보다 우선함) |

464| `DISABLE_PROMPT_CACHING_HAIKU` | `1`로 설정하면 실행 위치와 관계없이 [기본 Haiku 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 프롬프트 캐싱을 비활성화합니다 |470| `DISABLE_PROMPT_CACHING_HAIKU` | 실행 위치에 관계없이 [기본 Haiku 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다 |

465| `DISABLE_PROMPT_CACHING_OPUS` | `1`로 설정하면 [기본 Opus 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 프롬프트 캐싱을 비활성화합니다 |471| `DISABLE_PROMPT_CACHING_OPUS` | [기본 Opus 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다 |

466| `DISABLE_PROMPT_CACHING_SONNET` | `1`로 설정하면 [기본 Sonnet 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 프롬프트 캐싱을 비활성화합니다 |472| `DISABLE_PROMPT_CACHING_SONNET` | [기본 Sonnet 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다 |

467| `DISABLE_TELEMETRY` | `1`과 같이 비어 있지 않은 값으로 설정하면 텔레메트리를 거부합니다. 대부분의 켜기/끄기 변수와 달리 **`0` 또는 `false`로 설정해도 여전히 거부됩니다**. 텔레메트리를 다시 켜려면 변수 설정을 해제합니다. 텔레메트리 이벤트에는 코드, 파일 경로, Bash 명령과 같은 사용자 데이터가 포함되지 않습니다. [기능 플래그 가져오기](#features-that-need-feature-flag-fetching)도 비활성화합니다. [조직의 텔레메트리 끄기](/docs/ko/managed-settings#turn-telemetry-off-for-your-organization)를 참조하세요 |473| `DISABLE_TELEMETRY` | 텔레메트리를 거부하려면 `1`과 같이 비어 있지 않은 아무 값으로 설정합니다. 대부분의 켜기/끄기 변수와 달리 **`0` 또는 `false`로 설정해도 여전히 거부됩니다**. 텔레메트리를 다시 켜려면 변수를 설정 해제합니다. 텔레메트리 이벤트에는 코드, 파일 경로, Bash 명령 같은 사용자 데이터가 포함되지 않습니다. [기능 플래그 가져오기](#features-that-need-feature-flag-fetching)도 비활성화합니다. [조직의 텔레메트리 끄기](/docs/ko/managed-settings#turn-telemetry-off-for-your-organization)를 참조하세요 |

468| `DISABLE_UPDATES` | `1`로 설정하면 수동 `claude update` 및 `claude install`을 포함한 모든 업데이트를 차단합니다. `DISABLE_AUTOUPDATER`보다 엄격합니다. 자체 채널을 통해 Claude Code를 배포하며 사용자가 직접 업데이트해서는 안 되는 경우 사용합니다 |474| `DISABLE_UPDATES` | 수동 `claude update` 및 `claude install`을 포함한 모든 업데이트를 차단하려면 `1`로 설정합니다. `DISABLE_AUTOUPDATER`보다 엄격합니다. 자체 채널을 통해 Claude Code를 배포하며 사용자가 직접 업데이트해서는 안 되는 경우에 사용합니다 |

470| `DO_NOT_TRACK` | `1`로 설정하면 텔레메트리를 거부하며, [기능 플래그 가져오기](#features-that-need-feature-flag-fetching)에 대한 영향을 포함하여 `DISABLE_TELEMETRY`와 같은 효과를 냅니다. Claude Code는 이 변수를 표준 불리언으로 읽으므로 `0`은 텔레메트리를 켜진 상태로 유지하며, 많은 개발자 CLI가 인식하는 도구 간 공통 규약으로 이 변수를 존중합니다 |476| `DO_NOT_TRACK` | 텔레메트리를 거부하려면 `1`로 설정합니다. [기능 플래그 가져오기](#features-that-need-feature-flag-fetching)에 대한 영향을 포함하여 `DISABLE_TELEMETRY`와 동일한 효과가 있습니다. Claude Code는 이 변수를 표준 불리언으로 읽으므로 `0`은 텔레메트리를 켠 상태로 유지하며, 많은 개발자 CLI가 인식하는 도구 간 공통 규칙으로서 이를 준수합니다 |

471| `ENABLE_BETA_TRACING_DETAILED` | `1`로 설정하고 `BETA_TRACING_ENDPOINT`를 OTLP/HTTP 수집기 엔드포인트로 설정하면 [상세 베타 추적](/docs/ko/monitoring-usage#traces-beta)이 켜지며, 콘텐츠를 포함하는 span 속성과 `claude_code.hook` span이 추가됩니다. 대화형 CLI 세션에서는 조직이 베타 허용 목록에 등록되어 있어야 합니다. 두 변수 모두 [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |477| `ENABLE_BETA_TRACING_DETAILED` | `1`로 설정하고 `BETA_TRACING_ENDPOINT`를 OTLP/HTTP 수집기 엔드포인트로 설정하면 [상세 베타 트레이싱](/docs/ko/monitoring-usage#traces-beta)이 켜지며, 콘텐츠를 포함하는 스팬 속성과 `claude_code.hook` 스팬이 추가됩니다. 대화형 CLI 세션에서는 조직이 베타 허용 목록에 포함되어 있어야 합니다. 두 변수 모두 [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |

472| `ENABLE_CLAUDEAI_MCP_SERVERS` | `false`로 설정하면 Claude Code가 [claude.ai MCP 서버](/docs/ko/mcp#use-mcp-servers-from-claude-ai)를 가져오지 않습니다. 로그인한 사용자에게는 기본적으로 활성화되어 있습니다. 프로젝트별 또는 조직별로 비활성화하려면 대신 설정에서 [`disableClaudeAiConnectors`](/docs/ko/settings-reference#disableclaudeaiconnectors)를 설정합니다 |478| `ENABLE_CLAUDEAI_MCP_SERVERS` | Claude Code가 [claude.ai MCP 서버](/docs/ko/mcp#use-mcp-servers-from-claude-ai)를 가져오지 않도록 하려면 `false`로 설정합니다. 로그인한 사용자에게는 기본적으로 활성화되어 있습니다. 프로젝트별 또는 조직별로 비활성화하려면 대신 설정에서 [`disableClaudeAiConnectors`](/docs/ko/settings-reference#disableclaudeaiconnectors)를 설정합니다 |

473| `ENABLE_PROMPT_CACHING_1H` | `1`로 설정하면 기본값인 5분 대신 1시간 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 요청합니다. API 키, [Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai), [Microsoft Foundry](/docs/ko/microsoft-foundry), [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 사용자를 위한 것입니다. 포함된 사용량 범위 내의 구독 사용자는 [메인 대화](/docs/ko/prompt-caching#which-ttl-each-request-gets)에서 1시간 TTL을 자동으로 받습니다. [사용량 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)을 사용하는 구독 사용자는 이 변수를 설정하여 1시간 TTL을 유지할 수 있습니다. 1시간 캐시 쓰기에는 더 높은 요금이 청구됩니다. 대신 요청 버킷별로 TTL을 선택하려면 `CLAUDE_CODE_PROMPT_CACHE_TTL`과 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`을 사용하며, 이들은 이 변수보다 우선합니다 |479| `ENABLE_PROMPT_CACHING_1H` | 기본값인 5분 대신 1시간 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 요청하려면 `1`로 설정합니다. API 키, [Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai), [Microsoft Foundry](/docs/ko/microsoft-foundry), [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 사용자를 위한 것입니다. 포함된 사용량 범위 내의 구독 사용자는 [메인 대화](/docs/ko/prompt-caching#which-ttl-each-request-gets)에서 1시간 TTL을 자동으로 받습니다. [사용량 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)을 사용하는 구독 사용자는 1시간 TTL을 유지하기 위해 이를 설정할 수 있습니다. 1시간 캐시 쓰기는 더 높은 요율로 청구됩니다. 대신 요청 버킷별로 TTL을 선택하려면 `CLAUDE_CODE_PROMPT_CACHE_TTL` 및 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`을 사용하며, 이들은 이 변수보다 우선합니다 |

475| `ENABLE_TOOL_SEARCH` | [MCP 도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)을 제어합니다. 설정하지 않으면 Claude Code는 기본적으로 모든 MCP 도구를 지연 로드합니다. 단, Claude 4.5 세대 이전의 Google Cloud's Agent Platform 모델, Azure에서 호스팅되는 Microsoft Foundry 배포, 그리고 `ANTHROPIC_BASE_URL`이 퍼스트파티가 아닌 호스트를 가리키는 경우에는 여전히 미리 로드합니다. `true`는 동일한 Agent Platform 모델과 Microsoft Foundry 배포를 제외하고 항상 지연 로드하며 베타 헤더를 보냅니다. `tool_reference`를 지원하지 않는 프록시에서는 요청이 실패합니다. `auto`는 도구 정의가 컨텍스트의 10% 이내에 들어가면 미리 로드합니다. `auto:N`은 사용자 지정 임곗값을 설정하며, 예를 들어 `auto:5`는 5%입니다. `false`는 모든 도구를 미리 로드합니다. `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`가 설정된 경우 직접 설정한 값은 무시됩니다. v2.1.221 이전에는 이 변수를 `true`로 설정하지 않는 한 Claude Code가 Google Cloud's Agent Platform의 모든 모델에서 도구 검색을 비활성화했습니다 |481| `ENABLE_TOOL_SEARCH` | [MCP 도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)을 제어합니다. 설정하지 않으면 Claude Code는 기본적으로 모든 MCP 도구를 지연 로드합니다. 단, Claude 4.5 세대 이전의 Google Cloud's Agent Platform 모델, Azure에서 호스팅되는 Microsoft Foundry 배포, 그리고 `ANTHROPIC_BASE_URL`이 퍼스트 파티가 아닌 호스트를 가리키는 경우에는 여전히 미리 로드합니다. `true`는 동일한 Agent Platform 모델과 Microsoft Foundry 배포를 제외하고 항상 지연 로드하고 베타 헤더를 보냅니다. `tool_reference`를 지원하지 않는 프록시에서는 요청이 실패합니다. `auto`는 도구 정의가 컨텍스트의 10% 이내에 들어갈 때 미리 로드합니다. `auto:N`은 `auto:5`(5%)처럼 사용자 지정 임계값을 설정합니다. `false`는 모든 도구를 미리 로드합니다. `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`가 설정되어 있으면 직접 설정한 값은 무시됩니다. v2.1.221 이전에는 이 변수를 `true`로 설정하지 않는 한 Claude Code가 Google Cloud's Agent Platform의 모든 모델에서 도구 검색을 비활성화했습니다 |

476| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | `1`과 같이 비어 있지 않은 값으로 설정하면, 폴백 모델이 구성되지 않은 경우 모든 모델에서 반복되는 과부하 오류에 대해 Claude Code가 재시도를 중단합니다. 대부분의 켜기/끄기 변수와 달리 **`0` 또는 `false`로 설정해도 여전히 활성화됩니다**. 기본 재시도 동작을 복원하려면 변수 설정을 해제합니다. 이 변수가 없으면 Claude Code는 Claude 구독이 아닌 API 키 또는 [서드파티 공급자](/docs/ko/third-party-integrations)로 인증한 경우 Opus, Fable 또는 Mythos 모델로 인식하는 모델에서만 이 방식으로 재시도를 중단합니다. Claude Code v2.1.160 이상에서는 모든 기본 모델에서 반복되는 과부하 오류가 발생하면 구성된 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)으로 전환하므로, 이 변수는 폴백 모델로의 전환에 영향을 주지 않습니다 |482| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 폴백 모델이 구성되지 않은 경우 모든 모델에 대해 반복되는 과부하 오류 시 Claude Code가 재시도를 중단하도록 하려면 `1`과 같이 비어 있지 않은 아무 값으로 설정합니다. 대부분의 켜기/끄기 변수와 달리 **`0` 또는 `false`로 설정해도 여전히 활성화됩니다**. 기본 재시도 동작을 복원하려면 변수를 설정 해제합니다. 이 변수가 없으면 Claude Code는 Claude 구독이 아닌 API 키 또는 [서드 파티 공급자](/docs/ko/third-party-integrations)로 인증할 때 Opus, Fable 또는 Mythos 모델로 인식하는 모델에서만 이런 방식으로 재시도를 중단합니다. Claude Code v2.1.160 이상에서는 모든 기본 모델에 대해 반복되는 과부하 오류 시 Claude Code가 구성된 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)으로 전환하므로, 이 변수는 폴백 모델로의 전환에 영향을 주지 않습니다 |

478| `FORCE_HYPERLINK` | 터미널이 클릭 가능한 OSC 8 하이퍼링크를 지원하지만 자동으로 감지되지 않는 경우 `1`로 설정하여 활성화하고, `0`으로 설정하면 비활성화합니다. 설정하지 않으면 Claude Code는 터미널 지원을 감지한 경우에만 하이퍼링크를 활성화합니다. Claude Code는 이 값을 불리언이 아닌 숫자로 해석하므로, `false`, `no`, `off` 같은 값은 하이퍼링크를 비활성화하지 않고 활성화합니다. 하단의 [PR 또는 병합 요청 배지](/docs/ko/interactive-mode#pr-review-status)는 SSH를 통한 경우처럼 Claude Code가 터미널 지원을 감지할 수 없을 때에도 하이퍼링크로 렌더링됩니다. 배지를 일반 텍스트로 렌더링하려면 `0`으로 설정합니다 |484| `FORCE_HYPERLINK` | 터미널이 클릭 가능한 OSC 8 하이퍼링크를 지원하지만 자동으로 감지되지 않을 때 이를 활성화하려면 `1`로, 비활성화하려면 `0`으로 설정합니다. 설정하지 않으면 Claude Code는 터미널 지원을 감지한 경우에만 하이퍼링크를 활성화합니다. Claude Code는 이 값을 불리언이 아닌 숫자로 파싱하므로, `false`, `no`, `off` 같은 값은 하이퍼링크를 비활성화하는 대신 활성화합니다. 하단의 [PR 또는 병합 요청 배지](/docs/ko/interactive-mode#pr-review-status)는 SSH를 통한 경우처럼 Claude Code가 터미널 지원을 감지하지 못할 때에도 하이퍼링크로 렌더링됩니다. 배지를 일반 텍스트로 렌더링하려면 `0`으로 설정합니다 |

479| `FORCE_PROMPT_CACHING_5M` | `1`로 설정하면 1시간 TTL이 적용될 상황에서도 5분 프롬프트 캐시 TTL을 강제합니다. `CLAUDE_CODE_PROMPT_CACHE_TTL`, `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, `ENABLE_PROMPT_CACHING_1H`, 그리고 `promptCacheTtl` 및 `subagentPromptCacheTtl` 설정을 재정의합니다 |485| `FORCE_PROMPT_CACHING_5M` | 1시간 TTL이 적용되는 경우에도 5분 프롬프트 캐시 TTL을 강제하려면 `1`로 설정합니다. `CLAUDE_CODE_PROMPT_CACHE_TTL`, `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, `ENABLE_PROMPT_CACHING_1H`, 그리고 `promptCacheTtl` 및 `subagentPromptCacheTtl` 설정을 재정의합니다 |

482| `IS_DEMO` | `1`과 같이 비어 있지 않은 값으로 설정하면 데모 모드를 활성화합니다. 헤더와 `/status` 출력에서 이메일과 조직 이름을 숨기고 온보딩을 건너뜁니다. 대부분의 켜기/끄기 변수와 달리 **`0` 또는 `false`로 설정해도 여전히 데모 모드가 활성화됩니다**. 끄려면 변수 설정을 해제합니다. 세션을 스트리밍하거나 녹화할 때 유용합니다 |488| `IS_DEMO` | 데모 모드를 활성화하려면 `1`과 같이 비어 있지 않은 아무 값으로 설정합니다. 데모 모드는 헤더와 `/status` 출력에서 이메일과 조직 이름을 숨기고 온보딩을 건너뜁니다. 대부분의 켜기/끄기 변수와 달리 **`0` 또는 `false`로 설정해도 여전히 데모 모드가 활성화됩니다**. 끄려면 변수를 설정 해제합니다. 세션을 스트리밍하거나 녹화할 때 유용합니다 |

483| `MAX_MCP_OUTPUT_TOKENS` | MCP 도구 응답에 허용되는 최대 토큰 수입니다(기본값: 25000). 출력이 10,000 토큰을 초과하면 Claude Code가 경고를 표시합니다. [`anthropic/maxResultSizeChars`](/docs/ko/mcp#raise-the-limit-for-a-specific-tool)를 선언한 도구는 텍스트 콘텐츠에 대해 대신 해당 문자 한도를 사용하지만, 이러한 도구의 이미지 콘텐츠에는 여전히 이 변수가 적용됩니다. 해당 어노테이션이 없는 도구에서 50,000자를 초과하는 성공한 텍스트 결과는 이 변수와 관계없이 [파일로 저장](/docs/ko/mcp#mcp-output-limits-and-warnings)됩니다 |489| `MAX_MCP_OUTPUT_TOKENS` | MCP 도구 응답에 허용되는 최대 토큰 수입니다(기본값: 25000). 출력이 10,000 토큰을 초과하면 Claude Code가 경고를 표시합니다. [`anthropic/maxResultSizeChars`](/docs/ko/mcp#raise-the-limit-for-a-specific-tool)를 선언하는 도구는 텍스트 콘텐츠에 대해 대신 해당 문자 한도를 사용하지만, 해당 도구의 이미지 콘텐츠에는 여전히 이 변수가 적용됩니다. 해당 어노테이션이 없는 도구에서 반환된 50,000자를 초과하는 성공적인 텍스트 결과는 이 변수와 관계없이 [파일로 저장됩니다](/docs/ko/mcp#mcp-output-limits-and-warnings) |

484| `MAX_STRUCTURED_OUTPUT_RETRIES` | `-p` 플래그를 사용한 비대화형 모드에서 모델의 응답이 [`--json-schema`](/docs/ko/cli-reference#cli-flags)에 대한 검증에 실패할 때 Claude Code가 허용하는 시도 횟수입니다. 유효한 출력 없이 그만큼 시도에 실패하면 실행이 실패합니다. [워크플로](/docs/ko/workflows) 서브에이전트의 구조화된 출력이 검증에 실패할 때도 같은 한도가 적용됩니다. 기본값은 5로, 첫 시도와 네 번의 재시도입니다 |490| `MAX_STRUCTURED_OUTPUT_RETRIES` | `-p` 플래그를 사용하는 비대화형 모드에서 모델의 응답이 [`--json-schema`](/docs/ko/cli-reference#cli-flags)에 대한 검증에 실패할 때 Claude Code가 허용하는 시도 횟수입니다. 유효한 출력 없이 해당 횟수만큼 실패하면 실행이 실패합니다. [워크플로](/docs/ko/workflows) 서브에이전트의 구조화된 출력이 검증에 실패할 때도 동일한 상한이 적용됩니다. 기본값은 5이며, 첫 시도와 네 번의 재시도입니다 |

485| `MAX_THINKING_TOKENS` | [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)를 위한 고정 토큰 예산입니다. Claude Code는 이 값을 요청의 최대 출력 토큰보다 1 토큰 적은 값으로 제한하며, 1,024 미만으로는 내리지 않습니다. 해당 한도가 설정되는 방식은 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`를 참조하세요. 설정하지 않고 사고가 활성화된 경우, [적응형 추론](/docs/ko/model-config#adjust-effort-level)을 지원하는 모델은 자체적으로 사고 깊이를 선택하고, 다른 모델은 한도를 사용합니다. Anthropic API에서 사고를 비활성화하려면 `0`으로 설정합니다. 단, 사고를 끌 수 없는 Opus 5.5, Sonnet 5.5, Haiku 5.5 및 Fable 모델은 예외입니다. [서드파티 공급자](/docs/ko/third-party-integrations)에서는 `0`이 대신 `thinking` 매개변수를 생략합니다. Anthropic API에서 사고가 꺼진 경우, Claude Code는 Opus 5와 같이 [해당 조합을 허용하지 않는](/docs/ko/errors#effort-isnt-available-with-thinking-turned-off) 것으로 알려진 모델에 더 높은 수준 대신 effort `high`를 보냅니다. 양수 값의 경우, `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`이 적응형 추론을 끄는 경우를 제외하고 Claude Code는 적응형 추론 모델에서 숫자 자체를 무시합니다 |491| `MAX_THINKING_TOKENS` | [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)를 위한 고정 토큰 예산입니다. Claude Code는 이 값을 요청의 최대 출력 토큰보다 1 토큰 적은 값으로 제한하며, 1,024 미만으로는 내려가지 않습니다. 해당 한도가 설정되는 방식은 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`를 참조하세요. 설정하지 않고 사고가 활성화된 경우, [적응형 추론](/docs/ko/model-config#adjust-effort-level)을 지원하는 모델은 자체적으로 사고 깊이를 선택하고 다른 모델은 상한을 사용합니다. Anthropic API에서 사고를 비활성화하려면 `0`으로 설정합니다. 단, 사고를 끌 수 없는 Opus 5.5, Sonnet 5.5, Haiku 5.5 및 Fable 모델은 예외입니다. [서드 파티 공급자](/docs/ko/third-party-integrations)에서는 `0`이 대신 `thinking` 매개변수를 생략합니다. Anthropic API에서 사고가 꺼진 상태에서는, Opus 5처럼 [해당 조합을 허용하지 않는](/docs/ko/errors#effort-isnt-available-with-thinking-turned-off) 것으로 알려진 모델에 대해 Claude Code가 더 높은 수준 대신 effort `high`를 보냅니다. 양수 값의 경우, `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`이 적응형 추론을 끄는 경우를 제외하고 Claude Code는 적응형 추론 모델에서 숫자 자체를 무시합니다 |

486| `MCP_CLIENT_SECRET` | [사전 구성된 자격 증명](/docs/ko/mcp#use-pre-configured-oauth-credentials)이 필요한 MCP 서버를 위한 OAuth 클라이언트 시크릿입니다. `--client-secret`으로 서버를 추가할 때 대화형 프롬프트를 생략할 수 있습니다 |492| `MCP_CLIENT_SECRET` | [사전 구성된 자격 증명](/docs/ko/mcp#use-pre-configured-oauth-credentials)이 필요한 MCP 서버를 위한 OAuth 클라이언트 시크릿입니다. `--client-secret`으로 서버를 추가할 때 대화형 프롬프트를 피할 수 있습니다 |

487| `MCP_CONNECTION_NONBLOCKING` | 시작 시 첫 쿼리 전에 MCP 서버 연결을 기다릴지 여부를 제어합니다. MCP 시작은 기본적으로 비차단 방식입니다. 서버는 백그라운드에서 연결되며, 연결이 완료되는 대로 해당 도구를 사용할 수 있게 됩니다. `0`으로 설정하면 Claude Code가 첫 쿼리 전에 서버 연결을 기다립니다. [`alwaysLoad: true`](/docs/ko/mcp#exempt-a-server-from-deferral)로 구성된 서버는 첫 프롬프트를 구성할 때 해당 도구가 있어야 하므로, [검색 캐시](/docs/ko/mcp#server-status-detail)에서 제공되는 경우를 제외하고 이 설정과 관계없이 시작을 기다리게 합니다. `--input-format stream-json` 없이 비대화형 모드(`-p`)로 실행하는 경우에도 Claude Code는 이 변수와 관계없이 첫 턴 전에 아직 대기 중인 서버를 기다립니다. [`--mcp-config`](/docs/ko/cli-reference#cli-flags)를 명시적으로 전달하면 대기 기한이 더 길어집니다. 캐시된 서버의 예외에 대해서는 해당 플래그 항목을 참조하세요 |493| `MCP_CONNECTION_NONBLOCKING` | 첫 쿼리 전에 시작 과정이 MCP 서버 연결을 기다릴지 여부를 제어합니다. MCP 시작은 기본적으로 비차단 방식입니다. 서버는 백그라운드에서 연결되며, 연결이 완료되는 대로 해당 도구를 사용할 수 있게 됩니다. 첫 쿼리 전에 Claude Code가 서버 연결을 기다리도록 하려면 `0`으로 설정합니다. [`alwaysLoad: true`](/docs/ko/mcp#exempt-a-server-from-deferral)로 구성된 서버는 첫 프롬프트가 구성될 때 해당 도구가 있어야 하므로, [검색 캐시](/docs/ko/mcp#server-status-detail)에서 제공되는 경우를 제외하고는 이 설정과 관계없이 여전히 시작을 대기시킵니다. `--input-format stream-json` 없이 비대화형 모드(`-p`)에서는 이 변수와 관계없이 Claude Code가 첫 턴 전에 아직 대기 중인 서버도 기다립니다. [`--mcp-config`](/docs/ko/cli-reference#cli-flags)를 명시적으로 전달하면 대기 기한이 더 길어집니다. 캐시된 서버 예외에 대해서는 해당 플래그 항목을 참조하세요 |

488| `MCP_CONNECT_TIMEOUT_MS` | 차단 방식의 MCP 시작이 도구 목록의 스냅샷을 만들기 전에 연결 배치를 기다리는 시간(밀리초)입니다(기본값: 5000). `MCP_CONNECTION_NONBLOCKING=0`인 경우 또는 [`alwaysLoad: true`](/docs/ko/mcp#exempt-a-server-from-deferral)로 표시된 서버에 적용됩니다. 기한까지 대기 중인 서버는 백그라운드에서 계속 연결됩니다. 개별 서버의 연결 시도를 제한하는 `MCP_TIMEOUT`과는 다릅니다 |494| `MCP_CONNECT_TIMEOUT_MS` | 차단 방식 MCP 시작이 도구 목록의 스냅샷을 만들기 전에 연결 배치를 기다리는 시간(밀리초)입니다(기본값: 5000). `MCP_CONNECTION_NONBLOCKING=0`이거나 [`alwaysLoad: true`](/docs/ko/mcp#exempt-a-server-from-deferral)로 표시된 서버에 적용됩니다. 기한에 아직 대기 중인 서버는 백그라운드에서 계속 연결됩니다. 개별 서버의 연결 시도를 제한하는 `MCP_TIMEOUT`과는 다릅니다 |

489| `MCP_DISCOVERY_CACHE` | [MCP 검색 캐시](/docs/ko/mcp#server-status-detail)를 켜거나 끕니다. 캐시가 켜져 있으면 이전에 사용한 원격 HTTP 또는 SSE 서버가 [`cached` 상태](/docs/ko/mcp#server-status-detail)로 표시될 수 있으며, Claude Code는 시작 시가 아니라 첫 도구 호출 시에 해당 서버를 연결합니다. 점진적 롤아웃으로 계정에 활성화되지 않은 한 캐시는 기본적으로 꺼져 있습니다. 켜려면 `1`로, 롤아웃으로 활성화된 경우에도 끈 상태로 유지하려면 `0`으로 설정합니다. v2.1.238 이전에는 캐시가 기본적으로 켜져 있었습니다. `cached` 상태에는 Claude Code v2.1.221 이상이 필요합니다 |495| `MCP_DISCOVERY_CACHE` | [MCP 검색 캐시](/docs/ko/mcp#server-status-detail)를 켜거나 끕니다. 캐시가 켜져 있으면 이전에 사용한 원격 HTTP 또는 SSE 서버가 [`cached` 상태](/docs/ko/mcp#server-status-detail)로 표시될 수 있으며, Claude Code는 시작 시가 아니라 첫 도구 호출 시 해당 서버에 연결합니다. 점진적 롤아웃으로 계정에 활성화되지 않은 한 캐시는 기본적으로 꺼져 있습니다. 켜려면 `1`로, 롤아웃으로 활성화된 경우에도 꺼진 상태로 유지하려면 `0`으로 설정합니다. v2.1.238 이전에는 캐시가 기본적으로 켜져 있었습니다. `cached` 상태에는 Claude Code v2.1.221 이상이 필요합니다 |

490| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [검색 캐시](/docs/ko/mcp#server-status-detail) 항목의 최대 수명(초)입니다 (기본값: 14400, 즉 4시간). 시작 시 항목이 이보다 오래된 경우, Claude Code는 캐시가 꺼져 있을 때처럼 항목을 폐기하고 시작 시 서버를 연결합니다. Claude Code는 이 값을 7일로 제한합니다. v2.1.238 이전에는 기본값이 86400, 즉 24시간이었으며 Claude Code가 값을 제한하지 않았습니다 |496| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [검색 캐시](/docs/ko/mcp#server-status-detail) 항목의 최대 수명(초)입니다(기본값: 14400, 즉 4시간). 항목이 그보다 오래된 상태로 시작하면 Claude Code는 캐시가 꺼져 있을 때처럼 항목을 폐기하고 시작 시 서버에 연결합니다. Claude Code는 값을 7일로 제한합니다. v2.1.238 이전에는 기본값이 86400, 즉 24시간이었으며 Claude Code가 값을 제한하지 않았습니다 |

491| `MCP_DISCOVERY_CACHE_STRIKES` | 시작 시 [검색 캐시](/docs/ko/mcp#server-status-detail) 항목이 `MCP_DISCOVERY_CACHE_TTL_S`보다 오래된 경우 Claude Code는 백그라운드에서 항목을 새로 고칩니다. 이 변수는 Claude Code가 항목을 폐기하고 다음 시작 시 서버를 연결하기 전까지 연속으로 실패할 수 있는 새로 고침 횟수를 설정합니다(기본값: 1). 네트워크 연결이 가끔 끊기는 경우, 한 번의 새로 고침 실패로 항목이 폐기되지 않도록 값을 높입니다. Claude Code v2.1.238 이상이 필요합니다 |497| `MCP_DISCOVERY_CACHE_STRIKES` | [검색 캐시](/docs/ko/mcp#server-status-detail) 항목이 `MCP_DISCOVERY_CACHE_TTL_S`보다 오래된 상태로 시작하면 Claude Code는 백그라운드에서 항목을 새로 고칩니다. 이 변수는 Claude Code가 항목을 폐기하고 다음 시작 시 서버에 연결하기 전까지 연속으로 실패할 수 있는 새로 고침 횟수를 설정합니다(기본값: 1). 네트워크 연결이 가끔 끊기는 경우 값을 높이면 한 번의 새로 고침 실패로 항목이 폐기되지 않습니다. Claude Code v2.1.238 이상이 필요합니다 |

492| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code가 [검색 캐시](/docs/ko/mcp#server-status-detail) 항목을 새로 고치지 않고 사용하는 시간(초)입니다(기본값: 900). 시작 시 항목이 이보다 오래된 경우, Claude Code는 항목을 계속 사용하지만 백그라운드에서 새로 고칩니다. 항목이 `MCP_DISCOVERY_CACHE_MAX_STALE_S`보다 오래되면 Claude Code는 대신 항목을 폐기합니다. Claude Code는 이 값을 `MCP_DISCOVERY_CACHE_MAX_STALE_S`(기본값 4시간)로 제한합니다. v2.1.238 이전에는 Claude Code가 값을 제한하지 않았습니다 |498| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code가 [검색 캐시](/docs/ko/mcp#server-status-detail) 항목을 새로 고치지 않고 사용하는 시간(초)입니다(기본값: 900). 항목이 그보다 오래된 상태로 시작하면 Claude Code는 여전히 항목을 사용하되 백그라운드에서 새로 고칩니다. 항목이 `MCP_DISCOVERY_CACHE_MAX_STALE_S`보다 오래되면 Claude Code는 대신 항목을 폐기합니다. Claude Code는 값을 `MCP_DISCOVERY_CACHE_MAX_STALE_S`(기본값 4시간)로 제한합니다. v2.1.238 이전에는 Claude Code가 값을 제한하지 않았습니다 |

493| `MCP_OAUTH_CALLBACK_PORT` | OAuth 리디렉션 콜백을 위한 고정 포트로, [사전 구성된 자격 증명](/docs/ko/mcp#use-pre-configured-oauth-credentials)으로 MCP 서버를 추가할 때 `--callback-port`의 대안으로 사용합니다 |499| `MCP_OAUTH_CALLBACK_PORT` | [사전 구성된 자격 증명](/docs/ko/mcp#use-pre-configured-oauth-credentials)으로 MCP 서버를 추가할 때 `--callback-port`의 대안으로 사용하는 OAuth 리디렉션 콜백용 고정 포트입니다 |

494| `MCP_PROTOCOL_NEGOTIATION` | [v2 MCP 클라이언트 런타임](/docs/ko/mcp#mcp-client-runtimes)에서만, Claude Code가 서버에 MCP 프로토콜 개정판 2026-07-28을 탐색할지 여부입니다. HTTP, claude.ai 커넥터, stdio 서버를 탐색하려면 `auto`로, 어떤 서버도 탐색하지 않으려면 `legacy`로 설정합니다. 변수를 설정하지 않으면 Claude Code는 [MCP 클라이언트 런타임](/docs/ko/mcp#mcp-client-runtimes)에 설명된 서버를 탐색합니다. 다른 값은 디버그 로그에 경고와 함께 무시됩니다. Claude Code v2.1.221 이상이 필요합니다 |500| `MCP_PROTOCOL_NEGOTIATION` | [v2 MCP 클라이언트 런타임](/docs/ko/mcp#mcp-client-runtimes)에서만, Claude Code가 MCP 프로토콜 리비전 2026-07-28에 대해 서버를 탐색할지 여부입니다. HTTP, claude.ai 커넥터, stdio 서버를 탐색하려면 `auto`로, 아무것도 탐색하지 않으려면 `legacy`로 설정합니다. 변수를 설정하지 않으면 Claude Code는 [MCP 클라이언트 런타임](/docs/ko/mcp#mcp-client-runtimes)에 설명된 서버를 탐색합니다. 기타 값은 디버그 로그에 경고와 함께 무시됩니다. Claude Code v2.1.221 이상이 필요합니다 |

496| `MCP_SDK_GENERATION` | 이 프로세스가 MCP 서버에 연결할 때 사용하는 [MCP 클라이언트 런타임](/docs/ko/mcp#mcp-client-runtimes)을 고정합니다. MCP TypeScript SDK 1.x 기반의 `v1` 또는 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 기반의 `v2`를 지정합니다. 이 변수가 없으면 Claude Code는 해당 섹션에 나열된 버전부터 v2를 사용합니다. Claude Code v2.1.221 이상에서 v2 런타임은 MCP OAuth 서버가 인가 응답에서 반환하는 발급자를 확인하며, 일치하지 않으면 `Issuer mismatch in authorization response`로 시작하는 오류와 함께 로그인에 실패합니다. v1 런타임은 이 확인을 수행하지 않습니다. 인식할 수 없는 값을 설정하면 Claude Code는 이를 무시하고 디버그 로그에 경고를 기록합니다. Claude Code는 프로세스당 한 번 값을 읽습니다. Claude Code v2.1.218 이상이 필요합니다 |502| `MCP_SDK_GENERATION` | 이 프로세스가 MCP 서버에 연결할 때 사용할 [MCP 클라이언트 런타임](/docs/ko/mcp#mcp-client-runtimes)을 고정합니다. MCP TypeScript SDK 1.x 기반의 `v1` 또는 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 기반의 `v2`입니다. 변수가 없으면 Claude Code는 해당 섹션에 나열된 버전부터 v2를 사용합니다. Claude Code v2.1.221 이상에서 v2 런타임은 MCP OAuth 서버가 인가 응답에서 반환하는 발급자를 확인하고, 일치하지 않으면 `Issuer mismatch in authorization response`로 시작하는 오류와 함께 로그인을 실패시킵니다. v1 런타임은 이 확인을 실행하지 않습니다. 인식할 수 없는 값을 설정하면 Claude Code는 이를 무시하고 디버그 로그에 경고를 기록합니다. Claude Code는 프로세스당 한 번 값을 읽습니다. Claude Code v2.1.218 이상이 필요합니다 |

499| `MCP_TOOL_TIMEOUT` | MCP 도구 실행 타임아웃(밀리초)입니다(기본값: 100000000, 약 28시간). HTTP, SSE 또는 claude.ai 커넥터 서버의 경우 각 요청도 기본적으로 60초 후 시간 초과됩니다. 이 요청별 한도를 높이려면 이 변수 또는 서버별 `timeout`을 60000보다 크게 설정합니다. 더 낮은 값은 전체 도구 실행 타임아웃을 여전히 단축하지만 요청별 한도는 60초로 유지됩니다. Stdio 및 WebSocket 서버에는 요청별 타이머가 없습니다. `.mcp.json`의 서버별 `timeout` 필드는 해당 서버에 대해 이 값을 재정의합니다. 1000 이상의 서버별 `timeout`은 해당 서버의 도구 호출에 대한 최소 유휴 구간도 설정하므로, `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`이 이보다 먼저 호출을 중단하지 않습니다. 이 하한에는 Claude Code v2.1.203 이상이 필요합니다. 환경 변수의 경우 1000 미만의 값은 1초로 올림 처리되며, 서버별 필드의 경우 1000 미만의 값은 무시됩니다 |505| `MCP_TOOL_TIMEOUT` | MCP 도구 실행에 대한 타임아웃(밀리초)입니다(기본값: 100000000, 약 28시간). HTTP, SSE 또는 claude.ai 커넥터 서버의 경우 각 요청도 기본적으로 60초 후 시간 초과됩니다. 해당 요청별 한도를 높이려면 이 변수 또는 서버별 `timeout`을 60000보다 크게 설정합니다. 더 낮은 값은 전체 도구 실행 타임아웃을 줄이지만 요청별 한도는 60초로 유지됩니다. stdio 및 WebSocket 서버에는 요청별 타이머가 없습니다. `.mcp.json`의 서버별 `timeout` 필드는 해당 서버에 대해 이 값을 재정의합니다. 1000 이상의 서버별 `timeout`은 해당 서버의 도구 호출에 대한 최소 유휴 기간도 설정하므로, `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`이 그보다 빨리 중단하지 않습니다. 이 하한에는 Claude Code v2.1.203 이상이 필요합니다. 환경 변수의 경우 1000 미만의 값은 1초로 올림 처리되며, 서버별 필드의 경우 1000 미만의 값은 무시됩니다 |

501| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 속성 값 길이에 대한 표준 OpenTelemetry SDK 한도입니다. Claude Code는 콘텐츠를 포함하는 텔레메트리 속성을 이 값과 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 중 더 작은 값으로 제한하여, 잘림 표시가 SDK 한도 안에 머물도록 합니다. Claude Code는 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 및 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 변형도 같은 방식으로 읽으며, 설정된 값 중 가장 작은 값이 모든 신호에 적용됩니다. Claude Code v2.1.214 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage#common-configuration-variables)을 참조하세요 |507| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 속성 값 길이에 대한 표준 OpenTelemetry SDK 한도입니다. Claude Code는 잘림 표시가 SDK 한도 내에 유지되도록 콘텐츠를 포함하는 텔레메트리 속성을 이 값과 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 중 더 작은 값으로 제한합니다. Claude Code는 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 및 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 변형도 같은 방식으로 읽으며, 설정된 값 중 가장 작은 값이 모든 신호에 적용됩니다. Claude Code v2.1.214 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage#common-configuration-variables)을 참조하세요 |

502| `OTEL_LOG_ASSISTANT_RESPONSES` | `1`로 설정하면 `assistant_response` OpenTelemetry 로그 이벤트에 모델의 응답 텍스트를 포함합니다. 설정하지 않으면 Claude Code는 대신 `OTEL_LOG_USER_PROMPTS`의 값을 사용합니다. `OTEL_LOG_USER_PROMPTS`가 설정된 경우에도 응답을 가린 상태로 유지하려면 `0`으로 설정합니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. Claude Code v2.1.193 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage#assistant-response-event)을 참조하세요 |508| `OTEL_LOG_ASSISTANT_RESPONSES` | `assistant_response` OpenTelemetry 로그 이벤트에 모델의 응답 텍스트를 포함하려면 `1`로 설정합니다. 설정하지 않으면 Claude Code는 대신 `OTEL_LOG_USER_PROMPTS`의 값을 사용합니다. `OTEL_LOG_USER_PROMPTS`가 설정된 경우에도 응답을 가린 상태로 유지하려면 `0`으로 설정합니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. Claude Code v2.1.193 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage#assistant-response-event)을 참조하세요 |

503| `OTEL_LOG_MANAGED_SETTINGS` | `1`로 설정하면 가려진 관리형 설정과, 가리기 전 설정의 SHA-256 다이제스트를 `managed_settings_resolved` OpenTelemetry 로그 이벤트에 추가합니다. 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 프로젝트 또는 로컬 설정의 값으로는 켜지지 않습니다. Claude Code v2.1.274 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage#managed-settings-resolved-event)을 참조하세요 |509| `OTEL_LOG_MANAGED_SETTINGS` | `managed_settings_resolved` OpenTelemetry 로그 이벤트에 가려진 관리형 설정과 가리기 전 설정의 SHA-256 다이제스트를 추가하려면 `1`로 설정합니다. 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 프로젝트 또는 로컬 설정의 값으로는 켜지지 않습니다. Claude Code v2.1.274 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage#managed-settings-resolved-event)을 참조하세요 |

504| `OTEL_LOG_RAW_API_BODIES` | Anthropic Messages API 요청 및 응답 JSON을 `api_request_body` / `api_response_body` 로그 이벤트로 내보냅니다. 콘텐츠 한도에서 잘린 인라인 본문을 원하면 `1`로, 잘리지 않은 본문을 디스크에 쓰고 대신 `body_ref` 경로를 내보내려면 `file:<dir>`로 설정합니다. `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH`가 콘텐츠 한도를 구성하며, 기본값은 60 KB입니다. 기본적으로 비활성화되어 있으며, 본문에는 전체 대화 기록이 포함됩니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage#api-request-body-event)을 참조하세요 |510| `OTEL_LOG_RAW_API_BODIES` | Anthropic Messages API 요청 및 응답 JSON을 `api_request_body` / `api_response_body` 로그 이벤트로 내보냅니다. 콘텐츠 한도에서 잘린 인라인 본문을 원하면 `1`로, 잘리지 않은 본문을 디스크에 기록하고 대신 `body_ref` 경로를 내보내려면 `file:<dir>`로 설정합니다. `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH`가 콘텐츠 한도를 구성하며, 기본값은 60KB입니다. 기본적으로 비활성화되어 있으며, 본문에는 전체 대화 기록이 포함됩니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage#api-request-body-event)을 참조하세요 |

505| `OTEL_LOG_TOOL_CONTENT` | `1`로 설정하면 `tool.output` OpenTelemetry span 이벤트에 도구 콘텐츠를 포함합니다. span 속성은 [자체 게이트](/docs/ko/monitoring-usage#new-context-gates)에 따라 도구 콘텐츠를 전달합니다. [추적](/docs/ko/monitoring-usage#traces-beta)이 필요합니다. 민감한 데이터를 보호하기 위해 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage#tool-output-span-event)을 참조하세요 |511| `OTEL_LOG_TOOL_CONTENT` | `tool.output` OpenTelemetry 스팬 이벤트에 도구 콘텐츠를 포함하려면 `1`로 설정합니다. 스팬 속성은 [자체 게이트](/docs/ko/monitoring-usage#new-context-gates)에 따라 도구 콘텐츠를 포함합니다. [트레이싱](/docs/ko/monitoring-usage#traces-beta)이 필요합니다. 민감한 데이터를 보호하기 위해 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage#tool-output-span-event)을 참조하세요 |

506| `OTEL_LOG_TOOL_DETAILS` | `1`로 설정하면 OpenTelemetry 메트릭, 추적, 로그에 도구 입력 인수, MCP 서버 이름, 사용자가 작성한 워크플로 이름, 도구 실패 시의 원시 오류 문자열, `api_refusal` 이벤트의 거부 `category`, [비용 및 토큰 메트릭](/docs/ko/monitoring-usage#cost-counter)의 실제 에이전트, 스킬, 플러그인, MCP 서버 이름 및 기타 도구 세부 정보를 포함합니다. PII를 보호하기 위해 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |512| `OTEL_LOG_TOOL_DETAILS` | OpenTelemetry 메트릭, 트레이스, 로그에 도구 입력 인수, MCP 서버 이름, 사용자가 작성한 워크플로 이름, 도구 실패 시 원시 오류 문자열, `api_refusal` 이벤트의 거부 `category`, [비용 및 토큰 메트릭](/docs/ko/monitoring-usage#cost-counter)의 실제 에이전트, 스킬, 플러그인, MCP 서버 이름, 기타 도구 세부 정보를 포함하려면 `1`로 설정합니다. PII를 보호하기 위해 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

507| `OTEL_LOG_USER_PROMPTS` | `1`로 설정하면 OpenTelemetry 추적 및 로그에 사용자 프롬프트 텍스트를 포함합니다. 기본적으로 비활성화되어 있습니다(프롬프트가 가려짐). 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |513| `OTEL_LOG_USER_PROMPTS` | OpenTelemetry 트레이스와 로그에 사용자 프롬프트 텍스트를 포함하려면 `1`로 설정합니다. 기본적으로 비활성화되어 있습니다(프롬프트가 가려짐). 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

508| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | `false`로 설정하면 메트릭 속성에서 계정 UUID를 제외합니다(기본값: 포함). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |514| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | 메트릭 속성에서 계정 UUID를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

509| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | `true`로 설정하면 메트릭 속성에 세션 진입점을 포함합니다(기본값: 제외). v2.1.152에서 추가되었습니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |515| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 메트릭 속성에 세션 진입점을 포함하려면 `true`로 설정합니다(기본값: 제외). v2.1.152에서 추가되었습니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

510| `OTEL_METRICS_INCLUDE_REPOSITORY` | `true`로 설정하면 세션의 저장소를 식별하는 `vcs.*` 속성으로 OpenTelemetry 메트릭과 이벤트에 태그를 지정합니다(기본값: 제외). Claude Code v2.1.269 이상이 필요합니다. [저장소 속성](/docs/ko/monitoring-usage#repository-attributes)을 참조하세요 |516| `OTEL_METRICS_INCLUDE_REPOSITORY` | 세션의 저장소를 식별하는 `vcs.*` 속성으로 OpenTelemetry 메트릭과 이벤트에 태그를 지정하려면 `true`로 설정합니다(기본값: 제외). Claude Code v2.1.269 이상이 필요합니다. [저장소 속성](/docs/ko/monitoring-usage#repository-attributes)을 참조하세요 |

511| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | v2.1.161부터 Claude Code는 `OTEL_RESOURCE_ATTRIBUTES` 키를 메트릭 데이터 포인트 레이블에 첨부합니다. 이를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/docs/ko/monitoring-usage#multi-team-organization-support)을 참조하세요 |517| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | v2.1.161부터 Claude Code는 `OTEL_RESOURCE_ATTRIBUTES` 키를 메트릭 데이터 포인트 레이블에 첨부합니다. 이를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/docs/ko/monitoring-usage#multi-team-organization-support)을 참조하세요 |

512| `OTEL_METRICS_INCLUDE_SESSION_ID` | `false`로 설정하면 메트릭 속성에서 세션 ID를 제외합니다(기본값: 포함). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |518| `OTEL_METRICS_INCLUDE_SESSION_ID` | 메트릭 속성에서 세션 ID를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

513| `OTEL_METRICS_INCLUDE_VERSION` | `true`로 설정하면 메트릭 속성에 Claude Code 버전을 포함합니다(기본값: 제외). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |519| `OTEL_METRICS_INCLUDE_VERSION` | 메트릭 속성에 Claude Code 버전을 포함하려면 `true`로 설정합니다(기본값: 제외). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

514| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | [Skill 도구](/docs/ko/skills#control-who-invokes-a-skill)에 표시되는 스킬 메타데이터의 문자 예산을 재정의합니다. 예산은 컨텍스트 윈도우의 1%로 동적으로 조정되며, 폴백 값은 8,000자입니다. 하위 호환성을 위해 기존 이름이 유지됩니다 |520| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | [Skill 도구](/docs/ko/skills#control-who-invokes-a-skill)에 표시되는 스킬 메타데이터의 문자 예산을 재정의합니다. 예산은 컨텍스트 윈도우의 1%로 동적으로 조정되며, 폴백 값은 8,000자입니다. 하위 호환성을 위해 유지되는 레거시 이름입니다 |

515| `TASK_MAX_OUTPUT_LENGTH` | v2.1.277에서 이 변수가 크기를 지정하던 `TaskOutput` 도구와 함께 제거되어 이제 아무 효과가 없습니다. 이전에는 `TaskOutput` 도구가 보관하는 [백그라운드 작업](/docs/ko/tools-reference#background-commands) 출력의 최대 문자 수를 설정했습니다. 이제 Claude는 대신 `Read`로 백그라운드 작업의 출력 파일을 읽습니다 |521| `TASK_MAX_OUTPUT_LENGTH` | v2.1.277에서 이 변수가 크기를 지정하던 `TaskOutput` 도구와 함께 제거되었으며 이제 아무 작업도 수행하지 않습니다. 이전에는 `TaskOutput` 도구가 유지하는 [백그라운드 작업](/docs/ko/tools-reference#background-commands) 출력의 최대 문자 수를 설정했습니다. 이제 Claude는 대신 `Read`로 백그라운드 작업의 출력 파일을 읽습니다 |

537 543

538표준 OpenTelemetry 익스포터 변수(`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES` 및 신호별 변형)도 지원됩니다. 구성 세부 정보는 [모니터링](/docs/ko/monitoring-usage)을 참조하세요.544표준 OpenTelemetry 익스포터 변수(`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES` 및 신호별 변형)도 지원됩니다. 구성 세부 정보는 [모니터링](/docs/ko/monitoring-usage)을 참조하세요.

539 545

540`CLAUDE_CODE_ENABLE_TELEMETRY`와, 내보내기를 켜거나 대상을 선택하거나 콘텐츠를 캡처하는 OpenTelemetry 변수는 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. Claude Code는 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정에서 이 변수들을 무시합니다](/docs/ko/settings-reference#variables-claude-code-ignores-in-env). `OTEL_RESOURCE_ATTRIBUTES`와 `OTEL_METRIC_EXPORT_INTERVAL` 같은 내보내기 간격, 타임아웃, 압축 변수는 프로젝트 및 로컬 설정에서도 여전히 적용됩니다.546`CLAUDE_CODE_ENABLE_TELEMETRY`와 내보내기를 켜거나, 대상을 선택하거나, 콘텐츠를 캡처하는 OpenTelemetry 변수는 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. Claude Code는 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정에서 이들을 무시합니다](/docs/ko/settings-reference#variables-claude-code-ignores-in-env). `OTEL_RESOURCE_ATTRIBUTES`와 `OTEL_METRIC_EXPORT_INTERVAL` 같은 내보내기 간격, 타임아웃, 압축 변수는 프로젝트 및 로컬 설정에서도 계속 적용됩니다.

541 547

542<h2 id="what-the-subprocess-environment-scrub-removes">548<h2 id="what-the-subprocess-environment-scrub-removes">

543 하위 프로세스 환경 정리가 제거하는 항목549 하위 프로세스 환경 정리가 제거하는 항목

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

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

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

593* `MCP_PROTOCOL_NEGOTIATION=auto`를 설정하지 않은 경우, Claude Code가 claude.ai 커넥터 서버에 대해 [MCP 프로토콜 개정판 2026-07-28](/docs/ko/mcp#mcp-client-runtimes) 지원 여부를 확인하도록 하기

594* Git Bash가 설치된 Windows에서 claude.ai 및 Console 계정에 기본적으로 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 제공받기. `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`을 설정하지 않으면 Claude Code는 셸 명령을 Git Bash를 통해 실행합니다. Git Bash가 없는 Windows에서는 이 도구가 계속 켜져 있습니다599* Git Bash가 설치된 Windows에서 claude.ai 및 Console 계정에 기본적으로 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 제공받기. `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`을 설정하지 않으면 Claude Code는 셸 명령을 Git Bash를 통해 실행합니다. Git Bash가 없는 Windows에서는 이 도구가 계속 켜져 있습니다

595* [Claude가 초안을 작성한 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior) 받기. 이 기능은 Claude Code가 가져온 플래그를 통해 켭니다600* [Claude가 초안을 작성한 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior) 받기. 이 기능은 Claude Code가 가져온 플래그를 통해 켭니다

596* Claude가 [큰 붙여넣기를 입력한 텍스트가 아닌 붙여넣은 텍스트로 취급](/docs/ko/terminal-config#how-claude-treats-pasted-text)하도록 하기. `[Pasted text #N]` 플레이스홀더 뒤의 내용은 표시 없이 Claude에 전달됩니다601* Claude가 [큰 붙여넣기를 입력한 텍스트가 아닌 붙여넣은 텍스트로 취급](/docs/ko/terminal-config#how-claude-treats-pasted-text)하도록 하기. `[Pasted text #N]` 플레이스홀더 뒤의 내용은 표시 없이 Claude에 전달됩니다

errors.md +9 −54

Details

189| `<model> has safety measures that flagged this message for a cybersecurity topic` | [요청 오류](#safety-measures-flagged-a-cybersecurity-topic) |189| `<model> has safety measures that flagged this message for a cybersecurity topic` | [요청 오류](#safety-measures-flagged-a-cybersecurity-topic) |

192| `Installation was killed before it could finish (exit code 137)` | [설치 오류](#installation-was-killed-before-it-could-finish) |192| `Installation was killed before it could finish (exit code 137)` | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#installation-was-killed-before-it-could-finish) |

193| `The connection dropped while downloading the update` | [설치 오류](#the-connection-dropped-while-downloading-the-update) |193| `The connection dropped while downloading the update` | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |

194| `Download timed out: exceeded the total deadline` | [설치 오류](#the-connection-dropped-while-downloading-the-update) |194| `Download timed out: exceeded the total deadline` | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |

196| `Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.` | [명령줄 오류](#conflict-between-a-system-prompt-flag-and-its-file-form) |196| `Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.` | [명령줄 오류](#conflict-between-a-system-prompt-flag-and-its-file-form) |

197| `Cloud sessions cannot be created from a --restricted session` | [명령줄 오류](#cloud-sessions-cannot-be-created-from-a-restricted-session) |197| `Cloud sessions cannot be created from a --restricted session` | [명령줄 오류](#cloud-sessions-cannot-be-created-from-a-restricted-session) |

261| `Marketplace name impersonates an official Anthropic/Claude marketplace` | [플러그인 오류](#claude-code-refuses-the-marketplace-name) |261| `Marketplace name impersonates an official Anthropic/Claude marketplace` | [플러그인 오류](#claude-code-refuses-the-marketplace-name) |

262| `Marketplace "<name>" is already added from a different source` | [플러그인 오류](#marketplace-is-already-added-from-a-different-source) |262| `Marketplace "<name>" is already added from a different source` | [플러그인 오류](#marketplace-is-already-added-from-a-different-source) |

263| `"<name>" is another spelling of "<reserved>", a reserved marketplace name` | [플러그인 오류](#marketplace-name-is-another-spelling-of-a-reserved-name) |263| `"<name>" is another spelling of "<reserved>", a reserved marketplace name` | [플러그인 오류](#marketplace-name-is-another-spelling-of-a-reserved-name) |

264| `Cannot add marketplace "<name>": Claude Code cannot install plugins from a marketplace with this name` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#cannot-install-plugins-from-a-marketplace-with-this-name) |

264| `Marketplace "<name>" is added but ignored` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#marketplace-is-added-but-ignored) |265| `Marketplace "<name>" is added but ignored` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#marketplace-is-added-but-ignored) |

265| `Marketplace "<name>" is registered but was refused (see the debug log)` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#marketplace-is-added-but-ignored) |266| `Marketplace "<name>" is registered but was refused (see the debug log)` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#marketplace-is-added-but-ignored) |

266| `references ${user_config.*} in a shell-form command` | [플러그인 오류](#plugin-command-references-user-config) |267| `references ${user_config.*} in a shell-form command` | [플러그인 오류](#plugin-command-references-user-config) |

270| `An npm plugin source must name a registry package` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#an-npm-plugin-source-must-name-a-registry-package) |271| `An npm plugin source must name a registry package` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#an-npm-plugin-source-must-name-a-registry-package) |

271| `The packages it lists are not installed` / `The packages it lists were not installed, because` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#the-packages-it-lists-are-not-installed) |272| `The packages it lists are not installed` / `The packages it lists were not installed, because` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#the-packages-it-lists-are-not-installed) |

273| `does not load (...), so Claude Code ignores the whole file` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#does-not-load-so-claude-code-ignores-the-whole-file) |

274| `its marketplace entry path does not stay inside the marketplace directory` | [플러그인 오류](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |276| `its marketplace entry path does not stay inside the marketplace directory` | [플러그인 오류](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |

281| `Plugin "<plugin>" was not uninstalled: installed_plugins.json` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#installed-plugins-json-holds-a-record-this-version-cannot-read) |283| `Plugin "<plugin>" was not uninstalled: installed_plugins.json` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#installed-plugins-json-holds-a-record-this-version-cannot-read) |

284| `Plugin directory does not exist: <path>` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#plugin-directory-does-not-exist) |

386* Claude가 사고를 마친 후 텍스트나 도구 호출을 시작하기 전에 발생한 서버 오류 또는 과부하 응답. 이 시점의 서버 오류는 최대 2회까지 재시도합니다. v2.1.284 이전에는 이 시점에서 Claude Code가 오류와 함께 턴을 종료했습니다.389* Claude가 사고를 마친 후 텍스트나 도구 호출을 시작하기 전에 발생한 서버 오류 또는 과부하 응답. 이 시점의 서버 오류는 최대 2회까지 재시도합니다. v2.1.284 이전에는 이 시점에서 Claude Code가 오류와 함께 턴을 종료했습니다.

387* 끊어진 연결. Claude가 사고를 포함하여 응답의 어떤 부분도 완료하기 전에 요청 도중 연결이 끊어지면, 일부 텍스트가 이미 스트리밍되기 시작했더라도 Claude Code는 동일한 백오프로 요청을 다시 보내고 턴이 계속됩니다. Claude가 사고를 마친 후 텍스트나 도구 호출을 시작하기 전에 연결이 끊어지면, Claude Code는 대신 요청을 빠르게 연달아 최대 2회 다시 보내며, 이 시점에서 연결이 계속 끊어지면 `Connection lost before a response was produced`와 함께 턴을 종료합니다.390* 끊어진 연결. Claude가 사고를 포함하여 응답의 어떤 부분도 완료하기 전에 요청 도중 연결이 끊어지면, 일부 텍스트가 이미 스트리밍되기 시작했더라도 Claude Code는 동일한 백오프로 요청을 다시 보내고 턴이 계속됩니다. Claude가 사고를 마친 후 텍스트나 도구 호출을 시작하기 전에 연결이 끊어지면, Claude Code는 대신 요청을 빠르게 연달아 최대 2회 다시 보내며, 이 시점에서 연결이 계속 끊어지면 `Connection lost before a response was produced`와 함께 턴을 종료합니다.

388* 요청 도중 컴퓨터가 절전 모드로 전환되어 연결이 끊어졌다고 Claude Code가 감지한 경우. Claude Code는 이를 위 규칙에 따른 끊어진 연결로 간주합니다. 재시도 레이블에 구체적인 이유가 표시되면 `Connection lost while your computer was asleep`로 표시되며, Claude가 사고를 마친 후 텍스트나 도구 호출 전에 턴이 종료되면 메시지는 `Your computer went to sleep before a response was produced`로 표시됩니다.391* 요청 도중 컴퓨터가 절전 모드로 전환되어 연결이 끊어졌다고 Claude Code가 감지한 경우. Claude Code는 이를 위 규칙에 따른 끊어진 연결로 간주합니다. 재시도 레이블에 구체적인 이유가 표시되면 `Connection lost while your computer was asleep`로 표시되며, Claude가 사고를 마친 후 텍스트나 도구 호출 전에 턴이 종료되면 메시지는 `Your computer went to sleep before a response was produced`로 표시됩니다.

389* 응답 헤더는 도착했지만 Claude의 응답이 전혀 도착하지 않았거나, Claude가 사고를 마쳤지만 텍스트나 도구 호출을 시작하지 않은 상태에서 멈춘 응답 스트림: Claude Code는 멈춘 연결을 중단하고 위의 10회 재시도 예산과 별도로 요청을 최대 1회 다시 보냅니다. Claude가 사고를 마친 후 텍스트나 도구 호출 전에 응답이 두 번째로 멈추면, Claude Code는 `The response stalled before a response was produced`와 함께 턴을 종료합니다.392* 응답 헤더는 도착했지만 Claude의 응답이 전혀 도착하지 않았거나, Claude가 사고를 마쳤지만 텍스트나 도구 호출을 시작하지 않은 상태에서 멈춘 응답 스트림: Claude Code는 멈춘 연결을 중단하고 요청을 최대 1회 다시 스트리밍합니다. Claude가 사고를 마친 후 텍스트나 도구 호출 전에 응답이 두 번째로 멈추면, Claude Code는 `The response stalled before a response was produced`와 함께 턴을 종료합니다.

390* [첫 바이트 기한이 적용되는](/docs/ko/network-config#streaming-idle-watchdogs) 연결에서 API가 응답 헤더로 전혀 응답하지 않는 스트리밍 요청: Claude Code는 기한에 도달하면 요청을 중단하고 재시도 예산 내에서 모델 요청당 최대 1회 다시 보내며, 그 시도에도 응답이 없으면 [No response from API](#no-response-from-api)와 함께 턴을 종료합니다. 다른 연결에서는 요청이 `API_TIMEOUT_MS`만큼 기다립니다. `CLAUDE_CODE_RETRY_WATCHDOG`을 설정하면 1회 재시도 상한이 적용되지 않습니다.393* [첫 바이트 기한이 적용되는](/docs/ko/network-config#streaming-idle-watchdogs) 연결에서 API가 응답 헤더로 전혀 응답하지 않는 스트리밍 요청: Claude Code는 기한에 도달하면 요청을 중단하고 재시도 예산 내에서 모델 요청당 최대 1회 다시 보내며, 그 시도에도 응답이 없으면 [No response from API](#no-response-from-api)와 함께 턴을 종료합니다. 다른 연결에서는 요청이 `API_TIMEOUT_MS`만큼 기다립니다. `CLAUDE_CODE_RETRY_WATCHDOG`을 설정하면 1회 재시도 상한이 적용되지 않습니다.

391* Claude가 사고를 마치거나 텍스트 또는 도구 호출을 시작하기 전에 API의 출력 콘텐츠 필터가 중단시킨 스트리밍 응답. Claude Code는 재시도 예산 내에서 요청을 1회 다시 보내며, 필터가 두 번째 응답도 중단시키면 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)를 표시합니다.394* Claude가 사고를 마치거나 텍스트 또는 도구 호출을 시작하기 전에 API의 출력 콘텐츠 필터가 중단시킨 스트리밍 응답. Claude Code는 재시도 예산 내에서 요청을 1회 다시 보내며, 필터가 두 번째 응답도 중단시키면 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)를 표시합니다.

392* 일시적인 429 스로틀. 단, 게이트웨이의 지출 한도 `429`는 스로틀이 아니므로 제외됩니다. [Spend limit reached](#spend-limit-reached)를 참조하세요.395* 일시적인 429 스로틀. 단, 게이트웨이의 지출 한도 `429`는 스로틀이 아니므로 제외됩니다. [Spend limit reached](#spend-limit-reached)를 참조하세요.

2910* 마지막 메시지를 다르게 표현하거나 다른 접근 방식을 취합니다.2913* 마지막 메시지를 다르게 표현하거나 다른 접근 방식을 취합니다.

2911* 차단을 트리거한 턴 이전의 체크포인트로 되돌아가려면 Esc를 두 번 누르거나 `/rewind`를 실행합니다. [체크포인트](/docs/ko/checkpointing)를 참조하십시오.2914* 차단을 트리거한 턴 이전의 체크포인트로 되돌아가려면 Esc를 두 번 누르거나 `/rewind`를 실행합니다. [체크포인트](/docs/ko/checkpointing)를 참조하십시오.

2912 2915

2913<h2 id="installation-errors">

2914 설치 오류

2915</h2>

~~2916~~

2917이러한 오류는 Claude Code를 설치하거나 업데이트할 때 [설치 스크립트](/docs/ko/setup#install-claude-code), `claude install` 또는 `claude update`에서 나타납니다. 설정 중 `command not found`, PATH, 권한 및 TLS 문제의 경우 [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install)을 참조하십시오.

~~2918~~

2919<h3 id="installation-was-killed-before-it-could-finish">

2920 설치가 완료되기 전에 중단되었습니다

2921</h3>

~~2922~~

2923설치 스크립트는 `claude install` 단계가 신호에 의해 종료될 때 보고합니다. Linux에서 종료 코드 137은 프로세스가 SIGKILL을 수신했음을 의미하며, 메모리가 부족한 호스트에서는 일반적으로 커널 메모리 부족(OOM) 킬러입니다. 스크립트는 이 설명을 출력하고 코드 137로 종료됩니다:

~~2924~~

2925```text theme={null}

2926Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.

2927Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

2928```

~~2929~~

2930다른 치명적 신호의 경우, 그리고 macOS의 종료 코드 137의 경우, 스크립트는 `Installation was killed before it could finish (exit code <N>)`을 출력하며 실제 종료 코드를 포함하고 메모리 부족 설명을 생략합니다. 메시지는 macOS 및 Linux가 사용하는 설치 스크립트에서 나오며, WSL 내부의 설치도 포함합니다. 네이티브 Windows 설치 스크립트는 절대 이를 출력하지 않습니다. v2.1.200 이전에는 스크립트가 셸의 단순한 `Killed` 줄로만 종료되었습니다.

~~2931~~

2932**수행할 작업:**

~~2933~~

2934* 다른 프로세스를 중지하여 메모리를 확보한 후 설치 프로그램을 다시 실행합니다

2935* 스왑 공간을 추가하거나 더 큰 인스턴스로 이동합니다. 스왑 파일 명령은 [메모리 부족 Linux 서버에서 설치 중단됨](/docs/ko/troubleshoot-install#install-killed-on-low-memory-linux-servers)을 참조하십시오.

~~2936~~

2937<h3 id="the-connection-dropped-while-downloading-the-update">

2938 업데이트를 다운로드하는 동안 연결이 끊어졌습니다

2939</h3>

~~2940~~

2941다운로드 서버로의 연결이 `claude install` 또는 `claude update`가 Claude Code 바이너리를 가져오는 동안 끊어졌으며, 재시도로 복구되지 않았습니다. Claude Code는 연결이 끊어지거나, 전송이 중단되거나, 다운로드된 파일이 체크섬에 실패할 때 다운로드를 재시도하며, 총 3번까지 시도합니다. 404와 같은 완료된 HTTP 오류는 서버가 이미 응답했기 때문에 재시도되지 않습니다. v2.1.202 이전에는 단일 연결 끊김이 재시도 대신 단순한 오류 `aborted`로 다운로드를 즉시 실패했습니다.

~~2942~~

2943```text theme={null}

2944The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

2945```

~~2946~~

2947괄호의 텍스트는 어느 시도가 실패했는지와 기본 네트워크 오류를 나타냅니다. `claude update`는 stderr에서 메시지 앞에 `Error: Failed to install native update`를 붙입니다.

~~2948~~

2949연결된 상태이지만 10분 이내에 완료되지 않는 다운로드는 `Download timed out: exceeded the total deadline` 메시지로 실패합니다. Claude Code는 시간 초과된 다운로드를 재시도하지 않습니다. 왜냐하면 기한 내에 완료할 수 없을 정도로 느린 연결은 즉시 재시도에서도 완료되지 않기 때문입니다. 아래 단계는 두 메시지 모두에 적용됩니다.

~~2950~~

2951프록시 또는 게이트웨이는 완료되기 전에 긴 전송을 닫을 수 있으며, Claude Code 바이너리는 큰 다운로드입니다.

~~2952~~

2953**수행할 작업:**

~~2954~~

2955* `claude update`를 다시 실행합니다. 정상적인 네트워크에서는 다운로드가 일반적으로 다음 실행에서 성공합니다. 시간 초과 메시지의 경우 더 빠르거나 제한이 적은 네트워크에서 다시 실행합니다.

2956* 네트워크에 프록시가 필요한 경우 설치 프로그램 또는 `claude update`를 실행하기 전에 `HTTPS_PROXY`를 설정합니다. [네트워크 연결 확인](/docs/ko/troubleshoot-install#check-network-connectivity)을 참조하십시오.

2957* 회사 프록시가 계속 전송을 닫는 경우 네트워크 팀에 `downloads.claude.ai`에서 전체 다운로드를 허용하도록 요청합니다. [네트워크 액세스 요구 사항](/docs/ko/network-config#network-access-requirements)을 참조하십시오.

2958* 설치 진단을 위해 셸에서 `claude doctor`를 실행합니다

~~2959~~

2960<h2 id="command-line-errors">2916<h2 id="command-line-errors">

2961 명령줄 오류2917 명령줄 오류

2962</h2>2918</h2>

4064 Marketplace is already added from a different source4020 Marketplace is already added from a different source

4065</h3>4021</h3>

4066 4022

4067[`/plugin install <plugin> --marketplace <source>`](/docs/ko/plugins/install#add-a-marketplace-and-install-in-one-command)를 통해 마켓플레이스 추가를 확인했으며 해당 소스에서 Claude Code가 가져온 카탈로그가 이미 다른 소스에서 추가한 마켓플레이스와 동일한 이름으로 지정합니다. Claude Code는 기존 마켓플레이스를 유지하고 이를 대체하지 않으므로 플러그인이 설치되지 않습니다.4023세션 또는 셸에서 [설치 명령의 `--marketplace <source>`](/docs/ko/plugins/install#add-a-marketplace-and-install-in-one-command)로 새 마켓플레이스 소스를 지정했습니다. Claude Code가 해당 소스에서 가져온 카탈로그의 이름이 이미 다른 소스에서 추가한 마켓플레이스의 이름과 같습니다. Claude Code는 기존 마켓플레이스를 대체하지 않고 유지하며, 플러그인은 설치되지 않습니다.

4068 4024

4069```text theme={null}4025```text theme={null}

4070Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.4026Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

4817 이 세션에는 저장된 트랜스크립트가 없습니다4773 이 세션에는 저장된 트랜스크립트가 없습니다

4818</h3>4774</h3>

4819 4775

4820`←` 또는 `/background`로 다른 대화에서 백그라운드로 처리되고 첫 번째 응답이 완료되기 전에 중지된 [백그라운드 세션](/docs/ko/agent-view)에 연결했습니다. 첫 번째 응답이 완료될 때까지 대화는 백그라운드로 처리된 세션에만 존재하므로 `claude attach`는 같은 세션 ID로 빈 대화를 시작하는 대신 중지된 세션을 시작하기를 거부합니다. 메시지는 이 세션에 대한 `claude respawn` 명령으로 끝납니다:4776`←` 또는 `/background`로 [백그라운드로 이동한](/docs/ko/agent-view#from-inside-a-session) 세션이 자체 턴을 실행하기 전에 중지되었으며, 해당 세션에 연결했습니다. Claude Code가 세션을 이동해 온 원래 대화를 찾을 수 없으므로 세션에는 재개할 내용이 없습니다. 메시지는 이 세션에 대한 `claude respawn` 명령으로 끝납니다:

4821 4777

4822```text theme={null}4778```text theme={null}

4823This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.4779This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.

4827 4783

4828**할 일:**4784**할 일:**

4829 4785

4830* 백그라운드로 처리한 대화는 그대로 유지됩니다: [`claude --resume`](/docs/ko/sessions)으로 재개하거나 계속 작업합니다.

4831* 중지된 세션을 새로 시작하려면 메시지의 ID로 `claude respawn <id>`를 실행하거나 에이전트 뷰의 행에서 `Enter`를 두 번 누릅니다.4786* 중지된 세션을 새로 시작하려면 메시지의 ID로 `claude respawn <id>`를 실행하거나 에이전트 뷰의 행에서 `Enter`를 두 번 누릅니다.

4832* 세션이 응답을 완료했는데도 v2.1.214 이전 버전에서 이 거부가 표시되면 `~/.claude/projects`의 읽을 수 없는 폴더로 인해 트랜스크립트 스캔이 저장된 대화를 놓칠 수 있습니다. v2.1.214 이상으로 업데이트하면 스캔 중에 읽을 수 없는 폴더를 허용합니다.4787* 세션이 응답을 완료했는데도 v2.1.214 이전 버전에서 이 거부가 표시되면 `~/.claude/projects`의 읽을 수 없는 폴더로 인해 트랜스크립트 스캔이 저장된 대화를 놓칠 수 있습니다. v2.1.214 이상으로 업데이트하면 스캔 중에 읽을 수 없는 폴더를 허용합니다.

4833 4788

glossary.md +2 −2

Details

465 465

466클라우드 Claude Code 세션을 로컬 터미널로 가져오는 명령 `/teleport`입니다. Claude는 분기를 가져오고, 대화 기록을 로드하고, 클라우드 세션의 마지막 상태에서 재개합니다. 역방향은 `--cloud`이며, 로컬 작업을 클라우드에서 실행하도록 보냅니다.466클라우드 Claude Code 세션을 로컬 터미널로 가져오는 명령 `/teleport`입니다. Claude는 분기를 가져오고, 대화 기록을 로드하고, 클라우드 세션의 마지막 상태에서 재개합니다. 역방향은 `--cloud`이며, 로컬 작업을 클라우드에서 실행하도록 보냅니다.

467 467

468자세히 알아보기: [클라우드에서 터미널로](/docs/ko/claude-code-on-the-web#from-cloud-to-terminal)468자세히 알아보기: [터미널에서 클라우드 세션 계속하기](/docs/ko/claude-code-on-the-web#from-cloud-to-terminal)

469 469

470<h3 id="tool">470<h3 id="tool">

471 Tool471 Tool

511 Worktree isolation511 Worktree isolation

512</h3>512</h3>

513 513

514`.claude/worktrees/` 아래의 별도 git worktree에서 Claude를 실행하는 격리 모드이며, `-w` 플래그 또는 서브에이전트 구성의 `isolation: worktree`로 활성화됩니다. 변경 사항은 별도 디렉토리의 별도 분기에 남아 있으므로 병렬 에이전트가 서로의 파일을 덮어쓰지 않습니다.514`.claude/worktrees/` 아래의 별도 git worktree에서 Claude를 실행하는 격리 모드이며, `-w` 플래그 또는 서브에이전트 구성의 `isolation: worktree`로 활성화됩니다. 변경 사항은 별도 디렉토리의 별도 브랜치에 남아 있으므로 병렬 에이전트는 각자 자신의 파일 사본을 편집합니다.

515 515

516자세히 알아보기: [git worktrees로 병렬 세션 실행](/docs/ko/worktrees)516자세히 알아보기: [git worktrees로 병렬 세션 실행](/docs/ko/worktrees)

517 517

goal.md +1 −1

Details

127claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"127claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"

128```128```

129 129

130기본 텍스트 출력을 사용하면 실행이 끝날 때까지 아무것도 출력되지 않으므로 많은 턴을 실행하는 목표는 멈춘 것처럼 보일 수 있습니다. 루프가 실행되는 동안 각 메시지를 내보내려면 `--output-format stream-json --verbose`를 추가합니다.130기본 텍스트 출력을 사용하면 루프가 끝날 때 Claude의 최종 응답이 출력되므로 많은 턴을 실행하는 목표는 멈춘 것처럼 보일 수 있습니다. 루프가 실행되는 동안 각 메시지를 내보내려면 `--output-format stream-json --verbose`를 추가합니다.

131 131

132Ctrl+C로 프로세스를 중단하여 조건이 충족되기 전에 비대화형 목표를 중지합니다.132Ctrl+C로 프로세스를 중단하여 조건이 충족되기 전에 비대화형 목표를 중지합니다.

133 133

headless.md +15 −13

Details

35Claude Code는 성공 시 코드 0으로 종료되고 실행이 실패하면 0이 아닌 코드로 종료되므로 스크립트는 종료 상태에 따라 분기할 수 있습니다. 잘못된 플래그를 전달하면 Claude Code는 실행이 시작되기 전에 오류를 stderr에 보고합니다. 실행 중에 인증 누락과 같은 오류가 발생하면 Claude Code는 오류를 stdout의 결과로 출력합니다.35Claude Code는 성공 시 코드 0으로 종료되고 실행이 실패하면 0이 아닌 코드로 종료되므로 스크립트는 종료 상태에 따라 분기할 수 있습니다. 잘못된 플래그를 전달하면 Claude Code는 실행이 시작되기 전에 오류를 stderr에 보고합니다. 실행 중에 인증 누락과 같은 오류가 발생하면 Claude Code는 오류를 stdout의 결과로 출력합니다.

36 36

37<h3 id="start-faster-with-bare-mode">37<h3 id="start-faster-with-bare-mode">

~~38 베어 모드로 더 빠르게 시작하기~~38 bare 모드로 더 빠르게 시작하기

39</h3>39</h3>

40 40

41`--bare`를 추가하여 hooks, skills, 사용자 정의 명령, [서브에이전트](/docs/ko/sub-agents), 설치된 플러그인, MCP 서버, 자동 메모리 및 CLAUDE.md의 자동 검색을 건너뛰어 시작 시간을 단축합니다. 이를 사용하지 않으면 `claude -p`는 대화형 세션과 동일한 [컨텍스트](/docs/ko/how-claude-code-works#the-context-window)를 로드하며, 작업 디렉토리 또는 `~/.claude`에 구성된 모든 항목을 포함합니다.41`--bare`를 추가하여 훅, 스킬, 사용자 정의 명령, [서브에이전트](/docs/ko/sub-agents), 설치된 플러그인, MCP 서버, 자동 메모리 및 CLAUDE.md의 자동 검색을 건너뛰어 시작 시간을 단축합니다. 이를 사용하지 않으면 `claude -p`는 대화형 세션과 동일한 [컨텍스트](/docs/ko/how-claude-code-works#the-context-window)를 로드하며, 작업 디렉터리 또는 `~/.claude`에 구성된 모든 항목을 포함합니다.

42 42

43베어 모드는 모든 머신에서 동일한 결과가 필요한 CI 및 스크립트에 유용합니다. 팀원의 `~/.claude`에 있는 hook이나 프로젝트의 `.mcp.json`에 있는 MCP 서버는 베어 모드가 이들을 읽지 않기 때문에 실행되지 않습니다. `--add-dir`로 지정한 디렉토리는 부분적인 예외입니다: 베어 모드는 해당 `.claude/skills/` 폴더에서 skills를 로드하지만 여전히 해당 `.claude/commands/` 및 `.claude/agents/` 폴더를 건너뜁니다. [추가 디렉토리의 Skills](/docs/ko/skills#skills-from-additional-directories)는 로드되는 항목과 로드되지 않는 항목을 다룹니다.43bare 모드는 모든 머신에서 동일한 결과가 필요한 CI 및 스크립트에 유용합니다. 팀원의 `~/.claude`에 있는 훅이나 프로젝트의 `.mcp.json`에 있는 MCP 서버는 bare 모드가 이들을 읽지 않기 때문에 실행되지 않습니다. `--add-dir`로 지정한 디렉터리는 부분적인 예외입니다: bare 모드는 해당 `.claude/skills/` 폴더에서 스킬을 로드하지만 여전히 해당 `.claude/commands/` 및 `.claude/agents/` 폴더를 건너뜁니다. [추가 디렉터리의 스킬](/docs/ko/skills#skills-from-additional-directories)은 로드되는 항목과 로드되지 않는 항목을 다룹니다.

44 44

45`--bare` 없이 `-p` 세션은 프로젝트의 `.claude/settings.json`에서 hooks를 실행하고 해당 `.mcp.json`의 서버를 연결합니다. 이는 신뢰한 적이 없는 폴더에서도 마찬가지입니다. `-p` 세션은 워크스페이스 신뢰 대화 상자나 서버별 승인 프롬프트를 표시하지 않습니다. [폴더를 신뢰하기 전에 실행되는 항목](/docs/ko/permissions#what-runs-before-you-trust-a-folder)은 `-p` 아래의 각 종류의 저장소 콘텐츠와 이를 제외하는 방법을 다룹니다.45`--bare` 없이 `-p` 세션은 프로젝트의 `.claude/settings.json`에서 훅을 실행하고 해당 `.mcp.json`의 서버를 연결합니다. 이는 신뢰한 적이 없는 폴더에서도 마찬가지입니다. `-p` 세션은 워크스페이스 신뢰 대화 상자나 서버별 승인 프롬프트를 표시하지 않습니다. [폴더를 신뢰하기 전에 실행되는 항목](/docs/ko/permissions#what-runs-before-you-trust-a-folder)은 `-p` 아래의 각 종류의 저장소 콘텐츠와 이를 제외하는 방법을 다룹니다.

46 46

47이 예제는 베어 모드에서 일회성 요약 작업을 실행하고 Read 도구를 사전 승인하여 권한 프롬프트 없이 호출이 완료되도록 합니다. 베어 모드는 구독 로그인을 사용하지 않기 때문에 실행하기 전에 `ANTHROPIC_API_KEY`를 설정합니다:47이 예제는 bare 모드에서 일회성 요약 작업을 실행하고 Read 도구를 사전 승인하여 권한 프롬프트 없이 호출이 완료되도록 합니다. bare 모드는 구독 로그인을 사용하지 않기 때문에 실행하기 전에 `ANTHROPIC_API_KEY`를 설정합니다:

48 48

49```bash theme={null}49```bash theme={null}

50claude --bare -p "Summarize README.md" --allowedTools "Read"50claude --bare -p "Summarize README.md" --allowedTools "Read"

51```51```

52 52

53베어 모드에서 Claude Code는 OAuth 자격 증명이나 시스템 키체인을 읽지 않습니다. Anthropic API의 경우 환경에서 `ANTHROPIC_API_KEY`를 설정하고, [Claude Console](https://platform.claude.com)에서 생성한 키를 사용하거나, `--settings` JSON에서 `apiKeyHelper`를 제공합니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry는 일반적인 공급자 자격 증명을 계속 읽습니다.53bare 모드에서 Claude Code는 OAuth 자격 증명이나 시스템 키체인을 읽지 않습니다. Anthropic API의 경우 환경에서 `ANTHROPIC_API_KEY`를 설정하고, [Claude Console](https://platform.claude.com)에서 생성한 키를 사용하거나, `--settings` JSON에서 `apiKeyHelper`를 제공합니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry는 일반적인 공급자 자격 증명을 계속 읽습니다.

54 54

~~55베어 모드에서 Claude는 Bash, 파일 읽기 및 파일 편집 도구에 액세스할 수 있습니다. 플래그를 사용하여 필요한 컨텍스트를 전달합니다:~~55bare 모드에서 Claude는 Bash, 파일 읽기 및 파일 편집 도구에 액세스할 수 있습니다. 플래그를 사용하여 필요한 컨텍스트를 전달합니다:

56 56

57| 로드할 항목 | 사용 |57| 로드할 항목 | 사용 |

58| - | - |58| - | - |

84 84

85실행은 백그라운드 명령, 서브에이전트 및 워크플로, Monitor 감시, 대기 중인 `/loop` 웨이크업과 같은 백그라운드 작업을 기다립니다:85실행은 백그라운드 명령, 서브에이전트 및 워크플로, Monitor 감시, 대기 중인 `/loop` 웨이크업과 같은 백그라운드 작업을 기다립니다:

86 86

87* **[백그라운드 명령](/docs/ko/tools-reference#background-commands)**: 메인 대화가 시작한 명령(예: 개발 서버 또는 감시 빌드)의 경우, 실행은 명령이 종료되거나 [시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands)에 도달할 때까지 기다립니다. 그런 다음 Claude는 그 결과를 가지고 턴을 한 번 더 수행하며, 해당 턴의 결과가 실행의 마지막 결과가 되고 `text` 및 `json` 출력은 이 결과를 출력합니다. 명령이 실행되는 동안에는 10분 상한이 대기를 종료하지 않습니다.87* **[백그라운드 명령](/docs/ko/tools-reference#background-commands)**: 메인 대화가 시작한 명령(예: 개발 서버 또는 감시 빌드)의 경우, 실행은 명령이 종료되거나 [시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands)에 도달할 때까지 기다립니다. 그런 다음 Claude는 그 결과를 가지고 턴을 한 번 더 수행합니다. 명령이 실행되는 동안에는 10분 상한이 대기를 종료하지 않습니다.

88* **백그라운드 [서브에이전트](/docs/ko/sub-agents) 및 워크플로**: 해당 작업의 결과가 최종 출력의 일부이므로 작업이 완료될 때까지 실행이 열린 상태로 유지됩니다.88* **백그라운드 [서브에이전트](/docs/ko/sub-agents) 및 워크플로**: 해당 작업의 결과가 최종 출력의 일부이므로 작업이 완료될 때까지 실행이 열린 상태로 유지됩니다.

89* **[Monitor](/docs/ko/tools-reference#monitor-tool) 감시**: 실행은 감시가 시간 초과되거나 10분 상한이 대기를 종료할 때까지, 둘 중 먼저 발생하는 시점까지 기다립니다. 대기하는 동안 Claude는 감시가 보고하는 항목에 계속 응답합니다. 기본적으로 감시는 Claude가 시작한 후 5분 후에 시간 초과됩니다.89* **[Monitor](/docs/ko/tools-reference#monitor-tool) 감시**: 실행은 감시가 시간 초과되거나 10분 상한이 대기를 종료할 때까지, 둘 중 먼저 발생하는 시점까지 기다립니다. 대기하는 동안 Claude는 감시가 보고하는 항목에 계속 응답합니다. 기본적으로 감시는 Claude가 시작한 후 5분 후에 시간 초과됩니다.

90* **대기 중인 웨이크업**: 프롬프트를 `--input-format stream-json`이 아닌 텍스트로 전달한 실행에서 Claude가 [자체 속도 조절 `/loop` 웨이크업](/docs/ko/scheduled-tasks#let-claude-choose-the-interval)을 예약한 경우, 실행은 10분 상한을 넘더라도 각 웨이크업이 실행되기를 기다리고 [루프가 끝날](/docs/ko/scheduled-tasks#stop-a-loop) 때까지 해당 반복을 실행합니다.90* **대기 중인 웨이크업**: 프롬프트를 `--input-format stream-json`이 아닌 텍스트로 전달한 실행에서 Claude가 [자체 속도 조절 `/loop` 웨이크업](/docs/ko/scheduled-tasks#let-claude-choose-the-interval)을 예약한 경우, 실행은 10분 상한을 넘더라도 각 웨이크업이 실행되기를 기다리고 [루프가 끝날](/docs/ko/scheduled-tasks#stop-a-loop) 때까지 해당 반복을 실행합니다.

91 91

92실행이 [`--max-budget-usd`](/docs/ko/cli-reference#cli-flags) 상한에 도달하면 Claude Code는 기다리는 대신 남은 백그라운드 작업을 중지합니다.92실행이 [`--max-budget-usd`](/docs/ko/cli-reference#cli-flags) 상한에 도달하면 Claude Code는 기다리는 대신 남은 백그라운드 작업을 중지합니다.

93 93

94백그라운드 작업이 다른 턴을 시작하면, 실행은 기본 `text` 출력에서는 각 턴의 결과를 출력하고 `json` 출력에서는 마지막 턴의 결과를 출력합니다. v2.1.295 이전에는 `text` 출력에서도 마지막 턴의 결과만 출력했습니다.

94<h3 id="stop-a-run-with-sigterm">96<h3 id="stop-a-run-with-sigterm">

95 SIGTERM으로 실행 중지97 SIGTERM으로 실행 중지

96</h3>98</h3>

97 99

98`claude -p` 실행을 SIGTERM으로 중지하면(예: `kill` 또는 프로세스 감독자에서), Claude Code는 코드 143으로 종료됩니다. Claude Code는 진행 중인 턴을 완료하지 않은 상태로 두고 해당 턴에 대한 결과를 기록하지 않습니다. 턴을 대신 종료하려면 SIGINT를 보내거나 Agent SDK의 `interrupt()`를 호출한 후 프로세스를 중지합니다.100`claude -p` 실행을 SIGTERM으로 중지하면(예: `kill` 또는 프로세스 감독자에서), Claude Code는 코드 143으로 종료됩니다. Claude Code는 진행 중인 턴을 완료하지 않은 상태로 두고 해당 턴에 대한 결과를 기록하지 않습니다. 턴을 대신 종료하려면 SIGINT를 보내거나 Agent SDK의 `interrupt()`를 호출한 후 프로세스를 중지합니다.

99 101

100SIGTERM에서 Claude Code는 여전히 실행 중인 모든 Bash 명령의 프로세스 트리를 종료합니다. Claude Code는 [`SessionEnd` hooks](/docs/ko/hooks#sessionend)를 실행하고 종료합니다. 종료하는 동안 Claude Code는 새로운 도구 호출을 시작하지 않고, 새로운 모델 요청을 보내지 않으며, `SessionEnd` 이외의 hook을 실행하지 않습니다. 신호가 도착했을 때 실행이 명령 중간에 있거나 권한 프롬프트에 대한 답변을 기다리고 있었다면 Claude Code는 다음과 같이 해당 단계를 처리합니다:102SIGTERM에서 Claude Code는 여전히 실행 중인 모든 Bash 명령의 프로세스 트리를 종료합니다. Claude Code는 [`SessionEnd` 훅](/docs/ko/hooks#sessionend)을 실행하고 종료합니다. 종료하는 동안 Claude Code는 새로운 도구 호출을 시작하지 않고, 새로운 모델 요청을 보내지 않으며, `SessionEnd` 이외의 훅을 실행하지 않습니다. 신호가 도착했을 때 실행이 명령 중간에 있거나 권한 프롬프트에 대한 답변을 기다리고 있었다면 Claude Code는 다음과 같이 해당 단계를 처리합니다:

101 103

102* **명령 실행 중**: Claude Code는 명령을 세션에서 종료된 것으로 기록합니다.104* **명령 실행 중**: Claude Code는 명령을 세션에서 종료된 것으로 기록합니다.

103* **권한 프롬프트에 대한 답변 대기 중**: 프로세스에 SIGTERM을 보내면 Claude Code는 프롬프트를 답변하지 않은 상태로 둡니다. 프로그램이 Agent SDK를 통해 세션을 닫으면 SDK는 신호를 보내기 전에 Claude Code의 입력을 종료하고 Claude Code는 입력이 종료되는 즉시 프롬프트를 취소합니다.105* **권한 프롬프트에 대한 답변 대기 중**: 프로세스에 SIGTERM을 보내면 Claude Code는 프롬프트를 답변하지 않은 상태로 둡니다. 프로그램이 Agent SDK를 통해 세션을 닫으면 SDK는 신호를 보내기 전에 Claude Code의 입력을 종료하고 Claude Code는 입력이 종료되는 즉시 프롬프트를 취소합니다.

105[세션을 재개](#continue-conversations)할 때 Claude Code는 진행 중이던 턴을 그대로 두고 다음 프롬프트가 대화를 진행합니다. 재개 시 Claude Code가 진행 중이던 턴을 계속하도록 하려면 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1`](/docs/ko/env-vars)을 설정합니다.107[세션을 재개](#continue-conversations)할 때 Claude Code는 진행 중이던 턴을 그대로 두고 다음 프롬프트가 대화를 진행합니다. 재개 시 Claude Code가 진행 중이던 턴을 계속하도록 하려면 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1`](/docs/ko/env-vars)을 설정합니다.

106 108

107<h3 id="if-the-working-directory-is-deleted">109<h3 id="if-the-working-directory-is-deleted">

108 작업 디렉토리가 삭제된 경우110 작업 디렉터리가 삭제된 경우

109</h3>111</h3>

110 112

111`claude -p` 또는 Agent SDK 세션의 작업 디렉토리가 세션 중간에 삭제되면 세션은 계속 실행됩니다. 디렉토리가 없는 상태에서 턴이 시작되면 Claude Code는 `stream-json` 출력에서 [경고 메시지](/docs/ko/agent-sdk/typescript#sdkinformationalmessage)를 내보내고, 디렉토리가 다시 존재할 때까지 셸 명령이 실패합니다.113`claude -p` 또는 Agent SDK 세션의 작업 디렉터리가 세션 중간에 삭제되면 세션은 계속 실행됩니다. 디렉터리가 없는 상태에서 턴이 시작되면 Claude Code는 `stream-json` 출력에서 [경고 메시지](/docs/ko/agent-sdk/typescript#sdkinformationalmessage)를 내보내고, 디렉터리가 다시 존재할 때까지 셸 명령이 실패합니다.

112 114

113<h2 id="examples">115<h2 id="examples">

114 예제116 예제

264| `attempt` | 정수 | 현재 시도 번호, 1부터 시작 |266| `attempt` | 정수 | 현재 시도 번호, 1부터 시작 |

265| `max_retries` | 정수 | 이 실패의 원인에 대해 허용된 총 재시도 횟수, 세션 전체 예산보다 적을 수 있음 |267| `max_retries` | 정수 | 이 실패의 원인에 대해 허용된 총 재시도 횟수 |

266| `retry_delay_ms` | 정수 | 다음 시도까지의 밀리초 |268| `retry_delay_ms` | 정수 | 다음 시도까지의 밀리초 |

268| `no_response` | 객체, 선택 사항 | 실패한 시도가 [시간 내에 응답 헤더를 받지 못한](/docs/ko/errors#no-response-from-api) 경우에만 존재합니다. `waited_ms`는 해당 시도가 대기한 시간이고 `retry_wait_ms`는 재시도가 대기할 시간입니다. 이러한 이벤트에서 `max_retries`는 이 원인이 일반적으로 받는 하나의 재시도를 반영하며 세션 전체 예산이 아닙니다. Claude Code v2.1.261 이상이 필요합니다 |270| `no_response` | 객체, 선택 사항 | 실패한 시도가 [시간 내에 응답 헤더를 받지 못한](/docs/ko/errors#no-response-from-api) 경우에만 존재합니다. `waited_ms`는 해당 시도가 대기한 시간이고 `retry_wait_ms`는 재시도가 대기할 시간입니다. Claude Code v2.1.261 이상이 필요합니다 |

269| `error` | 문자열 | 오류 범주: `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, 또는 `unknown` |271| `error` | 문자열 | 오류 범주: `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, 또는 `unknown` |

270| `uuid` | 문자열 | 고유 이벤트 식별자 |272| `uuid` | 문자열 | 고유 이벤트 식별자 |

271| `session_id` | 문자열 | 이벤트가 속한 세션 |273| `session_id` | 문자열 | 이벤트가 속한 세션 |

hipaa-setup.md +3 −0

Details

139}139}

140```140```

141 141

142샌드박싱, 네트워크 허용 목록, 자격 증명 보호, 로컬 데이터 보존이 포함된 더 완전한 `managed-settings.json`은 [설정 예제 저장소](https://github.com/anthropics/claude-code/tree/main/examples/settings)의 `settings-hipaa.json` 및 `README-hipaa.md`를 참조하십시오.

143

142<h4 id="what-each-key-does">144<h4 id="what-each-key-does">

143 각 키의 역할145 각 키의 역할

144</h4>146</h4>

306 308

307* [HIPAA 대응 조직을 위한 Cowork(로컬 모드) 설정](https://claude.com/docs/cowork/hipaa-setup)309* [HIPAA 대응 조직을 위한 Cowork(로컬 모드) 설정](https://claude.com/docs/cowork/hipaa-setup)

308* [관리형 설정 배포하기](/docs/ko/managed-settings)310* [관리형 설정 배포하기](/docs/ko/managed-settings)

311* [HIPAA 설정 예시](https://github.com/anthropics/claude-code/tree/main/examples/settings)

309* [엔터프라이즈 네트워크 구성](/docs/ko/network-config)312* [엔터프라이즈 네트워크 구성](/docs/ko/network-config)

310* [제로 데이터 보존](/docs/ko/zero-data-retention)313* [제로 데이터 보존](/docs/ko/zero-data-retention)

311* [법률 및 규정 준수](/docs/ko/legal-and-compliance)314* [법률 및 규정 준수](/docs/ko/legal-and-compliance)

hooks.md +124 −35

Details

476| `async` | 아니요 | `true`이면 차단하지 않고 백그라운드에서 실행됩니다. [백그라운드에서 hook 실행](#run-hooks-in-the-background) 참조 |476| `async` | 아니요 | `true`이면 차단하지 않고 백그라운드에서 실행됩니다. [백그라운드에서 hook 실행](#run-hooks-in-the-background) 참조 |

477| `asyncRewake` | 아니요 | `true`이면 백그라운드에서 실행되고 종료 코드 2에서 Claude를 깨웁니다. 훅의 stderr 또는 stderr가 비어 있으면 stdout이 Claude에게 [시스템 리마인더](/docs/ko/glossary#system-reminder)로 표시되므로 장시간 실행되는 백그라운드 실패에 반응할 수 있습니다. |477| `asyncRewake` | 아니요 | `true`이면 백그라운드에서 실행되고 종료 코드 2에서 Claude를 깨웁니다. 훅의 stderr 또는 stderr가 비어 있으면 stdout이 Claude에게 [시스템 리마인더](/docs/ko/glossary#system-reminder)로 표시되므로 장시간 실행되는 백그라운드 실패에 반응할 수 있습니다. |

478| `shell` | 아니요 | 이 hook에 사용할 셸. `"bash"` 또는 `"powershell"`을 허용합니다. 기본값은 `"bash"` 또는 Git Bash가 설치되지 않은 경우 Windows에서 `"powershell"`입니다. `"powershell"`을 설정하면 Windows에서 PowerShell을 통해 명령을 실행합니다. `CLAUDE_CODE_USE_POWERSHELL_TOOL`이 필요하지 않습니다. hook이 PowerShell을 직접 생성하기 때문입니다. `args`가 설정되면 무시됩니다. |478| `shell` | 아니요 | 이 hook에 사용할 셸. `"bash"` 또는 `"powershell"`을 허용합니다. 기본값은 `"bash"` 또는 Git Bash가 설치되지 않은 경우 Windows에서 `"powershell"`입니다. `"powershell"`을 설정하면 Windows에서 PowerShell을 통해 명령을 실행합니다. `CLAUDE_CODE_USE_POWERSHELL_TOOL`이 필요하지 않습니다. hook이 PowerShell을 직접 생성하기 때문입니다. `args`가 설정되면 무시됩니다. |

479| `onFailure` | 아니요 | 훅이 실패할 때 해당 작업에 일어나는 동작: 기본값인 `"continue"` 또는 `"block"`. [훅이 실패할 때 작업 차단](#block-the-action-when-a-hook-fails)을 참조하십시오. Claude Code v2.1.295 이상이 필요합니다. |

479 480

480<a id="exec-form-and-shell-form" />481<a id="exec-form-and-shell-form" />

481 482

533| `url` | 예 | POST 요청을 보낼 URL |534| `url` | 예 | POST 요청을 보낼 URL |

534| `headers` | 아니요 | 키-값 쌍으로 추가 HTTP 헤더. 값은 `$VAR_NAME` 또는 `${VAR_NAME}` 구문을 사용한 환경 변수 보간을 지원합니다. `allowedEnvVars`에 나열된 변수만 해결됩니다. |535| `headers` | 아니요 | 키-값 쌍으로 추가 HTTP 헤더. 값은 `$VAR_NAME` 또는 `${VAR_NAME}` 구문을 사용한 환경 변수 보간을 지원합니다. `allowedEnvVars`에 나열된 변수만 해결됩니다. |

535| `allowedEnvVars` | 아니요 | 헤더 값에 보간될 수 있는 환경 변수 이름 목록. 나열되지 않은 변수에 대한 참조는 빈 문자열로 바뀝니다. 환경 변수 보간이 작동하려면 필수입니다. |536| `allowedEnvVars` | 아니요 | 헤더 값에 보간될 수 있는 환경 변수 이름 목록. 나열되지 않은 변수에 대한 참조는 빈 문자열로 바뀝니다. 환경 변수 보간이 작동하려면 필수입니다. |

537| `onFailure` | 아니요 | 훅이 실패할 때 해당 작업에 일어나는 동작: 기본값인 `"continue"` 또는 `"block"`. [훅이 실패할 때 작업 차단](#block-the-action-when-a-hook-fails)을 참조하십시오. Claude Code v2.1.295 이상이 필요합니다. |

536 538

537Claude Code는 hook의 [JSON 입력](#hook-input-and-output)을 `Content-Type: application/json`을 사용하여 POST 요청 본문으로 보냅니다. 응답 본문은 명령 hook과 동일한 [JSON 출력 형식](#json-output)을 사용합니다.539Claude Code는 hook의 [JSON 입력](#hook-input-and-output)을 `Content-Type: application/json`을 사용하여 POST 요청 본문으로 보냅니다. 응답 본문은 명령 hook과 동일한 [JSON 출력 형식](#json-output)을 사용합니다.

538 540

821 종료 코드 출력823 종료 코드 출력

822</h3>824</h3>

823 825

824hook 명령의 종료 코드는 Claude Code에 작업을 진행할지, 차단할지 또는 무시할지를 알려줍니다. 종료 코드는 단독으로 작동하지 않습니다. Claude Code는 0뿐만 아니라 모든 종료 코드에서 stdout의 [JSON 출력 필드](#json-output)를 읽으며, 표준 결정 모델을 사용하는 이벤트의 경우 스키마 검증을 통과하는 구문 분석된 객체가 코드와 함께 적용됩니다. Exit 2의 차단은 JSON이 재정의할 수 없는 유일한 결과입니다.826hook의 종료 코드는 도구 호출이나 프롬프트처럼 hook을 트리거한 작업을 계속 진행할지를 Claude Code에 알려줍니다. 완료된 실행의 결과는 다음 세 가지 중 하나입니다:

825 827

826두 개의 표가 이벤트별 예외를 다룹니다: [이벤트별 종료 코드 2 동작](#exit-code-2-behavior-per-event)은 각 이벤트에 대해 종료 코드가 수행하는 작업을 설명하고, [결정 제어](#decision-control)는 각 이벤트가 적용하는 결정 필드를 설명합니다. `systemMessage`와 같은 범용 필드는 대부분의 이벤트에서 작동하며 [JSON 출력](#json-output) 표에 나열됩니다.828* **성공**: hook이 0으로 종료합니다. Claude Code는 hook이 출력한 [JSON 출력](#json-output) 필드를 적용하며, 해당 필드가 작업을 차단하거나 거부하지 않는 한 작업이 진행됩니다.

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

830* **차단하지 않는 오류**: hook이 그 밖의 코드로 종료하거나, 시작되지 않거나 잘못된 JSON을 출력하는 등 다른 방식으로 실패합니다. 작업은 진행되며, `PreToolUse`와 같은 이벤트에서는 트랜스크립트에 `<hook name> hook error` 알림이 표시됩니다. 실패한 hook이 작업을 차단하게 하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.

831

832hook이 stdout에 출력하는 내용에 따라 결과가 달라질 수 있습니다. 예를 들어 `PreToolUse` hook이 1로 종료하지만 검증을 통과하는 JSON을 출력하면 실행은 성공이며 JSON 필드가 결과를 결정합니다. `PreToolUse`와 같은 이벤트에서 hook의 결과를 확인하려면 첫 번째 열에서 stdout에 출력한 내용을, 맨 위 행에서 종료 코드를 찾아 맞춰 봅니다:

833

834| Stdout | 종료 0 | 종료 2 | 그 밖의 종료 코드 |

835| :- | :- | :- | :- |

836| [스키마 검증](#json-output)을 통과하는 JSON 객체 | 성공. 필드가 적용됩니다 | 차단 오류. Claude Code는 여전히 필드를 읽지만 필드가 차단을 재정의할 수는 없습니다 | 성공. Claude Code는 종료 코드를 무시하고 필드만으로 결과를 결정합니다. [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정하면 실패로 간주됩니다 |

838| [일반 텍스트](#exit-code-0) 또는 출력 없음 | 성공 | 차단 오류. stderr이 이유가 됩니다 | 차단하지 않는 오류. 알림에 stderr의 첫 번째 줄이 표시됩니다 |

839

840일부 이벤트에는 자체 규칙이 있습니다:

841

842* **`WorktreeCreate`**: JSON 내용과 관계없이 0이 아닌 종료 코드는 worktree 생성을 실패하게 합니다.

843* **`WorktreeRemove`**: 0이 아닌 종료 코드는 이후에도 디렉터리가 여전히 존재하면 worktree 제거를 실패하게 합니다.

844* **`Stop`, `SubagentStop`, `TaskCompleted`, 플러그인의 `UserPromptSubmit` hook**: hook이 stdout에 아무것도 출력하지 않고 2로 종료하며 stderr에 `No such file or directory`처럼 파일이 없다는 내용이 있으면 Claude Code는 실행을 차단하지 않는 오류로 취급합니다.

845* **`Elicitation` 및 `ElicitationResult`**: Claude Code는 hook이 0으로 종료할 때 `hookSpecificOutput`을 적용하고, 그 밖의 종료 코드에서는 무시합니다.

846* **`StopFailure`와 같이 hook 출력을 버리는 이벤트**: Claude Code는 모든 종료 코드에서 JSON을 무시합니다. 단, `terminalSequence`와 같은 부수 효과 필드는 여전히 동작합니다.

847

848이벤트에서 종료 코드 2가 수행하는 작업은 [이벤트별 종료 코드 2 동작](#exit-code-2-behavior-per-event)을 참조하세요. 이벤트가 적용하는 결정 필드는 [결정 제어](#decision-control)를 참조하세요.

827 849

828<h4 id="exit-code-0">850<h4 id="exit-code-0">

829 종료 코드 0851 종료 코드 0

835 857

836Claude Code가 stdout을 [JSON 출력](#json-output)으로 읽는지 일반 텍스트로 읽는지는 주변 공백을 무시하고 시작 및 끝 문자에 따라 달라집니다:858Claude Code가 stdout을 [JSON 출력](#json-output)으로 읽는지 일반 텍스트로 읽는지는 주변 공백을 무시하고 시작 및 끝 문자에 따라 달라집니다:

837 859

838* **`{`로 시작하고 `}`로 끝남**: Claude Code는 이를 JSON으로 구문 분석합니다. 출력이 각각 자체적으로 JSON으로 구문 분석되는 두 줄 이상이고 필드를 설정하는 [JSON 출력](#json-output) 객체인 줄이 없는 경우 Claude Code는 전체 출력을 일반 텍스트로 취급합니다. 이러한 줄 중 하나가 필드를 설정하면 전체 출력은 아래에 설명된 구문 분석 실패가 됩니다.860* **`{`로 시작하고 `}`로 끝남**: Claude Code는 이를 JSON으로 구문 분석합니다. 출력이 각각 자체적으로 JSON으로 구문 분석되는 두 줄 이상이고 필드를 설정하는 [JSON 출력](#json-output) 객체인 줄이 없는 경우 Claude Code는 전체 출력을 일반 텍스트로 취급합니다. 이러한 줄 중 하나가 필드를 설정하면 전체 출력은 구문 분석 실패가 됩니다.

839* **`{`로 시작하지만 `}`로 끝나지 않음**: Claude Code는 이를 일반 텍스트로 취급합니다.861* **`{`로 시작하지만 `}`로 끝나지 않음**: Claude Code는 이를 일반 텍스트로 취급합니다.

840* **다른 것으로 시작**: Claude Code는 JSON 배열이나 따옴표로 묶인 JSON 문자열을 포함하여 이를 일반 텍스트로 취급합니다.862* **다른 것으로 시작**: Claude Code는 JSON 배열이나 따옴표로 묶인 JSON 문자열을 포함하여 이를 일반 텍스트로 취급합니다.

841 863

842표준 결정 모델을 사용하는 이벤트의 경우 스키마 검증에 실패하는 구문 분석된 객체와 함께 종료 0으로 나가면 차단하지 않는 오류입니다: 작업이 진행되고 트랜스크립트는 검증 메시지와 함께 `<hook name> hook error` 알림을 표시합니다. 2 이외의 다른 종료 코드에서도 동일한 일이 발생하며, [종료 2는 여전히 차단합니다](#exit-code-2).864Claude Code가 stdout을 JSON으로 구문 분석하려고 시도했지만 실패하거나, 구문 분석된 객체가 [스키마 검증](#json-output)에 실패하면 실행은 [차단하지 않는 오류](#exit-code-output)가 됩니다. `<hook name> hook error` 알림에 구문 분석 또는 검증 메시지가 표시됩니다. 일반 텍스트 stdout을 컨텍스트로 추가하는 이벤트에서 Claude Code는 구문 분석에 실패한 stdout을 추가하지 않습니다.

~~843~~

844표준 결정 모델을 사용하는 이벤트의 경우 Claude Code가 stdout을 JSON으로 구문 분석하려고 시도하고 실패하면 2 이외의 모든 종료 코드에서 차단하지 않는 오류를 보고합니다. 트랜스크립트는 구문 분석 메시지와 함께 `<hook name> hook error` 알림을 표시합니다. 일반 텍스트 stdout을 컨텍스트로 추가하는 이벤트에서 Claude Code는 텍스트를 추가하지 않습니다. v2.1.248 이전에는 Claude Code가 해당 stdout을 일반 텍스트로 취급했습니다.

845 865

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

847 867

848<h4 id="exit-code-2">868<h4 id="exit-code-2">

849 종료 코드 2869 종료 코드 2

850</h4>870</h4>

851 871

852종료 2는 차단 오류를 의미합니다. [차단할 수 있는 이벤트](#exit-code-2-behavior-per-event)에서 종료 2는 JSON을 출력하는지 여부와 관계없이 차단합니다: JSON `permissionDecision`의 `"allow"`도 이를 재정의할 수 없습니다. Claude Code는 여전히 stdout에서 유효한 [JSON 출력](#json-output)을 읽습니다. `Elicitation` 및 `ElicitationResult`에서는 종료 2 hook의 `hookSpecificOutput`이 무시됩니다.872작업을 차단하려면 코드 2로 종료합니다. [차단할 수 있는 이벤트](#exit-code-2-behavior-per-event)에서 Claude Code는 작업을 중지합니다. 예를 들어 `PreToolUse` hook은 도구 호출을 차단하고 `UserPromptSubmit` hook은 프롬프트를 거부합니다.

853 873

854차단 메시지는 JSON이 차단 결정을 하는 경우 해당 결정의 이유이며, 그렇지 않으면 stderr 텍스트입니다. 차단이 수행하는 작업은 이벤트에 따라 다릅니다: `PreToolUse`는 도구 호출을 차단하고 `UserPromptSubmit`은 프롬프트를 거부하는 식입니다. [이벤트별 종료 코드 2 동작](#exit-code-2-behavior-per-event)은 모든 이벤트의 효과를 나열하며, 각 이벤트의 섹션에서 메시지가 어디로 가는지 설명합니다.874차단과 함께 전달되는 메시지는 hook의 stderr입니다. hook이 차단 결정을 하는 JSON도 출력했다면 Claude Code는 대신 해당 결정의 이유를 사용합니다.

855 875

856[JSON 출력](#json-output) 스키마 검증에 실패하는 JSON을 출력하면서 종료 2로 나가는 hook은 여전히 차단합니다: Claude Code는 stderr을 차단 이유로 사용하고 검증 실패를 디버그 로그에 기록합니다. v2.1.214 이전에는 Claude Code가 해당 조합을 차단하지 않는 오류로 취급하여 작업이 진행되었습니다.876hook이 JSON을 출력하더라도 종료 2는 차단합니다:

877

878* **스키마 검증을 통과하는 JSON**: Claude Code는 여전히 [JSON 출력](#json-output) 필드를 읽지만 필드가 차단을 재정의할 수는 없습니다. `permissionDecision`의 `"allow"`도 작업을 통과시키지 않습니다. `Elicitation` 및 `ElicitationResult`에서는 종료 2 hook의 `hookSpecificOutput`이 무시됩니다.

879* **스키마 검증에 실패하는 JSON**: hook은 여전히 차단합니다. Claude Code는 stderr을 차단 이유로 사용하고 검증 실패를 디버그 로그에 기록합니다.

857 880

858이 스크립트는 종료 2로 `rm` 명령을 차단하고 다른 모든 명령은 일반 권한 흐름에 맡깁니다:881이 스크립트는 종료 2로 `rm` 명령을 차단하고 다른 모든 명령은 일반 권한 흐름에 맡깁니다:

859 882

871exit 0 # No decision: the normal permission flow applies894exit 0 # No decision: the normal permission flow applies

872```895```

873 896

897이 스크립트를 `Bash`에 대한 `PreToolUse` hook으로 등록하면 `rm`으로 시작하는 명령이 차단되고, Claude는 이벤트 이름, 도구 이름, hook의 명령이 접두사로 붙은 hook의 stderr을 도구의 오류로 받습니다:

898

899```text theme={null}

900PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/no-rm.sh]: Blocked: rm commands are not allowed

901```

902

874<h4 id="other-exit-codes">903<h4 id="other-exit-codes">

875 다른 종료 코드904 다른 종료 코드

876</h4>905</h4>

877 906

878다른 종료 코드는 대부분의 hook 이벤트에서 그 자체로는 차단하지 않습니다. 발생하는 일은 stdout에 따라 다릅니다:907hook이 0 또는 2 이외의 코드로 종료하고 stdout에 일반 텍스트를 출력하거나 아무것도 출력하지 않으면 실행은 [차단하지 않는 오류](#exit-code-output)가 됩니다. 트랜스크립트에는 `Failed with non-blocking status code:`와 hook의 stderr 첫 번째 줄이 포함된 `<hook name> hook error` 알림이 표시됩니다. 예를 들어 `Bash`에 대한 `PreToolUse` hook이 stderr에 `something broke`를 출력하고 1로 종료하면 `PreToolUse:Bash hook error` 알림에 다음 줄이 표시됩니다:

879 908

880* 스키마 검증을 통과하는 구문 분석된 객체가 있으면, 표준 결정 모델을 사용하는 이벤트의 경우 Claude Code는 종료 코드를 무시하고 JSON만으로 결과를 결정합니다:909```text theme={null}

881 * 이벤트가 지원하는 각 필드는 `permissionDecision`, `additionalContext`, `updatedInput`, `systemMessage`를 포함하여 적용되며 hook은 오류로 보고되지 않습니다.910Failed with non-blocking status code: something broke

882 * [결정 제어](#decision-control)는 이벤트별 결정 필드를 나열합니다. `systemMessage`와 같은 범용 필드는 [JSON 출력](#json-output) 표를 따릅니다.911```

883* 스키마 검증에 실패하는 구문 분석된 객체가 있으면, 표준 결정 모델을 사용하는 이벤트의 경우 [종료 0](#exit-code-0)과 동일한 차단하지 않는 오류입니다: 작업이 진행되고 `<hook name> hook error` 알림에 검증 메시지가 표시됩니다.

884* Claude Code가 [JSON으로 구문 분석하려고 시도하고 실패](#exit-code-0)하는 stdout이 있으면, 표준 결정 모델을 사용하는 이벤트에 대해 Claude Code는 종료 0과 동일한 차단하지 않는 오류를 보고합니다. 작업이 진행되고 알림에 구문 분석 메시지가 표시됩니다.

885* Claude Code가 [일반 텍스트로 취급](#exit-code-0)하는 stdout이 있거나 stdout이 비어 있으면 대부분의 hook 이벤트에서 차단하지 않는 오류입니다: 작업이 진행되고 트랜스크립트는 `<hook name> hook error` 알림과 함께 `Failed with non-blocking status code:` 접두사가 붙은 stderr의 첫 번째 줄을 표시합니다. 전체 stderr을 캡처하려면 [디버그 로깅](#debug-hooks)을 활성화합니다.

886 912

887표준 결정 모델 외부의 이벤트는 [이벤트별 표](#exit-code-2-behavior-per-event)의 자체 행을 따릅니다: `WorktreeCreate`는 JSON 내용과 관계없이 0이 아닌 종료 코드에서 생성을 실패시키고, `StopFailure`와 같이 hook 출력을 완전히 버리는 이벤트는 모든 종료 코드에서 JSON을 무시합니다. 단, `terminalSequence`와 같은 부수 효과 필드는 여전히 동작합니다.913첫 번째 줄이 아닌 전체 stderr을 캡처하려면 [디버그 로깅](#debug-hooks)을 활성화합니다.

888 914

889시작할 수 없는 hook도 동일한 차단하지 않는 범주에 속합니다. 스크립트 경로가 존재하지 않거나 실행 가능하지 않으면 셸은 127과 같은 코드로 종료되고 인터프리터의 메시지와 함께 동일한 알림이 표시됩니다. 예: `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`. 대부분의 hook 이벤트에서 작업이 진행됩니다. 정책 hook을 설정할 때 첫 번째 실행에서 이 알림을 확인하세요: `settings.json`의 경로에 오타가 있으면 게이트가 조용히 비활성화됩니다.915시작할 수 없는 hook도 차단하지 않는 오류입니다. 셸 형식에서 스크립트 경로가 존재하지 않거나 실행 가능하지 않으면 셸은 127과 같은 코드로 종료되고 알림에 인터프리터의 메시지가 표시됩니다. 예: `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`. 정책 hook을 설정할 때는 첫 번째 실행에서 이 알림을 확인하세요. `settings.json`의 경로에 오타가 있으면 hook이 전혀 실행되지 않습니다. 대신 작업을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.

890 916

891<Warning>917<Warning>

892 대부분의 hook 이벤트에서 종료 코드 2는 코드만으로 차단하는 유일한 종료 코드입니다. stdout에 유효한 JSON이 없으면 Claude Code는 1이 관례적인 Unix 실패 코드임에도 불구하고 종료 코드 1을 차단하지 않는 오류로 취급하고 작업을 진행합니다. hook이 정책을 적용하기 위한 것이라면 `exit 2`를 사용합니다. worktree 이벤트는 다릅니다: `WorktreeCreate`의 0이 아닌 종료 코드는 worktree 생성을 중단하고, `WorktreeRemove`의 0이 아닌 종료 코드는 이후에도 디렉터리가 여전히 존재하면 worktree 제거를 실패하게 합니다.918 stdout에 유효한 JSON이 없으면 Claude Code는 1이 관례적인 Unix 실패 코드임에도 불구하고 종료 코드 1을 차단하지 않는 오류로 취급합니다. hook이 정책을 적용하기 위한 것이라면 `exit 2`를 사용합니다.

893</Warning>919</Warning>

894 920

895<h4 id="timeouts">921<h4 id="timeouts">

900 926

901[`PreModelSwitch`](#premodelswitch)에서는 타임아웃으로 취소된 hook이 모델 전환을 차단합니다. `PreToolUse`에서는 두 hook 유형이 다르게 동작합니다:927[`PreModelSwitch`](#premodelswitch)에서는 타임아웃으로 취소된 hook이 모델 전환을 차단합니다. `PreToolUse`에서는 두 hook 유형이 다르게 동작합니다:

902 928

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

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

905 931

932<h4 id="block-the-action-when-a-hook-fails">

933 hook이 실패할 때 작업 차단

934</h4>

935

936대부분의 이벤트에서 hook이 실패하거나 시간 초과되어도 Claude Code는 작업을 계속 수행하므로, 경로가 잘못되었거나 스크립트가 충돌하는 정책 hook은 모든 것을 통과시킵니다. 대신 작업을 차단하려면 `command` 또는 `http` hook에 `"onFailure": "block"`을 설정합니다. 기본값은 `"continue"`입니다. Claude Code v2.1.295 이상이 필요합니다.

937

938`.claude/settings.json`의 이 `PreToolUse` hook은 각 Bash 명령 전에 프로젝트 스크립트를 실행하고, 스크립트가 실패하면 명령을 차단합니다:

939

940```json theme={null}

941{

942 "hooks": {

943 "PreToolUse": [

944 {

945 "matcher": "Bash",

946 "hooks": [

947 {

948 "type": "command",

949 "command": "node",

950 "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],

951 "onFailure": "block"

952 }

953 ]

954 }

955 ]

956 }

957}

958```

959

960테스트하려면 `check-command.js`를 없는 상태로 두고 Claude에 `ls`와 같은 Bash 명령을 실행하도록 요청합니다. Claude Code는 호출을 차단하며, 오류에는 `failed; blocking because onFailure is "block"`과 그 뒤에 node 자체의 오류 출력이 포함됩니다. 여기서는 한 줄로 줄였습니다:

961

962```text theme={null}

963PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block"

964Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js'

965```

966

967타임아웃 후에는 메시지에 `failed` 대신 `timed out`이 표시됩니다. `onFailure`를 설정하지 않으면 동일하게 스크립트가 없는 경우에도 차단하지 않는 오류가 되며 `ls`가 실행됩니다.

968

969다음 각 항목은 실패로 간주됩니다:

970

971* **시작할 수 없음**: 예를 들어 스크립트나 실행 파일이 존재하지 않아 명령 hook이 시작되지 않는 경우

972* **0 또는 2 이외의 종료 코드**: 명령 hook이 `permissionDecision: "allow"`처럼 작업을 허용하는 JSON을 출력했더라도 실패로 간주됩니다. JSON 결정을 반환하려면 0으로 종료합니다

973* **HTTP 오류**: HTTP hook의 연결이 실패하거나 응답 상태가 2xx가 아닌 경우

974* **타임아웃**: hook이 [`timeout`](#common-fields)에 도달한 경우

975* **잘못된 출력**: JSON 출력을 [구문 분석할 수 없거나](#exit-code-0) [스키마 검증](#json-output)에 실패하는 경우. HTTP hook의 경우 비어 있지도 않고 JSON 객체도 아닌 2xx 본문도 포함됩니다. 명령 hook의 일반 텍스트 stdout은 실패가 아닙니다

976

977`"block"`이 설정되면 실패는 [해당 이벤트에서 종료 코드 2가 하는 일](#exit-code-2-behavior-per-event)을 수행합니다. 단, `PermissionRequest`에서는 요청을 거부합니다. 예를 들어 `PreToolUse` 실패는 도구 호출을 차단하고 `UserPromptSubmit` 실패는 프롬프트를 차단합니다.

978

979이 필드는 다음 hook에는 효과가 없습니다:

980

981* **`Stop`, `SubagentStop`, `TaskCompleted`, `TeammateIdle` hook**: 이러한 이벤트에서 종료 코드 2는 Claude가 계속 작업하도록 되돌려 보내며, Claude는 실행되지 않는 hook을 고칠 수 없습니다

982* **백그라운드 명령 hook**: [`async` 또는 `asyncRewake`](#run-hooks-in-the-background)를 설정한 명령 hook

983

906<h4 id="exit-code-2-behavior-per-event">984<h4 id="exit-code-2-behavior-per-event">

907 이벤트별 종료 코드 2 동작985 이벤트별 종료 코드 2 동작

908</h4>986</h4>

960* **연결 실패**: 차단하지 않는 오류, 실행이 계속됨1038* **연결 실패**: 차단하지 않는 오류, 실행이 계속됨

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

962 1040

963명령 hook과 달리 HTTP hook은 상태 코드만으로 차단 오류를 신호할 수 없습니다. 도구 호출을 차단하거나 권한을 거부하려면 적절한 결정 필드를 포함하는 JSON 본문과 함께 2xx 응답을 반환합니다.1041HTTP hook은 상태 코드만으로 차단 오류를 신호할 수 없습니다. 2xx가 아닌 상태나 실패한 연결은 [차단하지 않는 오류](#exit-code-output)입니다. 도구 호출을 차단하거나 권한을 거부하려면 적절한 결정 필드를 포함하는 JSON 본문과 함께 2xx 응답을 반환합니다. 요청이 실패하거나 2xx가 아닌 상태를 반환할 때 작업을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.

964 1042

965<h3 id="json-output">1043<h3 id="json-output">

966 JSON 출력1044 JSON 출력

1237 SessionStart 결정 제어1315 SessionStart 결정 제어

1238</h4>1316</h4>

1239 1317

1240Claude Code는 [일반 텍스트로 처리하는](#exit-code-0) stdout을 Claude의 컨텍스트에 추가합니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 다음 이벤트별 필드를 반환할 수 있습니다:1318SessionStart 훅은 Claude를 위한 컨텍스트 추가, 첫 사용자 메시지 제공, 세션 제목 설정, 파일 감시, 스킬 다시 로드를 할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에 각 항목에 해당하는 필드를 반환합니다.

1241 1319

1242| 필드 | 설명 |1320| 필드 | 설명 |

1243| :- | :- |1321| :- | :- |

1244| `additionalContext` | 대화 시작 시 첫 프롬프트 전에 Claude의 컨텍스트에 추가되는 문자열. 텍스트가 전달되는 방식과 넣을 내용은 [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |1322| `additionalContext` | 대화 시작 시 첫 프롬프트 전에 Claude의 컨텍스트에 추가되는 문자열. 텍스트가 전달되는 방식과 넣을 내용은 [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |

1245| `initialUserMessage` | 세션의 첫 사용자 메시지로 사용되는 문자열. `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에 적용되며, 프롬프트가 제공되지 않아도 첫 턴이 됩니다. 프롬프트가 제공되면 그다음 턴으로 이어집니다. 기존 턴에 첨부되는 `additionalContext`와 달리 이 필드는 턴을 생성합니다 |1323| `initialUserMessage` | `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에서 세션의 첫 사용자 메시지로 사용되는 문자열입니다. 프롬프트를 전달하지 않아도 첫 턴이 됩니다. 프롬프트를 전달하면 그 프롬프트는 다음 턴으로 이어집니다 |

1246| `sessionTitle` | 세션 제목을 설정하며 `/rename`과 동일한 효과가 있습니다. 실행 폴더, git 브랜치 또는 worktree 이름으로 세션 이름을 자동 지정하는 데 사용합니다. `source`가 `"startup"`, `"resume"` 또는 `"fork"`일 때 적용되며, `"clear"`와 `"compact"`에서는 무시됩니다 |1324| `sessionTitle` | 세션 제목을 설정하며, `/rename`과 같은 효과를 냅니다. `source`가 `"startup"`, `"resume"` 또는 `"fork"`일 때 적용됩니다 |

1248| `reloadSkills` | 불리언. `true`이면 Claude Code는 SessionStart 훅이 완료된 후 [스킬](/docs/ko/skills) 및 명령 디렉터리를 다시 스캔하므로, 훅이 설치한 스킬을 첫 프롬프트부터 같은 세션에서 사용할 수 있습니다 |1326| `reloadSkills` | 불리언입니다. `true`이면 SessionStart 훅이 완료된 후 Claude Code가 [스킬](/docs/ko/skills) 및 명령 디렉터리를 다시 스캔합니다. [훅이 설치한 스킬 다시 로드](#reload-skills-that-a-hook-installs)를 참조하세요 |

1327

1328이 출력은 컨텍스트를 추가하고 세션 이름을 지정합니다.

1249 1329

1250```json theme={null}1330```json theme={null}

1251{1331{

1257}1337}

1258```1338```

1259 1339

1260이 이벤트에서는 일반 stdout이 이미 Claude에 전달되므로, 컨텍스트만 로드하는 훅은 JSON을 만들지 않고 stdout에 바로 출력할 수 있습니다. 컨텍스트를 `sessionTitle` 같은 다른 필드와 결합해야 할 때 JSON 형식을 사용하세요.1340컨텍스트만 추가하는 훅은 JSON을 만들지 않고 출력만 해도 됩니다. Claude Code는 SessionStart 훅의 [일반 텍스트 stdout](#exit-code-0)을 Claude의 컨텍스트에 추가하기 때문입니다.

1341

1342플러그인의 SessionStart 훅이 `initialUserMessage` 또는 `sessionTitle`을 제공한다면 세션이 시작되기 전에 플러그인을 설치하세요. SessionStart 훅이 실행된 후에 설치가 완료된 플러그인의 두 필드는 Claude Code가 무시합니다.

1343

1344<h4 id="reload-skills-that-a-hook-installs">

1345 훅이 설치한 스킬 다시 로드

1346</h4>

1347

1348SessionStart 훅이 설치한 스킬을 같은 세션에서 사용할 수 있게 하려면 `reloadSkills`를 반환하세요. 스킬 검색은 일반적으로 SessionStart 훅이 완료되기 전에 실행되므로, 이 필드가 없으면 훅이 `~/.claude/skills/` 또는 `.claude/skills/`에 쓴 파일이 첫 프롬프트 실행 시 누락될 수 있습니다.

1261 1349

1262SessionStart 훅이 스킬을 설치하거나 업데이트할 때는 `reloadSkills`를 사용하세요. 스킬 검색은 일반적으로 SessionStart 훅이 완료되기 전에 실행되므로, 이 필드가 없으면 훅이 `~/.claude/skills/` 또는 `.claude/skills/`에 쓴 파일은 다음 세션에서만 나타납니다. 이 예시는 공유 스킬 저장소를 동기화하고 다시 스캔을 요청합니다:1350이 예시는 공유 스킬 저장소를 동기화하고 다시 스캔을 요청합니다.

1263 1351

1264```bash theme={null}1352```bash theme={null}

1265#!/bin/bash1353#!/bin/bash

1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1358echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

1271```1359```

1272 1360

1273저장소 URL은 자리 표시자이므로 자체 스킬 저장소로 바꾸세요. 자리 표시자를 그대로 두면 clone이 실패하고 stderr에 `fatal:` 메시지가 출력됩니다. 0으로 종료되는 SessionStart 훅의 stderr는 정보 제공용일 뿐이므로 `reloadSkills` 요청은 여전히 적용됩니다.1361저장소 URL은 예시용입니다. 자신의 스킬 저장소로 바꾸세요.

1274 1362

1275<h4 id="persist-environment-variables">1363<h4 id="persist-environment-variables">

1276 환경 변수 유지1364 환경 변수 유지

1419 1507

1420`UserPromptSubmit` 훅은 `command`, `http`, `mcp_tool` 유형의 기본 타임아웃이 30초로, 대부분의 다른 이벤트에서 이러한 유형의 기본값인 600초보다 짧습니다. 이 훅은 모든 프롬프트 전에 실행되고 완료될 때까지 모델 처리를 차단하므로, 멈춘 훅은 세션을 정지시킵니다. 훅에 더 많은 시간이 필요하면 훅 항목에서 `timeout` 필드를 설정하세요.1508`UserPromptSubmit` 훅은 `command`, `http`, `mcp_tool` 유형의 기본 타임아웃이 30초로, 대부분의 다른 이벤트에서 이러한 유형의 기본값인 600초보다 짧습니다. 이 훅은 모든 프롬프트 전에 실행되고 완료될 때까지 모델 처리를 차단하므로, 멈춘 훅은 세션을 정지시킵니다. 훅에 더 많은 시간이 필요하면 훅 항목에서 `timeout` 필드를 설정하세요.

1421 1509

1422[`async: true`](#run-hooks-in-the-background)로 실행하는 command 훅을 제외하고, 타임아웃에 도달한 `UserPromptSubmit` command, HTTP 또는 MCP 도구 훅은 취소되며 `additionalContext`를 포함한 출력은 버려집니다. 프롬프트는 해당 컨텍스트 없이 여전히 Claude에 전달됩니다. 트랜스크립트에는 훅 이름, 발생한 타임아웃, 출력이 버려졌다는 사실을 알리는 알림이 표시됩니다.1510[`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)을 설정하십시오. 트랜스크립트에는 훅 이름, 발생한 타임아웃, 출력이 버려졌다는 사실을 알리는 알림이 표시됩니다.

1423 1511

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

1425 1513

1860| :- | :- | :- | :- |1948| :- | :- | :- | :- |

1863 1952

1864<h5 id="websearch">1953<h5 id="websearch">

1865 WebSearch1954 WebSearch

2114 2203

2115`decision` 객체 없이 종료 코드 2로 종료하는 훅은 권한 흐름을 변경하지 않으며, stderr는 버려집니다. `decision` 객체만 요청을 허용하거나 거부할 수 있습니다.2204`decision` 객체 없이 종료 코드 2로 종료하는 훅은 권한 흐름을 변경하지 않으며, 해당 stderr는 버려집니다. 요청을 허용하거나 거부하려면 `decision` 객체를 반환하십시오.

2116 2205

2117```json theme={null}2206```json theme={null}

2118{2207{

2678 TaskCreated 결정 제어2767 TaskCreated 결정 제어

2679</h4>2768</h4>

2680 2769

2681TaskCreated 훅은 두 가지 방법으로 생성을 차단할 수 있습니다. 어느 방법이든 Claude Code는 작업을 삭제하고 메시지를 도구 오류로 Claude에게 반환합니다. Claude Code는 이 이벤트의 `continue: false`를 무시하며 Claude는 계속 작업합니다.2770TaskCreated 훅은 종료 코드 2 또는 JSON 결정으로 생성을 차단할 수 있습니다. 어느 경우든 Claude Code는 작업을 삭제하고 메시지를 도구의 오류로 Claude에 반환합니다. Claude Code는 이 이벤트의 `continue: false`를 무시하며 Claude는 계속 작업합니다.

2682 2771

2683* **종료 코드 2**: Claude Code가 stderr 텍스트를 메시지로 반환합니다.2772* **종료 코드 2**: Claude Code가 stderr 텍스트를 메시지로 반환합니다.

2684* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code가 `reason`을 메시지로 반환합니다.2773* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code가 `reason`을 메시지로 반환합니다.

3561 3650

3562Claude Code는 결정과 관계없이 훅이 반환한 `systemMessage`를 사용자에게 표시하므로, 비용 보고 훅은 `{"systemMessage": "..."}`를 반환하고 0으로 종료할 수 있습니다.3651Claude Code는 결정과 관계없이 훅이 반환한 `systemMessage`를 사용자에게 표시하므로, 비용 보고 훅은 `{"systemMessage": "..."}`를 반환하고 0으로 종료할 수 있습니다.

3563 3652

3564타임아웃 전에 응답하지 않는 PreModelSwitch 훅은 전환을 차단합니다. 반면 [PreToolUse](#timeouts)에서는 시간 초과된 명령 훅이 도구 호출을 계속 진행하도록 허용합니다. 이 이벤트의 기본 타임아웃은 30초입니다. `PreModelSwitch`는 `command`, `http`, `mcp_tool` 훅만 실행하므로 `prompt` 및 `agent`의 기본값은 적용되지 않습니다.3653타임아웃 전에 응답하지 않는 PreModelSwitch 훅은 전환을 차단합니다. 다른 이벤트에서 타임아웃이 미치는 영향은 [Timeouts](#timeouts)를 참조하십시오. 이 이벤트의 기본 타임아웃은 30초입니다. `PreModelSwitch`는 `command`, `http`, `mcp_tool` 훅만 실행하므로 `prompt` 및 `agent` 기본값은 적용되지 않습니다.

3565 3654

35660이나 2가 아닌 코드로 종료하고 JSON 결정을 출력하지 않는 훅은 차단하지 않습니다. [기타 종료 코드](#other-exit-codes)에서 설명한 대로 Claude Code는 stderr를 표시하고 전환을 적용합니다.36550 또는 2가 아닌 코드로 종료하고 JSON 결정을 출력하지 않는 훅은 [기타 종료 코드](#other-exit-codes)에 설명된 대로 차단하지 않는 오류입니다.

3567 3656

3568<h3 id="postmodelswitch">3657<h3 id="postmodelswitch">

3569 PostModelSwitch3658 PostModelSwitch

4279비동기 hook은 동기 hook과 비교하여 여러 제약이 있습니다:4368비동기 hook은 동기 hook과 비교하여 여러 제약이 있습니다:

4280 4369

4281* Hook 출력은 다음 대화 턴에 전달됩니다. 세션이 유휴 상태이면 응답은 다음 사용자 상호 작용까지 기다립니다. 예외: `asyncRewake` hook이 종료 코드 2로 종료되면 세션이 유휴 상태일 때도 Claude를 즉시 깨웁니다.4370* Hook 출력은 다음 대화 턴에 전달됩니다. 세션이 유휴 상태이면 응답은 다음 사용자 상호 작용까지 기다립니다. 예외: `asyncRewake` hook이 종료 코드 2로 종료되면 세션이 유휴 상태일 때도 Claude를 즉시 깨웁니다.

4282* 각 실행은 별도의 백그라운드 프로세스를 생성합니다. 동일한 비동기 hook의 여러 발생에 걸쳐 중복 제거가 없습니다.4371* 각 실행은 별도의 백그라운드 프로세스를 생성합니다.

4283 4372

4284<h2 id="security-considerations">4373<h2 id="security-considerations">

4285 보안 고려 사항4374 보안 고려 사항

hooks-guide.md +14 −11

Details

242 242

243hook을 테스트하려면 Claude에게 JavaScript 파일에 단일 따옴표 문자열이 있는 줄을 추가하도록 요청한 다음 파일을 엽니다: Prettier의 기본 설정을 사용하면 hook이 이를 이중 따옴표로 다시 작성합니다.243hook을 테스트하려면 Claude에게 JavaScript 파일에 단일 따옴표 문자열이 있는 줄을 추가하도록 요청한 다음 파일을 엽니다: Prettier의 기본 설정을 사용하면 hook이 이를 이중 따옴표로 다시 작성합니다.

244 244

245hook이 성공하면 Claude Code는 대화에서 아무것도 표시하지 않습니다. hook이 실행되었는지 확인하려면 편집된 파일이 다시 형식화되었는지 확인하거나 [디버그 기법](#debug-techniques)을 참조하세요.245훅이 성공하면 Claude Code는 대화에서 아무것도 표시하지 않습니다. 훅이 실행되었는지 확인하려면 편집된 파일이 다시 형식화되었는지 확인하거나 [훅이 수행한 작업 확인](#check-what-a-hook-did)을 참조하세요.

246 246

247`Bash` 명령이 파일을 다시 작성할 때를 포함하여 파일이 어떻게 변경되든 특정 파일을 다시 형식화하려면 대신 [FileChanged](/docs/ko/hooks#filechanged) hook을 사용합니다.247`Bash` 명령이 파일을 다시 작성할 때를 포함하여 파일이 어떻게 변경되든 특정 파일을 다시 형식화하려면 대신 [FileChanged](/docs/ko/hooks#filechanged) hook을 사용합니다.

248 248

979}979}

980```980```

981 981

982엔드포인트는 명령 hooks와 동일한 [출력 형식](/docs/ko/hooks#json-output)을 사용하여 JSON 응답 본문을 반환해야 합니다. 도구 호출을 차단하려면 적절한 `hookSpecificOutput` 필드와 함께 2xx 응답을 반환합니다. HTTP 상태 코드만으로는 작업을 차단할 수 없습니다.982엔드포인트는 명령 hooks와 동일한 [출력 형식](/docs/ko/hooks#json-output)의 JSON 본문으로 응답하며, Claude Code는 응답 상태도 확인합니다:

983

984* **2xx 상태**: 도구 호출을 차단하려면 본문에 적절한 `hookSpecificOutput` 필드를 반환합니다.

985* **그 외 모든 상태 또는 요청 실패**: Claude Code는 [비차단 오류](/docs/ko/hooks#exit-code-output)를 보고하고 작업을 계속 진행합니다. 엔드포인트가 실패했을 때 작업을 차단하려면 hook에 [`onFailure: "block"`](/docs/ko/hooks#block-the-action-when-a-hook-fails)을 설정합니다.

983 986

984헤더 값은 `$VAR_NAME` 또는 `${VAR_NAME}` 구문을 사용한 환경 변수 보간을 지원합니다. `allowedEnvVars` 배열에 나열된 변수만 해결됩니다. 다른 모든 `$VAR` 참조는 비어 있습니다.987헤더 값은 `$VAR_NAME` 또는 `${VAR_NAME}` 구문을 사용한 환경 변수 보간을 지원합니다. `allowedEnvVars` 배열에 나열된 변수만 해결됩니다. 다른 모든 `$VAR` 참조는 비어 있습니다.

985 988

1103 1106

1104Hook이 `permissionDecision` 또는 `additionalContext`를 `hookSpecificOutput` 내부가 아닌 최상위 수준에서 반환할 때 JSON은 여전히 구문 분석되고 Claude Code는 잘못된 위치의 필드를 무시하고 오류를 보고하지 않습니다. 무시된 필드를 확인하려면 `claude --debug`로 Claude Code를 시작하고 [디버그 로그](/docs/ko/hooks#debug-hooks)에서 `Hook JSON output had unrecognized keys`를 검색합니다.1107Hook이 `permissionDecision` 또는 `additionalContext`를 `hookSpecificOutput` 내부가 아닌 최상위 수준에서 반환할 때 JSON은 여전히 구문 분석되고 Claude Code는 잘못된 위치의 필드를 무시하고 오류를 보고하지 않습니다. 무시된 필드를 확인하려면 `claude --debug`로 Claude Code를 시작하고 [디버그 로그](/docs/ko/hooks#debug-hooks)에서 `Hook JSON output had unrecognized keys`를 검색합니다.

1105 1108

1106<h3 id="debug-techniques">1109<h3 id="check-what-a-hook-did">

1107 디버그 기법1110 훅이 수행한 작업 확인

1108</h3>1111</h3>

1109 1112

1110`Ctrl+O`를 눌러 트랜스크립트 보기를 열어 hook 실행의 결과를 확인합니다:1113`Ctrl+O`를 눌러 트랜스크립트 보기를 열고 훅의 결과를 확인합니다:

1111 1114

1112* **성공적인 실행**: hook의 JSON이 `systemMessage` 또는 Stop hook 피드백과 같은 것을 표시하지 않는 한 아무것도 표시되지 않습니다.1115* **성공**: 훅의 JSON이 `systemMessage` 또는 Stop 훅 피드백과 같은 것을 표시하지 않는 한 아무것도 표시되지 않습니다.

1113 * Hook이 실행되었는지 확인하려면 재포맷된 파일과 같은 효과를 확인하거나 아래에 설명된 대로 디버그 로깅을 켜고 hook을 다시 트리거합니다1116 * 훅이 실행되었는지 확인하려면 재포맷된 파일과 같은 효과를 확인합니다

1114* **차단 오류**: 대부분의 이벤트에서 hook의 피드백이 표시됩니다. Hook의 JSON이 차단 결정을 내렸을 때 피드백은 해당 결정의 이유입니다. 그렇지 않으면 hook의 stderr입니다. `ConfigChange` 및 `Elicitation`과 같은 몇 가지 이벤트에서는 블록이 메시지를 표시하지 않습니다.1117* **차단 오류**: 대부분의 이벤트에서는 차단과 함께 전달된 메시지(예: `Blocked: rm commands are not allowed`)가 표시됩니다. `ConfigChange` 및 `Elicitation`과 같은 몇 가지 이벤트에서는 메시지가 표시되지 않습니다. 메시지의 출처는 [종료 코드 2](/docs/ko/hooks#exit-code-2)에서 다룹니다.

1115* **차단하지 않는 오류**: 작업이 진행되었고 `<hook name> hook error` 공지가 표시되며 stderr의 첫 번째 줄이 `Failed with non-blocking status code:`로 접두사가 붙거나 JSON 검증 또는 구문 분석 메시지와 같은 간단한 설명이 표시됩니다.1118* **차단하지 않는 오류**: `Failed with non-blocking status code:` 뒤에 오는 stderr의 첫 번째 줄이나 JSON 검증 또는 구문 분석 메시지와 같은 간단한 설명과 함께 `<hook name> hook error` 공지가 표시됩니다. 작업은 계속 진행되었습니다.

1116 1119

1117각 결과를 생성하는 종료 코드 및 JSON 조합(이벤트별 예외 포함)은 참조의 [Exit code output](/docs/ko/hooks#exit-code-output) 섹션에 정의되어 있습니다.1120이벤트별 예외를 포함하여 특정 종료 코드와 stdout에 대한 결과를 확인하려면 참조의 [Exit code output](/docs/ko/hooks#exit-code-output)을 참조하십시오.

1118 1121

1119전체 실행 세부 정보(일치한 hooks, 종료 코드, stdout 및 stderr 포함)는 디버그 로그를 읽습니다. `claude --debug-file /tmp/claude.log`로 Claude Code를 시작하여 알려진 경로에 쓰거나 다른 터미널에서 `tail -f /tmp/claude.log`를 실행합니다. 해당 플래그 없이 시작한 경우 세션 중에 `/debug`를 실행하여 로깅을 활성화하고 로그 경로를 찾습니다.1122훅 종료 코드, stdout 및 stderr를 포함한 전체 실행 세부 정보는 디버그 로그에서 확인합니다. `claude --debug-file /tmp/claude.log`로 Claude Code를 시작하여 알려진 경로에 로그를 쓴 다음, 다른 터미널에서 `tail -f /tmp/claude.log`를 실행합니다. 해당 플래그 없이 시작한 경우 세션 중에 `/debug`를 실행하여 로깅을 활성화하고 로그 경로를 찾습니다.

1120 1123

1121<h2 id="learn-more">1124<h2 id="learn-more">

1122 자세히 알아보기1125 자세히 알아보기

interactive-mode.md +6 −5

Details

216| `^` | 첫 번째 공백이 아닌 문자 |216| `^` | 첫 번째 공백이 아닌 문자 |

217| `gg` | 입력의 시작 |217| `gg` | 입력의 시작 |

218| `G` | 마지막 줄의 시작 |218| `G` | 마지막 줄의 시작 |

219| `f{char}` | 다음 문자 발생으로 점프 |219| `f{char}` | 현재 줄에서 다음 문자 발생으로 점프 |

220| `F{char}` | 이전 문자 발생으로 점프 |220| `F{char}` | 현재 줄에서 이전 문자 발생으로 점프 |

221| `t{char}` | 다음 문자 발생 바로 앞으로 점프 |221| `t{char}` | 현재 줄에서 다음 문자 발생 바로 앞으로 점프 |

222| `T{char}` | 이전 문자 발생 바로 뒤로 점프 |222| `T{char}` | 현재 줄에서 이전 문자 발생 바로 뒤로 점프 |

223| `;` | 마지막 f/F/t/T 모션 반복 |223| `;` | 마지막 f/F/t/T 모션 반복 |

224| `,` | 마지막 f/F/t/T 모션을 역순으로 반복 |224| `,` | 마지막 f/F/t/T 모션을 역순으로 반복 |

225| `/` | 역방향 히스토리 검색을 열기, `Ctrl+R`과 동일합니다. 빈 검색 프롬프트는 힌트를 표시합니다: `Esc`를 누른 후 `i`를 누른 후 `/`를 눌러 명령어 메뉴를 대신 열기 |225| `/` | 역방향 히스토리 검색을 열기, `Ctrl+R`과 동일합니다. 빈 검색 프롬프트는 힌트를 표시합니다: `Esc`를 누른 후 `i`를 누른 후 `/`를 눌러 명령어 메뉴를 대신 열기 |

239| `dd` | 줄 삭제 |239| `dd` | 줄 삭제 |

240| `D` | 줄의 끝까지 삭제 |240| `D` | 줄의 끝까지 삭제 |

242| `df{char}`/`dt{char}` | 다음 문자 발생까지 포함하여 또는 까지 삭제 |242| `df{char}`/`dt{char}` | 현재 줄에서 다음 문자 발생 위치까지(해당 문자 포함 또는 바로 앞까지) 삭제 |

245| `d0`/`c0`/`y0` | 커서에서 줄의 시작까지 삭제, 변경 또는 야앙크합니다. Claude Code v2.1.281 이상이 필요합니다 |245| `d0`/`c0`/`y0` | 커서에서 줄의 시작까지 삭제, 변경 또는 야앙크합니다. Claude Code v2.1.281 이상이 필요합니다 |

859* 단순한 `#123`859* 단순한 `#123`

860* `group/subgroup/project#123`과 같은 중첩된 GitLab 경로860* `group/subgroup/project#123`과 같은 중첩된 GitLab 경로

861* 코드 스팬 또는 코드 블록 내의 모든 참조861* 코드 스팬 또는 코드 블록 내의 모든 참조

862* 약 1,000줄 또는 100,000자를 초과하는 응답 내의 모든 참조

862 863

863Claude Code는 참조가 지칭하는 저장소가 아니라, git 원격에서 식별한 저장소의 호스트에 맞춰 링크를 구성합니다:864Claude Code는 참조가 지칭하는 저장소가 아니라, git 원격에서 식별한 저장소의 호스트에 맞춰 링크를 구성합니다:

864 865

jetbrains.md +8 −4

Details

55 사용법55 사용법

56</h2>56</h2>

57 57

~~58<h3 id="from-your-ide">~~58<span id="from-your-ide" />

~~59 IDE에서~~59

60<h3 id="run-claude-code-from-your-ide">

61 IDE에서 Claude Code 실행

60</h3>62</h3>

61 63

62IDE의 통합 터미널에서 `claude`를 실행하면 모든 통합 기능이 활성화됩니다.64IDE의 통합 터미널에서 `claude`를 실행하면 모든 통합 기능이 활성화됩니다.

63 65

~~64<h3 id="from-external-terminals">~~66<span id="from-external-terminals" />

~~65 외부 터미널에서~~67

68<h3 id="connect-from-an-external-terminal">

69 외부 터미널에서 연결

66</h3>70</h3>

67 71

68모든 외부 터미널에서 `/ide` 명령을 사용하여 Claude Code를 JetBrains IDE에 연결하고 모든 기능을 활성화합니다:72모든 외부 터미널에서 `/ide` 명령을 사용하여 Claude Code를 JetBrains IDE에 연결하고 모든 기능을 활성화합니다:

managed-settings.md +2 −0

Details

79 79

80Jamf, Iru, Intune 및 그룹 정책용 시작 템플릿은 [MDM 예제 저장소](https://github.com/anthropics/claude-code/tree/main/examples/mdm)에 있습니다.80Jamf, Iru, Intune 및 그룹 정책용 시작 템플릿은 [MDM 예제 저장소](https://github.com/anthropics/claude-code/tree/main/examples/mdm)에 있습니다.

81 81

82조직에 [HIPAA 구성](/docs/ko/hipaa-setup#deploy-managed-settings)이 적용되어 있다면, 샌드박싱, 네트워크 허용 목록, 자격 증명 보호, 로컬 데이터 보존이 포함된 더 완전한 `managed-settings.json`은 [설정 예제 저장소](https://github.com/anthropics/claude-code/tree/main/examples/settings)의 `settings-hipaa.json` 및 `README-hipaa.md`를 참조하세요.

82`managed-mcp.json`을 통해 이들 중 어느 것과 함께 배포하거나 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers) 키를 통해 제공하는 관리되는 MCP 서버의 경우 [관리되는 MCP 구성](/docs/ko/managed-mcp)을 참조하세요.84`managed-mcp.json`을 통해 이들 중 어느 것과 함께 배포하거나 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers) 키를 통해 제공하는 관리되는 MCP 서버의 경우 [관리되는 MCP 구성](/docs/ko/managed-mcp)을 참조하세요.

83 85

84<h3 id="where-and-when-a-policy-applies">86<h3 id="where-and-when-a-policy-applies">

mcp.md +18 −10

Details

181 181

182각각은 [MCP 서버 설치](#installing-mcp-servers)의 네 가지 옵션 중 하나가 취하는 입력 중 하나입니다. 아래에서 보유한 형태를 찾아 Claude Code가 허용하는 명령으로 변환하세요. 각 명령은 `--scope project` 또는 `--scope user`를 추가하지 않는 한 [로컬 범위](#local-scope)에 씁니다.182각각은 [MCP 서버 설치](#installing-mcp-servers)의 네 가지 옵션 중 하나가 취하는 입력 중 하나입니다. 아래에서 보유한 형태를 찾아 Claude Code가 허용하는 명령으로 변환하세요. 각 명령은 `--scope project` 또는 `--scope user`를 추가하지 않는 한 [로컬 범위](#local-scope)에 씁니다.

183 183

184<h4 id="from-a-url">184<span id="from-a-url" />

185 URL에서185

186<h4 id="add-a-server-from-a-url">

187 URL에서 서버 추가

186</h4>188</h4>

187 189

188URL은 서버가 원격임을 의미합니다. `https://` 엔드포인트의 경우 `--transport http`로 추가하거나, 지침에서 엔드포인트가 SSE를 사용한다고 말할 때 [옵션 2](#option-2-add-a-remote-sse-server)를 따르세요. `wss://` 엔드포인트의 경우 `--transport`가 `ws`를 허용하지 않으므로 대신 [옵션 4](#option-4-add-a-remote-websocket-server)를 사용하세요:190URL은 서버가 원격임을 의미합니다. `https://` 엔드포인트의 경우 `--transport http`로 추가하거나, 지침에서 엔드포인트가 SSE를 사용한다고 말할 때 [옵션 2](#option-2-add-a-remote-sse-server)를 따르세요. `wss://` 엔드포인트의 경우 `--transport`가 `ws`를 허용하지 않으므로 대신 [옵션 4](#option-4-add-a-remote-websocket-server)를 사용하세요:

193 195

194지침에서 API 키 또는 토큰 헤더도 제공하면 [옵션 1](#option-1-add-a-remote-http-server)에 표시된 대로 `--header`로 전달하세요.196지침에서 API 키 또는 토큰 헤더도 제공하면 [옵션 1](#option-1-add-a-remote-http-server)에 표시된 대로 `--header`로 전달하세요.

195 197

196<h4 id="from-an-npx-uvx-or-binary-command">198<span id="from-an-npx-uvx-or-binary-command" />

197 `npx`, `uvx` 또는 바이너리 명령에서199

200<h4 id="add-a-server-from-an-npx-uvx-or-binary-command">

201 `npx`, `uvx` 또는 바이너리 명령에서 서버 추가

198</h4>202</h4>

199 203

200시작 명령은 서버가 로컬 stdio 프로세스로 실행됨을 의미합니다. 전체 명령을 `--` 뒤에 배치하여 Claude Code가 `-y`와 같은 플래그를 서버를 시작하는 명령에 전달하도록 하고 자신의 옵션으로 읽지 않도록 하세요. 지침에서 요청하는 환경 변수를 `--env`로 전달하세요. 서버 이름 뒤에 `--` 앞에:204시작 명령은 서버가 로컬 stdio 프로세스로 실행됨을 의미합니다. 전체 명령을 `--` 뒤에 배치하여 Claude Code가 `-y`와 같은 플래그를 서버를 시작하는 명령에 전달하도록 하고 자신의 옵션으로 읽지 않도록 하세요. 지침에서 요청하는 환경 변수를 `--env`로 전달하세요. 서버 이름 뒤에 `--` 앞에:

205 209

206[옵션 3](#option-3-add-a-local-stdio-server)은 `--` 구분자를 완전히 다룹니다.210[옵션 3](#option-3-add-a-local-stdio-server)은 `--` 구분자를 완전히 다룹니다.

207 211

208<h4 id="from-an-mcpservers-json-block">212<span id="from-an-mcpservers-json-block" />

209 `mcpServers` JSON 블록에서213

214<h4 id="add-a-server-from-an-mcpservers-json-block">

215 `mcpServers` JSON 블록에서 서버 추가

210</h4>216</h4>

211 217

212Claude Desktop과 같은 다른 MCP 클라이언트용으로 작성된 `mcpServers` 블록은 Claude Code가 읽는 래퍼 키와 항목 형태를 사용합니다. `claude mcp add-json`에 `mcpServers` 내부의 객체를 전달하세요. 래퍼는 아닙니다. 두 항목은 먼저 수리가 필요합니다:218Claude Desktop과 같은 다른 MCP 클라이언트용으로 작성된 `mcpServers` 블록은 Claude Code가 읽는 래퍼 키와 항목 형태를 사용합니다. `claude mcp add-json`에 `mcpServers` 내부의 객체를 전달하세요. 래퍼는 아닙니다. 두 항목은 먼저 수리가 필요합니다:

367 373

368v2에서 Claude Code는 또한:374v2에서 Claude Code는 또한:

369 375

370* HTTP 및 stdio 서버에 더 새로운 개정을 지원하는지 묻고, 지원하는 서버와 함께 사용합니다. 기능 플래그를 가져오는 세션에서는 claude.ai 커넥터 서버에도 묻습니다. 다른 모든 서버에는 v1처럼 연결합니다.376* HTTP, stdio 및 claude.ai 커넥터 서버에 더 새로운 개정을 지원하는지 묻고, 지원하는 서버와 함께 사용합니다. 다른 모든 서버에는 v1처럼 연결합니다.

371* [열린 스트림](#notification-streams-on-the-v2-runtime)을 통해 더 새로운 개정의 서버에서 `list_changed` 알림을 받습니다.377* [열린 스트림](#notification-streams-on-the-v2-runtime)을 통해 더 새로운 개정의 서버에서 `list_changed` 알림을 받습니다.

372* 더 새로운 개정에 연결되는 [채널](#push-messages-with-channels) 서버를 등록하지 않습니다. 해당 개정은 채널 메시지를 전달할 수 없기 때문입니다.378* 더 새로운 개정에 연결되는 [채널](#push-messages-with-channels) 서버를 등록하지 않습니다. 해당 개정은 채널 메시지를 전달할 수 없기 때문입니다.

373* 인증 응답이 예상치 못한 발급자의 이름을 지정하는 [MCP OAuth 로그인](#authenticate-with-remote-mcp-servers)을 실패합니다.379* 인증 응답이 예상치 못한 발급자의 이름을 지정하는 [MCP OAuth 로그인](#authenticate-with-remote-mcp-servers)을 실패합니다.

891 명령줄에서 인증897 명령줄에서 인증

892</h3>898</h3>

893 899

894`claude mcp login <name>` 명령은 구성된 서버의 OAuth 흐름을 셸에서 직접 실행하므로 세션 내에서 `/mcp` 패널을 열 필요가 없습니다.900`claude mcp login <name>` 명령은 구성된 서버의 OAuth 흐름을 셸에서 직접 실행하므로 세션 내에서 `/mcp` 패널을 열 필요가 없습니다. claude.ai 커넥터의 경우 [셸에서 커넥터 다시 인증](/docs/ko/remote-control#authorize-a-connector-again-from-your-shell)을 따르세요.

895 901

896```bash theme={null}902```bash theme={null}

897claude mcp login sentry903claude mcp login sentry

1581 도구 검색은 Microsoft Foundry [Azure에서 호스팅되는 배포](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)에서 지원되지 않으며, 이는 서버 측에서 거부합니다. Claude Code는 거부를 감지하고 해당 배포에 대해 대신 MCP 도구를 미리 로드합니다. [`ENABLE_TOOL_SEARCH`](#configure-tool-search)는 거부가 배포 자체에서 발생하므로 이를 재정의할 수 없습니다.1587 도구 검색은 Microsoft Foundry [Azure에서 호스팅되는 배포](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)에서 지원되지 않으며, 이는 서버 측에서 거부합니다. Claude Code는 거부를 감지하고 해당 배포에 대해 대신 MCP 도구를 미리 로드합니다. [`ENABLE_TOOL_SEARCH`](#configure-tool-search)는 거부가 배포 자체에서 발생하므로 이를 재정의할 수 없습니다.

1582</Note>1588</Note>

1583 1589

1584<h3 id="for-mcp-server-authors">1590<span id="for-mcp-server-authors" />

1585 MCP 서버 작성자를 위한 정보1591

1592<h3 id="tool-search-for-mcp-server-authors">

1593 MCP 서버 작성자를 위한 도구 검색

1586</h3>1594</h3>

1587 1595

1588MCP 서버를 구축하는 경우, 도구 검색이 활성화되면 서버 지침 필드가 더욱 유용해집니다. 서버 지침은 Claude가 도구를 검색할 시기를 이해하는 데 도움이 되며, [기술](/docs/ko/skills)이 작동하는 방식과 유사합니다.1596MCP 서버를 구축하는 경우, 도구 검색이 활성화되면 서버 지침 필드가 더욱 유용해집니다. 서버 지침은 Claude가 도구를 검색할 시기를 이해하는 데 도움이 되며, [기술](/docs/ko/skills)이 작동하는 방식과 유사합니다.

monitoring-usage.md +23 −9

Details

599 599

600`/login`을 통해 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)에 로그인한 세션에서 CLI는 인증된 ID로 내보내기를 스탬프합니다: `user.id`는 IdP 주체, `user.email`은 로그인한 이메일, `user.groups`는 IdP 그룹 멤버십을 쉼표로 구분된 문자열로 전달합니다. 각 내보내기는 또한 `identity.source: gateway-oidc`를 전달합니다. 게이트웨이 ID가 마지막에 적용되므로 `OTEL_RESOURCE_ATTRIBUTES`를 통해 설정된 `user.*` 및 `identity.*` 키는 해당 세션에서 무시됩니다.600`/login`을 통해 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)에 로그인한 세션에서 CLI는 인증된 ID로 내보내기를 스탬프합니다: `user.id`는 IdP 주체, `user.email`은 로그인한 이메일, `user.groups`는 IdP 그룹 멤버십을 쉼표로 구분된 문자열로 전달합니다. 각 내보내기는 또한 `identity.source: gateway-oidc`를 전달합니다. 게이트웨이 ID가 마지막에 적용되므로 `OTEL_RESOURCE_ATTRIBUTES`를 통해 설정된 `user.*` 및 `identity.*` 키는 해당 세션에서 무시됩니다.

601 601

602<Note>

603 개발자가 로그인하기 전에 Claude Code가 로그에 기록하는 이벤트에는 게이트웨이 ID가 포함되지 않습니다. 예를 들어 [게이트웨이가 로그인을 종료한](/docs/ko/errors#cloud-gateway-session-expired) 후처럼 Claude Code가 게이트웨이에서 로그아웃된 상태로 세션을 열면, 로그인 전에 기록된 시작 이벤트에는 익명 `user.id`가 포함되고 `identity.source`는 포함되지 않습니다. 여기에는 [`managed_settings_resolved`](#managed-settings-resolved-event), [`plugin_loaded`](#plugin-loaded-event), [`mcp_server_connection`](#mcp-server-connection-event)이 포함됩니다.

604</Note>

605

602게이트웨이를 통해 연결되는 Claude Desktop 및 Cowork 세션의 ID 속성에 대해서는 [게이트웨이 `telemetry` 참조](/docs/ko/claude-apps-gateway-config#telemetry)를 참조하세요.606게이트웨이를 통해 연결되는 Claude Desktop 및 Cowork 세션의 ID 속성에 대해서는 [게이트웨이 `telemetry` 참조](/docs/ko/claude-apps-gateway-config#telemetry)를 참조하세요.

603 607

604이벤트는 추가로 다음 속성을 포함합니다. 이들은 무제한 카디널리티를 야기할 수 있으므로 메트릭에 절대 첨부되지 않습니다:608이벤트는 추가로 다음 속성을 포함합니다. 이들은 무제한 카디널리티를 야기할 수 있으므로 메트릭에 절대 첨부되지 않습니다:

917* `error`: 오류 메시지921* `error`: 오류 메시지

918* `status_code`: HTTP 상태 코드 (숫자). 연결 실패와 같은 비 HTTP 오류의 경우 없음.922* `status_code`: HTTP 상태 코드 (숫자). 연결 실패와 같은 비 HTTP 오류의 경우 없음.

919* `duration_ms`: 요청 지속 시간 (밀리초)923* `duration_ms`: 요청 지속 시간 (밀리초)

920* `attempt`: 초기 요청을 포함한 총 시도 횟수 (`1`은 재시도가 발생하지 않았음을 의미)924* `attempt`: 최초 요청을 포함한 시도 횟수입니다. 횟수가 다시 시작되는 시점은 [재시도 소진 감지](#detect-retry-exhaustion)에서 설명합니다

921* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명함.925* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명함.

922* `client_request_id`: `x-client-request-id` 요청 헤더로 전송된 클라이언트 생성 UUID. 시간 초과 또는 연결 오류와 같은 실패가 서버 `request_id`를 생성하지 않았을 때도 사용 가능; 존재할 때는 [이벤트 상관 속성](#event-correlation-attributes) 테이블을 참조하세요. Claude Code v2.1.214 이상 필요926* `client_request_id`: `x-client-request-id` 요청 헤더로 전송된 클라이언트 생성 UUID. 시간 초과 또는 연결 오류와 같은 실패가 서버 `request_id`를 생성하지 않았을 때도 사용 가능; 존재할 때는 [이벤트 상관 속성](#event-correlation-attributes) 테이블을 참조하세요. Claude Code v2.1.214 이상 필요

923* `speed`: `"fast"` 또는 `"normal"`, 빠른 모드가 활성화되었는지 여부를 나타냄927* `speed`: `"fast"` 또는 `"normal"`, 빠른 모드가 활성화되었는지 여부를 나타냄

1190 1194

1191Claude Code가 프롬프트의 `@`-멘션을 해결할 때 기록됩니다. 모든 멘션이 이벤트를 내보내는 것은 아닙니다: 권한 거부, 과도한 파일, PDF 참조 첨부, 디렉토리 나열 실패와 같은 조기 종료 경로는 로깅 없이 반환됩니다.1195Claude Code가 프롬프트의 `@`-멘션을 해결할 때 기록됩니다. 모든 멘션이 이벤트를 내보내는 것은 아닙니다: 권한 거부, 과도한 파일, PDF 참조 첨부, 디렉토리 나열 실패와 같은 조기 종료 경로는 로깅 없이 반환됩니다.

1192 1196

1197Claude Code는 프롬프트를 읽을 때마다 `mention_type`이 `"agent"`인 이벤트와 `"mcp_resource"`인 이벤트를 각각 최대 100개까지 로그에 기록합니다. 어느 한도를 초과한 멘션도 여전히 확인되지만 이벤트를 내보내지 않습니다.

1198

1193**이벤트 이름**: `claude_code.at_mention`1199**이벤트 이름**: `claude_code.at_mention`

1194 1200

1195**속성**:1201**속성**:

1528 1534

1529Claude Code는 실패한 API 요청을 내부적으로 재시도하고 포기한 후에만 단일 `claude_code.api_error` 이벤트를 내보내므로 이벤트 자체가 해당 요청의 최종 신호입니다. 중간 재시도 시도는 별도의 이벤트로 기록되지 않습니다.1535Claude Code는 실패한 API 요청을 내부적으로 재시도하고 포기한 후에만 단일 `claude_code.api_error` 이벤트를 내보내므로 이벤트 자체가 해당 요청의 최종 신호입니다. 중간 재시도 시도는 별도의 이벤트로 기록되지 않습니다.

1530 1536

1531이벤트의 `attempt` 속성은 총 시도 횟수를 기록합니다. `CLAUDE_CODE_MAX_RETRIES`는 기본값이 10이고 최대 15입니다. v2.1.199 이상에서는 `CLAUDE_CODE_RETRY_WATCHDOG`을 설정하여 기본값을 높이고 상한을 제거할 수 있습니다.1537이벤트의 `attempt` 속성은 시도 횟수를 기록합니다. `CLAUDE_CODE_MAX_RETRIES`는 기본값이 10이고 최대 15입니다. v2.1.199 이상에서는 `CLAUDE_CODE_RETRY_WATCHDOG`을 설정하여 기본값을 높이고 상한을 제거할 수 있습니다.

1532 1538

1533요청이 일시적 오류에 대한 모든 재시도를 소진하면 `attempt`는 해당 유효 제한보다 하나 많습니다: 기본값으로는 11이고 감시 기능이 설정되지 않은 경우 16을 초과하지 않습니다. 더 낮은 값은 `400` 응답과 같은 재시도 불가능한 오류를 나타내거나 자체 더 작은 재시도 예산이 있는 원인을 나타냅니다. 예를 들어 Claude Code는 AWS 또는 Google Cloud 자격 증명 로드 실패를 최대 두 번 재시도합니다.1539요청이 일시적 오류에 대한 모든 재시도를 소진하면 `attempt`는 최대 해당 유효 제한보다 하나 많은 값이 됩니다: 기본값으로는 11입니다.

1540

1541더 낮은 값도 재시도가 소진되었음을 의미할 수 있습니다: Claude Code가 스트리밍 실패 후 요청을 다시 보낼 때마다 `attempt`는 `1`부터 다시 시작합니다.

1534 1542

1535복구된 세션과 정체된 세션을 구분하려면 `session.id`로 이벤트를 그룹화하고 오류 후 나중에 `api_request` 이벤트가 존재하는지 확인합니다.1543복구된 세션과 정체된 세션을 구분하려면 `session.id`로 이벤트를 그룹화하고 오류 후 나중에 `api_request` 이벤트가 존재하는지 확인합니다.

1536 1544

1699 1707

1700메트릭, 로그 및 추적 백엔드 선택은 수행할 수 있는 분석 유형을 결정합니다:1708메트릭, 로그 및 추적 백엔드 선택은 수행할 수 있는 분석 유형을 결정합니다:

1701 1709

1702<h3 id="for-metrics">1710<span id="for-metrics" />

1703 메트릭의 경우1711

1712<h3 id="backends-for-metrics">

1713 메트릭용 백엔드

1704</h3>1714</h3>

1705 1715

1706* **시계열 데이터베이스**: 비율 계산, 집계된 메트릭1716* **시계열 데이터베이스**: 비율 계산, 집계된 메트릭

1707* **컬럼형 저장소**: 복잡한 쿼리, 고유 사용자 분석1717* **컬럼형 저장소**: 복잡한 쿼리, 고유 사용자 분석

1708* **완전한 기능의 관찰성 플랫폼**: 고급 쿼리, 시각화, 경고1718* **완전한 기능의 관찰성 플랫폼**: 고급 쿼리, 시각화, 경고

1709 1719

1710<h3 id="for-events/logs">1720<span id="for-events/logs" />

1711 이벤트/로그의 경우1721

1722<h3 id="backends-for-events-and-logs">

1723 이벤트 및 로그용 백엔드

1712</h3>1724</h3>

1713 1725

1714* **로그 집계 시스템**: 전체 텍스트 검색, 로그 분석1726* **로그 집계 시스템**: 전체 텍스트 검색, 로그 분석

1715* **컬럼형 저장소**: 구조화된 이벤트 분석1727* **컬럼형 저장소**: 구조화된 이벤트 분석

1716* **완전한 기능의 관찰성 플랫폼**: 메트릭과 이벤트 간의 상관 관계1728* **완전한 기능의 관찰성 플랫폼**: 메트릭과 이벤트 간의 상관 관계

1717 1729

1718<h3 id="for-traces">1730<span id="for-traces" />

1719 추적의 경우1731

1732<h3 id="backends-for-traces">

1733 추적용 백엔드

1720</h3>1734</h3>

1721 1735

1722분산 추적 저장소 및 스팬 상관 관계를 지원하는 백엔드를 선택합니다:1736분산 추적 저장소 및 스팬 상관 관계를 지원하는 백엔드를 선택합니다:

plugins/cli-reference.md +1 −0

Details

91| `-y, --yes` | `Run this command now?` 프롬프트 없이 표시된 설치 명령을 수락합니다. Bash 도구나 훅에서와 같이 Claude Code 세션 내부에서 명령이 실행될 때는 무시됩니다. Claude Code v2.1.229 이상 필요 |91| `-y, --yes` | `Run this command now?` 프롬프트 없이 표시된 설치 명령을 수락합니다. Bash 도구나 훅에서와 같이 Claude Code 세션 내부에서 명령이 실행될 때는 무시됩니다. Claude Code v2.1.229 이상 필요 |

92| `--accept-command <sha256>` | 이전 [`--json` 실행](#plugin-json-result)이 `shownCommand`에서 보고한 `sha256`인 표시된 설치 명령을 수락합니다. `-y` 대신 사용합니다. `-y`와 결합할 수 없습니다. [표시된 설치 명령 수락](#accept-a-displayed-install-command)을 참조하세요. Claude Code v2.1.271 이상 필요 |92| `--accept-command <sha256>` | 이전 [`--json` 실행](#plugin-json-result)이 `shownCommand`에서 보고한 `sha256`인 표시된 설치 명령을 수락합니다. `-y` 대신 사용합니다. `-y`와 결합할 수 없습니다. [표시된 설치 명령 수락](#accept-a-displayed-install-command)을 참조하세요. Claude Code v2.1.271 이상 필요 |

93| `--json` | 스크립트에서 사용하기 위해 사람이 읽을 수 있는 메시지 대신 stdout의 마지막 줄에 하나의 JSON 객체로 결과를 출력합니다. [JSON 결과 형식](#plugin-json-result)을 참조하세요. Claude Code v2.1.268 이상 필요 |93| `--json` | 스크립트에서 사용하기 위해 사람이 읽을 수 있는 메시지 대신 stdout의 마지막 줄에 하나의 JSON 객체로 결과를 출력합니다. [JSON 결과 형식](#plugin-json-result)을 참조하세요. Claude Code v2.1.268 이상 필요 |

94| `--marketplace <source>` | 이름만으로 지정한 `<plugin>`을 `<source>`의 마켓플레이스에서 설치합니다. 해당 마켓플레이스를 아직 추가하지 않았다면 먼저 추가합니다. [한 번의 명령으로 마켓플레이스 추가 및 설치](/docs/ko/plugins/install#add-a-marketplace-and-install-in-one-command)를 참조하세요. Claude Code v2.1.292 이상 필요 |

94 95

95셸에서 `claude plugin install --help`를 실행하여 버전이 지원하는 모든 옵션을 확인하세요.96셸에서 `claude plugin install --help`를 실행하여 버전이 지원하는 모든 옵션을 확인하세요.

96 97

plugins/create.md +13 −7

Details

185 185

186세 가지 방법으로 단일 세션 동안 플러그인을 로드할 수 있습니다: `--plugin-dir`으로 디스크의 디렉토리 또는 `.zip` 아카이브에서, `--plugin-url`로 URL에서, 또는 플래그를 추가할 수 없을 때 환경 변수에서. 각 플러그인은 해당 세션에만 로드되며, 설정에 아무것도 기록되지 않습니다. 세션 중에 플러그인의 파일을 편집하면 `/reload-plugins`를 실행하여 변경 사항을 로드합니다.186세 가지 방법으로 단일 세션 동안 플러그인을 로드할 수 있습니다: `--plugin-dir`으로 디스크의 디렉토리 또는 `.zip` 아카이브에서, `--plugin-url`로 URL에서, 또는 플래그를 추가할 수 없을 때 환경 변수에서. 각 플러그인은 해당 세션에만 로드되며, 설정에 아무것도 기록되지 않습니다. 세션 중에 플러그인의 파일을 편집하면 `/reload-plugins`를 실행하여 변경 사항을 로드합니다.

187 187

188<h4 id="from-a-directory-or-zip">188<span id="from-a-directory-or-zip" />

189 디렉토리 또는 `.zip`에서189

190<h4 id="load-a-plugin-from-a-directory-or-zip">

191 디렉토리 또는 `.zip`에서 플러그인 로드

190</h4>192</h4>

191 193

192셸에서 `claude`를 시작할 때 `--plugin-dir`을 플러그인의 루트 디렉토리 또는 그 `.zip` 아카이브와 함께 전달합니다. 여러 플러그인을 로드하려면 플래그를 반복합니다:194셸에서 `claude`를 시작할 때 `--plugin-dir`을 플러그인의 루트 디렉토리 또는 그 `.zip` 아카이브와 함께 전달합니다. 여러 플러그인을 로드하려면 플래그를 반복합니다:

196```198```

197 199

198<h4 id="load-a-folder-of-plugins">200<h4 id="load-a-folder-of-plugins">

199 플러그인 폴더에서201 플러그인 폴더 로드

200</h4>202</h4>

201 203

202한 곳에서 여러 플러그인을 로드하려면 `--plugin-dir ./plugins`와 같이 플러그인을 보관하는 폴더를 전달합니다. 플러그인 폴더를 로드하려면 Claude Code v2.1.265 이상이 필요합니다.204한 곳에서 여러 플러그인을 로드하려면 `--plugin-dir ./plugins`와 같이 플러그인을 보관하는 폴더를 전달합니다. 플러그인 폴더를 로드하려면 Claude Code v2.1.265 이상이 필요합니다.

212 214

213이러한 각 변경에 대해 세션에 메시지가 나타납니다. 중간 대화 중에 플러그인을 로드하거나 언로드하면 [프롬프트 캐시](/docs/ko/prompt-caching#enabling-or-disabling-a-plugin)가 무효화되면 변경이 대신 보류되고 메시지는 적용하려면 `/reload-plugins`를 실행하도록 알려줍니다.215이러한 각 변경에 대해 세션에 메시지가 나타납니다. 중간 대화 중에 플러그인을 로드하거나 언로드하면 [프롬프트 캐시](/docs/ko/prompt-caching#enabling-or-disabling-a-plugin)가 무효화되면 변경이 대신 보류되고 메시지는 적용하려면 `/reload-plugins`를 실행하도록 알려줍니다.

214 216

215<h4 id="fetch-an-archive-from-a-url-for-one-session">217<span id="fetch-an-archive-from-a-url-for-one-session" />

216 URL에서218

219<h4 id="load-a-plugin-from-a-url">

220 URL에서 플러그인 로드

217</h4>221</h4>

218 222

219셸에서 `claude`를 시작할 때 `--plugin-url`을 `.zip` 아카이브의 주소(예: CI가 게시하는 빌드 아티팩트)와 함께 전달합니다:223셸에서 `claude`를 시작할 때 `--plugin-url`을 `.zip` 아카이브의 주소(예: CI가 게시하는 빌드 아티팩트)와 함께 전달합니다:

228 232

229Claude Code가 아카이브를 가져올 수 없거나 아카이브가 유효하지 않으면 플러그인 없이 시작되고 `/plugin` 관리자의 **Errors** 탭에서 검토할 수 있는 플러그인 로드 오류를 기록합니다.233Claude Code가 아카이브를 가져올 수 없거나 아카이브가 유효하지 않으면 플러그인 없이 시작되고 `/plugin` 관리자의 **Errors** 탭에서 검토할 수 있는 플러그인 로드 오류를 기록합니다.

230 234

231<h4 id="from-an-environment-variable">235<span id="from-an-environment-variable" />

232 환경 변수에서236

237<h4 id="load-plugins-from-an-environment-variable">

238 환경 변수에서 플러그인 로드

233</h4>239</h4>

234 240

235`--plugin-dir` 플래그를 추가할 수 없는 세션에서 플러그인을 로드하려면 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/ko/env-vars#variables) 환경 변수에 절대 경로를 나열하세요. Claude Code는 각 경로를 `--plugin-dir` 경로로 로드합니다. 이 플러그인은 `--plugin-dir`으로 전달하는 모든 플러그인에 추가로 로드됩니다. [프로젝트 및 로컬 설정은 이 변수를 설정할 수 없습니다](/docs/ko/settings-reference#variables-claude-code-ignores-in-env). `CLAUDE_CODE_PLUGIN_DIRS`는 Claude Code v2.1.280 이상이 필요합니다.241`--plugin-dir` 플래그를 추가할 수 없는 세션에서 플러그인을 로드하려면 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/ko/env-vars#variables) 환경 변수에 절대 경로를 나열하세요. Claude Code는 각 경로를 `--plugin-dir` 경로로 로드합니다. 이 플러그인은 `--plugin-dir`으로 전달하는 모든 플러그인에 추가로 로드됩니다. [프로젝트 및 로컬 설정은 이 변수를 설정할 수 없습니다](/docs/ko/settings-reference#variables-claude-code-ignores-in-env). `CLAUDE_CODE_PLUGIN_DIRS`는 Claude Code v2.1.280 이상이 필요합니다.

plugins/host-marketplace.md +8 −2

Details

413 사용자가 headersHelper 명령을 수락하는 방법413 사용자가 headersHelper 명령을 수락하는 방법

414</h3>414</h3>

415 415

416사용자는 해당 플러그인 항목을 설치 또는 업데이트할 때마다 명령을 수락합니다. 그들은 `/plugin`의 플러그인 자체 보기에서 또는 `claude plugin install` 또는 `claude plugin update`로 수행합니다. Claude Code는 명령과 아카이브 URL을 표시하고 사용자가 수락한 후에만 명령을 실행합니다.416사용자는 해당 플러그인 하나를 직접 설치하거나 업데이트할 때마다 플러그인 항목의 명령을 수락합니다. Claude Code는 명령과 아카이브 URL을 표시하고 사용자가 수락한 후에만 명령을 실행합니다.

417

418사용자는 터미널의 Claude Code 세션 내에서, 세션이 실행되지 않은 상태의 셸에서, 또는 VS Code 확장에서 플러그인을 설치하거나 업데이트할 수 있습니다:

419

420* **터미널 세션**: `/plugin`의 플러그인 자체 보기에서 수행합니다.

421* **셸**: `claude plugin install` 또는 `claude plugin update`로 수행합니다.

422* **VS Code 확장**: [**Manage plugins** 대화 상자](/docs/ko/vs-code#manage-plugins)에서 수행하며, 확장 버전 2.1.290 이상이 필요합니다.

417 423

418비대화형 셸에서 [`--yes`](/docs/ko/plugins/cli-reference#plugin-install)를 전달하여 명령을 수락합니다. 이전 `--json` 실행이 표시한 명령만 수락하려면 실행이 보고한 `sha256`과 함께 [`--accept-command`](/docs/ko/plugins/cli-reference#plugin-install)를 전달하세요.424비대화형 셸에서 [`--yes`](/docs/ko/plugins/cli-reference#plugin-install)를 전달하여 명령을 수락합니다. 이전 `--json` 실행이 표시한 명령만 수락하려면 실행이 보고한 `sha256`과 함께 [`--accept-command`](/docs/ko/plugins/cli-reference#plugin-install)를 전달하세요.

419 425

420Claude Code는 표시한 명령만 실행하며 표시한 아카이브 URL의 경우입니다. 그 사이에 항목의 명령 또는 아카이브 URL이 변경되면 Claude Code는 설치 또는 업데이트를 거부합니다. 쿼리 문자열만의 변경은 계산되지 않습니다.426Claude Code는 표시한 명령만 실행하며 표시한 아카이브 URL의 경우입니다. 그 사이에 항목의 명령 또는 아카이브 URL이 변경되면 Claude Code는 설치 또는 업데이트를 거부합니다. 쿼리 문자열만의 변경은 계산되지 않습니다. 단, VS Code 확장에서나 `--accept-command`를 사용하는 경우는 예외입니다.

421 427

422<h3 id="installs-and-updates-that-refuse-the-command-instead-of-asking">428<h3 id="installs-and-updates-that-refuse-the-command-instead-of-asking">

423 명령을 요청하는 대신 거부하는 설치 및 업데이트429 명령을 요청하는 대신 거부하는 설치 및 업데이트

plugins/install.md +22 −4

Details

189 189

190* **범위**: 기본적으로 사용자 범위. `--scope project` 또는 `--scope local`을 전달하여 변경합니다.190* **범위**: 기본적으로 사용자 범위. `--scope project` 또는 `--scope local`을 전달하여 변경합니다.

191* **플러그인이 로드되는 시기**: 설치한 플러그인은 다음 번에 Claude Code를 시작할 때 또는 이미 열려 있는 세션에서 `/reload-plugins`을 실행할 때 로드됩니다.191* **플러그인이 로드되는 시기**: 설치한 플러그인은 다음 번에 Claude Code를 시작할 때 또는 이미 열려 있는 세션에서 `/reload-plugins`을 실행할 때 로드됩니다.

192* **마켓플레이스를 먼저 추가해야 함**: 아직 아무도 대화형 Claude Code 세션을 열지 않은 머신에서는 공식 마켓플레이스가 등록되지 않으므로, 이를 설치하는 스크립트는 설치 전에 `claude plugin marketplace add anthropics/claude-plugins-official`을 실행합니다.192* **새 머신의 마켓플레이스**: 아직 아무도 대화형 Claude Code 세션을 열지 않은 머신에서는 공식 마켓플레이스가 등록되지 않으므로, 이를 설치하는 스크립트는 설치 전에 `claude plugin marketplace add anthropics/claude-plugins-official`을 실행합니다. [셸에서 추가 및 설치](#add-and-install-from-your-shell)를 참조하세요.

193 193

194```bash theme={null}194```bash theme={null}

195claude plugin install formatter@your-org --scope project195claude plugin install formatter@your-org --scope project

232 마켓플레이스 추가 및 한 명령으로 설치232 마켓플레이스 추가 및 한 명령으로 설치

233</h3>233</h3>

234 234

235아직 추가하지 않은 마켓플레이스에서 플러그인을 설치하려면 Claude Code 세션에서 `/plugin install`을 실행하고 `--marketplace`로 마켓플레이스 소스를 이름 지정합니다. Claude Code v2.1.275 이상이 필요합니다.235아직 추가하지 않은 마켓플레이스에서 플러그인을 설치하려면 세션 또는 셸에서 설치 명령에 `--marketplace`로 마켓플레이스 소스를 지정합니다. 소스는 GitHub `owner/repo`, git URL 또는 로컬 경로와 같이 [`/plugin marketplace add`와 동일한 형식](#add-a-marketplace)을 사용합니다. 플러그인 이름을 `@marketplace` 접미사 없이 지정합니다.

236

237<h4 id="add-and-install-in-a-session">

238 세션에서 추가 및 설치

239</h4>

240

241Claude Code 세션에서 플러그인과 소스를 지정하여 `/plugin install`을 실행합니다. Claude Code v2.1.275 이상이 필요합니다. 세션에서는 소스에 공백을 포함할 수 없습니다.

236 242

237```text theme={null}243```text theme={null}

238/plugin install deploy-helper --marketplace your-org/plugins244/plugin install deploy-helper --marketplace your-org/plugins

239```245```

240 246

241소스는 GitHub `owner/repo`, git URL 또는 로컬 경로와 같이 [/plugin marketplace add와 동일한 형식](#add-a-marketplace)을 사용합니다. 단, 공백을 포함할 수 없습니다. 플러그인 이름을 `@marketplace` 접미사 없이 지정합니다.

~~242~~

243아직 해당 마켓플레이스를 추가하지 않았으면 Claude Code는 해결한 소스를 표시하고 추가하기 전에 확인하도록 요청합니다. 마켓플레이스가 추가되면 플러그인의 세부 정보가 열리고 [설치 범위](#install-a-plugin)를 선택합니다. 소스가 이미 추가한 마켓플레이스와 일치하면 Claude Code는 확인을 건너뛰고 해당 마켓플레이스에서 플러그인의 세부 정보를 엽니다.247아직 해당 마켓플레이스를 추가하지 않았으면 Claude Code는 해결한 소스를 표시하고 추가하기 전에 확인하도록 요청합니다. 마켓플레이스가 추가되면 플러그인의 세부 정보가 열리고 [설치 범위](#install-a-plugin)를 선택합니다. 소스가 이미 추가한 마켓플레이스와 일치하면 Claude Code는 확인을 건너뛰고 해당 마켓플레이스에서 플러그인의 세부 정보를 엽니다.

244 248

249<h4 id="add-and-install-from-your-shell">

250 셸에서 추가 및 설치

251</h4>

252

253셸에서 세션을 시작하지 않고 플러그인과 소스를 지정하여 `claude plugin install`을 실행합니다. Claude Code v2.1.292 이상이 필요합니다.

254

255```bash theme={null}

256claude plugin install deploy-helper --marketplace your-org/plugins

257```

258

259셸 명령은 확인 단계 없이 마켓플레이스를 추가합니다. 해당 소스에서 이미 추가한 마켓플레이스는 재사용됩니다. 새 마켓플레이스는 `claude plugin marketplace add`와 동일한 [조직 정책 검사](/docs/ko/plugins/org#restrict-what-users-can-install)를 거쳐 추가되며, `--scope project`를 전달하더라도 사용자 설정에 선언됩니다.

260

261아직 해당 마켓플레이스를 추가하지 않았으면 명령은 `Successfully added marketplace: <name> (declared in user settings)`를 인쇄한 다음 [플러그인을 설치합니다](#install-from-your-shell).

262

245<h3 id="add-a-private-marketplace">263<h3 id="add-a-private-marketplace">

246 비공개 마켓플레이스 추가264 비공개 마켓플레이스 추가

247</h3>265</h3>

plugins/manifest-reference.md +1 −1

Details

185| `official`을 `claude` 또는 `anthropic` 옆에 배치, 예: `official-claude-tools` | 오류 |185| `official`을 `claude` 또는 `anthropic` 옆에 배치, 예: `official-claude-tools` | 오류 |

186| `mcp-for-claude`와 같이 다른 곳에서 `claude`, `anthropic` 또는 `anthropics`를 전체 단어로 포함 | 경고 |186| `mcp-for-claude`와 같이 다른 곳에서 `claude`, `anthropic` 또는 `anthropics`를 전체 단어로 포함 | 경고 |

187 187

188오류는 `Plugin name "<name>" is reserved: it passes as one of Anthropic's own`으로 읽히고 경고는 `Plugin name "<name>" reads as one of Anthropic's own`으로 읽힙니다. `claude plugin init` 및 `claude plugin tag`는 오류를 그리는 이름을 거부합니다. 이 명령들만 이름을 확인합니다. Claude Code는 여전히 이름을 거부하는 플러그인을 설치하고 로드합니다.188오류는 `Plugin name "<name>" is reserved: it passes as one of Anthropic's own`으로 읽히고 경고는 `Plugin name "<name>" reads as one of Anthropic's own`으로 읽힙니다. `claude plugin init` 및 `claude plugin tag`는 오류가 발생하는 이름을 거부합니다. Claude Code는 이 명령들이 거부하는 이름의 플러그인도 여전히 설치하고 로드합니다.

189 189

190<h3 id="displayname">190<h3 id="displayname">

191 `displayName`191 `displayName`

plugins/marketplace-reference.md +1 −1

Details

64 64

65| 필드 | 유형 | 설명 |65| 필드 | 유형 | 설명 |

66| :- | :- | :- |66| :- | :- | :- |

67| `name` | string | 마켓플레이스 식별자: 문자, 숫자, `.`, `_`, `-`로 구성되며, 문자 또는 숫자로 시작하고 `..`가 없습니다. Claude Code는 그 외의 이름을 사용하는 마켓플레이스에서 플러그인을 설치할 수 없으므로 `claude plugin validate`는 다른 이름을 실패로 처리합니다. 사용자는 플러그인을 설치할 때 `my-plugin@my-marketplace`와 같은 [플러그인 id](/docs/ko/plugins/loading#find-where-a-plugin-came-from)에서 `@` 뒤에 이 이름을 입력합니다. [예약된 이름](#reserved-names) 참조 |67| `name` | string | 마켓플레이스 식별자: 문자, 숫자, `.`, `_`, `-`로 구성되며, 문자 또는 숫자로 시작하고 `..`가 없습니다. Claude Code는 [그 외의 이름을 사용하는 마켓플레이스에서 플러그인을 설치할 수 없으므로](/docs/ko/plugins/troubleshooting#cannot-install-plugins-from-a-marketplace-with-this-name) `claude plugin validate`는 다른 이름을 실패로 처리합니다. 사용자는 플러그인을 설치할 때 `my-plugin@my-marketplace`와 같은 [플러그인 id](/docs/ko/plugins/loading#find-where-a-plugin-came-from)에서 `@` 뒤에 이 이름을 입력합니다. [예약된 이름](#reserved-names) 참조 |

plugins/mods/admin.md +1 −1

Details

142 142

143`hooks:` 줄에서 [`tool.call`](/docs/ko/plugins/mods/reference#tools)과 [`prompt.submit`](/docs/ko/plugins/mods/reference#prompts-and-what-claude-reads)은 mod가 모든 도구 호출과 모든 프롬프트를 확인하고 변경할 수 있음을 의미합니다. [`session.append`](/docs/ko/plugins/mods/reference#session)는 mod가 대화의 각 행이 저장되기 전에 이를 다시 작성할 수 있음을 의미합니다. [`ui.render{component=AskUserQuestion}`](/docs/ko/plugins/mods/interface#change-what-claude-code-already-draws)는 Claude가 사용자에게 질문할 때 사용하는 대화 상자를 mod가 다시 그릴 수 있음을 의미합니다. `tool.check`는 권한 프롬프트가 표시되기 전에 mod가 도구 호출을 승인하거나 거부할 수 있음을 의미합니다. [기본 동작 알아보기](#know-what-happens-by-default)에서 mod의 응답보다 우선 적용되는 규칙과 훅을 확인할 수 있습니다.143`hooks:` 줄에서 [`tool.call`](/docs/ko/plugins/mods/reference#tools)과 [`prompt.submit`](/docs/ko/plugins/mods/reference#prompts-and-what-claude-reads)은 mod가 모든 도구 호출과 모든 프롬프트를 확인하고 변경할 수 있음을 의미합니다. [`session.append`](/docs/ko/plugins/mods/reference#session)는 mod가 대화의 각 행이 저장되기 전에 이를 다시 작성할 수 있음을 의미합니다. [`ui.render{component=AskUserQuestion}`](/docs/ko/plugins/mods/interface#change-what-claude-code-already-draws)는 Claude가 사용자에게 질문할 때 사용하는 대화 상자를 mod가 다시 그릴 수 있음을 의미합니다. `tool.check`는 권한 프롬프트가 표시되기 전에 mod가 도구 호출을 승인하거나 거부할 수 있음을 의미합니다. [기본 동작 알아보기](#know-what-happens-by-default)에서 mod의 응답보다 우선 적용되는 규칙과 훅을 확인할 수 있습니다.

144 144

plugins/mods/api.md +106 −7

Details

79 모델 호출하기79 모델 호출하기

80</h2>80</h2>

81 81

82mod는 대화와 별개로 모델에 자체적인 질문을 보내 텍스트를 분류하거나 요약하는 등의 작은 작업을 수행할 수 있습니다. `$.model.complete`는 사용자 세션의 자격 증명으로 모델에 프롬프트 하나를 보내고 그 응답으로 resolve됩니다. 대화 기록은 포함되지 않습니다.82mod는 텍스트를 분류하거나 요약하는 등의 작은 작업을 위해 모델에 자체적인 요청을 보낼 수 있습니다. `$.model.complete`는 프롬프트만 단독으로 보내고, `$.model.fork({ prompt })`는 현재 대화의 끝에 프롬프트를 붙여 보냅니다.

84다음 표는 각 요청에 포함되는 내용을 비교합니다.

86| 요청에 포함되는 항목 | `$.model.complete` | `$.model.fork` |

87| :- | :- | :- |

88| 모델 | 전달한 `model` | 세션의 모델 |

89| 시스템 프롬프트 | 짧은 [attribution 블록](/docs/ko/llm-gateway-protocol#system-prompt-attribution-block), 그리고 `system`을 전달한 경우 그 내용 | 세션의 시스템 프롬프트 |

90| 메시지 | 전달한 `prompt`로 된 사용자 메시지 하나 | 지금까지의 대화, 그리고 사용자 메시지로 전달한 `prompt` |

91| CLAUDE.md 및 기타 프로젝트 컨텍스트 | 포함되지 않음 | 대화의 마지막 요청과 동일하게 포함됨 |

92| 도구 | 없음 | Claude의 도구(모델이 호출할 수는 없음) |

94fork는 대화의 마지막 요청을 반복하므로, 대화가 아직 캐시되어 있는 동안에는 Claude API가 대부분을 [프롬프트 캐시](/docs/ko/prompt-caching)에서 처리합니다.

96두 호출 모두 세션의 자격 증명을 사용하므로 사용자의 플랜, API 키 또는 클라우드 제공업체로 청구됩니다. [사용 중인 빌드의 타입](/docs/ko/plugins/mods/create#get-the-types-for-your-build)에는 모든 `$.model` 메서드가 문서화되어 있습니다.

98<h3 id="send-one-prompt">

99 프롬프트 하나 보내기

100</h3>

101

102`$.model.complete`에 `model`과 `prompt`를 전달합니다. `prompt`는 사용자 메시지가 됩니다. 역할이나 출력 형식과 같은 지침을 모델에 제공하려면 `system`도 함께 전달합니다. 이 값은 시스템 프롬프트가 됩니다.

83 103

84다음 훅은 [명령으로 등록된](#add-a-command) `/triage` 명령에 응답하며, 작은 모델에 명령 뒤에 입력된 텍스트의 레이블을 지정하도록 요청합니다.104다음 훅은 [명령으로 등록된](#add-a-command) `/triage` 명령에 응답하며, 작은 모델에 명령 뒤에 입력된 텍스트의 레이블을 지정하도록 요청합니다.

85 105

100})120})

101```121```

102 122

103`/triage the export button does nothing`를 실행하면 mod가 해당 텍스트를 모델에 보내고 `Label: bug`와 같은 응답을 출력합니다. Claude의 대화는 요청에 포함되지 않습니다. 모델이 응답하지 않으면 레이블은 `unknown`이 됩니다.123`/triage the export button does nothing`를 실행하면 mod가 해당 텍스트를 모델에 보내고 `Label: bug`와 같은 응답을 출력합니다. 모델이 응답하지 않으면 레이블은 `unknown`이 됩니다.

124

125Claude API 오류가 발생해도 호출이 reject되지는 않으므로 `r.isAnswered`를 확인하고, 값이 `false`이면 `r.reason`을 읽어야 합니다. 조직에서 차단한 모델처럼 Claude Code가 보내지 않는 요청의 경우에는 호출이 reject됩니다.

126

127[사용 중인 빌드의 타입](/docs/ko/plugins/mods/create#get-the-types-for-your-build)에는 `effort`와 같은 다른 옵션이 나열되어 있으며, [제한](/docs/ko/plugins/mods/reference#limits)에서 `maxTokens` 기본값을 확인할 수 있습니다.

128

129<h3 id="use-prompt-caching">

130 프롬프트 캐싱 사용하기

131</h3>

132

133`$.model.complete`는 Claude API의 [프롬프트 캐싱](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)을 지원합니다. API는 요청의 시작 부분, 즉 프리픽스를 사용자가 설정한 [캐시 브레이크포인트](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)까지 캐시합니다. 모든 호출이 지침이나 참고 자료처럼 동일한 길고 정적인 콘텐츠로 시작한다면, 해당 콘텐츠의 끝에 브레이크포인트를 설정합니다. 그러면 이후 호출은 해당 콘텐츠에 대해 전체 입력 가격을 지불하는 대신 캐시에서 읽어 옵니다.

134

135브레이크포인트를 설정하려면 `prompt`를 문자열 대신 `{ text }` 블록의 배열로 전달하고, 정적 콘텐츠의 마지막 블록에 `cache: true`를 추가합니다. Claude Code는 해당 블록을 API의 `cache_control` 필드와 함께 보냅니다. `system`도 동일한 배열 형식을 사용할 수 있습니다. 둘 중 어느 것을 사용할지 결정하려면 [`prompt`와 `system` 중에서 선택하기](#choose-between-prompt-and-system)를 참조하세요.

136

137<Note>

138 블록 배열을 사용하려면 Claude Code v2.1.292 이상이 필요합니다. 이전 버전에서는 `prompt`의 배열을 `takes { model, prompt } (host check)`로 끝나는 오류와 함께 거부하며, `system`의 배열은 요청에서 제외합니다.

139</Note>

140

141다음은 [`/triage` 훅](#send-one-prompt)의 다른 버전으로, 레이블을 지정할 텍스트 앞에 긴 레이블링 규칙을 보내고 규칙 뒤에 브레이크포인트를 둡니다. `RULES`는 사용자가 직접 작성한 문자열입니다.

142

143```javascript theme={null}

144on('command.run', { command: 'triage' }, async ($, e) => {

145 const r = await $.model.complete({

146 model: 'haiku',

147 prompt: [

148 // Identical on every call, so it forms the cached prefix

149 { text: RULES, cache: true },

150 // Changes on every call, so it goes after the breakpoint

151 { text: e.args },

152 ],

153 })

154 return { text: 'Label: ' + (r.isAnswered ? r.text.trim() : 'unknown') }

155})

156```

157

158TTL과 브레이크포인트 수에는 다음과 같은 제한이 있습니다.

159

160* **TTL**: 캐시 항목은 마지막으로 사용된 후 5분 동안 유지됩니다. TTL은 호출이 아니라 사용자의 Claude Code 설정에 따라 결정됩니다. 1시간으로 설정하려면 [`subagentPromptCacheTtl`](/docs/ko/prompt-caching#choose-the-ttl-yourself)을 `1h`로 설정합니다.

161* **요청당 브레이크포인트**: API는 [최대 4개](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#when-to-use-multiple-breakpoints)까지 허용하며, 하나를 더 추가하면 `r.reason`에 `api-error`가 반환됩니다

162

163<h4 id="choose-between-prompt-and-system">

164 `prompt`와 `system` 중에서 선택하기

165</h4>

166

167요청이 Claude API로 직접 전송된다는 것을 알고 있는 경우가 아니라면, 호출 간에 공유되는 정적 콘텐츠를 `prompt`의 시작 부분에 배치합니다.

168

169* **API 키 또는 Claude 구독을 사용해 Claude API로 직접 전송하는 경우**: 어느 필드든 사용할 수 있습니다

170* **[Amazon Bedrock](/docs/ko/amazon-bedrock), [Claude Platform on AWS](/docs/ko/claude-platform-on-aws), [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai), [Microsoft Foundry](/docs/ko/microsoft-foundry) 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 거치는 경우**: `prompt`를 사용합니다. Claude Code는 시스템 프롬프트를 [attribution 블록](/docs/ko/llm-gateway-protocol#system-prompt-attribution-block)으로 시작하며, 이 블록의 fingerprint는 사용자 메시지의 시작 부분에서 생성됩니다. `api.anthropic.com` 엔드포인트는 캐싱 전에 이 블록을 제거합니다. 다른 엔드포인트는 이 블록을 프롬프트의 일부로 받으므로, `prompt`의 시작 부분이 달라지면 `system`의 브레이크포인트가 캐시 미스를 일으킬 수 있습니다.

171* **다른 사람이 실행하는 mod인 경우**: 그들의 제공업체를 선택할 수 없으므로 `prompt`를 사용합니다

172

173프리픽스에서 `system`은 `prompt`보다 앞에 오므로, `prompt`의 브레이크포인트는 `system`까지 포함하며, `system`이 다른 호출은 캐시 미스가 발생합니다.

104 174

105Claude API 오류가 발생해도 호출이 reject되지는 않으므로 `r.isAnswered`를 확인하고, 값이 `false`이면 `r.reason`을 읽어야 합니다. 조직에서 차단한 모델처럼 Claude Code가 보내지 않는 요청의 경우에는 호출이 reject됩니다. [사용 중인 빌드의 타입](/docs/ko/plugins/mods/create#get-the-types-for-your-build)에는 `effort`와 같은 다른 옵션이 나열되어 있으며, [제한](/docs/ko/plugins/mods/reference#limits)에서 `maxTokens` 기본값을 확인할 수 있습니다.175<h4 id="check-for-cache-hits">

176 캐시 적중 확인하기

177</h4>

106 178

107`$.model.fork({ prompt })`는 대신 현재 대화를 바탕으로 동일한 모델과 시스템 프롬프트를 사용해 질문 하나를 보내므로, Claude API가 대부분을 프롬프트 캐시에서 처리합니다.179`$.model.complete`의 결과에는 API의 [캐시 필드](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance)가 담긴 `usage` 객체가 있습니다. `usage.cache_creation_input_tokens`는 호출이 캐시에 기록한 토큰 수를, `usage.cache_read_input_tokens`는 캐시에서 읽은 토큰 수를 나타냅니다. 첫 번째 호출에서는 기록이, TTL 내의 이후 호출에서는 읽기가 발생해야 합니다.

108 180

109이러한 호출에는 사용자의 플랜 또는 API 키가 사용됩니다.181모든 호출이 기록만 하고 읽기가 전혀 없다면, 호출 간에 프리픽스가 다르거나 호출 간격이 TTL보다 깁니다. 프리픽스가 다른 경우에 대해서는 [`prompt`와 `system` 중에서 선택하기](#choose-between-prompt-and-system)를 참조하세요.

182

183모델이 응답한 호출에서 두 필드가 모두 0으로 유지된다면 아무것도 캐시되지 않은 것입니다. 다음 각 원인을 확인하세요.

184

185* **프리픽스가 너무 짧음**: API는 모델의 [최소 길이](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations)보다 짧은 프리픽스를 캐시하지 않으며, 오류도 반환하지 않습니다

186* **프롬프트 캐싱이 비활성화됨**: 모델에 [`DISABLE_PROMPT_CACHING` 변수](/docs/ko/prompt-caching#disable-prompt-caching)가 적용되면 Claude Code는 브레이크포인트를 제거하고 텍스트를 캐시 없이 보냅니다

187* **게이트웨이가 `cache_control`을 제거함**: 게이트웨이는 [필드를 제거하고도 성공을 반환](/docs/ko/prompt-caching#where-the-cache-lives)할 수 있습니다

188* **다른 mod가 텍스트의 시작 부분을 다시 작성함**: 이 경우 Claude Code는 [브레이크포인트 없이 텍스트를 보냅니다](#what-a-model-complete-hook-receives)

189

190<h3 id="what-a-model-complete-hook-receives">

191 `model.complete` 훅이 받는 내용

192</h3>

193

194다른 mod의 요청을 검사하거나 변경하기 위해 [`model.complete`](/docs/ko/plugins/mods/reference#mods-api-calls) 이벤트에 훅을 연결하는 경우, 다음 필드에서 텍스트를 읽습니다.

195

196* **`e.prompt`**: 항상 문자열입니다. 호출자가 배열을 전달한 경우 블록의 텍스트를 순서대로 연결한 값입니다.

197* **`e.system`**: 같은 방식으로 만들어진 문자열이며, 호출자가 `system`을 전달하지 않은 경우에는 없습니다

198* **`e.promptBlocks` 및 `e.systemBlocks`**: 호출자의 배열이며, 각각 호출자가 해당 필드에 배열을 전달한 경우에만 존재합니다

199

200Claude Code는 훅이 `next`에 전달한 문자열을 보내고, 함께 전달한 배열을 사용해 [캐시 브레이크포인트](#use-prompt-caching)를 배치합니다. 문자열의 시작 부분과 여전히 일치하는 앞쪽 블록은 브레이크포인트와 함께 유지하고, 문자열의 나머지 부분은 브레이크포인트 없이 보냅니다. 예를 들어 `next({ ...e, prompt: e.prompt + NOTE })`는 호출자의 브레이크포인트를 유지하지만, `prompt`의 시작 부분을 변경하는 훅은 브레이크포인트를 제거합니다.

110 201

111<h2 id="run-work-in-the-background">202<h2 id="run-work-in-the-background">

112 백그라운드에서 작업 실행하기203 백그라운드에서 작업 실행하기

140| 호출 | 사용자에게 표시되는 내용 |231| 호출 | 사용자에게 표시되는 내용 |

141| :- | :- |232| :- | :- |

145 236

146<h3 id="start-a-turn-from-a-background-job">237<h3 id="start-a-turn-from-a-background-job">

159 세션 간 메시지 보내기 및 받기250 세션 간 메시지 보내기 및 받기

160</h2>251</h2>

161 252

162mod는 사용자의 다른 세션이나 이 세션의 서브에이전트 중 하나에 일반 텍스트 메시지를 보낼 수 있으며, 도착하고 나가는 메시지를 관찰할 수 있습니다. `$.session.send({ to, text })`는 메시지 하나를 보내며, SendMessage 도구와 동일한 방식으로 전달합니다. `to`는 세션의 경우 `{ sessionId }`, `$.agent.list()`에서 가져온 서브에이전트의 경우 `{ agentId }`, 또는 수신된 메시지의 발신 문자열 주소입니다. 이 호출은 메시지가 대기열에 추가되면 `{ isDelivered: true }`로 resolve됩니다. 아무것도 전달되지 않은 경우 `{ isDelivered: false, reason }`으로 resolve되며, `reason`에 그 이유가 담깁니다.253mod는 사용자의 다른 세션, 이 세션의 서브에이전트 중 하나, 또는 [에이전트 팀](/docs/ko/agent-teams)의 팀원에게 일반 텍스트 메시지를 보낼 수 있습니다. 또한 도착하고 나가는 메시지를 관찰할 수 있습니다.

254

255메시지를 보내려면 `$.session.send({ to, text })`를 호출합니다. 이 호출은 SendMessage 도구와 동일한 방식으로 전달합니다. `to`는 메시지를 받는 대상에 따라 설정합니다.

256

257* **사용자의 다른 세션**: `{ sessionId }`

258* **서브에이전트 또는 팀원**: `$.agent.list()`에서 가져온 id를 사용한 `{ agentId }`

259* **수신된 메시지의 발신자**: 해당 메시지의 발신 문자열 주소

260

261이 호출은 메시지가 대기열에 추가되면 `{ isDelivered: true }`로 resolve됩니다. 아무것도 전달되지 않은 경우 `{ isDelivered: false, reason }`으로 resolve되며, `reason`에 그 이유가 담깁니다.

163 262

164다음 훅은 [명령으로 등록된](#add-a-command) `/ping` 명령에 응답하여, 명령 뒤에 입력한 id의 세션에 상태를 요청합니다.263다음 훅은 [명령으로 등록된](#add-a-command) `/ping` 명령에 응답하여, 명령 뒤에 입력한 id의 세션에 상태를 요청합니다.

165 264

plugins/mods/create.md +1 −1

Details

281 사용 중인 버전의 타입 정의 가져오기281 사용 중인 버전의 타입 정의 가져오기

282</h3>282</h3>

283 283

284Claude Code는 `--plugin-dir`에 전달한 디렉터리의 mod나 [Claude가 작성한](#ask-claude-for-a-mod) mod를 로드하거나 다시 로드할 때마다 `.d.ts`로 끝나는 TypeScript 선언 파일을 mod 디렉터리 안의 `.claude-plugin/types/`에 작성합니다. 이 파일은 실행 중인 Claude Code 버전의 정확한 이벤트, mods API 메서드, 요소를 기술하므로 편집기에서 훅을 자동 완성하고 타입 검사할 수 있습니다. 선언을 온라인에서 살펴보려면 Claude Code 저장소의 [`mods/types/claude-code.d.ts`](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts)를 읽어 보세요. 이 파일의 첫 줄에는 파일을 작성한 버전이 명시되어 있습니다. 디렉터리에는 다음 파일이 있습니다.284Claude Code는 대화형 세션에서 `--plugin-dir`로 mod를 로드하거나 [Claude가 작성한](#ask-claude-for-a-mod) mod를 로드할 때 TypeScript 선언 파일을 mod의 `.claude-plugin/types/` 디렉터리에 작성합니다. 이 파일은 실행 중인 Claude Code 버전의 정확한 이벤트, mods API 메서드, 요소를 기술하므로 편집기에서 훅을 자동 완성하고 타입 검사할 수 있습니다. 디렉터리에는 다음 파일이 있습니다.

285 285

286| 경로 | 선언 내용 |286| 경로 | 선언 내용 |

287| :- | :- |287| :- | :- |

plugins/mods/events.md +12 −3

Details

145 145

146Claude가 `.mdx` 파일을 편집하거나 작성하면 트랜스크립트의 흐린 줄에 해당 파일 이름이 표시됩니다. 다른 종류의 파일이나 거부되거나 실패한 호출은 로그에 기록되지 않습니다. 훅이 받은 결과를 그대로 반환하므로 Claude가 보는 호출 내용은 변하지 않습니다.146Claude가 `.mdx` 파일을 편집하거나 작성하면 트랜스크립트의 흐린 줄에 해당 파일 이름이 표시됩니다. 다른 종류의 파일이나 거부되거나 실패한 호출은 로그에 기록되지 않습니다. 훅이 받은 결과를 그대로 반환하므로 Claude가 보는 호출 내용은 변하지 않습니다.

147 147

148호출을 변경하려면 변경된 인수를 `next`에 전달합니다. 호출을 재시도하려면 `next(e)`를 다시 호출합니다. 첫 번째 결과에서 `isError`를 확인한 훅은 도구를 한 번 더 실행하고 그 결과를 반환할 수 있습니다. 호출에 직접 응답하려면 `next`를 호출하지 않고 `{ result: 'Skipped by my-mod' }`처럼 `result` 필드가 있는 객체를 반환합니다. 이렇게 하면 권한 프롬프트가 표시되지 않고 도구도 실행되지 않으므로, 반환한 결과가 Claude가 해당 상황에 대해 알게 되는 전부입니다.148훅은 호출을 변경하거나, 재시도하거나, 직접 응답하거나, 그 결과를 보류할 수도 있습니다.

149

150* **호출 변경하기**: 변경된 인수를 `next`에 전달합니다.

151* **호출 재시도하기**: `next(e)`를 다시 호출합니다. 첫 번째 결과에서 `isError`를 확인한 훅은 도구를 한 번 더 실행하고 그 결과를 반환할 수 있습니다.

152* **호출에 직접 응답하기**: `next`를 호출하지 않고 `result` 필드가 있는 객체를 반환합니다. 기본 제공 도구의 경우 `result`에는 [빌드의 타입](/docs/ko/plugins/mods/create#get-the-types-for-your-build)에서 해당 도구 자체의 결과가 갖는 형태를 지정합니다. 권한 프롬프트가 표시되지 않고 도구도 실행되지 않으므로, 반환한 결과가 Claude가 해당 상황에 대해 알게 되는 전부입니다.

153* **Claude에게 결과 보류하기**: `await next(e)` 후에 `{ deny: reason }`을 반환합니다. Claude는 `next`가 반환한 값 대신 지정한 이유를 읽습니다. 도구가 실행된 경우 deny는 Claude가 그 결과를 보지 못하게 할 뿐, 도구가 수행한 작업을 되돌리지는 않습니다. 도구가 실행되어 성공한 경우 이유 앞에 `Bash ran, and a plugin withheld its result:` 같은 안내 문구가 붙습니다.

149 154

150조직의 [관리형 설정](/docs/ko/server-managed-settings)에 있는 훅은 모든 mod의 `tool.call` 훅보다 먼저 실행되며, 이 훅 중 하나의 차단은 최종적입니다.155조직의 [관리형 설정](/docs/ko/server-managed-settings)에 있는 훅은 모든 mod의 `tool.call` 훅보다 먼저 실행되며, 이 훅 중 하나의 차단은 최종적입니다.

151 156

225 230

226| 수행할 작업 | 반환할 값 |231| 수행할 작업 | 반환할 값 |

227| :- | :- |232| :- | :- |

228| 프롬프트를 다시 작성합니다. 트랜스크립트의 메시지에 새 텍스트가 표시됩니다. | `next({ ...e, text: newText })` |233| 프롬프트를 다시 작성합니다. 트랜스크립트와 [프롬프트 기록](/docs/ko/interactive-mode#command-history)에 새 텍스트가 표시됩니다. | `next({ ...e, text: newText })` |

229| 프롬프트 뒤에 Claude만 읽는 텍스트를 추가합니다 | `next({ ...e, context: [...(e.context ?? []), extraText] })` |234| 프롬프트 뒤에 Claude만 읽는 텍스트를 추가합니다 | `next({ ...e, context: [...(e.context ?? []), extraText] })` |

230| 프롬프트가 전송되지 않도록 합니다 | `{ drop: 'the reason' }` |235| 프롬프트가 전송되지 않도록 합니다 | `{ drop: 'the reason' }` |

231 236

245 250

246`open a PR for this change` 같은 프롬프트를 보내면 트랜스크립트의 메시지는 그대로 보이며, Claude는 그 뒤에 `Current branch: feature/auth` 같은 줄도 읽습니다. 풀 리퀘스트를 언급하지 않는 프롬프트는 변경 없이 전달되며 `git`도 실행되지 않습니다.251`open a PR for this change` 같은 프롬프트를 보내면 트랜스크립트의 메시지는 그대로 보이며, Claude는 그 뒤에 `Current branch: feature/auth` 같은 줄도 읽습니다. 풀 리퀘스트를 언급하지 않는 프롬프트는 변경 없이 전달되며 `git`도 실행되지 않습니다.

247 252

248프롬프트를 중단하려면 `next`를 호출하지 않고 `{ drop: 'the reason' }`을 반환합니다. 훅의 `next(e)` 호출이 프롬프트를 통과시킨 후에 훅이 `drop`을 반환하면 턴은 그대로 실행되며, 훅은 `a drop after its next() was answered`가 포함된 메시지와 함께 [실패합니다](#handle-a-hook-that-fails).253프롬프트를 중단하려면 `next`를 호출하지 않고 `{ drop: 'the reason' }`을 반환합니다. 텍스트는 사용자의 프롬프트 입력란으로 되돌아가고, 사용자에게는 `Prompt dropped by a hook:` 뒤에 지정한 이유가 표시되므로 이유는 사용자를 대상으로 작성해야 합니다. 훅의 `next(e)` 호출이 프롬프트를 통과시킨 후에 훅이 `drop`을 반환하면 턴은 그대로 실행되며, 훅은 `a drop after its next() was answered`가 포함된 메시지와 함께 [실패합니다](#handle-a-hook-that-fails).

249 254

250[다른 이벤트](/docs/ko/plugins/mods/reference#prompts-and-what-claude-reads)는 Claude가 읽는 나머지 내용을 다룹니다. 시스템 프롬프트의 각 섹션에는 `prompt.section`, 첫 번째 메시지와 함께 전송되는 컨텍스트에는 `prompt.context`, 스킬의 텍스트에는 `skill.prompt`를 사용합니다. 이러한 훅에서 나온 텍스트가 요청마다 달라지면 [프롬프트 캐시가 무효화됩니다](/docs/ko/prompt-caching).255[다른 이벤트](/docs/ko/plugins/mods/reference#prompts-and-what-claude-reads)는 Claude가 읽는 나머지 내용을 다룹니다. 시스템 프롬프트의 각 섹션에는 `prompt.section`, 첫 번째 메시지와 함께 전송되는 컨텍스트에는 `prompt.context`, 스킬의 텍스트에는 `skill.prompt`를 사용합니다. 이러한 훅에서 나온 텍스트가 요청마다 달라지면 [프롬프트 캐시가 무효화됩니다](/docs/ko/prompt-caching).

251 256

281 286

282`result.usage`에는 Claude API가 요청에 대해 보고하는 토큰 수인 `input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens`와 응답한 `model`이 들어 있습니다. 이 훅은 서브에이전트의 요청에도 실행되므로, 메인 대화만 원하는 경우 `e.agentId`를 확인하세요.287`result.usage`에는 Claude API가 요청에 대해 보고하는 토큰 수인 `input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens`와 응답한 `model`이 들어 있습니다. 이 훅은 서브에이전트의 요청에도 실행되므로, 메인 대화만 원하는 경우 `e.agentId`를 확인하세요.

283 288

289[advisor 도구](/docs/ko/advisor) 호출처럼 요청 중에 API가 직접 실행한 도구 호출을 확인하려면 `result.serverToolUses`를 읽습니다. Claude Code는 이러한 호출을 실행하지 않으므로 `tool.call`이나 `tool.check` 훅이 발생하지 않습니다. 응답에 이러한 호출이 없으면 이 필드는 존재하지 않으며, Claude Code v2.1.290 이상이 필요합니다.

290

284<h3 id="hook-the-settings-hook-events">291<h3 id="hook-the-settings-hook-events">

285 설정 훅 이벤트 처리하기292 설정 훅 이벤트 처리하기

286</h3>293</h3>

369* **`tool.check`**: `{ decision: 'deny', reason: 'the reason' }`을 반환합니다376* **`tool.check`**: `{ decision: 'deny', reason: 'the reason' }`을 반환합니다

370* **`plugin.register`**: [검사가 실패하면 mod 거부하기](/docs/ko/plugins/mods/admin#refuse-mods-when-your-check-fails)에 나와 있듯이 `{ refuse: 'the reason' }`을 반환합니다377* **`plugin.register`**: [검사가 실패하면 mod 거부하기](/docs/ko/plugins/mods/admin#refuse-mods-when-your-check-fails)에 나와 있듯이 `{ refuse: 'the reason' }`을 반환합니다

371 378

379`tool.call`에서는 `next`가 완료된 후에 반환된 `deny`가 [Claude에게 결과를 전달하지 않습니다](#guard-or-change-a-tool-call).

380

372<h2 id="next-steps">381<h2 id="next-steps">

373 다음 단계382 다음 단계

374</h2>383</h2>

plugins/mods/interface.md +11 −3

Details

10 10

11다음 맵은 터미널 세션에서 mod가 그릴 수 있는 위치를 보여 줍니다.11다음 맵은 터미널 세션에서 mod가 그릴 수 있는 위치를 보여 줍니다.

12 12

13<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5fda26b6609c62b68c6f9e528c1590ea" className="dark:hidden" alt="Claude Code 터미널 세션의 맵. mod는 오른쪽에 사이드바로 창을, 트랜스크립트 오른쪽 상단에 토스트를, 트랜스크립트에 로그 줄을, 프롬프트 위에 밴드를, 프롬프트 아래에 상태줄을 추가할 수 있습니다. mod는 메시지, 도구 호출 행, 스피너를 다시 그릴 수 있습니다. 프롬프트는 Claude Code 자체의 것입니다." width="600" height="336" data-path="images/mods-screen-map.svg" />13<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5fda26b6609c62b68c6f9e528c1590ea" className="dark:hidden" alt="전체 화면 렌더링에서의 Claude Code 터미널 세션 맵. mod는 오른쪽에 사이드바로 창을, 트랜스크립트 오른쪽 상단에 토스트를, 트랜스크립트에 로그 줄을, 프롬프트 위에 밴드를, 프롬프트 아래에 상태줄을 추가할 수 있습니다. mod는 메시지, 도구 호출 행, 스피너를 다시 그릴 수 있습니다. 프롬프트는 Claude Code 자체의 것입니다." width="600" height="336" data-path="images/mods-screen-map.svg" />

14 14

15<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map-dark.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5b4161581a1bd2c0450b0c8b57bc1225" className="hidden dark:block" alt="Claude Code 터미널 세션의 맵. mod는 오른쪽에 사이드바로 창을, 트랜스크립트 오른쪽 상단에 토스트를, 트랜스크립트에 로그 줄을, 프롬프트 위에 밴드를, 프롬프트 아래에 상태줄을 추가할 수 있습니다. mod는 메시지, 도구 호출 행, 스피너를 다시 그릴 수 있습니다. 프롬프트는 Claude Code 자체의 것입니다." width="600" height="336" data-path="images/mods-screen-map-dark.svg" />15<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map-dark.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5b4161581a1bd2c0450b0c8b57bc1225" className="hidden dark:block" alt="전체 화면 렌더링에서의 Claude Code 터미널 세션 맵. mod는 오른쪽에 사이드바로 창을, 트랜스크립트 오른쪽 상단에 토스트를, 트랜스크립트에 로그 줄을, 프롬프트 위에 밴드를, 프롬프트 아래에 상태줄을 추가할 수 있습니다. mod는 메시지, 도구 호출 행, 스피너를 다시 그릴 수 있습니다. 프롬프트는 Claude Code 자체의 것입니다." width="600" height="336" data-path="images/mods-screen-map-dark.svg" />

16 16

17더 좁은 터미널에서는 창이 트랜스크립트 옆이 아닌 프롬프트 위에 배치됩니다.17더 좁은 터미널에서는 창이 트랜스크립트 옆이 아닌 프롬프트 위에 배치됩니다.

18 18

330 330

337 337

338Claude가 작업하는 동안 명령으로 pane을 열 수 있게 하려면 [명령을 등록](/docs/ko/plugins/mods/api#add-a-command)할 때 `immediate: true`를 추가합니다. 이 설정이 없으면 턴 중에 입력한 명령은 턴이 끝날 때까지 대기합니다.338Claude가 작업하는 동안 명령으로 pane을 열 수 있게 하려면 [명령을 등록](/docs/ko/plugins/mods/api#add-a-command)할 때 `immediate: true`를 추가합니다. 이 설정이 없으면 턴 중에 입력한 명령은 턴이 끝날 때까지 대기합니다.

339 339

340<h4 id="hold-toasts-behind-a-dialog">

341 대화 상자 뒤에 토스트 보류하기

342</h4>

343

344pane이 사용자가 응답한 뒤 떠나는 대화 상자인 경우 `$.ui.open`에 `holdToasts: true`를 전달하여 사용자가 결정하는 동안 토스트가 나타나지 않도록 합니다. 터미널에서 보류는 해당 pane이 표시되는 동안 유지되며, 그 사이에 발생한 토스트는 보류가 끝날 때까지 대기합니다.

345

346Claude Code는 mod가 [`$.ui.toast`](/docs/ko/plugins/mods/api#show-something-without-starting-a-turn)로 발생시키는 토스트뿐 아니라 다른 mod의 토스트와 Claude Code 자체의 짧은 알림도 보류합니다. 계속 열려 있는 pane에서는 사용자가 이러한 알림을 계속 볼 수 있도록 이 필드를 생략하십시오.

347

340<h4 id="when-a-pane-waits-for-a-wider-terminal">348<h4 id="when-a-pane-waits-for-a-wider-terminal">

341 pane이 더 넓은 터미널을 기다리는 경우349 pane이 더 넓은 터미널을 기다리는 경우

342</h4>350</h4>

plugins/mods/reference.md +5 −3

Details

64| :- | :- | :- |64| :- | :- | :- |

65| [`tool.call`](/docs/ko/plugins/mods/events#guard-or-change-a-tool-call) | 도구가 실행되기 직전 | `next(e)`, `{ deny: reason }` 또는 `{ result }` |65| [`tool.call`](/docs/ko/plugins/mods/events#guard-or-change-a-tool-call) | 도구가 실행되기 직전 | `next(e)`, `{ deny: reason }` 또는 `{ result }` |

66| [`tool.check`](/docs/ko/plugins/mods/events#where-settings-hooks-run-in-the-order) | `tool.call` 및 `PreToolUse` 훅 이후, Claude Code가 도구 호출의 실행 허용 여부를 결정할 때. `next(e)`는 규칙, 권한 모드, 그리고 해당 훅들이 내린 결정으로 확정됩니다. | `{ decision }`(`allow`, `ask` 또는 `deny`) |66| [`tool.check`](/docs/ko/plugins/mods/events#where-settings-hooks-run-in-the-order) | `tool.call` 및 `PreToolUse` 훅 이후, Claude Code가 도구 호출의 실행 허용 여부를 결정할 때. `next(e)`는 규칙, 권한 모드, 그리고 해당 훅들이 내린 결정으로 확정됩니다. | `{ decision }`(`allow`, `ask` 또는 `deny`) |

67| `tool.describe` | 각 도구의 설명이 Claude에 처음 전송될 때 도구마다 한 번 | `{ description }`. 선택적으로 `isDeferred`를 함께 지정할 수 있으며, `true`로 설정하면 도구를 [도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search) 뒤에 두고 `false`로 설정하면 처음부터 로드합니다 |67| `tool.describe` | 각 도구의 설명이 Claude에 처음 전송될 때 도구마다 한 번. MCP 도구의 경우 Claude가 [도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)을 통해 해당 도구를 로드할 때 한 번 더 발생하며, 이때 `e.description`은 로드된 도구에 대해 Claude가 읽는 텍스트로 설정됩니다. | `{ description }`. 선택적으로 `isDeferred`를 함께 지정할 수 있으며, `true`로 설정하면 도구를 도구 검색 뒤에 두고 `false`로 설정하면 처음부터 로드합니다 |

68 68

69<h4 id="agent-and-organization-fields-on-tool-check">69<h4 id="agent-and-organization-fields-on-tool-check">

70 `tool.check`의 에이전트 및 조직 필드70 `tool.check`의 에이전트 및 조직 필드

133| `session.end` | 세션이 종료되거나 `/clear`, `/resume` 또는 `/branch`가 실행될 때. `e.reason`은 `clear`, `resume`, `logout`, `prompt_input_exit` 또는 `other`입니다. `/branch`는 `resume`으로 보고됩니다. | `next(e)` |133| `session.end` | 세션이 종료되거나 `/clear`, `/resume` 또는 `/branch`가 실행될 때. `e.reason`은 `clear`, `resume`, `logout`, `prompt_input_exit` 또는 `other`입니다. `/branch`는 `resume`으로 보고됩니다. | `next(e)` |

134| `session.compact` | 대화가 압축되기 직전 | `{ skip: reason }` |134| `session.compact` | 대화가 압축되기 직전 | `{ skip: reason }` |

135| [`session.receive`](/docs/ko/plugins/mods/api#send-and-receive-messages-between-sessions), [`session.send`](/docs/ko/plugins/mods/api#send-and-receive-messages-between-sessions) | 다른 에이전트나 세션에서 메시지가 도착하거나, 다른 에이전트나 세션으로 메시지가 전송되기 직전. [세션 간 메시지 주고받기](/docs/ko/plugins/mods/api#send-and-receive-messages-between-sessions)를 참조하세요. | `receive`의 경우 `{ consumed: reason }`, `send`의 경우 `{ isDelivered: false, reason }` |135| [`session.receive`](/docs/ko/plugins/mods/api#send-and-receive-messages-between-sessions), [`session.send`](/docs/ko/plugins/mods/api#send-and-receive-messages-between-sessions) | 다른 에이전트나 세션에서 메시지가 도착하거나, 다른 에이전트나 세션으로 메시지가 전송되기 직전. [세션 간 메시지 주고받기](/docs/ko/plugins/mods/api#send-and-receive-messages-between-sessions)를 참조하세요. | `receive`의 경우 `{ consumed: reason }`, `send`의 경우 `{ isDelivered: false, reason }` |

136| `session.append` | 프롬프트, 응답 블록, 도구 결과, 알림 등 대화가 보관하는 각 행이 저장되기 전에 행마다 한 번 | 행의 `content`를 다시 작성하려면 `next({ ...e, message })` |136| `session.append` | 프롬프트, 응답 블록, 도구 결과, 알림 등 대화가 보관하는 각 행이 저장되기 전에 행마다 한 번 | 행의 텍스트 블록이나 그 안에 있는 `tool_result` 블록의 `content`를 다시 작성하려면 `message.content`를 변경한 `next({ ...e, message })` |

139 139

209| [`$.ui`](/docs/ko/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, `focus`, `scroll`, `toast`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit` |209| [`$.ui`](/docs/ko/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, `focus`, `scroll`, `toast`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit` |

212| `$.agent` | `register`, `spawn`, `list` |212| `$.agent` | `register`, `spawn`, `list`. `list()`는 이 세션의 서브에이전트와 팀원을 반환하며, 각 항목의 `status`는 `pending`, `running`, `waiting`, `idle`, `completed`, `failed`, `killed` 중 하나입니다. 이 중 `idle`과 `waiting`에는 Claude Code v2.1.289 이상이 필요합니다. |

214| [`$.prompt`](/docs/ko/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. Claude는 해당 mod를 발신자로 명시하는 문장 뒤에 오는 `submit({ text })`의 텍스트를 읽습니다. `submit({ text, asUser: true })`는 그 문장 없이 텍스트를 사용자 본인의 말로 보냅니다. |214| [`$.prompt`](/docs/ko/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. Claude는 해당 mod를 발신자로 명시하는 문장 뒤에 오는 `submit({ text })`의 텍스트를 읽습니다. `submit({ text, asUser: true })`는 그 문장 없이 텍스트를 사용자 본인의 말로 보냅니다. |

320| 훅의 `drop` 사유 또는 `config.set` `deny` 사유 | 4,096자. 이보다 긴 사유는 끝부분이 잘리며, drop 또는 deny는 그대로 적용됩니다. 잘라내기에는 Claude Code v2.1.292 이상이 필요하며, 이전 버전에서는 대신 훅이 [실패합니다](/docs/ko/plugins/mods/events#handle-a-hook-that-fails). |

320| 하나의 트리에 포함된 텍스트 | 처음 100,000자까지 그려집니다 |321| 하나의 트리에 포함된 텍스트 | 처음 100,000자까지 그려집니다 |

321| `Code`의 `language` 또는 `path`, `Select` 옵션의 `value`, `Client`의 `module` | 10,000자. 이보다 길면 Claude Code가 [해당 위치를 자체 버전으로 그립니다](/docs/ko/plugins/mods/interface#build-a-tree-from-elements). |322| `Code`의 `language` 또는 `path`, `Select` 옵션의 `value`, `Client`의 `module` | 10,000자. 이보다 길면 Claude Code가 [해당 위치를 자체 버전으로 그립니다](/docs/ko/plugins/mods/interface#build-a-tree-from-elements). |

325| `$.ui.invalidate('ui.render')` 다시 그리기 | 초당 10회로 제한되며, 터미널에서는 표시 중인 창, 확장된 밴드, 프롬프트 아래의 힌트 줄에 대해 초당 30회로 제한됩니다. 그보다 빨리 들어오는 호출은 하나로 병합됩니다. |326| `$.ui.invalidate('ui.render')` 다시 그리기 | 초당 10회로 제한되며, 터미널에서는 표시 중인 창, 확장된 밴드, 프롬프트 아래의 힌트 줄에 대해 초당 30회로 제한됩니다. 그보다 빨리 들어오는 호출은 하나로 병합됩니다. |

326| `$.ui.toast` | `{ timeoutMs }`를 전달하지 않으면 4초 동안 표시됩니다 |327| `$.ui.toast` | `{ timeoutMs }`를 전달하지 않으면 4초 동안 표시됩니다 |

327| 사용자가 요청하지 않았는데 열린 창 | 터미널 너비가 144열 이상일 때 배치되며, 사용자가 한 번 연 이후에는 110열 이상일 때 배치됩니다 |328| 사용자가 요청하지 않았는데 열린 창 | 터미널 너비가 144열 이상일 때 배치되며, 사용자가 한 번 연 이후에는 110열 이상일 때 배치됩니다 |

329| 훅 모듈의 한 파일 안에서 서로 중첩된 함수, 블록, 루프 등의 범위 | 2,000 |

330 332

plugins/mods/test.md +7 −2

Details

110* `returned neither { value } nor { deny }`: mods API 호출에 대한 스텁이 값을 그대로 반환했으며, 이 경우 테스트가 실패합니다110* `returned neither { value } nor { deny }`: mods API 호출에 대한 스텁이 값을 그대로 반환했으며, 이 경우 테스트가 실패합니다

111* `no implementation for` 뒤에 이름이 오는 경우: mod가 해당 호출을 했지만 응답하는 스텁이 없습니다111* `no implementation for` 뒤에 이름이 오는 경우: mod가 해당 호출을 했지만 응답하는 스텁이 없습니다

112 112

113키트는 네임스페이스 전체에 대신 응답하는 인메모리 mock도 내보냅니다. `mock.clock(on)`은 [`$.clock`](/docs/ko/plugins/mods/api#run-work-in-the-background)에 응답하고, `mock.store(on, { count: 7 })`는 지정한 항목으로 시작하는 저장소에서 `$.store`에 응답하며, `mock.env(on, { CI: 'true' })`는 지정한 변수에서 `$.env.get`에 응답합니다. `mock.clock`은 테스트가 시간을 앞당길 수 있는 mock 시계를 반환하므로, 타이머 테스트가 기다릴 필요가 없습니다. `mock.store`는 아무것도 반환하지 않으므로, mod가 무엇을 저장했는지 확인하려면 [그리기 테스트](#test-a-drawing)처럼 두 개의 `store` 스텁을 직접 작성해야 합니다.113키트는 시계, 저장소, 환경 변수, 대화에 추가된 행을 위한 미리 만들어진 mock도 내보냅니다.

114

115* **`mock.clock(on)`**: [`$.clock`](/docs/ko/plugins/mods/api#run-work-in-the-background)에 응답하고, 테스트가 시간을 앞당길 수 있는 mock 시계를 반환하므로 타이머 테스트가 기다릴 필요가 없습니다.

116* **`mock.store(on, { count: 7 })`**: 지정한 항목으로 시작하는 저장소에서 `$.store`에 응답합니다. 아무것도 반환하지 않으므로, mod가 무엇을 저장했는지 확인하려면 [그리기 테스트](#test-a-drawing)처럼 두 개의 `store` 스텁을 직접 작성해야 합니다.

117* **`mock.env(on, { CI: 'true' })`**: 지정한 변수에서 `$.env.get`에 응답합니다.

118* **`mock.session(on)`**: mod가 [`$.session.append`](/docs/ko/plugins/mods/reference#session)로 추가한 행을 오래된 것부터 나열하는 `appended()` 메서드가 있는 mock 세션을 반환합니다. Claude Code v2.1.293 이상이 필요합니다.

114 119

115<h3 id="follow-the-test-kit’s-rules">120<h3 id="follow-the-test-kit’s-rules">

116 테스트 키트의 규칙 따르기121 테스트 키트의 규칙 따르기

168 스텁이 반환하는 값 찾아보기173 스텁이 반환하는 값 찾아보기

169</h3>174</h3>

170 175

171테스트에서 mod가 하는 모든 mods API 호출에는 Claude Code 대신 응답하는 스텁이 필요합니다. 단, 키트가 직접 응답하는 몇 가지, 즉 [`$.ui.invalidate`](/docs/ko/plugins/mods/interface#redraw-when-something-changes)와 [`$.state`](/docs/ko/plugins/mods/interface#keep-state) 호출은 예외입니다. `$.clock` 호출에는 `mock.clock(on)`을 사용해야 하며, 그렇지 않으면 mod의 `$.clock.now()`가 `no implementation for clock.now`로 실패합니다.176테스트에서 mod가 하는 모든 mods API 호출에는 Claude Code 대신 응답하는 스텁이 필요합니다. 단, 키트가 직접 응답하는 몇 가지, 즉 [`$.ui.invalidate`](/docs/ko/plugins/mods/interface#redraw-when-something-changes), [`$.state`](/docs/ko/plugins/mods/interface#keep-state), `$.session.append` 호출은 예외입니다. `$.clock` 호출에는 `mock.clock(on)`을 사용해야 하며, 그렇지 않으면 mod의 `$.clock.now()`가 `no implementation for clock.now`로 실패합니다.

172 177

173다음 표에는 mod가 가장 많이 사용하는 항목이 나와 있습니다. 첫 번째 열은 mod가 하는 호출 또는 `next(e)`로 넘기는 이벤트입니다. 두 번째 열은 그 이름으로 `on`에 전달할 함수이므로, `$.store.get` 행은 `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`이 됩니다. 스텁의 `'...'`은 사용자가 채울 텍스트를 나타냅니다.178다음 표에는 mod가 가장 많이 사용하는 항목이 나와 있습니다. 첫 번째 열은 mod가 하는 호출 또는 `next(e)`로 넘기는 이벤트입니다. 두 번째 열은 그 이름으로 `on`에 전달할 함수이므로, `$.store.get` 행은 `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`이 됩니다. 스텁의 `'...'`은 사용자가 채울 텍스트를 나타냅니다.

174 179

plugins/mods/troubleshoot.md +31 −1

Details

116 116

117값을 설정하거나 변경합니다. 줄 끝에 `settings.json`의 해당 `pluginConfigs` 항목이 명시되어 있습니다.117값을 설정하거나 변경합니다. 줄 끝에 `settings.json`의 해당 `pluginConfigs` 항목이 명시되어 있습니다.

118 118

119<h3 id="code-nested-too-deep-to-scan-more-than-2000-scopes">

120 `code nested too deep to scan: more than 2000 scopes`

121</h3>

122

123이 줄은 mod 이름으로 시작하고, 그 뒤에 `hooks module did not load:`, 파일, `code nested too deep to scan: more than 2000 scopes`가 나옵니다. 훅 모듈의 파일은 함수, 블록, 루프와 같은 범위를 [2,000단계](/docs/ko/plugins/mods/reference#limits)보다 깊게 중첩할 수 없습니다. [`claude plugin validate`](/docs/ko/plugins/mods/create#check-what-claude-code-reads-from-your-mod)도 같은 이유를 보고합니다.

124

125범위가 덜 깊게 중첩되도록 코드를 다시 작성합니다.

126

119<h3 id="no-mod-loads-in-a-directory-you-opened-for-the-first-time">127<h3 id="no-mod-loads-in-a-directory-you-opened-for-the-first-time">

120 처음 연 디렉터리에서 mod가 로드되지 않음128 처음 연 디렉터리에서 mod가 로드되지 않음

121</h3>129</h3>

132 140

133이 플래그 없이 시작합니다.141이 플래그 없이 시작합니다.

134 142

143<h3 id="claude-code-stops-asking-to-enable-hot-reloading">

144 Claude Code가 핫 리로드 활성화 여부를 더 이상 묻지 않음

145</h3>

146

147Claude가 대화형 세션에서 mod를 작성했지만 아무것도 로드되지 않고, Claude Code가 [핫 리로드를 활성화할지](/docs/ko/plugins/mods/create#ask-claude-for-a-mod) 다시 묻지 않습니다. 답을 선택하지 않은 채 질문이 세 번 종료되면 핫 리로드는 꺼진 상태로 유지됩니다. 예를 들어 [`askUserQuestionTimeout`](/docs/ko/settings-reference#askuserquestiontimeout)을 설정했는데 응답하기 전에 시간이 지나면 질문이 그렇게 종료됩니다. Claude Code는 [`AskUserQuestion`이 사용하는 것과 동일한 질문 대화 상자](/docs/ko/tools-reference#question-auto-continue-timeout)에서 묻기 때문에 이 설정이 여기에도 적용됩니다. 사용자가 직접 닫은 질문은 세 번에 포함되지 않습니다.

148

149mod를 실행하려면 [mod 디렉터리를 mods 폴더 밖으로 복사](/docs/ko/plugins/mods/create#use-the-mod-in-other-sessions)한 다음, 셸에서 `claude --plugin-dir ~/mods/git-branch`와 같이 `--plugin-dir`로 새 세션을 시작합니다.

150

135<h2 id="a-hook-is-skipped-or-a-mod-is-unloaded">151<h2 id="a-hook-is-skipped-or-a-mod-is-unloaded">

136 훅이 건너뛰어지거나 mod가 언로드되는 경우152 훅이 건너뛰어지거나 mod가 언로드되는 경우

137</h2>153</h2>

209 그림이 나타나지 않거나 반응하지 않음225 그림이 나타나지 않거나 반응하지 않음

210</h2>226</h2>

211 227

212mod는 로드되었지만 해당 pane, band 또는 컨트롤이 예상대로 동작하지 않습니다.228mod는 로드되었지만 해당 pane, band, toast 또는 컨트롤이 예상대로 동작하지 않습니다.

213 229

214<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">230<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">

215 pane 또는 band가 비어 있거나 Claude Code의 일반 콘텐츠를 표시함231 pane 또는 band가 비어 있거나 Claude Code의 일반 콘텐츠를 표시함

247 263

248명령이나 버튼에서 pane을 열거나, 호출의 `isPlaced` 결과를 확인합니다. [적절한 시점에 pane 열기](/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)를 참조하세요.264명령이나 버튼에서 pane을 열거나, 호출의 `isPlaced` 결과를 확인합니다. [적절한 시점에 pane 열기](/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)를 참조하세요.

249 265

266<h3 id="a-toast-doesn’t-appear">

267 toast가 나타나지 않음

268</h3>

269

270mod가 대화형 터미널 세션에서 [`$.ui.toast`](/docs/ko/plugins/mods/api#show-something-without-starting-a-turn)를 호출하지만 toast가 보이지 않습니다. 호출이 실행되었는지 확인하려면 [디버그 로그](#read-the-debug-log)에서 mod 이름과 toast 텍스트가 포함된 줄을 찾습니다. 예를 들면 `$.ui.toast (first-mod): build finished`와 같습니다. 그런 다음 다음과 같은 원인을 확인합니다.

271

272* **호출에 대한 줄이 없는 경우**: Claude Code가 호출을 거부한 이유를 알려 주는 줄을 찾습니다. 예를 들면 `first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000`과 같습니다.

273* **pane이 toast를 보류하고 있는 경우**: 현재 표시 중인 pane을 열 때 해당 mod나 다른 mod가 [`holdToasts`](/docs/ko/plugins/mods/interface#hold-toasts-behind-a-dialog)를 전달했습니다. pane을 닫으면 보류가 해제됩니다. 해당 pane이 사용자의 mod에 속하고 계속 열려 있어야 한다면 `$.ui.open` 호출에서 `holdToasts`를 제거하고 pane을 다시 엽니다.

274* **toast가 프롬프트 아래에 있는 경우**: [클래식 렌더러](/docs/ko/fullscreen#enable-fullscreen-rendering)에서는 프롬프트 아래 오른쪽을 확인합니다. 이 위치의 toast는 오른쪽 위의 상자가 아니라 mod 이름으로 시작하는 한 줄입니다.

275* **mod가 더 새로운 toast를 띄운 경우**: 클래식 렌더러에서는 mod의 더 새로운 toast가 표시 중이거나 표시 대기 중인 toast를 대체할 수 있습니다. 디버그 로그에는 이전 toast에 대한 줄이 하나 더 있으며, 표시 중이었다면 `gave way, cut short`로, 나타나지 않았다면 `gave way, unseen`으로 끝납니다. 두 메시지를 모두 표시하려면 하나의 toast에 넣습니다.

276* **toast가 그려지기 전에 시간이 만료된 경우**: 전체 화면 렌더링에서 Claude Code는 한 번에 최대 세 개의 toast만 그리므로, toast가 그려지기 전에 시간이 만료될 수 있습니다. 디버그 로그에는 해당 toast에 대한 줄이 하나 더 있으며 `left the stack, never drawn`으로 끝납니다. mod가 여러 toast를 한꺼번에 띄운다면 메시지를 하나의 toast에 넣습니다.

277

278v2.1.290 이전에는 Claude Code가 해당 mod에 대해 마지막으로 표시한 toast 이후 2초 이내에 띄워진 toast를 삭제했으며, 삭제된 toast에 대한 디버그 로그 줄에는 `within 2000ms of the last; dropped`가 표시되었습니다.

279

250<h3 id="hotkeys-do-nothing">280<h3 id="hotkeys-do-nothing">

251 단축키가 작동하지 않음281 단축키가 작동하지 않음

252</h3>282</h3>

plugins/publish.md +2 −1

Details

110}110}

111```111```

112 112

113셸에서 저장소의 `claude plugin validate .`을 실행하여 푸시하기 전에 파일을 확인하세요.113푸시하기 전에 셸에서 저장소의 `claude plugin validate .`을 실행하세요. 실행 시 확인하는 항목은 [디렉터리 검증](/docs/ko/plugins/cli-reference#validate-a-directory)을 참조하세요.

114 114

115[마켓플레이스 만들기](/docs/ko/plugins/create-marketplace)는 한 저장소에 여러 플러그인이 있는 레이아웃을 다룹니다.115[마켓플레이스 만들기](/docs/ko/plugins/create-marketplace)는 한 저장소에 여러 플러그인이 있는 레이아웃을 다룹니다.

116 116

129* 마켓플레이스를 한 번 추가: `claude plugin marketplace add your-org/your-marketplace`. 인수는 GitHub `owner/repo` 약자, URL 또는 경로입니다129* 마켓플레이스를 한 번 추가: `claude plugin marketplace add your-org/your-marketplace`. 인수는 GitHub `owner/repo` 약자, URL 또는 경로입니다

130* 플러그인 설치: `claude plugin install deploy-helper@your-marketplace`130* 플러그인 설치: `claude plugin install deploy-helper@your-marketplace`

131* 또는 세션 내에서 둘 다 수행: `/plugin install deploy-helper --marketplace your-org/your-marketplace`. Claude Code v2.1.275 이상이 필요합니다. [한 명령으로 마켓플레이스 추가 및 설치](/docs/ko/plugins/install#add-a-marketplace-and-install-in-one-command)를 참조하세요131* 또는 세션 내에서 둘 다 수행: `/plugin install deploy-helper --marketplace your-org/your-marketplace`. Claude Code v2.1.275 이상이 필요합니다. [한 명령으로 마켓플레이스 추가 및 설치](/docs/ko/plugins/install#add-a-marketplace-and-install-in-one-command)를 참조하세요

132* 또는 셸에서 한 명령으로 둘 다 수행: `claude plugin install deploy-helper --marketplace your-org/your-marketplace`. Claude Code v2.1.292 이상이 필요합니다

132 133

133<h3 id="ship-updates-to-users">134<h3 id="ship-updates-to-users">

134 사용자에게 업데이트 배포135 사용자에게 업데이트 배포

plugins/troubleshooting.md +73 −3

Details

163 `Invalid marketplace source format`163 `Invalid marketplace source format`

164</h3>164</h3>

165 165

166`/plugin marketplace add <source>` 또는 `claude plugin marketplace add <source>`를 실행했고, Claude Code가 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`로 응답했습니다.166`/plugin marketplace add <source>`, `claude plugin marketplace add <source>` 또는 `claude plugin install <plugin> --marketplace <source>`를 실행했고, Claude Code가 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`로 응답했습니다.

167 167

168Claude Code는 다음 형식 중 하나의 소스를 허용합니다:168Claude Code는 다음 형식 중 하나의 소스를 허용합니다:

169 169

237* **마켓플레이스를 소유한 경우**: 파일을 해당 위치에 놓고 마켓플레이스를 다시 추가합니다.237* **마켓플레이스를 소유한 경우**: 파일을 해당 위치에 놓고 마켓플레이스를 다시 추가합니다.

238* **다른 사람이 호스팅하는 경우**: 정확한 소스를 게시하는 소유자에게 요청합니다.238* **다른 사람이 호스팅하는 경우**: 정확한 소스를 게시하는 소유자에게 요청합니다.

239 239

240<h3 id="cannot-install-plugins-from-a-marketplace-with-this-name">

241 `Cannot add marketplace "<name>": Claude Code cannot install plugins from a marketplace with this name`

242</h3>

243

244마켓플레이스를 추가했는데, 해당 `marketplace.json`의 [`name`](/docs/ko/plugins/marketplace-reference#top-level-fields)이 `my-plugin@my-marketplace`와 같은 [플러그인 id](/docs/ko/plugins/loading#find-where-a-plugin-came-from)에서 `@` 뒤에 오는 부분으로 유효하지 않습니다. Claude Code는 추가를 거부하고 아무것도 등록하지 않습니다.

245

246메시지의 나머지 부분은 이름에 대한 규칙을 설명합니다. 이 예에서 `_internal`은 `_`로 시작하므로 규칙을 위반합니다:

247

248```text theme={null}

249Cannot add marketplace "_internal": Claude Code cannot install plugins from a marketplace with this name. Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. The name is set by "name" in the marketplace's marketplace.json; ask its maintainer to change it.

250```

251

252해당 규칙에 맞는 이름을 마켓플레이스에 지정한 다음 다시 추가합니다:

253

254* **마켓플레이스를 소유한 경우**: `marketplace.json`의 `name`을 예를 들어 `internal-tools`로 변경합니다.

255* **다른 사람이 호스팅하는 경우**: 소유자에게 이름 변경을 요청합니다.

256

257v2.1.295 이전에는 Claude Code가 이 예의 추가를 성공한 것으로 보고했습니다.

258

240<h3 id="ssh-authentication-failed-or-https-authentication-failed">259<h3 id="ssh-authentication-failed-or-https-authentication-failed">

241 `SSH authentication failed` 또는 `HTTPS authentication failed`260 `SSH authentication failed` 또는 `HTTPS authentication failed`

242</h3>261</h3>

568 `Marketplace "<name>" is already added from a different source`587 `Marketplace "<name>" is already added from a different source`

569</h3>588</h3>

570 589

571[`/plugin install <plugin> --marketplace <source>`](/docs/ko/plugins/install#add-a-marketplace-and-install-in-one-command)를 통해 마켓플레이스 추가를 확인했고, Claude Code가 해당 소스에서 가져온 카탈로그가 다른 소스에서 이미 추가한 마켓플레이스와 동일한 이름을 가지고 있습니다. Claude Code는 기존 마켓플레이스를 대체하지 않고 유지하며 플러그인은 설치되지 않습니다.590세션 또는 셸에서 [설치 명령의 `--marketplace <source>`](/docs/ko/plugins/install#add-a-marketplace-and-install-in-one-command)로 새 마켓플레이스 소스를 지정했습니다. Claude Code가 해당 소스에서 가져온 카탈로그가 다른 소스에서 이미 추가한 마켓플레이스와 동일한 이름을 가지고 있습니다. Claude Code는 기존 마켓플레이스를 대체하지 않고 유지하며 플러그인은 설치되지 않습니다.

572 591

573전체 메시지는 다음과 같습니다:592전체 메시지는 다음과 같습니다:

574 593

786 805

787Claude Code는 사용할 수 없는 기록을 `.set-aside` 파일로 복사하고 목록에서 삭제합니다. Claude Code는 복사본을 다시 읽지 않으며 복사본은 [`cleanupPeriodDays`](/docs/ko/settings-reference#cleanupperioddays) 일정에 따라 만료됩니다.806Claude Code는 사용할 수 없는 기록을 `.set-aside` 파일로 복사하고 목록에서 삭제합니다. Claude Code는 복사본을 다시 읽지 않으며 복사본은 [`cleanupPeriodDays`](/docs/ko/settings-reference#cleanupperioddays) 일정에 따라 만료됩니다.

788 807

808<h3 id="does-not-load-so-claude-code-ignores-the-whole-file">

809 `does not load (...), so Claude Code ignores the whole file`

810</h3>

811

812명령은 작동했습니다. 경고에 명시된 설정 파일에 오류가 있으므로, 이를 수정할 때까지 Claude Code는 명령이 해당 파일에 기록한 내용을 포함하여 파일 전체를 무시합니다.

813

814경고에 명시된 오류를 수정합니다. Claude Code가 허용하지 않는 값의 경우 [손상된 설정 파일 수정](/docs/ko/settings#fix-a-broken-settings-file)에서 방법을 설명합니다. 그런 다음 명령의 변경 사항이 더 이상 파일에 없으면 명령을 다시 실행합니다.

815

816이 경고는 셸에서 실행한 `claude plugin install`, `enable`, `disable` 또는 `claude plugin marketplace add`의 성공 줄 다음에 표시됩니다:

817

818```text theme={null}

819⚠ /home/user/.claude/settings.json does not load (its "permissions" is not valid), so Claude Code ignores the whole file, including anything this command wrote there. Fix the file, then run this command again if its change is missing. If a newer Claude Code wrote the file, update Claude Code instead.

820```

821

822괄호 안의 텍스트가 오류를 나타냅니다:

823

824* **`its "<key>" is not valid`**: 따옴표로 묶인 설정에 Claude Code가 허용하지 않는 값이 있습니다. 허용되는 값은 [설정 참조](/docs/ko/settings-reference)에서 해당 설정을 찾아 확인합니다. 둘 이상의 값이 실패하면 텍스트는 `its "permissions" and 1 other value are not valid`처럼 첫 번째 설정을 명시하고 나머지의 개수를 표시합니다.

825* **`it is not a JSON object`**: 최상위 수준이 배열인 파일처럼 파일의 최상위 수준이 JSON 객체가 아닙니다.

826

789<h3 id="a-plugin-you-disabled-still-loads">827<h3 id="a-plugin-you-disabled-still-loads">

790 `Disabled in ~/.claude/settings.json but still loads`828 `Disabled in ~/.claude/settings.json but still loads`

791</h3>829</h3>

812 850

813조직이 플러그인을 미리 설치하면 대신 관리 설정을 통해 그렇게 합니다. [플러그인 사전 설치 및 필수](/docs/ko/plugins/org#pre-install-and-require-plugins)를 참조합니다.851조직이 플러그인을 미리 설치하면 대신 관리 설정을 통해 그렇게 합니다. [플러그인 사전 설치 및 필수](/docs/ko/plugins/org#pre-install-and-require-plugins)를 참조합니다.

814 852

853<h3 id="a-plugin-stays-installed-after-plugin-uninstall-on-windows">

854 Windows에서 `plugin uninstall` 후에도 플러그인이 설치된 상태로 남음

855</h3>

856

857Windows에서 프로젝트 또는 로컬 범위로 `claude plugin uninstall`을 실행하면 성공했다고 보고되지만, `claude plugin list` 또는 `/plugin`에 여전히 플러그인이 나열됩니다.

858

859`installed_plugins.json`에 프로젝트 폴더에 대한 플러그인 설치 기록이 두 개 있었고, 각 기록은 폴더 경로를 서로 다르게 표기하며, 한 번의 제거로는 그중 하나만 삭제됩니다. 확인하려면 셸에서 `claude plugin list --json`을 실행합니다. 남아 있는 플러그인 행의 `projectPath`는 제거를 실행한 위치와 폴더를 다르게 표기합니다(예: `C:\work\app`에 대해 `c:\work\app`).

860

861같은 폴더에서 같은 `--scope`로 동일한 제거 명령을 다시 실행합니다. 두 번째 실행은 자체 경로 표기 아래에서 기록을 찾지 못하므로 다른 표기 아래의 기록을 제거합니다. 프로젝트 범위 설치의 경우:

862

863```shell theme={null}

864claude plugin uninstall <name>@<marketplace> --scope project

865```

866

867그런 다음 `claude plugin list --json`을 다시 실행하여 해당 행이 사라졌는지 확인합니다.

868

869v2.1.295 이전에는 두 번째 실행이 `Plugin "<name>" is not installed in project scope`로 실패합니다. `claude update`를 실행한 다음 제거를 다시 실행합니다.

870

815<h3 id="failed-to-load-hooks-from-and-hooks-that-dont-fire">871<h3 id="failed-to-load-hooks-from-and-hooks-that-dont-fire">

816 `Failed to load hooks from <path>` 및 발화하지 않는 훅872 `Failed to load hooks from <path>` 및 발화하지 않는 훅

817</h3>873</h3>

835 891

836stderr이 플러그인의 경로를 공백에서 자르면 훅의 셸 형식 명령이 `${CLAUDE_PLUGIN_ROOT}`를 따옴표 외부에서 사용하고 설치 경로에 공백이 포함되어 있습니다. 변수를 큰따옴표로 감싸거나 [exec 형식](/docs/ko/hooks#exec-form-and-shell-form)을 사용합니다. 따옴표 없는 변수를 찾으려면 플러그인 디렉토리에서 `claude plugin validate`를 실행하고 [따옴표 경고](/docs/ko/plugins/manifest-reference#quoting-and-path-separators)를 찾습니다.892stderr이 플러그인의 경로를 공백에서 자르면 훅의 셸 형식 명령이 `${CLAUDE_PLUGIN_ROOT}`를 따옴표 외부에서 사용하고 설치 경로에 공백이 포함되어 있습니다. 변수를 큰따옴표로 감싸거나 [exec 형식](/docs/ko/hooks#exec-form-and-shell-form)을 사용합니다. 따옴표 없는 변수를 찾으려면 플러그인 디렉토리에서 `claude plugin validate`를 실행하고 [따옴표 경고](/docs/ko/plugins/manifest-reference#quoting-and-path-separators)를 찾습니다.

837 893

894공지가 `Failed to run: Plugin directory does not exist: <path>`로 표시되면 [`Plugin directory does not exist`](#plugin-directory-does-not-exist)를 참조합니다.

895

838다른 오류의 경우 플러그인 디렉토리에서 훅의 명령을 직접 실행하여 전체 출력을 보거나 [디버그 로깅](/docs/ko/hooks#debug-hooks)으로 전체 stderr을 캡처합니다.896다른 오류의 경우 플러그인 디렉토리에서 훅의 명령을 직접 실행하여 전체 출력을 보거나 [디버그 로깅](/docs/ko/hooks#debug-hooks)으로 전체 stderr을 캡처합니다.

839 897

840<h4 id="a-plugin-hook-blocks-a-tool-call-or-prompt">898<h4 id="a-plugin-hook-blocks-a-tool-call-or-prompt">

869 </Step>927 </Step>

870</Steps>928</Steps>

871 929

930<h3 id="plugin-directory-does-not-exist">

931 `Plugin directory does not exist: <path>`

932</h3>

933

934메시지에 다시 설치하라고 나와 있더라도 먼저 Claude Code 프롬프트에서 `/reload-plugins`를 실행합니다. 세션이 플러그인의 훅을 로드한 디렉토리가 디스크에서 사라지면 플러그인의 훅이 `Failed to run: Plugin directory does not exist: <path> (<plugin> — run /plugin to reinstall)`로 실패하고 훅이 실행되지 않습니다. [`Plugin directory not found at path: <path>`](#plugin-directory-not-found-at-path)는 마켓플레이스 항목에 관한 다른 메시지입니다.

935

936다시 로드하면 플러그인의 현재 디렉토리에서 훅을 로드합니다. 실패는 각 훅 이벤트와 명령마다 세션당 한 번만 표시되므로, 훅이 더 이상 오류를 표시하지 않는다고 해서 문제가 해결되었음을 확인할 수는 없습니다. 대신 다시 로드의 출력을 읽습니다:

937

938* **오류 줄이 없는 `Reloaded:`**: 플러그인의 훅이 더 이상 누락된 디렉토리를 가리키지 않습니다.

939* **`N errors during load. Run /plugin for details.`**: `/plugin`에서 **Errors** 탭을 열고 표시된 메시지에 대한 이 페이지의 항목을 따릅니다.

940* **`Run /reload-plugins --force to apply.`로 끝나는 줄**: 아무것도 다시 로드되지 않았으며 훅이 계속 실패합니다. Claude Code 프롬프트에서 `/reload-plugins --force`를 실행합니다.

941

872<h3 id="invalid-mcp-server-config-for-and-mcp-servers-that-dont-start">942<h3 id="invalid-mcp-server-config-for-and-mcp-servers-that-dont-start">

873 `Invalid MCP server config for "<server>"` 및 시작하지 않는 MCP 서버943 `Invalid MCP server config for "<server>"` 및 시작하지 않는 MCP 서버

874</h3>944</h3>

1063 1133

1064`claude plugin validate <path>`를 실행했거나 세션에서 `/plugin validate <path>`를 실행했고 `Found N errors` 및 `Validation failed`를 인쇄한 다음 종료 코드 1로 종료했습니다.1134`claude plugin validate <path>`를 실행했거나 세션에서 `/plugin validate <path>`를 실행했고 `Found N errors` 및 `Validation failed`를 인쇄한 다음 종료 코드 1로 종료했습니다.

1065 1135

1066검증자는 제공한 경로에서 매니페스트를 읽습니다: 플러그인 디렉터리의 `.claude-plugin/plugin.json` 또는 마켓플레이스 디렉터리의 `.claude-plugin/marketplace.json`. 마켓플레이스의 경우 항목 자체의 매니페스트의 문제를 항목 인덱스로 접두사로 붙입니다(예: `plugins[1] plugin.json → json: ...`).1136검증자는 제공한 경로에서 매니페스트를 읽습니다: 플러그인 디렉터리의 경우 `.claude-plugin/plugin.json`, 마켓플레이스 디렉터리의 경우 `.claude-plugin/marketplace.json`, 둘 다 보유하는 디렉터리의 경우 둘 모두를 읽습니다. 마켓플레이스의 경우 항목 자체의 매니페스트의 문제를 항목 인덱스로 접두사로 붙입니다(예: `plugins[1] plugin.json → json: ...`). v2.1.289 이전에는 Claude Code가 둘 다 보유하는 디렉터리를 마켓플레이스로만 검증했습니다.

1067 1137

1068표는 유효성 검사를 중단하는 메시지와 두 가지 경고(`No frontmatter block found` 및 `Unknown field '<key>'`)를 다룹니다. `--strict`를 전달할 때만 중단됩니다. 누락된 설명과 같은 다른 경고는 나열되지 않습니다.1138표는 유효성 검사를 중단하는 메시지와 두 가지 경고(`No frontmatter block found` 및 `Unknown field '<key>'`)를 다룹니다. `--strict`를 전달할 때만 중단됩니다. 누락된 설명과 같은 다른 경고는 나열되지 않습니다.

1069 1139

remote-control.md +53 −20

Details

364 제한 사항364 제한 사항

365</h2>365</h2>

366 366

367* **대화형 프로세스당 하나의 원격 세션**: 서버 모드 외에는 각 Claude Code 인스턴스가 한 번에 하나의 원격 세션을 지원합니다. [서버 모드](#start-a-remote-control-session)를 사용하여 단일 프로세스에서 여러 개의 동시 세션을 실행하십시오.367* **대화형 프로세스당 원격 세션 하나**: 서버 모드가 아닌 경우 각 Claude Code 인스턴스는 한 번에 하나의 원격 세션만 지원합니다. 단일 프로세스에서 여러 세션을 동시에 실행하려면 [서버 모드](#start-a-remote-control-session)를 사용합니다.

368* **로컬 프로세스가 계속 실행되어야 함**: Remote Control은 로컬 프로세스로 실행됩니다. 터미널을 닫거나, Desktop 앱 또는 VS Code를 종료하거나, 그 밖의 방법으로 `claude` 프로세스를 중지하면 [다시 시작](#resume-sessions-after-stopping-the-server)할 때까지 세션이 오프라인 상태가 됩니다. 원격 머신의 터미널에서 `claude`를 실행하는 경우 SSH 연결을 끊은 후에도 세션이 계속 실행되도록 `tmux` 또는 `screen` 안에서 시작합니다.368* **로컬 프로세스가 계속 실행되어야 함**: Remote Control은 로컬 프로세스로 실행됩니다. 터미널을 닫거나 Desktop 앱 또는 VS Code를 종료하거나 그 밖의 방식으로 `claude` 프로세스를 중지하면, [다시 시작](#resume-sessions-after-stopping-the-server)할 때까지 세션이 오프라인 상태가 됩니다. 원격 머신의 터미널에서 `claude`를 실행하는 경우 SSH 연결을 끊은 후에도 세션이 계속 실행되도록 `tmux` 또는 `screen` 안에서 시작합니다.

369* **서버 모드에서 충돌한 세션**: `claude remote-control`로 제공되는 세션이 충돌하면 연결된 디바이스에서 메시지를 보내십시오. Claude Code가 다시 제공합니다. 서버를 다시 시작할 필요가 없습니다. Claude Code v2.1.238 이상이 필요합니다.369* **서버 모드에서 충돌한 세션**: `claude remote-control`이 제공하는 세션이 충돌하면 연결된 기기에서 해당 세션에 메시지를 보냅니다. 그러면 Claude Code가 세션을 다시 제공합니다. 서버를 다시 시작할 필요는 없습니다. Claude Code v2.1.238 이상이 필요합니다.

370* **연결된 세션에서 HTTP 403 거부**: 대화형 세션이 연결되면 Claude Code는 VPN 또는 네트워크 변경 후 발생할 수 있는 것처럼 머신과 Anthropic의 서버 사이의 무언가가 HTTP 403으로 응답할 때 최대 3분 동안 재시도를 계속합니다. 거부가 더 오래 지속되면 Claude Code는 연결을 해제하고 거부한 대상을 명시합니다: 네트워크 엣지 또는 자신의 네트워크의 프록시, VPN 또는 방화벽.370* **연결된 세션에서의 HTTP 403 거부**: 대화형 세션이 연결되면, 사용자의 머신과 Anthropic 서버 사이의 무언가가 HTTP 403으로 응답할 때 Claude Code는 최대 3분 동안 재시도를 계속합니다. 이는 VPN이나 네트워크 변경 후에 발생할 수 있습니다. 거부가 더 오래 지속되면 Claude Code는 연결을 끊고, 그 사유에 거부한 주체가 명시됩니다. 즉, 네트워크 엣지인지 또는 사용자 네트워크의 프록시, VPN, 방화벽인지가 표시됩니다.

371* **확장된 네트워크 중단**: 머신이 켜져 있지만 네트워크에 도달할 수 없는 경우 다음 작업은 모드에 따라 달라집니다:371* **장시간 네트워크 중단**: 머신이 깨어 있지만 네트워크에 연결할 수 없는 경우, 다음에 할 일은 모드에 따라 다릅니다.

372 * **서버 모드**: Claude Code는 약 10분 후에 포기하고 `claude remote-control` 프로세스가 종료됩니다. 새 세션을 시작하려면 `claude remote-control`을 다시 실행하십시오.372 * **서버 모드**: Claude Code는 약 10분 후에 포기하고 `claude remote-control` 프로세스가 종료됩니다. 새 세션을 시작하려면 `claude remote-control`을 다시 실행합니다.

373 * **대화형 세션**: 로컬에서 계속 작업하십시오. Claude Code는 중단이 지속되는 동안 재시도를 계속하고 네트워크가 복구되면 자동으로 다시 연결됩니다.373 * **대화형 세션**: 로컬에서 계속 작업합니다. Claude Code는 중단이 지속되는 동안 계속 재시도하며, 네트워크가 복구되면 자동으로 다시 연결됩니다.

374* **다운로드되지 않는 첨부 파일**: 휴대폰이나 브라우저에서 첨부한 파일을 머신으로 다운로드할 수 없는 경우에도 Claude는 메시지와 다운로드된 파일을 받습니다. 누락된 파일 대신 Claude Code는 메시지에 `[1 of 3 attachments did not arrive]`와 같은 메모를 추가합니다.374* **다운로드되지 않는 첨부 파일**: 휴대폰이나 브라우저에서 첨부한 파일을 머신으로 다운로드할 수 없는 경우에도 Claude는 메시지와 다운로드된 파일을 받습니다. 누락된 파일 대신 Claude Code는 메시지에 `[1 of 3 attachments did not arrive]`와 같은 메모를 추가합니다.

375* **현재 상태 하트비트 실패**: 대화형 세션이 `could not reach the Remote Control server for about 30 minutes`로 연결이 끊어지면 `/remote-control`을 실행하여 다시 연결하십시오.375* **프레즌스 하트비트 실패**: 대화형 세션이 `could not reach the Remote Control server for about 30 minutes`와 함께 연결이 끊어지면 `/remote-control`을 실행하여 다시 연결합니다.

376* **전달된 대화 상자 만료**: Claude Code는 권한 프롬프트와 `AskUserQuestion` 질문을 답변할 때까지 열어 둡니다. Claude Code가 안전 거부 후 표시되는 모델 선택 프롬프트와 같은 다른 종류의 대화 상자를 원격 세션으로 전달할 때 기본적으로 5분을 기다린 후 대화 상자를 닫고 대화 상자의 작업 없음 기본값으로 계속합니다. [`dialogExpiry`](/docs/ko/settings-reference#dialogexpiry)를 설정하여 기한을 조정하거나 비활성화하십시오. Claude Code v2.1.224 이상이 필요합니다.376* **전달된 대화 상자의 만료**: Claude Code는 권한 프롬프트와 `AskUserQuestion` 질문을 사용자가 응답할 때까지 열어 둡니다. 안전 거부 후 표시되는 모델 선택 프롬프트처럼 다른 종류의 대화 상자를 원격 세션으로 전달할 때는 기본적으로 5분 동안 기다린 다음 대화 상자를 닫고 해당 대화 상자의 무동작 기본값으로 계속 진행합니다. 기한을 조정하거나 비활성화하려면 [`dialogExpiry`](/docs/ko/settings-reference#dialogexpiry)를 설정합니다. Claude Code v2.1.224 이상이 필요합니다.

377* **Fable 사용량 크레딧 동의 프롬프트는 전달되지 않음**: Claude Code는 세션이 실행되는 위치에만 중간 세션 [Fable 사용량 크레딧 동의 프롬프트](/docs/ko/model-config#fable-and-usage-credits)를 표시하며, 디바이스에는 표시하지 않습니다. 세션이 터미널에서 실행되고 Claude Code가 프롬프트를 닫기 전에 아무도 응답하지 않으면 요청을 보내지 않고 턴이 종료됩니다. [프롬프트 확인이 응답되지 않음](/docs/ko/errors#the-prompt-to-confirm-went-unanswered)을 참조하십시오.377* **Fable 사용량 크레딧 동의 프롬프트는 전달되지 않음**: Claude Code는 세션 도중의 [Fable 사용량 크레딧 동의 프롬프트](/docs/ko/model-config#fable-and-usage-credits)를 사용자의 기기가 아닌 세션이 실행되는 곳에만 표시합니다. 세션이 터미널에서 실행되고 Claude Code가 프롬프트를 닫기 전에 그곳에서 아무도 응답하지 않으면, 요청을 보내지 않고 턴이 종료됩니다. [The prompt to confirm went unanswered](/docs/ko/errors#the-prompt-to-confirm-went-unanswered)를 참조하세요.

378* **일부 명령은 로컬 전용**: `/plugin` 또는 `/resume`과 같이 터미널 인터페이스에서만 실행되는 명령은 인수를 전달하는지 여부에 관계없이 로컬 CLI에서만 작동합니다. `/claude-api`도 모바일 또는 웹에서 입력하면 사용할 수 없습니다. 그래도 Claude는 그곳에서 [해당 스킬을 자체적으로 로드](/docs/ko/skills#work-on-claude-api-projects)할 수 있습니다. 다음은 모바일 및 웹에서 작동합니다:378* **일부 명령은 로컬 전용**: `/plugin`이나 `/resume`처럼 터미널 인터페이스에서만 실행되는 명령은 인수 전달 여부와 관계없이 로컬 CLI에서만 작동합니다. `/claude-api`도 모바일이나 웹에서 입력하면 사용할 수 없습니다. 다만 그곳에서도 Claude가 [해당 스킬을 스스로 로드](/docs/ko/skills#work-on-claude-api-projects)할 수는 있습니다. 다음은 모바일과 웹에서 작동합니다.

379 * 텍스트 출력 명령: `/compact`, `/clear`, `/context`, `/usage`, `/exit`, `/usage-credits`, `/recap`, 및 `/reload-plugins`. `/usage-credits`는 브라우저를 열지 않고 청구 URL을 인쇄합니다. `/reload-plugins`는 세션이 대화형 터미널에서 실행될 때만 작동합니다. 터미널이 없는 세션은 이를 거부합니다.379 * 텍스트 출력 명령: `/compact`, `/clear`, `/context`, `/usage`, `/exit`, `/usage-credits`, `/recap`, `/reload-plugins`. `/usage-credits`는 브라우저를 여는 대신 청구 URL을 출력합니다. `/reload-plugins`는 세션이 대화형 터미널에서 실행될 때만 작동하며, 대화형 터미널이 없는 세션은 이를 거부합니다.

380 * `/model`, `/effort`, `/fast`, `/color`, 및 `/rename`: 값을 인수로 전달하십시오. 예를 들어 `/model sonnet` 또는 `/effort high`. 모바일 및 웹에서 `/model`과 `/effort`는 터미널 선택기 또는 슬라이더 대신 인수를 사용합니다.380 * `/model`, `/effort`, `/fast`, `/color`, `/rename`: 값을 인수로 전달합니다. 예를 들어 `/model sonnet` 또는 `/effort high`와 같습니다. 모바일과 웹에서 `/model`과 `/effort`는 터미널의 선택기나 슬라이더 대신 인수를 받습니다.

381 * `/mcp`: 모바일 앱에서는 선택기를 열지 않고 서버 상태의 텍스트 요약을 반환합니다. 웹에서 `/mcp`는 요약을 반환하지 않고 [claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai)의 디렉토리를 엽니다. `reconnect`, `enable`, 및 `disable` [하위 명령](/docs/ko/commands#all-commands)은 둘 다에서 작동합니다. 서버 이름 없이 `/mcp reconnect`를 실행하면 실패했거나 인증이 필요한 모든 서버를 재시도합니다.381 * `/mcp`: 모바일 앱에서는 선택기를 여는 대신 서버 상태의 텍스트 요약을 반환합니다. 웹에서는 `/mcp`만 입력하면 요약을 반환하는 대신 [claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai) 디렉터리가 열립니다. `reconnect`, `enable`, `disable` [하위 명령](/docs/ko/commands#all-commands)은 세션이 대화형 터미널에서 실행될 때 양쪽 모두에서 작동합니다. 서버 이름 없이 `/mcp reconnect`를 실행하면 실패했거나 인증이 필요한 모든 서버를 재시도합니다. 선택기 없이 claude.ai 커넥터를 인가하려면 [Authorize a connector again from your shell](#authorize-a-connector-again-from-your-shell)을 참조하세요.

382 * `/config`: 모바일 앱에서 `key=value`를 전달하여 설정을 지정하거나 인수 없이 실행하여 설정할 수 있는 키를 나열하십시오. 웹에서 `/config`는 대신 설정의 Claude Code 섹션을 열고 명령 뒤의 텍스트를 무시합니다.382 * `/config`: 모바일 앱에서는 `key=value`를 전달하여 설정을 지정하거나, 인수 없이 실행하여 설정할 수 있는 키 목록을 확인합니다. 웹에서는 `/config`가 대신 설정의 Claude Code 섹션을 열며, 명령 뒤의 텍스트는 무시합니다.

383 * Team 및 Enterprise에서 모바일 또는 웹의 `/usage-credits`는 [관리자에게 사용량 크레딧 요청](/docs/ko/costs#add-usage-credits-to-your-subscription)을 보내지 않습니다. 전송하려면 대화형 CLI에만 나타나는 확인이 필요하므로 명령은 대신 거기서 실행하도록 지시합니다.383 * Team 및 Enterprise에서는 모바일이나 웹에서 `/usage-credits`를 실행해도 [관리자에게 사용량 크레딧 요청](/docs/ko/costs#add-usage-credits-to-your-subscription)이 전송되지 않습니다. 전송하려면 대화형 CLI에서만 표시되는 확인이 필요하므로, 명령은 대신 그곳에서 실행하라고 안내합니다.

384 * `/autocompact`, v2.1.221부터: 창 크기를 인수로 전달하십시오. 예를 들어 `/autocompact 500k`. 인수 없이 실행하면 터미널 세션에서 명령이 표시하는 대화 상자를 열지 않고 현재 창 크기를 텍스트로 인쇄합니다.384 * `/autocompact`, v2.1.221부터: 윈도우 크기를 인수로 전달합니다. 예를 들어 `/autocompact 500k`와 같습니다. 인수 없이 실행하면 터미널 세션에서 이 명령이 표시하는 대화 상자를 여는 대신 현재 윈도우 크기를 텍스트로 출력합니다.

385 * `/advisor`, v2.1.260부터: 모델을 인수로 전달하십시오. 예를 들어 `/advisor opus` 또는 `off`를 전달하여 어드바이저를 끕니다. 두 형식 모두 현재 세션에만 적용되며 저장된 기본값은 변경하지 않습니다. 인수 없이 실행하면 선택기를 열지 않고 현재 어드바이저를 텍스트로 인쇄합니다.385 * `/advisor`, v2.1.260부터: 모델을 인수로 전달하거나(예: `/advisor opus`), `off`를 전달하여 advisor를 끕니다. 두 형식 모두 현재 세션에만 적용되며 저장된 기본값은 변경되지 않습니다. 인수 없이 실행하면 선택기를 여는 대신 현재 advisor를 텍스트로 출력합니다.

386 * `/output-style`, v2.1.269부터: 스타일 이름을 인수로 전달하십시오. 예를 들어 `/output-style concise` 또는 인수 없이 실행하여 스타일을 나열하십시오. 모바일 및 웹에서 [기본 제공 스타일](/docs/ko/output-styles#built-in-output-styles)만 나열하고 선택할 수 있습니다. [사용자 정의 스타일](/docs/ko/output-styles#create-a-custom-output-style)을 사용하려면 세션 자체에서 선택하십시오.386 * `/output-style`, v2.1.269부터: 스타일 이름을 인수로 전달하거나(예: `/output-style concise`), 인수 없이 실행하여 스타일 목록을 확인합니다. 모바일과 웹에서는 [기본 제공 스타일](/docs/ko/output-styles#built-in-output-styles)만 나열하고 선택할 수 있습니다. [사용자 지정 스타일](/docs/ko/output-styles#create-a-custom-output-style)을 사용하려면 세션 자체에서 선택합니다.

387 * `/focus`, v2.1.281부터: 인수로 `on` 또는 `off`를 전달하십시오. 예를 들어 `/focus on` 또는 인수 없이 실행하여 [포커스 보기](/docs/ko/commands#all-commands)를 전환하십시오. 두 형식 모두 현재 세션에만 적용되며 저장된 선택은 변경하지 않습니다.387 * `/focus`, v2.1.281부터: `on` 또는 `off`를 인수로 전달하거나(예: `/focus on`), 인수 없이 실행하여 [포커스 뷰](/docs/ko/commands#all-commands)를 전환합니다. 두 형식 모두 현재 세션에만 적용되며 저장된 선택은 변경되지 않습니다.

388

389<h2 id="authorize-a-connector-again-from-your-shell">

390 셸에서 커넥터 다시 인가하기

391</h2>

392

393Remote Control로 조작하는 세션에서 claude.ai 커넥터에 인증이 필요한 경우, 모바일 앱이나 웹에서는 `/mcp` 패널을 사용할 수 없습니다. 세션이 실행 중인 머신의 터미널에서 인가 링크를 받은 다음, 사용 중인 기기에서 해당 링크를 엽니다. 이 명령은 모바일 앱이나 웹에서 실행할 수 없습니다. 그곳에서 보내는 `!`로 시작하는 줄은 Claude에게 메시지로 전달되며 [셸 모드](/docs/ko/interactive-mode#shell-mode-with-prefix)에서 실행되지 않습니다.

394

395<Steps>

396 <Step title="인가 링크 받기">

397 SSH를 통한 접속 등으로 세션이 실행 중인 머신의 터미널에서 커넥터 이름을 따옴표로 묶어 `claude mcp login`을 실행합니다. 커넥터 이름은 `claude.ai`로 시작하며, 예를 들어 Slack 커넥터의 이름은 `claude.ai Slack`입니다. 다음 명령은 Slack 커넥터의 링크를 받습니다:

398

399 ```bash theme={null}

400 claude mcp login "claude.ai Slack" --no-browser

401 ```

402

403 이 명령은 claude.ai 링크를 출력한 후 종료됩니다. 브라우저에서 링크를 열고 claude.ai에서 인가를 완료합니다. `--no-browser`는 명령이 해당 머신에서 브라우저를 열지 않도록 합니다. 해당 머신은 사용 중인 기기가 아닐 수 있기 때문입니다.

404 </Step>

405

406 <Step title="세션에서 커넥터 사용하기">

407 새 세션을 시작하거나, 이미 실행 중인 세션에서 커넥터를 다시 연결합니다:

408

409 * **새 세션**: 인가 후에 시작하는 세션은 추가 단계 없이 커넥터에 연결됩니다.

410 * **실행 중인 세션**: Claude Code 프롬프트에서 또는 모바일 앱이나 웹에서 동일한 이름을 따옴표 없이 사용하여 `/mcp reconnect`를 실행합니다. 세션이 모바일 앱이나 웹에서 이 명령을 받아들이는지 확인하려면 [모바일과 웹에서 작동하는 명령](#limitations)의 `/mcp` 항목을 참조하세요.

411

412 다음 명령은 Slack 커넥터를 다시 연결합니다:

413

414 ```text theme={null}

415 /mcp reconnect claude.ai Slack

416 ```

417

418 터미널에서는 Claude Code가 `Successfully reconnected to claude.ai Slack`을 출력합니다. 모바일 앱이나 웹에서의 응답은 `Reconnected "claude.ai Slack".`입니다.

419 </Step>

420</Steps>

388 421

389<h2 id="troubleshooting">422<h2 id="troubleshooting">

390 문제 해결423 문제 해결

scheduled-tasks.md +21 −4

Details

191 지터191 지터

192</h3>192</h3>

193 193

194스케줄러는 모든 세션이 동일한 벽시계 시간에 API에 도달하는 것을 방지하기 위해 실행 시간에 결정론적 오프셋을 추가합니다:194예약 작업은 일정에 지정된 시간과 다른 시간에 실행될 수 있습니다. 모든 세션의 작업이 정확히 일정대로 실행되면 많은 작업이 같은 순간에 API를 호출하게 되므로, Claude Code는 각 작업의 실행 시간을 조정합니다. 반복 작업은 늦게 실행되고, 정시 또는 30분에 예약된 일회성 작업은 약간 일찍 실행됩니다.

195 195

196* 반복 작업은 스케줄된 시간 이후 최대 30분 후에 실행되거나(또는 시간별보다 더 자주 실행되는 작업의 경우 간격의 최대 절반), 최대 30분으로 제한됩니다. `:00`에 스케줄된 시간별 작업은 `:30`까지 언제든지 실행될 수 있습니다.196<h4 id="how-late-a-recurring-task-runs">

197* 시간의 맨 위 또는 맨 아래에 스케줄된 일회성 작업은 최대 90초 일찍 실행됩니다.197 반복 작업이 얼마나 늦게 실행되는지

198</h4>

198 199

199오프셋은 작업 ID에서 파생되므로 동일한 작업은 항상 동일한 오프셋을 가집니다. 정확한 타이밍이 중요한 경우 `0 9 * * *` 대신 `3 9 * * *`와 같이 `:00` 또는 `:30`이 아닌 분을 선택하면 일회성 지터가 적용되지 않습니다.200반복 작업을 생성하면 Claude Code는 해당 작업에 고정된 지연 시간을 부여하고 모든 실행에 이 지연 시간을 더합니다. 지연 시간은 작업 ID로부터 계산되므로, 세션이 유휴 상태이고 다른 작업이 실행되지 않는 경우를 포함하여 동일한 작업은 매번 같은 분만큼 늦게 실행됩니다.

201

202더 자주 실행되는 작업일수록 지연 시간이 짧으며, 작업에 적용될 수 있는 최대 지연 시간은 30분입니다. 다음은 몇 가지 일반적인 일정에 대한 지연 시간 범위입니다:

203

204| 작업 실행 주기 | 지연 시간 범위 |

205| :- | :- |

206| 10분마다 | 0분에서 5분 사이 |

207| 30분마다 | 0분에서 15분 사이 |

208| 매시간 또는 매일처럼 그보다 덜 자주 | 0분에서 30분 사이 |

209

210예를 들어 `7,37 * * * *`는 작업을 `:07`과 `:37`에 예약하며, 이 둘은 30분 간격이므로 지연 시간은 0분에서 15분 사이입니다. 이 작업의 지연 시간이 14분이라면 매시간 `:21`과 `:51`에 실행됩니다. 일정을 다른 분으로 변경하면 실행 시간이 이동하며, 여전히 그 위에 지연 시간이 더해집니다.

211

212<h4 id="when-a-one-shot-task-runs-early">

213 일회성 작업이 일찍 실행되는 경우

214</h4>

215

216`:00` 또는 `:30`에 예약된 일회성 작업은 최대 90초 일찍 실행됩니다. Claude Code는 그 외의 분에 예약된 일회성 작업은 조정하지 않으므로, 타이밍이 중요한 경우 정시와 30분을 피해 예약하세요: `0 9 * * *` 대신 `3 9 * * *`를 사용합니다.

200 217

201<h3 id="seven-day-expiry">218<h3 id="seven-day-expiry">

202 7일 만료219 7일 만료

security-guidance.md +12 −6

Details

74 74

75[자신의 규칙을 추가](#add-your-own-rules)하여 각 계층을 확장할 수 있습니다. 기본 제공 확인은 개별적으로 제거할 수 없지만 [각 계층을 독립적으로 비활성화](#disable-or-uninstall)할 수 있습니다.75[자신의 규칙을 추가](#add-your-own-rules)하여 각 계층을 확장할 수 있습니다. 기본 제공 확인은 개별적으로 제거할 수 없지만 [각 계층을 독립적으로 비활성화](#disable-or-uninstall)할 수 있습니다.

76 76

~~77<h3 id="on-each-file-edit">~~77<span id="on-each-file-edit" />

~~78 각 파일 편집 시~~78

79<h3 id="checks-on-each-file-edit">

80 각 파일 편집 시 확인

79</h3>81</h3>

80 82

81Claude가 파일에 쓸 때 플러그인은 새 콘텐츠를 알려진 위험한 패턴에 대해 스캔합니다. 이는 모델 호출이 없는 패턴 일치이므로 사용 비용이 추가되지 않습니다.83Claude가 파일에 쓸 때 플러그인은 새 콘텐츠를 알려진 위험한 패턴에 대해 스캔합니다. 이는 모델 호출이 없는 패턴 일치이므로 사용 비용이 추가되지 않습니다.

91 93

92`security-patterns.yaml` 파일로 이 계층에 [자신의 패턴을 추가](#add-custom-per-edit-patterns)할 수 있습니다.94`security-patterns.yaml` 파일로 이 계층에 [자신의 패턴을 추가](#add-custom-per-edit-patterns)할 수 있습니다.

93 95

~~94<h3 id="at-the-end-of-each-turn">~~96<span id="at-the-end-of-each-turn" />

~~95 각 턴의 끝에서~~97

98<h3 id="checks-at-the-end-of-each-turn">

99 각 턴의 끝에서 확인

96</h3>100</h3>

97 101

98턴은 Claude가 응답하는 한 라운드입니다: 메시지를 보내고, Claude가 작업하고 회신하며, 턴이 끝납니다. 각 턴 후에 플러그인은 Claude의 편집 도구, Bash 명령 및 서브에이전트의 변경 사항을 포함하여 턴 중에 작업 트리에서 변경된 모든 것의 git diff를 계산하고 보안에 중점을 둔 별도의 Claude 검토로 보냅니다. 검토는 백그라운드에서 실행되므로 Claude의 회신이 지연되지 않습니다. 검토에서 문제를 발견하면 Claude는 발견 사항으로 다시 프롬프트되고 후속 조치로 해결합니다.102턴은 Claude가 응답하는 한 라운드입니다: 메시지를 보내고, Claude가 작업하고 회신하며, 턴이 끝납니다. 각 턴 후에 플러그인은 Claude의 편집 도구, Bash 명령 및 서브에이전트의 변경 사항을 포함하여 턴 중에 작업 트리에서 변경된 모든 것의 git diff를 계산하고 보안에 중점을 둔 별도의 Claude 검토로 보냅니다. 검토는 백그라운드에서 실행되므로 Claude의 회신이 지연되지 않습니다. 검토에서 문제를 발견하면 Claude는 발견 사항으로 다시 프롬프트되고 후속 조치로 해결합니다.

107 111

108세션에서 발견 사항과 Claude의 해결책을 모두 직접 볼 수 있습니다. 검토는 턴당 최대 30개의 변경된 파일을 포함하고 최대 3번 연속으로 발생한 후 다시 사용자에게 양보합니다.112세션에서 발견 사항과 Claude의 해결책을 모두 직접 볼 수 있습니다. 검토는 턴당 최대 30개의 변경된 파일을 포함하고 최대 3번 연속으로 발생한 후 다시 사용자에게 양보합니다.

109 113

110<h3 id="on-each-commit-or-push-claude-makes">114<span id="on-each-commit-or-push-claude-makes" />

111 Claude가 수행하는 각 커밋 또는 푸시 시115

116<h3 id="checks-on-each-commit-or-push-claude-makes">

117 Claude가 수행하는 각 커밋 또는 푸시 시 확인

112</h3>118</h3>

113 119

114Claude가 Bash 도구를 통해 `git commit` 또는 `git push`를 실행할 때 플러그인은 백그라운드에서 변경 사항에 대한 더 깊은 에이전트 검토를 실행합니다. 이 검토는 호출자, 새니타이저 및 관련 파일을 포함한 주변 코드를 읽어 발견 사항이 보고되기 전에 실제인지 결정합니다. 추가 컨텍스트는 코드베이스에서 격리되어 보면 위험해 보이지만 안전한 패턴에 대한 거짓 양성을 낮게 유지합니다.120Claude가 Bash 도구를 통해 `git commit` 또는 `git push`를 실행할 때 플러그인은 백그라운드에서 변경 사항에 대한 더 깊은 에이전트 검토를 실행합니다. 이 검토는 호출자, 새니타이저 및 관련 파일을 포함한 주변 코드를 읽어 발견 사항이 보고되기 전에 실제인지 결정합니다. 추가 컨텍스트는 코드베이스에서 격리되어 보면 위험해 보이지만 안전한 패턴에 대한 거짓 양성을 낮게 유지합니다.

self-hosted-environments-configuration.md +16 −3

Details

403 403

404* 표준 시스템 경로에 있는 엔터프라이즈 범위 [관리형 MCP 파일](/docs/ko/managed-mcp): Linux 러너 호스트에서는 `/etc/claude-code/managed-mcp.json`, macOS 호스트에서는 `/Library/Application Support/ClaudeCode/managed-mcp.json`입니다. 관리자가 나열한 서버만 로드할 수 있도록 잠긴 플릿에 사용합니다. 우선순위 규칙은 [managed-mcp.json을 통한 배타적 제어](/docs/ko/managed-mcp#exclusive-control-with-managed-mcp-json)를 참조하세요. 이 파일이 러너 호스트에 있으면 Claude Code는 claude.ai 커넥터를 포함하여 Anthropic의 컨트롤 플레인이 세션에 전달하는 MCP 서버를 건너뛰고, 세션 자식 프로세스의 stderr에 경고로 해당 서버 이름을 표시하며, 러너는 이를 `debug` 로그 수준으로 기록합니다. v2.1.229 이전에는 이러한 세션이 `You cannot dynamically configure MCP servers when an enterprise MCP config is present`와 함께 시작 시 종료되었습니다.404* 표준 시스템 경로에 있는 엔터프라이즈 범위 [관리형 MCP 파일](/docs/ko/managed-mcp): Linux 러너 호스트에서는 `/etc/claude-code/managed-mcp.json`, macOS 호스트에서는 `/Library/Application Support/ClaudeCode/managed-mcp.json`입니다. 관리자가 나열한 서버만 로드할 수 있도록 잠긴 플릿에 사용합니다. 우선순위 규칙은 [managed-mcp.json을 통한 배타적 제어](/docs/ko/managed-mcp#exclusive-control-with-managed-mcp-json)를 참조하세요. 이 파일이 러너 호스트에 있으면 Claude Code는 claude.ai 커넥터를 포함하여 Anthropic의 컨트롤 플레인이 세션에 전달하는 MCP 서버를 건너뛰고, 세션 자식 프로세스의 stderr에 경고로 해당 서버 이름을 표시하며, 러너는 이를 `debug` 로그 수준으로 기록합니다. v2.1.229 이전에는 이러한 세션이 `You cannot dynamically configure MCP servers when an enterprise MCP config is present`와 함께 시작 시 종료되었습니다.

405* 러너 호스트의 [관리형 설정](/docs/ko/managed-settings)에 있는 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers) 키: 배타적 제어를 하지 않고 HTTP 및 SSE 서버를 제공하므로 다른 소스의 서버도 계속 로드됩니다. Claude Code v2.1.259 이상이 필요합니다.405* 러너 호스트의 [관리형 설정](/docs/ko/managed-settings)에 있는 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers) 키: 배타적 제어를 하지 않고 HTTP 및 SSE 서버를 제공하므로 다른 소스의 서버도 계속 로드됩니다. Claude Code v2.1.259 이상이 필요합니다.

406* `<repo>/.mcp.json`: 프로젝트 범위입니다. 파일을 저장소에 커밋하면 해당 서버는 클라우드 세션에서 자동 승인됩니다.406* `<repo>/.mcp.json`: 프로젝트 범위입니다. 파일을 저장소에 커밋하면 해당 서버는 클라우드 세션에서 자동 승인됩니다. 여러 저장소가 있는 세션에서는 [최대 하나의 저장소 파일만 로드됩니다](#repository-settings-in-sessions-with-several-repositories).

407 407

408조직에 커넥터 전달이 활성화되어 있으면 Anthropic의 컨트롤 플레인은 claude.ai에서 구성한 커넥터를 `api.anthropic.com`을 경유하는 서버 제공 MCP 구성을 통해 대화형으로 생성된 세션에 전달합니다. [CLI 디스패치](/docs/ko/self-hosted-environments-testing#run-the-test-loop)와 같이 프로그래밍 방식으로 생성된 세션은 커넥터 전달을 받지 않으므로, 이 섹션에 나열된 다른 소스를 통해 MCP 서버를 제공해야 합니다. 자식 프로세스의 OAuth 토큰에는 커넥터를 직접 가져오기 위한 범위가 포함되어 있지 않으므로 자식 프로세스는 직접 가져오기를 시도하지 않으며, 전달은 서버 주도로 이루어집니다.408조직에 커넥터 전달이 활성화되어 있으면 Anthropic의 컨트롤 플레인은 claude.ai에서 구성한 커넥터를 `api.anthropic.com`을 경유하는 서버 제공 MCP 구성을 통해 대화형으로 생성된 세션에 전달합니다. [CLI 디스패치](/docs/ko/self-hosted-environments-testing#run-the-test-loop)와 같이 프로그래밍 방식으로 생성된 세션은 커넥터 전달을 받지 않으므로, 이 섹션에 나열된 다른 소스를 통해 MCP 서버를 제공해야 합니다. 자식 프로세스의 OAuth 토큰에는 커넥터를 직접 가져오기 위한 범위가 포함되어 있지 않으므로 자식 프로세스는 직접 가져오기를 시도하지 않으며, 전달은 서버 주도로 이루어집니다.

409 409

540exit 0540exit 0

541```541```

542 542

543훅은 세션이 끝나기 전에 Claude에 커밋하고 푸시하도록 프롬프트하며 디렉토리가 git 저장소가 아니거나 원격이 없을 때 침묵합니다.543훅은 세션이 끝나기 전에 Claude에게 커밋하고 푸시하도록 요청하며, 디렉토리가 git 저장소가 아니거나 원격이 없을 때는 아무것도 출력하지 않습니다. 저장소가 여러 개인 세션의 경우 [`$CLAUDE_PROJECT_DIR`이 가리키는 대상](#repository-settings-in-sessions-with-several-repositories)을 참조하세요.

544 544

545<h2 id="permissions-and-tool-approval">545<h2 id="permissions-and-tool-approval">

546 권한 및 도구 승인546 권한 및 도구 승인

569 569

570`SELF_HOSTED_RUNNER_HOST_CONFIG_DIR`을 설정하여 다른 경로에서 시드하거나 빈 디렉토리를 가리켜 시딩을 비활성화하십시오.570`SELF_HOSTED_RUNNER_HOST_CONFIG_DIR`을 설정하여 다른 경로에서 시드하거나 빈 디렉토리를 가리켜 시딩을 비활성화하십시오.

571 571

572저장소 커밋된 `.claude/settings.json`은 프로젝트 설정으로 위에 계층화됩니다. 세션은 또한 러너 이미지의 표준 시스템 경로에서 [`managed-settings.json`](/docs/ko/settings#where-settings-live)을 읽습니다. 해당 키가 [서버 관리 설정](/docs/ko/server-managed-settings)과 함께 적용되는지 여부는 [Claude Code가 관리되는 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)을 따릅니다. 기본적으로 조직이 서버 관리 키를 제공할 때 세션은 [Claude Code가 모든 관리자 소스에서 읽는 키](/docs/ko/managed-settings#keys-read-from-every-admin-source)(예: `env` 블록, 샌드박스 잠금, 샌드박스 바이너리 경로 및 `forceRemoteSettingsRefresh`)를 제외하고 러너 이미지의 파일을 무시합니다. [설정 우선순위](/docs/ko/settings#settings-precedence)를 참조하십시오.572저장소 커밋된 `.claude/settings.json`은 프로젝트 설정으로 위에 계층화됩니다. 여러 저장소가 있는 세션에서는 [최대 하나의 저장소 파일만 적용됩니다](#repository-settings-in-sessions-with-several-repositories). 세션은 또한 러너 이미지의 표준 시스템 경로에서 [`managed-settings.json`](/docs/ko/settings#where-settings-live)을 읽습니다. 해당 키가 [서버 관리 설정](/docs/ko/server-managed-settings)과 함께 적용되는지 여부는 [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)을 따릅니다. 기본적으로 조직이 서버 관리 키를 제공할 때 세션은 [Claude Code가 모든 관리자 소스에서 읽는 키](/docs/ko/managed-settings#keys-read-from-every-admin-source)(예: `env` 블록, 샌드박스 잠금, 샌드박스 바이너리 경로 및 `forceRemoteSettingsRefresh`)를 제외하고 러너 이미지의 파일을 무시합니다. [설정 우선순위](/docs/ko/settings#settings-precedence)를 참조하십시오.

573 573

574Anthropic의 제어 평면이 세션에 [Claude Code 훅](/docs/ko/hooks)을 제공할 때 러너는 자신의 구성 위에 설치하지 않고 자신의 구성과 함께 설치합니다. Claude Code v2.1.229 이상이 필요합니다.574Anthropic의 제어 평면이 세션에 [Claude Code 훅](/docs/ko/hooks)을 제공할 때 러너는 자신의 구성 위에 설치하지 않고 자신의 구성과 함께 설치합니다. Claude Code v2.1.229 이상이 필요합니다.

575 575

581 581

582호스트의 `~/.claude/`에 대한 러너의 스냅샷에는 `projects/` 디렉토리가 포함되지 않습니다. 자동 메모리의 기본 스토리지 위치는 이 디렉토리 아래에 있습니다. 이곳에 메모리 파일을 넣더라도 러너는 이를 세션으로 시드하지 않으며, 해당 파일로 자동 메모리가 켜지지도 않습니다.582호스트의 `~/.claude/`에 대한 러너의 스냅샷에는 `projects/` 디렉토리가 포함되지 않습니다. 자동 메모리의 기본 스토리지 위치는 이 디렉토리 아래에 있습니다. 이곳에 메모리 파일을 넣더라도 러너는 이를 세션으로 시드하지 않으며, 해당 파일로 자동 메모리가 켜지지도 않습니다.

583 583

584<h3 id="repository-settings-in-sessions-with-several-repositories">

585 여러 저장소가 있는 세션의 저장소 설정

586</h3>

587

588여러 저장소가 있는 세션에서 Claude Code는 세션이 시작되는 디렉토리에서 프로젝트 설정을 읽으므로, 최대 하나의 저장소의 `.claude/settings.json`만 프로젝트 설정으로 적용됩니다. 다른 저장소의 파일에 정의된 훅은 실행되지 않고, 그 안의 거부 규칙은 적용되지 않으며, 해당 `env`도 설정되지 않습니다.

589

590* **기본값인 `--capacity 1`과 기본 제공 체크아웃 사용 시**: 세션은 저장소 목록의 첫 번째 저장소에서 시작됩니다. 해당 저장소의 `.claude/settings.json`이 프로젝트 설정으로 적용되고 `.mcp.json`이 로드되며, 다른 저장소의 파일은 적용되거나 로드되지 않습니다.

591* **1보다 큰 `--capacity` 또는 [`checkout` 훅](#checkout) 사용 시**: 세션은 체크아웃을 포함하는 세션별 디렉토리에서 시작됩니다. 어떤 저장소의 `.claude/settings.json`도 프로젝트 설정으로 적용되지 않고, 어떤 저장소의 `.mcp.json`도 로드되지 않으며, 훅 명령의 [`$CLAUDE_PROJECT_DIR`](/docs/ko/hooks#reference-scripts-by-path)은 체크아웃이 아닌 해당 디렉토리입니다.

592

593각 저장소의 `CLAUDE.md`와 스킬은 세션이 어디에서 시작되든 로드됩니다. 러너는 모든 저장소를 Claude Code에 [추가 디렉토리](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration)로 전달하므로, Claude Code는 각 저장소의 `.claude/settings.json`에서 `enabledPlugins` 및 `extraKnownMarketplaces` 키도 읽습니다.

594

595모든 세션에서 훅을 실행하거나 권한 규칙을 적용하려면 러너 호스트의 `~/.claude/settings.json`에 넣으십시오. 러너는 세션이 어디에서 시작되든 [호스트 파일을 모든 세션으로 시드합니다](#how-each-session’s-config-is-assembled). `Read` 또는 `Edit` 규칙의 경로는 `//` 절대 경로 또는 `~/` 홈 기준 [패턴](/docs/ko/permissions#read-and-edit)으로 작성하십시오. 다른 패턴은 설정 소스 또는 현재 디렉토리를 기준으로 고정되기 때문입니다.

596

584<h3 id="repository-committed-permission-rules">597<h3 id="repository-committed-permission-rules">

585 저장소 커밋된 권한 규칙598 저장소 커밋된 권한 규칙

586</h3>599</h3>

server-managed-settings.md +4 −0

Details

92 92

93 <Step title="저장 및 배포">93 <Step title="저장 및 배포">

94 변경 사항을 저장합니다. Claude Code 클라이언트는 다음 시작 또는 시간별 폴링 주기에 업데이트된 설정을 수신합니다.94 변경 사항을 저장합니다. Claude Code 클라이언트는 다음 시작 또는 시간별 폴링 주기에 업데이트된 설정을 수신합니다.

96 편집기는 Claude Code 설정용으로 게시된 JSON 스키마를 기준으로 JSON을 검사합니다. 구문 분석이 가능한 JSON에서 문제를 발견하면 경고를 표시하고 저장 버튼의 레이블을 변경합니다. 설정이 이미 저장되어 있으면 레이블은 **Update with errors**이고, 아직 저장된 설정이 없으면 **Add with errors**입니다. 스키마 경고는 저장을 차단하지 않으므로 이 버튼으로도 저장됩니다.

98 스키마는 [최신 릴리스보다 늦게 업데이트될 수 있으므로](/docs/ko/settings#edit-a-settings-file) 편집기가 [설정 참조](/docs/ko/settings-reference#all-settings)에 문서화된 키나 값을 문제로 표시할 수 있습니다. Claude Code는 저장된 키와 값을 그대로 받아 로드할 때 [자체 유효성 검사](#invalid-entries-in-delivered-settings)를 실행합니다.

95 </Step>99 </Step>

96</Steps>100</Steps>

97 101

settings.md +15 −15

Details

411 411

412파일 열에서 `~/.claude`는 홈 디렉토리의 `.claude` 폴더이고, 단순 `.claude`는 프로젝트 내부의 `.claude` 폴더입니다.412파일 열에서 `~/.claude`는 홈 디렉터리의 `.claude` 폴더이고, 단순 `.claude`는 프로젝트 내부의 `.claude` 폴더입니다.

413 413

414<span id="where-each-file-applies" />414<span id="where-each-file-applies" />

415 415

428* **`~/.claude/settings.json`**: 머신의 모든 프로젝트, 팀원의 것이나 클라우드 세션의 것은 제외428* **`~/.claude/settings.json`**: 머신의 모든 프로젝트, 팀원의 것이나 클라우드 세션의 것은 제외

429* **`acme-app/.claude/settings.json`**: 사용자의 `acme-app/`. 파일을 버전 제어에 커밋한 경우에만 팀원의 클론과 클라우드 세션에 도달합니다. 커밋하기 전까지는 다른 파일처럼 디스크의 파일이며 다른 사람은 이를 가지지 않습니다.429* **`acme-app/.claude/settings.json`**: 사용자의 `acme-app/`. 파일을 버전 제어에 커밋한 경우에만 팀원의 클론과 클라우드 세션에 도달합니다. 커밋하기 전까지는 다른 파일처럼 디스크의 파일이며 다른 사람은 이를 가지지 않습니다.

430* **`acme-app/.claude/settings.local.json`**: 사용자의 `acme-app/`만. Claude Code는 파일을 처음 작성할 때 전역 git 제외에 추가하므로 커밋에서 제외됩니다. 수동으로 파일을 생성한 경우 [`.gitignore`에 직접 추가](#keep-personal-settings-out-of-a-repository)합니다.430* **`acme-app/.claude/settings.local.json`**: 사용자의 `acme-app/`만. Claude Code는 파일을 처음 작성할 때 전역 git 제외에 추가하므로 커밋에서 제외됩니다. 수동으로 파일을 생성한 경우 [`.gitignore`에 직접 추가](#keep-personal-settings-out-of-a-repository)합니다.

431* **관리되는 설정**, `managed-settings.json` 파일, MDM 정책, 또는 claude.ai 콘솔의 [서버 관리 설정](/docs/ko/server-managed-settings): 조직이 배포하는 모든 머신의 모든 프로젝트, 또는 조직 계정으로 로그인한 모든 머신. 서버 관리 설정만 클라우드 세션에 도달합니다.431* **관리형 설정**, `managed-settings.json` 파일, MDM 정책, 또는 claude.ai 콘솔의 [서버 관리형 설정](/docs/ko/server-managed-settings): 조직이 배포하는 모든 머신의 모든 프로젝트, 또는 조직 계정으로 로그인한 모든 머신. 서버 관리형 설정만 클라우드 세션에 도달합니다.

432 432

433<span id="which-files-you-have" />433<span id="which-files-you-have" />

434 434

443* **사용자** 및 **프로젝트 로컬**: 직접 생성하거나 Claude Code가 생성하도록 합니다. 테마와 같이 사용자 설정에 저장되는 `/config` 메뉴의 옵션을 처음 변경할 때 `~/.claude/settings.json`을 작성하고, Bash 명령에 대해 "Yes, and don't ask again"과 같은 권한 프롬프트에서 처음 승인을 할 때 `.claude/settings.local.json`을 작성합니다. **Show tips**를 포함한 몇 가지 `/config` 옵션은 사용자 파일 대신 `.claude/settings.local.json`에 저장됩니다.443* **사용자** 및 **프로젝트 로컬**: 직접 생성하거나 Claude Code가 생성하도록 합니다. 테마와 같이 사용자 설정에 저장되는 `/config` 메뉴의 옵션을 처음 변경할 때 `~/.claude/settings.json`을 작성하고, Bash 명령에 대해 "Yes, and don't ask again"과 같은 권한 프롬프트에서 처음 승인을 할 때 `.claude/settings.local.json`을 작성합니다. **Show tips**를 포함한 몇 가지 `/config` 옵션은 사용자 파일 대신 `.claude/settings.local.json`에 저장됩니다.

444 444

445<Info>445<Info>

446 Windows에서 `~/.claude`는 `%USERPROFILE%\.claude`를 의미합니다. 홈 디렉토리 파일을 다른 곳에 보관하려면 [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)을 설정합니다. Claude Code는 설정, 세션 기록, 플러그인을 대신 그곳에 저장합니다.446 Windows에서 `~/.claude`는 `%USERPROFILE%\.claude`를 의미합니다. 홈 디렉터리 파일을 다른 곳에 보관하려면 [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)을 설정합니다. Claude Code는 설정, 세션 기록, 플러그인을 대신 그곳에 저장합니다.

447</Info>447</Info>

448 448

449Claude Code는 또한 다섯 번째 파일인 [`~/.claude.json`](/docs/ko/claude-directory#ce-claude-json)을 유지합니다. 이는 Claude Code가 자신을 위해 작성하는 파일이므로 편집할 필요가 없습니다. 로그인 세션, [MCP 서버](/docs/ko/mcp) 구성, 신뢰 결정과 같은 프로젝트별 상태, `/config`가 사용자를 위해 작성하는 [전역 구성 키](/docs/ko/settings-reference#global-config-settings)를 보유합니다.449Claude Code는 또한 다섯 번째 파일인 [`~/.claude.json`](/docs/ko/claude-directory#ce-claude-json)을 유지합니다. 이는 Claude Code가 자신을 위해 작성하는 파일이므로 편집할 필요가 없습니다. 로그인 세션, [MCP 서버](/docs/ko/mcp) 구성, 신뢰 결정과 같은 프로젝트별 상태, `/config`가 사용자를 위해 작성하는 [전역 구성 키](/docs/ko/settings-reference#global-config-settings)를 보유합니다.

486 Claude Code가 git 저장소에서 로컬 파일을 보관하는 위치486 Claude Code가 git 저장소에서 로컬 파일을 보관하는 위치

487</h4>487</h4>

488 488

489Claude가 Bash 명령을 실행할 권한을 요청하고 "Yes, and don't ask again"을 선택하면, Claude Code는 해당 승인을 `.claude/settings.local.json`의 `allow` 규칙으로 저장합니다. git 저장소의 하위 디렉토리에서 Claude Code를 시작하면 저장소 루트에서 해당 파일을 읽고 작성하며 전체 저장소에 승인을 적용합니다. [worktree](/docs/ko/worktrees)에서는 주 체크아웃의 루트에 있는 파일을 사용합니다.489Claude가 Bash 명령을 실행할 권한을 요청하고 "Yes, and don't ask again"을 선택하면, Claude Code는 해당 승인을 `.claude/settings.local.json`의 `allow` 규칙으로 저장합니다. git 저장소의 하위 디렉터리에서 Claude Code를 시작하면 저장소 루트에서 해당 파일을 읽고 작성하며 전체 저장소에 승인을 적용합니다. [worktree](/docs/ko/worktrees)에서는 주 체크아웃의 루트에 있는 파일을 사용합니다.

490 490

491두 가지 규칙이 루트 위치를 한정합니다:491두 가지 규칙이 루트 위치를 한정합니다:

492 492

493* **파일이 `.claude/settings.json` 대신 유지되는 경우**: git 저장소 외부, 저장소 루트가 홈 디렉토리인 경우, Windows에서, 또는 저장소 루트나 `.git` 또는 `.claude` 항목이 사용자가 소유하지 않은 경우.493* **파일이 `.claude/settings.json` 대신 유지되는 경우**: git 저장소 외부, 저장소 루트가 홈 디렉터리인 경우, Windows에서, 또는 저장소 루트나 `.git` 또는 `.claude` 항목이 사용자가 소유하지 않은 경우.

494* **파일의 경로는 저장소 루트에 고정되지 않습니다**: `/`로 시작하거나 상대 샌드박스 경로인 권한 규칙은 [세션의 기본 작업 디렉토리](/docs/ko/permissions#read-and-edit)에 고정됩니다.494* **파일의 경로는 저장소 루트에 고정되지 않습니다**: `/`로 시작하거나 상대 샌드박스 경로인 권한 규칙은 [세션의 기본 작업 디렉터리](/docs/ko/permissions#read-and-edit)에 고정됩니다.

495 495

496v2.1.211 이전에는 Claude Code가 시작 디렉토리에 파일을 보관했습니다. 이전 버전이 루트 파일 옆에 남긴 파일을 여전히 읽습니다. 두 파일이 동일한 키를 설정하는 경우 루트의 값이 적용되고, 두 파일의 권한 규칙이 적용됩니다. Agent SDK의 [`resolveSettings()`](/docs/ko/agent-sdk/typescript#resolvesettings) 헬퍼는 항상 시작 디렉토리에서 파일을 읽습니다.496v2.1.211 이전에는 Claude Code가 시작 디렉터리에 파일을 보관했습니다. 이전 버전이 루트 파일 옆에 남긴 파일을 여전히 읽습니다. 두 파일이 동일한 키를 설정하는 경우 루트의 값이 적용되고, 두 파일의 권한 규칙이 적용됩니다. Agent SDK의 [`resolveSettings()`](/docs/ko/agent-sdk/typescript#resolvesettings) 헬퍼는 항상 시작 디렉터리에서 파일을 읽습니다.

497 497

498Claude Code는 공유 `.claude/settings.json`을 세션의 [기본 작업 디렉토리](/docs/ko/permissions#working-directories)에서 읽으므로, 저장소 루트에 커밋된 파일을 사용하려면 거기서 Claude Code를 시작합니다. [`/cd`로 세션을 이동](/docs/ko/permissions#move-the-session-to-another-directory)한 후, Claude Code는 대신 새 디렉토리에서 두 프로젝트 파일을 읽으며, 로컬 파일을 동일한 규칙으로 배치합니다. 이동한 디렉토리에서 읽으려면 Claude Code v2.1.246 이상이 필요합니다.498Claude Code는 공유 `.claude/settings.json`을 세션의 [기본 작업 디렉터리](/docs/ko/permissions#working-directories)에서 읽으므로, 저장소 루트에 커밋된 파일을 사용하려면 거기서 Claude Code를 시작합니다. [`/cd`로 세션을 이동](/docs/ko/permissions#move-the-session-to-another-directory)한 후, Claude Code는 대신 새 디렉터리에서 두 프로젝트 파일을 읽으며, 로컬 파일을 동일한 규칙으로 배치합니다. 이동한 디렉터리에서 읽으려면 Claude Code v2.1.246 이상이 필요합니다.

499 499

500<span id="managed-settings-delivery" />500<span id="managed-settings-delivery" />

501 501

511 조직이 적용하는 항목 확인511 조직이 적용하는 항목 확인

512</h3>512</h3>

513 513

514조직이 Claude Code를 관리하는 경우, 일부 설정은 사용자를 위해 결정되며 자신의 파일에 입력한 것이 이를 변경하지 않습니다. 어떤 것인지 확인하려면 `/status`를 실행합니다. `Setting sources` 줄은 사용자에게 적용되는 관리되는 소스의 이름을 지정합니다. 관리되는 설정은 이 머신에서 Claude Code가 실행되는 모든 곳에 적용됩니다. [개발자가 변경할 수 있는 항목](/docs/ko/managed-settings#what-a-developer-can-change)은 로컬 관리자 권한 및 Claude Code 이외의 도구를 다룹니다.514조직이 Claude Code를 관리하는 경우, 일부 설정은 사용자를 위해 결정되며 자신의 파일에 입력한 것이 이를 변경하지 않습니다. 어떤 것인지 확인하려면 `/status`를 실행합니다. `Setting sources` 줄은 사용자에게 적용되는 관리형 소스의 이름을 지정합니다. 관리형 설정은 이 머신에서 Claude Code가 실행되는 모든 곳에 적용됩니다. [개발자가 변경할 수 있는 항목](/docs/ko/managed-settings#what-a-developer-can-change)은 로컬 관리자 권한 및 Claude Code 이외의 도구를 다룹니다.

515 515

516관리되는 설정은 관리되는 설정 페이지의 [전달 메커니즘](/docs/ko/managed-settings#delivery-mechanisms)을 통해 사용자에게 도달합니다. 가장 일반적으로:516관리형 설정은 관리형 설정 페이지의 [전달 메커니즘](/docs/ko/managed-settings#delivery-mechanisms)을 통해 사용자에게 도달합니다. 가장 일반적으로:

517 517

518* [서버 관리 설정](/docs/ko/server-managed-settings), Claude Code가 claude.ai 관리 콘솔 또는 자체 호스팅 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)에서 가져옴518* [서버 관리형 설정](/docs/ko/server-managed-settings), Claude Code가 claude.ai 관리 콘솔 또는 자체 호스팅 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)에서 가져옴

519* MDM 또는 OS 수준 정책, 시스템 디렉토리의 `managed-settings.json` 파일519* MDM 또는 OS 수준 정책, 시스템 디렉터리의 `managed-settings.json` 파일

520* Claude Desktop과 같은 임베딩 호스트, SDK `managedSettings` 옵션을 통해. [임베딩 호스트에서 정책 제어](/docs/ko/managed-settings#parent-settings-from-embedding-hosts)를 참조합니다.520* Claude Desktop과 같은 임베딩 호스트, SDK `managedSettings` 옵션을 통해. [임베딩 호스트에서 정책 제어](/docs/ko/managed-settings#parent-settings-from-embedding-hosts)를 참조합니다.

521 521

522Claude Desktop 앱에서 머신에서 실행되는 [Cowork](https://claude.com/docs/cowork/overview) 세션에서, Claude Code는 claude.ai 관리 콘솔에서 서버 관리 설정을 가져오지 않으며, 조직의 Claude Desktop 구성이 `requireCoworkFullVmSandbox`를 설정하지 않는 한 디바이스에 배포된 정책을 읽습니다. [정책이 적용되는 위치 및 시기](/docs/ko/managed-settings#where-and-when-a-policy-applies)는 Cowork 및 클라우드 세션을 다룹니다.522Claude Desktop 앱에서 머신에서 실행되는 [Cowork](https://claude.com/docs/cowork/overview) 세션에서, Claude Code는 claude.ai 관리 콘솔에서 서버 관리형 설정을 가져오지 않으며, 조직의 Claude Desktop 구성이 `requireCoworkFullVmSandbox`를 설정하지 않는 한 디바이스에 배포된 정책을 읽습니다. [정책이 적용되는 위치 및 시기](/docs/ko/managed-settings#where-and-when-a-policy-applies)는 Cowork 및 클라우드 세션을 다룹니다.

523 523

524관리자인 경우, [조직을 위해 Claude Code 설정](/docs/ko/admin-setup)은 적용할 항목 선택을 안내하고, [관리되는 설정 배포](/docs/ko/managed-settings)는 전달 및 정책이 적용 중인지 확인하는 방법을 다룹니다.524관리자인 경우, [조직을 위해 Claude Code 설정](/docs/ko/admin-setup)은 적용할 항목 선택을 안내하고, [관리형 설정 배포](/docs/ko/managed-settings)는 전달 및 정책이 적용 중인지 확인하는 방법을 다룹니다. claude.ai 관리 콘솔의 관리형 설정 편집기에 표시될 수 있는 경고는 [서버 관리형 설정 구성](/docs/ko/server-managed-settings#configure-server-managed-settings)을 참조합니다.

525 525

526<h2 id="change-a-setting">526<h2 id="change-a-setting">

527 설정 변경527 설정 변경

809 809

810[클라우드 세션](/docs/ko/claude-code-on-the-web)은 [클라우드 환경](/docs/ko/cloud-environments)에서 저장소의 신선한 복제본에서 실행되며, 머신에서 실행되지 않습니다. 이는 어느 설정이 도달하는지 변경합니다:810[클라우드 세션](/docs/ko/claude-code-on-the-web)은 [클라우드 환경](/docs/ko/cloud-environments)에서 저장소의 신선한 복제본에서 실행되며, 머신에서 실행되지 않습니다. 이는 어느 설정이 도달하는지 변경합니다:

811 811

812* **공유 프로젝트 설정** (`.claude/settings.json`): 한 저장소가 있는 세션에서 읽습니다. 파일이 복제본의 일부이고 세션이 그 안에서 시작되기 때문입니다. 해당 세션에 적용하려면 설정을 거기에 커밋합니다. 여러 저장소가 있는 세션은 복제본 위에서 시작되고 각 저장소의 `.claude/settings.json`에서 `enabledPlugins` 및 `extraKnownMarketplaces` 키만 읽으며, 권한 규칙, hooks, `env` 또는 기타 키는 읽지 않습니다. 이 두 키가 선언하는 마켓플레이스와 플러그인은 여전히 [클라우드 세션에서 로드되지 않습니다](/docs/ko/cloud-environments#what-carries-over-from-your-setup).812* **공유 프로젝트 설정** (`.claude/settings.json`): 한 저장소가 있는 세션에서 읽습니다. 파일이 복제본의 일부이고 세션이 그 안에서 시작되기 때문입니다. 해당 세션에 적용하려면 설정을 거기에 커밋합니다. Anthropic 호스팅 환경에서 여러 저장소가 있는 세션은 복제본 위에서 시작되고 각 저장소의 `.claude/settings.json`에서 `enabledPlugins` 및 `extraKnownMarketplaces` 키만 읽으며, 권한 규칙, 훅, `env` 또는 기타 키는 읽지 않습니다. 이 두 키가 선언하는 마켓플레이스와 플러그인은 여전히 [클라우드 세션에서 로드되지 않습니다](/docs/ko/cloud-environments#what-carries-over-from-your-setup). 자체 호스팅 환경의 경우 [어느 저장소의 설정이 적용되는지](/docs/ko/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories)를 참조하세요.

813* **사용자 및 프로젝트 로컬 설정** (`~/.claude/settings.json` 및 `.claude/settings.local.json`): 읽지 않습니다. 둘 다 머신에 유지되고 로컬 파일은 복제본에 없습니다.813* **사용자 및 프로젝트 로컬 설정** (`~/.claude/settings.json` 및 `.claude/settings.local.json`): 읽지 않습니다. 둘 다 머신에 유지되고 로컬 파일은 복제본에 없습니다.

814* **관리되는 설정**: 장치의 `managed-settings.json` 파일이나 MDM 프로필은 클라우드 세션에 도달하지 않습니다. 조직의 [서버 관리 설정](/docs/ko/server-managed-settings)은 도달합니다. [표면 범위](/docs/ko/model-config#surface-coverage)는 어느 클라우드 세션이 이를 수신하는지 나열합니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)도 실행기 이미지의 관리되는 설정 파일을 읽습니다. [Claude Code가 관리되는 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 해당 파일이 적용되는 시기를 설명합니다.814* **관리되는 설정**: 장치의 `managed-settings.json` 파일이나 MDM 프로필은 클라우드 세션에 도달하지 않습니다. 조직의 [서버 관리 설정](/docs/ko/server-managed-settings)은 도달합니다. [표면 범위](/docs/ko/model-config#surface-coverage)는 어느 클라우드 세션이 이를 수신하는지 나열합니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)도 실행기 이미지의 관리되는 설정 파일을 읽습니다. [Claude Code가 관리되는 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 해당 파일이 적용되는 시기를 설명합니다.

815* **`/config`**: 브라우저에서 claude.ai/code에서 설정 값을 변경하는 대신 claude.ai 설정의 Claude Code 섹션을 엽니다. 클라우드 세션에 대해 설정을 변경하려면 환경에서 [환경 변수](/docs/ko/cloud-environments#set-environment-variables)를 설정하거나, 한 저장소가 있는 세션에서 해당 저장소의 `.claude/settings.json`에 키를 커밋합니다.815* **`/config`**: 브라우저에서 claude.ai/code에서 설정 값을 변경하는 대신 claude.ai 설정의 Claude Code 섹션을 엽니다. 클라우드 세션에 대해 설정을 변경하려면 환경에서 [환경 변수](/docs/ko/cloud-environments#set-environment-variables)를 설정하거나, 한 저장소가 있는 세션에서 해당 저장소의 `.claude/settings.json`에 키를 커밋합니다.

setup.md +20 −10

Details

638 638

639Claude Code를 제거하려면 설치 방법에 따른 지침을 따르세요. 제거 후에도 `claude`가 계속 실행되면 두 번째 설치 또는 이전 설치 프로그램의 남은 셸 별칭이 있을 가능성이 높습니다. [충돌하는 설치 확인](/docs/ko/troubleshoot-install#check-for-conflicting-installations)을 참조하여 이를 찾아 제거하세요.639Claude Code를 제거하려면 설치 방법에 따른 지침을 따르세요. 제거 후에도 `claude`가 계속 실행되면 두 번째 설치 또는 이전 설치 프로그램의 남은 셸 별칭이 있을 가능성이 높습니다. [충돌하는 설치 확인](/docs/ko/troubleshoot-install#check-for-conflicting-installations)을 참조하여 이를 찾아 제거하세요.

640 640

641<h3 id="native-installation">641<span id="native-installation" />

642 네이티브 설치642

643<h3 id="uninstall-a-native-installation">

644 네이티브 설치 제거

643</h3>645</h3>

644 646

645Claude Code 바이너리 및 버전 파일을 제거하세요:647Claude Code 바이너리 및 버전 파일을 제거하세요:

660 </Tab>662 </Tab>

661</Tabs>663</Tabs>

662 664

663<h3 id="homebrew-installation">665<span id="homebrew-installation" />

664 Homebrew 설치666

667<h3 id="uninstall-with-homebrew">

668 Homebrew로 제거

665</h3>669</h3>

666 670

667설치한 Homebrew cask를 제거하세요. 안정적인 cask를 설치한 경우:671설치한 Homebrew cask를 제거하세요. 안정적인 cask를 설치한 경우:

676brew uninstall --cask claude-code@latest680brew uninstall --cask claude-code@latest

677```681```

678 682

679<h3 id="winget-installation">683<span id="winget-installation" />

680 WinGet 설치684

685<h3 id="uninstall-with-winget">

686 WinGet으로 제거

681</h3>687</h3>

682 688

683WinGet 패키지를 제거하세요:689WinGet 패키지를 제거하세요:

686winget uninstall Anthropic.ClaudeCode692winget uninstall Anthropic.ClaudeCode

687```693```

688 694

689<h3 id="apt-/-dnf-/-apk">695<span id="apt-/-dnf-/-apk" />

690 apt / dnf / apk696

697<h3 id="uninstall-with-apt-dnf-or-apk">

698 apt, dnf 또는 apk로 제거

691</h3>699</h3>

692 700

693패키지 및 저장소 구성을 제거하세요:701패키지 및 저장소 구성을 제거하세요:

716 </Tab>724 </Tab>

717</Tabs>725</Tabs>

718 726

719<h3 id="npm">727<span id="npm" />

720 npm728

729<h3 id="uninstall-with-npm">

730 npm으로 제거

721</h3>731</h3>

722 732

723전역 npm 패키지를 제거하세요:733전역 npm 패키지를 제거하세요:

skills.md +2 −0

Details

94| `migrate` | 기존 Claude API 코드를 최신 모델에 맞게 업데이트 | v2.1.221 이전 |94| `migrate` | 기존 Claude API 코드를 최신 모델에 맞게 업데이트 | v2.1.221 이전 |

95| `upgrade` | 프로젝트의 Anthropic SDK 의존성을 메이저 버전 간에 이전(현재는 Python `anthropic` 패키지를 0.x에서 1.x로) | v2.1.236 이상 |95| `upgrade` | 프로젝트의 Anthropic SDK 의존성을 메이저 버전 간에 이전(현재는 Python `anthropic` 패키지를 0.x에서 1.x로) | v2.1.236 이상 |

96| `managed-agents-onboard` | 새 Managed Agent 생성 과정을 단계별로 안내 | v2.1.221 이전 |96| `managed-agents-onboard` | 새 Managed Agent 생성 과정을 단계별로 안내 | v2.1.221 이전 |

97| `managed-agents-onboard <url>` | [Managed Agents 문서](https://platform.claude.com/docs/en/managed-agents/overview)의 페이지 등 해당 URL의 페이지에 설명된 Managed Agent를 구축 | v2.1.290 이상 |

98| `managed-agents-onboard <quickstart-name>` | `deep-researcher` 등 Console의 빠른 시작 템플릿 중 하나를 구축. 템플릿 이름이 아닌 단어 하나를 입력하면 Claude가 유효한 이름 목록을 표시 | v2.1.290 이상 |

97| `prompt-audit` | 프롬프트, 스킬, 도구 설명에서 이전 모델용으로 작성된 지침에 플래그를 지정하고 수정 사항을 diff로 제안 | v2.1.221 이상 |99| `prompt-audit` | 프롬프트, 스킬, 도구 설명에서 이전 모델용으로 작성된 지침에 플래그를 지정하고 수정 사항을 diff로 제안 | v2.1.221 이상 |

98| `cost-optimize` | 프로젝트의 Claude API 지출이 어디에 쓰이는지 프로파일링하고, 프롬프트 캐싱, 불필요한 입력 및 출력 토큰 줄이기, 배치 처리, effort, 모델 선택 등의 옵션을 통한 절감 방안을 한 번에 하나씩 제안 | v2.1.247 이상 |100| `cost-optimize` | 프로젝트의 Claude API 지출이 어디에 쓰이는지 프로파일링하고, 프롬프트 캐싱, 불필요한 입력 및 출력 토큰 줄이기, 배치 처리, effort, 모델 선택 등의 옵션을 통한 절감 방안을 한 번에 하나씩 제안 | v2.1.247 이상 |

99| `build-eval` | Claude 기반 앱을 위한 평가 세트 구축 | v2.1.259 이상 |101| `build-eval` | Claude 기반 앱을 위한 평가 세트 구축 | v2.1.259 이상 |

sub-agents.md +4 −2

Details

609주 대화의 권한 모드는 Claude Code가 설정한 값을 사용하는지 결정합니다:609주 대화의 권한 모드는 Claude Code가 설정한 값을 사용하는지 결정합니다:

610 610

611* 주 대화가 `bypassPermissions`, `acceptEdits`, 또는 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에 있을 때, 서브에이전트는 동일한 모드에서 실행되고 Claude Code는 설정한 `permissionMode`를 무시합니다. 자동 모드에서, 분류자는 주 대화의 차단 및 허용 규칙으로 서브에이전트의 도구 호출을 평가합니다. 서브에이전트가 완료되면, 분류자는 보고서가 전달되기 전에 작업과 최종 보고서도 검토합니다. [자동 모드가 서브에이전트를 처리하는 방법](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)을 참조하세요.611* 주 대화가 `bypassPermissions`, `acceptEdits`, 또는 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에 있을 때, 서브에이전트는 동일한 모드에서 실행되고 Claude Code는 설정한 `permissionMode`를 무시합니다. 자동 모드에서, 분류자는 주 대화의 차단 및 허용 규칙으로 서브에이전트의 도구 호출을 평가합니다. 서브에이전트가 완료되면, 분류자는 보고서가 전달되기 전에 작업과 최종 보고서도 검토합니다. [자동 모드가 서브에이전트를 처리하는 방법](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)을 참조하세요.

612* 주 대화가 `default`, `dontAsk`, 또는 `plan` 모드에 있을 때, 서브에이전트는 설정한 권한 모드에서 실행됩니다. `bypassPermissions` 제외. `bypassPermissions`를 선언하는 서브에이전트는 주 대화의 모드를 대신 유지합니다. `bypassPermissions` 예외는 Claude Code v2.1.267 이상이 필요합니다.612* 주 대화가 `default`, `dontAsk`, 또는 `plan` 모드일 때, 서브에이전트는 설정한 권한 모드에서 실행됩니다. 다음 경우에는 대신 주 대화의 권한 모드를 유지합니다:

613 * `bypassPermissions`를 설정한 경우. `bypassPermissions` 예외는 Claude Code v2.1.267 이상이 필요합니다.

614 * `auto`를 설정했지만 서브에이전트에서 [자동 모드를 사용할 수 없는](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 경우. 예를 들어 설정 파일이 [`disableAutoMode`](/docs/ko/settings-reference#disableautomode)를 설정했거나 서브에이전트의 모델이 자동 모드를 지원하지 않는 경우입니다.

613 615

614`permissionMode`는 이러한 값을 허용하며, `manual`을 `default`의 별칭으로 허용합니다:616`permissionMode`는 이러한 값을 허용하며, `manual`을 `default`의 별칭으로 허용합니다:

615 617

640Implement API endpoints. Follow the conventions and patterns from the preloaded skills.642Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

641```643```

642 644

643나열된 각 스킬의 전체 내용은 시작 시 서브에이전트의 컨텍스트에 주입됩니다. 이 필드는 서브에이전트가 실행 중에 발견하고 호출할 수 있는 스킬을 제어하지 않습니다. 이 필드는 미리 로드할 스킬을 제어합니다. 이 필드 없이, 서브에이전트는 여전히 실행 중에 스킬 도구를 통해 프로젝트, 사용자, 및 플러그인 스킬을 발견하고 호출할 수 있습니다. 서브에이전트가 스킬을 완전히 호출하지 못하도록 하려면, [`tools`](#available-tools) 목록에서 `Skill`을 생략하거나 `disallowedTools`에 추가하세요.645나열된 각 스킬의 전체 내용은 목록의 처음 32개 고유 이름까지 시작 시 서브에이전트의 컨텍스트에 주입됩니다. 이 필드는 서브에이전트가 접근할 수 있는 스킬이 아니라 미리 로드할 스킬을 제어합니다. 이 필드가 없어도 서브에이전트는 실행 중에 Skill 도구를 통해 프로젝트, 사용자, 및 플러그인 스킬을 발견하고 호출할 수 있습니다. 서브에이전트가 스킬을 아예 호출하지 못하도록 하려면, [`tools`](#available-tools) 목록에서 `Skill`을 생략하거나 `disallowedTools`에 추가하세요.

644 646

645[`disable-model-invocation: true`](/docs/ko/skills#control-who-invokes-a-skill)를 설정한 스킬은 미리 로드할 수 없습니다. 미리 로드는 Claude가 호출할 수 있는 스킬 세트에서 가져오기 때문입니다. 여기에는 Claude가 스스로 실행할 수 없는 번들 `/verify` 스킬도 포함됩니다.647[`disable-model-invocation: true`](/docs/ko/skills#control-who-invokes-a-skill)를 설정한 스킬은 미리 로드할 수 없습니다. 미리 로드는 Claude가 호출할 수 있는 스킬 세트에서 가져오기 때문입니다. 여기에는 Claude가 스스로 실행할 수 없는 번들 `/verify` 스킬도 포함됩니다.

646 648

tools-reference.md +1 −1

Details

666 666

667* WebFetch는 요청을 하기 전에 `localhost` 및 점이 없는 다른 호스트명(예: 베어 인트라넷 이름)을 거부합니다. [반환되는 오류](/docs/ko/errors#webfetch-cannot-fetch-localhost)는 Claude에 Bash를 통해 `curl`로 로컬 서버에 도달하도록 지시합니다.667* WebFetch는 요청을 하기 전에 `localhost` 및 점이 없는 다른 호스트명(예: 베어 인트라넷 이름)을 거부합니다. [반환되는 오류](/docs/ko/errors#webfetch-cannot-fetch-localhost)는 Claude에 Bash를 통해 `curl`로 로컬 서버에 도달하도록 지시합니다.

668* HTTP URL은 자동으로 HTTPS로 업그레이드됩니다.668* HTTP URL은 자동으로 HTTPS로 업그레이드됩니다.

669* 큰 페이지는 처리 전에 고정된 문자 제한으로 잘립니다.669* WebFetch는 호출당 페이지 콘텐츠를 최대 100,000자까지 읽습니다. Claude Code v2.1.290 이상에서는 더 긴 페이지에 대한 결과가 읽지 않은 분량을 Claude에 알려 주므로, Claude가 다음 부분을 가져올 수 있습니다.

670* WebFetch는 기본적으로 각 응답을 15분 동안 캐시하므로, 동일한 URL의 반복된 가져오기가 빠르게 반환됩니다. Claude Code v2.1.233 이상에서는 [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/ko/env-vars#variables)를 설정하여 WebFetch가 각 응답을 유지하는 기간을 변경할 수 있습니다.670* WebFetch는 기본적으로 각 응답을 15분 동안 캐시하므로, 동일한 URL의 반복된 가져오기가 빠르게 반환됩니다. Claude Code v2.1.233 이상에서는 [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/ko/env-vars#variables)를 설정하여 WebFetch가 각 응답을 유지하는 기간을 변경할 수 있습니다.

671* 5분 이내에 다운로드를 완료하지 못한 페이지(WebFetch가 따라가는 모든 리디렉션 포함)는 마감 오류로 실패합니다. Claude Code v2.1.268 이상에서는 [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/ko/env-vars#variables)를 설정하여 제한을 변경하거나, `0`으로 설정하여 제거할 수 있습니다.671* 5분 이내에 다운로드를 완료하지 못한 페이지(WebFetch가 따라가는 모든 리디렉션 포함)는 마감 오류로 실패합니다. Claude Code v2.1.268 이상에서는 [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/ko/env-vars#variables)를 설정하여 제한을 변경하거나, `0`으로 설정하여 제거할 수 있습니다.

672* URL이 다른 호스트로 리디렉션될 때, WebFetch는 원본 URL과 리디렉션 대상을 이름으로 지정하는 텍스트 결과를 반환하고 따라가지 않습니다. 그러면 Claude는 두 번째 WebFetch 호출로 새 URL을 가져옵니다.672* URL이 다른 호스트로 리디렉션될 때, WebFetch는 원본 URL과 리디렉션 대상을 이름으로 지정하는 텍스트 결과를 반환하고 따라가지 않습니다. 그러면 Claude는 두 번째 WebFetch 호출로 새 URL을 가져옵니다.

troubleshoot-install.md +205 −43

Details

6 6

7> Claude Code 설치 또는 로그인 시 command not found, PATH, 권한, 네트워크 및 인증 오류를 수정합니다.7> Claude Code 설치 또는 로그인 시 command not found, PATH, 권한, 네트워크 및 인증 오류를 수정합니다.

8 8

9설치가 실패하거나 로그인할 수 없는 경우 아래에서 오류를 찾으세요. Claude Code가 작동한 후 런타임 문제의 경우 [문제 해결](/docs/ko/troubleshooting)을 참조하세요. 설정이 적용되지 않거나 hooks가 실행되지 않는 등의 구성 문제의 경우 [구성 디버깅](/docs/ko/debug-your-config)을 참조하세요.9설치가 실패하거나 로그인할 수 없는 경우 아래에서 오류를 찾으세요. Claude Code가 작동한 후 런타임 문제의 경우 [문제 해결](/docs/ko/troubleshooting)을 참조하세요. 설정이 적용되지 않거나 훅이 실행되지 않는 등의 구성 문제의 경우 [구성 디버깅](/docs/ko/debug-your-config)을 참조하세요.

10 10

11<h2 id="find-your-error">11<h2 id="find-your-error">

12 오류 찾기12 오류 찾기

17| 표시되는 내용 | 해결책 |17| 표시되는 내용 | 해결책 |

18| :- | :- |18| :- | :- |

19| `command not found: claude` 또는 `'claude' is not recognized` | [PATH 수정](#command-not-found-claude-after-installation) |19| `command not found: claude` 또는 `'claude' is not recognized` | [PATH 수정](#command-not-found-claude-after-installation) |

20| `Native installation exists but ... is not in your PATH` | [설치 디렉터리를 PATH에 추가](#verify-your-path) |

21| `where.exe claude` 실행 시 `INFO: Could not find files for the given pattern(s).` | [Claude Code가 설치되어 있는지 확인](#check-for-conflicting-installations) |

22| `zsh: permission denied: /Users/you/.zshrc` 또는 `bash: /home/you/.bashrc: Permission denied` | [셸 구성 파일을 쓰기 가능하도록 설정](#permission-denied-when-adding-to-your-path) |

20| `syntax error near unexpected token '<'` | [설치 스크립트가 HTML 반환](#install-script-returns-html-instead-of-a-shell-script) |23| `syntax error near unexpected token '<'` | [설치 스크립트가 HTML 반환](#install-script-returns-html-instead-of-a-shell-script) |

24| CMD에서 `< was unexpected at this time` | [설치 스크립트가 HTML 반환](#install-script-returns-html-instead-of-a-shell-script) |

25| `The term 'System.Xml.XmlDocument' is not recognized` | [설치 스크립트가 HTML 반환](#install-script-returns-html-instead-of-a-shell-script) |

21| `curl: (22) The requested URL returned error: 403` | [설치 스크립트가 403 반환](#install-script-returns-html-instead-of-a-shell-script) |26| `curl: (22) The requested URL returned error: 403` | [설치 스크립트가 403 반환](#install-script-returns-html-instead-of-a-shell-script) |

22| `curl: (23)` 또는 `curl: (56) Failure writing output to destination` | [연결성 확인 또는 대체 설치 프로그램 사용](#curl-56-failure-writing-output-to-destination) |27| `curl: (23)` 또는 `curl: (56) Failure writing output to destination` | [연결성 확인 또는 대체 설치 프로그램 사용](#curl-56-failure-writing-output-to-destination) |

29| `Installation was killed before it could finish` | [메모리 확보 후 설치 프로그램 다시 실행](#installation-was-killed-before-it-could-finish) |

24| 설치 중 `Raw mode is not supported` | [설치 프로그램 다시 실행](#raw-mode-is-not-supported-during-install) |30| 설치 중 `Raw mode is not supported` | [설치 프로그램 다시 실행](#raw-mode-is-not-supported-during-install) |

25| 설치 중 `EACCES: permission denied` | [설치 디렉터리의 권한 수정](#permission-errors-during-installation) |31| 설치 중 `EACCES: permission denied` | [설치 디렉터리의 권한 수정](#permission-errors-during-installation) |

26| `TLS connect error` 또는 `SSL/TLS secure channel` | [CA 인증서 업데이트](#tls-or-ssl-connection-errors) |32| `TLS connect error` 또는 `SSL/TLS secure channel` | [CA 인증서 업데이트](#tls-or-ssl-connection-errors) |

33| `CRYPT_E_NO_REVOCATION_CHECK` 또는 `CRYPT_E_REVOCATION_OFFLINE` | [차단된 인증서 해지 확인 우회](#tls-or-ssl-connection-errors) |

27| `Failed to fetch version` 또는 다운로드 서버에 도달할 수 없음 | [네트워크 및 프록시 설정 확인](#check-network-connectivity) |34| `Failed to fetch version` 또는 다운로드 서버에 도달할 수 없음 | [네트워크 및 프록시 설정 확인](#check-network-connectivity) |

35| `The connection dropped while downloading the update` 또는 `Download timed out: exceeded the total deadline` | [업데이트 다시 실행 또는 프록시 설정](#the-connection-dropped-while-downloading-the-update) |

28| `irm is not recognized` 또는 `The token '&&' is not a valid statement separator` | [셸에 맞는 명령 사용](#wrong-install-command-on-windows) |36| `irm is not recognized` 또는 `The token '&&' is not a valid statement separator` | [셸에 맞는 명령 사용](#wrong-install-command-on-windows) |

29| `Cask 'claude-code' is unavailable: No Cask with this name exists` | [Homebrew 업데이트](#homebrew-cask-unavailable-or-outdated) |37| `Cask 'claude-code' is unavailable: No Cask with this name exists` | [Homebrew 업데이트](#homebrew-cask-unavailable-or-outdated) |

38| `Cask 'claude-code@latest' is not installed` | [설치한 cask 업그레이드](#cask-is-not-installed) |

30| `'bash' is not recognized as the name of a cmdlet` | [Windows 설치 프로그램 명령 사용](#wrong-install-command-on-windows) |39| `'bash' is not recognized as the name of a cmdlet` | [Windows 설치 프로그램 명령 사용](#wrong-install-command-on-windows) |

31| `A parameter cannot be found that matches parameter name 'fsSL'` | [Windows 설치 프로그램 명령 사용](#wrong-install-command-on-windows) |40| `A parameter cannot be found that matches parameter name 'fsSL'` | [Windows 설치 프로그램 명령 사용](#wrong-install-command-on-windows) |

32| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [셸 설치](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |41| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [셸 설치](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |

43| `running scripts is disabled on this system` 또는 `PSSecurityException` | [npm shim이 실행되도록 허용](#running-scripts-is-disabled-on-this-system) |52| `running scripts is disabled on this system` 또는 `PSSecurityException` | [npm shim이 실행되도록 허용](#running-scripts-is-disabled-on-this-system) |

44| `Error: claude native binary not installed` | [npm 설치 완료](#native-binary-not-found-after-npm-install) |53| `Error: claude native binary not installed` | [npm 설치 완료](#native-binary-not-found-after-npm-install) |

45| 업데이트 또는 재설치 중 `npm error code ENOTEMPTY` | [남은 패키지 디렉터리 제거](#npm-enotempty-during-update-or-reinstall) |54| 업데이트 또는 재설치 중 `npm error code ENOTEMPTY` | [남은 패키지 디렉터리 제거](#npm-enotempty-during-update-or-reinstall) |

47| Windows에서 설치 명령이 스크립트 텍스트를 인쇄하고 아무것도 설치되지 않음 | [전체 설치 명령 실행](#wrong-install-command-on-windows) |56| Windows에서 설치 명령이 스크립트 텍스트를 인쇄하고 아무것도 설치되지 않음 | [전체 설치 명령 실행](#wrong-install-command-on-windows) |

48| `App unavailable in region` | Claude Code는 귀국에서 사용할 수 없습니다. [지원되는 국가](https://www.anthropic.com/supported-countries)를 참조하세요. |57| `App unavailable in region` | Claude Code는 귀국에서 사용할 수 없습니다. [지원되는 국가](https://www.anthropic.com/supported-countries)를 참조하세요. |

49| `unable to get local issuer certificate` | [회사 CA 인증서 구성](#tls-or-ssl-connection-errors) |58| `unable to get local issuer certificate` | [회사 CA 인증서 구성](#tls-or-ssl-connection-errors) |

50| `OAuth error` 또는 `403 Forbidden` | [인증 수정](#login-and-authentication) |59| `OAuth error` 또는 `403 Forbidden` | [인증 수정](#login-and-authentication) |

51| `Claude Code access has not been granted for this account` | [Claude Code를 포함하는 역할 얻기](#claude-code-access-has-not-been-granted-for-this-account) |60| `Claude Code access has not been granted for this account` | [Claude Code를 포함하는 역할 얻기](#claude-code-access-has-not-been-granted-for-this-account) |

52| 설정 중 `Unable to connect to Anthropic services` | 오류 참조에서 [Anthropic 서비스에 연결할 수 없음](/docs/ko/errors#unable-to-connect-to-anthropic-services)을 참조하세요 |61| 설정 중 `Unable to connect to Anthropic services` | 오류 참조에서 [Anthropic 서비스에 연결할 수 없음](/docs/ko/errors#unable-to-connect-to-anthropic-services)을 참조하세요 |

53| `Could not load the default credentials` 또는 `Could not load credentials from any providers` | [Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry 자격증명](#bedrock-agent-platform-or-foundry-credentials-not-loading) |62| `Could not load the default credentials` 또는 `Could not load credentials from any providers` | [Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry 자격 증명](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

54| `ChainedTokenCredential authentication failed` 또는 `CredentialUnavailableError` | [Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry 자격증명](#bedrock-agent-platform-or-foundry-credentials-not-loading) |63| `ChainedTokenCredential authentication failed` 또는 `CredentialUnavailableError` | [Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry 자격 증명](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

55| `API Error: 500`, `529 Overloaded`, `429` 또는 위에 나열되지 않은 기타 4xx 및 5xx 오류 | [오류 참조](/docs/ko/errors)를 참조하세요 |64| `API Error: 500`, `529 Overloaded`, `429` 또는 위에 나열되지 않은 기타 4xx 및 5xx 오류 | [오류 참조](/docs/ko/errors)를 참조하세요 |

56 65

57문제가 나열되지 않은 경우 아래의 진단 검사를 수행하여 원인을 좁혀보세요.66문제가 나열되지 않은 경우 아래의 진단 검사를 수행하여 원인을 좁혀보세요.

123 PATH 확인132 PATH 확인

124</h3>133</h3>

125 134

126설치가 성공했지만 `claude`를 실행할 때 `command not found` 또는 `not recognized` 오류가 발생하면 설치 디렉토리가 PATH에 없습니다. 셸은 PATH에 나열된 디렉토리에서 프로그램을 검색하고 설치 프로그램은 macOS/Linux에서 `~/.local/bin/claude`에 또는 Windows에서 `%USERPROFILE%\.local\bin\claude.exe`에 `claude`를 배치합니다.135설치가 성공했지만 `claude`를 실행할 때 `command not found` 또는 `not recognized` 오류가 발생하면 설치 디렉터리가 PATH에 없습니다. 셸은 PATH에 나열된 디렉터리에서 프로그램을 검색하고 설치 프로그램은 macOS/Linux에서 `~/.local/bin/claude`에 또는 Windows에서 `%USERPROFILE%\.local\bin\claude.exe`에 `claude`를 배치합니다.

136

137설치 프로그램은 이 경우를 감지하여 출력의 `Setup notes:` 아래에 보고합니다. macOS 및 Linux에서는 `Native installation exists but ~/.local/bin is not in your PATH.`, Windows에서는 `Native installation exists but C:\Users\you\.local\bin is not in your PATH.`가 표시됩니다. 이 메모와 함께 해결 방법을 출력하지만 PATH 자체를 변경하지는 않습니다.

127 138

128<Note>139<Note>

129 [VS Code 확장](/docs/ko/vs-code)은 `claude`를 이 위치에 배치하지 않습니다. 확장 디렉토리 내에 CLI의 개인 복사본을 번들로 제공하며 자체 채팅 패널용으로 사용하고 PATH에 추가하지 않습니다. 확장만 설치한 경우 `~/.local/bin/claude`가 존재하지 않습니다. [독립 실행형 설치](/docs/ko/setup)를 실행하여 터미널에서 `claude`를 사용한 다음 아래를 계속하세요.140 [VS Code 확장](/docs/ko/vs-code)은 `claude`를 이 위치에 배치하지 않습니다. 확장 디렉터리 내에 CLI의 개인 복사본을 번들로 제공하며 자체 채팅 패널용으로 사용하고 PATH에 추가하지 않습니다. 확장만 설치한 경우 `~/.local/bin/claude`가 존재하지 않습니다. [독립 실행형 설치](/docs/ko/setup)를 실행하여 터미널에서 `claude`를 사용한 다음 아래를 계속하세요.

130</Note>141</Note>

131 142

132PATH 항목을 나열하고 `local/bin`을 필터링하여 설치 디렉토리가 PATH에 있는지 확인하세요:143먼저 프로그램이 존재하는지 확인한 다음, 해당 폴더가 PATH에 있는지 확인하세요. PATH 수정은 영구적이므로 한 번만 적용하면 됩니다. 사용 중인 플랫폼의 탭을 선택하고 해당 명령을 실행하세요. macOS 및 Linux에서는 터미널에서, Windows에서는 PowerShell 또는 명령 프롬프트에서 실행합니다.

133 144

134<Tabs>145<Tabs>

135 <Tab title="macOS/Linux">146 <Tab title="macOS/Linux">

147 설치 프로그램이 프로그램을 제자리에 배치했는지 확인하세요:

148

149 ```bash theme={null}

150 ls -la ~/.local/bin/claude

151 ```

152

153 * **`No such file or directory`**: 네이티브 설치가 없습니다. npm, Homebrew 또는 Linux 패키지 관리자 등 다른 방법으로 Claude Code를 설치하지 않았다면 [Claude Code를 설치](/docs/ko/setup#install-claude-code)하세요. 다른 방법으로 설치했다면 [충돌하는 설치 확인](#check-for-conflicting-installations)을 참조하세요.

154 * **파일 목록이 표시됨**: 프로그램이 존재합니다. 다음으로 PATH를 확인하세요.

155

156 PATH 항목을 나열하고 설치 폴더를 필터링하세요:

157

136 ```bash theme={null}158 ```bash theme={null}

137 echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"159 echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

138 ```160 ```

139 161

140 이것이 `/Users/you/.local/bin` 또는 `/home/you/.local/bin`을 인쇄하면 디렉토리가 PATH에 있으므로 [충돌하는 설치 확인](#check-for-conflicting-installations)으로 건너뛸 수 있습니다. 출력이 없으면 셸 구성에 추가하세요.162 이것이 `/Users/you/.local/bin` 또는 `/home/you/.local/bin`을 출력하면 디렉터리가 PATH에 있으므로 [충돌하는 설치 확인](#check-for-conflicting-installations)으로 건너뛸 수 있습니다. 출력이 없으면 사용 중인 셸에 해당하는 두 명령으로 셸 구성에 추가하세요. `echo` 명령은 모든 새 터미널에 적용되도록 설정을 저장하고, `source`는 현재 창에 설정을 적용합니다. `echo` 명령은 성공하면 아무것도 출력하지 않습니다.

141 163

142 macOS의 기본값인 Zsh의 경우:164 macOS의 기본값인 Zsh의 경우:

143 165

162 184

163 또는 터미널을 닫았다가 다시 여세요.185 또는 터미널을 닫았다가 다시 여세요.

164 186

187 `echo` 명령이 `permission denied`를 출력하면 [PATH에 추가할 때 `permission denied`](#permission-denied-when-adding-to-your-path)를 참조하세요.

188

165 fish 또는 Nushell과 같은 다른 셸의 경우 셸의 자체 구성 구문을 사용하여 `~/.local/bin`을 PATH에 추가한 다음 터미널을 다시 시작하세요.189 fish 또는 Nushell과 같은 다른 셸의 경우 셸의 자체 구성 구문을 사용하여 `~/.local/bin`을 PATH에 추가한 다음 터미널을 다시 시작하세요.

166 190

167 수정이 작동했는지 확인하세요:191 수정이 작동했는지 확인하세요:

169 ```bash theme={null}193 ```bash theme={null}

170 claude --version194 claude --version

171 ```195 ```

196

197 `claude`를 여전히 찾을 수 없다면 다음 원인을 확인하세요:

198

199 * **변경 이전에 열린 터미널**: 이미 열려 있던 창은 이전 PATH를 유지하며, 편집기 내부의 터미널은 편집기에서 PATH를 가져옵니다. 새 창을 열거나 편집기를 종료했다가 다시 여세요.

200 * **줄이 저장되지 않음**: 사용 중인 셸의 파일 이름으로 `grep -n '.local/bin' ~/.zshrc`를 실행하세요. 줄이 있으면 줄 번호와 함께 해당 줄을 출력합니다. 아무것도 출력되지 않으면 두 PATH 명령을 다시 실행하세요.

201 * **줄이 다른 셸의 파일에 추가됨**: `echo $0`을 실행하여 사용 중인 셸을 확인한 다음, 해당 셸에 맞는 두 PATH 명령을 실행하세요.

172 </Tab>202 </Tab>

173 203

174 <Tab title="Windows PowerShell">204 <Tab title="Windows PowerShell">

205 설치 프로그램이 프로그램을 제자리에 배치했는지 확인하세요:

206

207 ```powershell theme={null}

208 Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

209 ```

210

211 * **`False`**: 네이티브 설치가 없습니다. npm 또는 WinGet 등 다른 방법으로 Claude Code를 설치하지 않았다면 [Claude Code를 설치](/docs/ko/setup#install-claude-code)하세요. 다른 방법으로 설치했다면 [충돌하는 설치 확인](#check-for-conflicting-installations)을 참조하세요.

212 * **`True`**: 프로그램이 존재합니다. 다음으로 PATH를 확인하세요.

213

214 PATH 항목을 나열하고 설치 폴더를 필터링하세요:

215

175 ```powershell theme={null}216 ```powershell theme={null}

176 $env:PATH -split ';' | Select-String '\.local\\bin'217 $env:PATH -split ';' | Select-String '\.local\\bin'

177 ```218 ```

178 219

179 출력이 없으면 설치 디렉토리를 사용자 PATH에 추가하세요:220 이것이 `C:\Users\you\.local\bin`을 출력하면 디렉터리가 PATH에 있으므로 [충돌하는 설치 확인](#check-for-conflicting-installations)으로 건너뛸 수 있습니다. 출력이 없으면 설치 디렉터리를 사용자 PATH에 추가하세요:

180 221

181 ```powershell theme={null}222 ```powershell theme={null}

182 $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')223 $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')

190 ```powershell theme={null}231 ```powershell theme={null}

191 claude --version232 claude --version

192 ```233 ```

234

235 새 터미널에서도 `claude`를 여전히 찾을 수 없다면 다음 원인을 확인하세요:

236

237 * **터미널이 편집기 내부에서 실행됨**: 편집기에서 PATH를 가져오므로 편집기를 종료했다가 다시 여세요.

238 * **변경 사항이 저장되지 않음**: `[Environment]::GetEnvironmentVariable('PATH', 'User')`를 실행하고 출력된 PATH에서 `.local\bin`을 찾으세요. 없으면 두 명령을 다시 실행하세요.

193 </Tab>239 </Tab>

194 240

195 <Tab title="Windows CMD">241 <Tab title="Windows CMD">

242 설치 프로그램이 프로그램을 제자리에 배치했는지 확인하세요:

243

244 ```batch theme={null}

245 dir "%USERPROFILE%\.local\bin\claude.exe"

246 ```

247

248 * **`File Not Found` 또는 `The system cannot find the path specified.`**: 네이티브 설치가 없습니다. npm 또는 WinGet 등 다른 방법으로 Claude Code를 설치하지 않았다면 [Claude Code를 설치](/docs/ko/setup#install-claude-code)하세요. 다른 방법으로 설치했다면 [충돌하는 설치 확인](#check-for-conflicting-installations)을 참조하세요.

249 * **`claude.exe` 목록이 표시됨**: 프로그램이 존재합니다. 다음으로 PATH를 확인하세요.

250

251 PATH 항목을 나열하고 설치 폴더를 필터링하세요:

252

196 ```batch theme={null}253 ```batch theme={null}

197 echo %PATH% | findstr /i "local\bin"254 echo %PATH% | findstr /i "local\bin"

198 ```255 ```

204 ```batch theme={null}261 ```batch theme={null}

205 claude --version262 claude --version

206 ```263 ```

264

265 새 터미널에서도 `claude`를 여전히 찾을 수 없다면, 편집기 내부의 터미널은 편집기에서 PATH를 가져오므로 편집기도 종료했다가 다시 여세요.

207 </Tab>266 </Tab>

208</Tabs>267</Tabs>

209 268

221 which -a claude280 which -a claude

222 ```281 ```

223 282

224 이것이 아무것도 인쇄하지 않으면 아직 PATH에 `claude`가 없습니다. [PATH 확인](#verify-your-path)으로 돌아가세요.283 이것이 `claude not found`, `no claude in` 줄을 출력하거나 아무것도 출력하지 않으면 PATH에 `claude`가 없습니다. 다음 검사를 통해 설치되어 있는지 여부를 확인할 수 있습니다.

225 284

226 `claude` 바이너리가 올 수 있는 세 위치를 확인하세요. `~/.local/bin/claude`는 네이티브 설치 프로그램이고 `~/.claude/local/`은 Claude Code의 이전 버전에서 생성한 레거시 로컬 npm 설치이며 npm 글로벌 목록은 `-g` 설치를 표시합니다:285 `claude` 바이너리가 올 수 있는 세 위치를 확인하세요. `~/.local/bin/claude`는 네이티브 설치 프로그램이고 `~/.claude/local/`은 Claude Code의 이전 버전에서 생성한 레거시 로컬 npm 설치이며 npm 글로벌 목록은 `-g` 설치를 표시합니다:

227 286

231 290

232 네이티브 설치는 `~/.local/share/claude/versions/`로의 심볼릭 링크를 표시합니다. 이 경로에서 직접 만든 스크립트 또는 심볼릭 링크는 사용자 정의 런처이며, [자동 업데이트는 제자리에 남겨둡니다](/docs/ko/setup#auto-updates).291 네이티브 설치는 `~/.local/share/claude/versions/`로의 심볼릭 링크를 표시합니다. 이 경로에서 직접 만든 스크립트 또는 심볼릭 링크는 사용자 정의 런처이며, [자동 업데이트는 제자리에 남겨둡니다](/docs/ko/setup#auto-updates).

233 292

234 `ls` 명령이 `No such file or directory`를 인쇄하면 오류가 아닙니다. 이는 해당 위치에 아무것도 설치되지 않았음을 의미하므로 다음 검사로 이동하세요.293 `ls` 명령 중 하나가 `No such file or directory`를 출력하면 오류가 아닙니다. 이는 해당 위치에 아무것도 설치되지 않았음을 의미하므로 다음 검사로 이동하세요.

235 294

236 ```bash theme={null}295 ```bash theme={null}

237 ls -la ~/.claude/local/296 ls -la ~/.claude/local/

240 ```bash theme={null}299 ```bash theme={null}

241 npm -g ls @anthropic-ai/claude-code 2>/dev/null300 npm -g ls @anthropic-ai/claude-code 2>/dev/null

242 ```301 ```

302

303 `ls -la ~/.local/bin/claude`가 `No such file or directory`를 출력했다면 네이티브 설치가 없습니다. npm, Homebrew 또는 Linux 패키지 관리자 등 다른 방법으로 Claude Code를 설치하지 않았다면 [Claude Code를 설치](/docs/ko/setup#install-claude-code)하세요. `~/.local/bin/claude`가 존재하지만 `which -a claude`에 나열되지 않았다면 해당 폴더가 PATH에 없는 것입니다. [PATH 확인](#verify-your-path)을 참조하세요.

243 </Tab>304 </Tab>

244 305

245 <Tab title="Windows PowerShell">306 <Tab title="Windows PowerShell">

249 where.exe claude310 where.exe claude

250 ```311 ```

251 312

313 이것이 `INFO: Could not find files for the given pattern(s).`를 출력하면 PATH에 `claude`가 없습니다.

314

252 네이티브 설치 프로그램이 바이너리를 배치했는지 확인하세요:315 네이티브 설치 프로그램이 바이너리를 배치했는지 확인하세요:

253 316

254 ```powershell theme={null}317 ```powershell theme={null}

255 Test-Path "$env:USERPROFILE\.local\bin\claude.exe"318 Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

256 ```319 ```

320

321 * **`True`**: 네이티브 설치가 존재합니다. `where.exe`가 아무것도 찾지 못했다면 해당 폴더가 PATH에 없는 것입니다. [PATH 확인](#verify-your-path)을 참조하세요.

322 * **`False`**: 네이티브 설치가 없습니다. npm 또는 WinGet 등 다른 방법으로 Claude Code를 설치하지 않았다면 [Claude Code를 설치](/docs/ko/setup#install-claude-code)하세요.

257 </Tab>323 </Tab>

258</Tabs>324</Tabs>

259 325

294```360```

295 361

296<h3 id="check-directory-permissions">362<h3 id="check-directory-permissions">

297 디렉토리 권한 확인363 디렉터리 권한 확인

298</h3>364</h3>

299 365

300권한 문제로 실패한 설치는 생성하거나 쓸 수 없었던 경로를 표시합니다. Windows에서는 설치가 `%USERPROFILE%` 아래에 기록되며, 이 위치는 기본적으로 사용자가 쓸 수 있으므로 이 섹션은 거의 적용되지 않습니다.366권한 문제로 실패한 설치는 생성하거나 쓸 수 없었던 경로를 표시합니다. Windows에서는 설치가 `%USERPROFILE%` 아래에 기록되며, 이 위치는 기본적으로 사용자가 쓸 수 있으므로 이 섹션은 거의 적용되지 않습니다.

310 376

311`XDG_DATA_HOME`, `XDG_STATE_HOME` 또는 `XDG_CACHE_HOME`을 설정한 경우 설치는 `~/.local/share`, `~/.local/state`, `~/.cache` 대신 해당 경로를 사용합니다. [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)을 설정한 경우 전역 설정 파일은 홈 디렉터리 대신 해당 디렉터리 아래에 위치합니다.377`XDG_DATA_HOME`, `XDG_STATE_HOME` 또는 `XDG_CACHE_HOME`을 설정한 경우 설치는 `~/.local/share`, `~/.local/state`, `~/.cache` 대신 해당 경로를 사용합니다. [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)을 설정한 경우 전역 설정 파일은 홈 디렉터리 대신 해당 디렉터리 아래에 위치합니다.

312 378

313디렉토리가 쓸 수 있는지 확인하세요:379디렉터리가 쓸 수 있는지 확인하세요:

314 380

315```bash theme={null}381```bash theme={null}

316test -w ~/.local/bin && echo "writable" || echo "not writable"382test -w ~/.local/bin && echo "writable" || echo "not writable"

317test -w ~/.claude && echo "writable" || echo "not writable"383test -w ~/.claude && echo "writable" || echo "not writable"

318```384```

319 385

320디렉토리를 쓸 수 없으면 설치 디렉토리를 만들고 사용자를 소유자로 설정하세요:386디렉터리를 쓸 수 없으면 설치 디렉터리를 만들고 사용자를 소유자로 설정하세요:

321 387

322```bash theme={null}388```bash theme={null}

323sudo mkdir -p ~/.local/bin389sudo mkdir -p ~/.local/bin

368 설치 스크립트가 셸 스크립트 대신 HTML을 반환합니다434 설치 스크립트가 셸 스크립트 대신 HTML을 반환합니다

369</h3>435</h3>

370 436

371설치 명령을 실행할 때 다음 오류 중 하나가 표시될 수 있습니다.437설치 명령이 다운로드한 내용이 설치 스크립트가 아니면 다음 오류 중 하나와 함께 실패합니다.

438

439**Bash 또는 Zsh**: 오류가 반환된 페이지의 첫 줄을 인용합니다.

372 440

373```text theme={null}441```text theme={null}

374bash: line 1: syntax error near unexpected token `<'442bash: line 1: syntax error near unexpected token `<'

375bash: line 1: `<!DOCTYPE html>'443bash: line 1: `<!DOCTYPE html>'

376```444```

377 445

378PowerShell에서는 동일한 문제가 반환된 페이지를 가리키는 구문 분석 오류로 나타나며, `iex`가 HTML과 CSS를 PowerShell로 실행하려고 시도합니다.446**PowerShell, 구문 분석 오류**: 오류가 반환된 페이지를 가리키며, `iex`가 HTML과 CSS를 PowerShell로 실행하려고 시도합니다.

379 447

380```text theme={null}448```text theme={null}

381iex : At line:1 char:2310449iex : At line:1 char:2310

386 454

387표현은 PowerShell 버전과 시스템 언어에 따라 다릅니다. `Missing expression after unary operator '--'` 또는 `ParserError`와 함께 `ParseException`이 표시될 수 있습니다. 인용된 텍스트의 HTML 태그 또는 CSS는 이 오류를 식별합니다. `-OutFile install.ps1`로 다운로드하면 저장된 파일도 동일한 웹 페이지이므로 도움이 되지 않습니다.455표현은 PowerShell 버전과 시스템 언어에 따라 다릅니다. `Missing expression after unary operator '--'` 또는 `ParserError`와 함께 `ParseException`이 표시될 수 있습니다. 인용된 텍스트의 HTML 태그 또는 CSS는 이 오류를 식별합니다. `-OutFile install.ps1`로 다운로드하면 저장된 파일도 동일한 웹 페이지이므로 도움이 되지 않습니다.

388 456

389요청이 라우팅된 방식에 따라 HTML 본문이 없는 403이 표시될 수 있습니다.457**PowerShell, `System.Xml.XmlDocument`**: 오류가 페이지를 인용하는 대신 이 타입의 이름을 표시합니다.

458

459```text theme={null}

460System.Xml.XmlDocument : The term 'System.Xml.XmlDocument' is not recognized as the name of a cmdlet, function, script

461file, or operable program.

462```

463

464`irm`이 응답을 XML로 구문 분석할 수 있으면 텍스트 대신 XML 객체를 반환하고, `iex`는 해당 객체의 타입 이름을 명령으로 실행하려고 시도합니다. 설치 스크립트는 PowerShell 코드이며 XML로 구문 분석되지 않으므로, 이 오류 역시 응답이 스크립트가 아닌 다른 것이었음을 의미합니다. 타입 이름 주변의 표현은 PowerShell 버전과 시스템 언어에 따라 다르지만 `System.Xml.XmlDocument` 자체는 동일하게 유지되므로 타입 이름으로 식별합니다.

465

466**CMD**: 다음 오류가 표시되고 그 뒤에 반환된 페이지의 HTML이 이어집니다.

467

468```text theme={null}

469< was unexpected at this time.

470

471C:\Users\you><!DOCTYPE html>...

472```

473

474첫 줄은 시스템 언어로 표시되므로 그 뒤에 이어지는 HTML을 확인합니다.

475

476**페이지 없는 403**: 요청이 라우팅된 방식에 따라 curl이 HTML 본문 없이 403 상태를 보고할 수 있습니다.

390 477

391```text theme={null}478```text theme={null}

392curl: (22) The requested URL returned error: 403479curl: (22) The requested URL returned error: 403

393```480```

394 481

395이 모든 경우는 설치 URL이 설치 스크립트 대신 HTML 페이지 또는 오류 상태를 반환했음을 의미합니다. HTML 페이지에 "App unavailable in region"이라고 표시되면 Claude Code를 사용할 수 없는 국가입니다. [지원되는 국가](https://www.anthropic.com/supported-countries)를 참조하세요.482이 모든 경우는 설치 URL이 설치 스크립트 대신 웹 페이지, XML 문서 또는 오류 상태를 반환했음을 의미합니다. 오류 출력에 "App unavailable in region"이 인용되어 있으면 Claude Code를 사용할 수 없는 국가입니다. [지원되는 국가](https://www.anthropic.com/supported-countries)를 참조하세요.

396 483

397본문이 없는 단순 403은 동일한 원인을 가질 수 있지만 회사 프록시 또는 방화벽이 다운로드를 차단할 수도 있습니다. 지원되는 국가에 있는데도 403이 표시되면 아래의 대체 설치 프로그램을 시도하기 전에 [네트워크 연결 확인](#check-network-connectivity)을 진행하세요. 대체 설치 프로그램도 동일한 호스트에 도달하기 때문입니다.484본문이 없는 단순 403은 동일한 원인을 가질 수 있지만 회사 프록시 또는 방화벽이 다운로드를 차단할 수도 있습니다. 지원되는 국가에 있는데도 403이 표시되면 아래의 대체 설치 프로그램을 시도하기 전에 [네트워크 연결 확인](#check-network-connectivity)을 진행하세요. 대체 설치 프로그램도 동일한 호스트에 도달하기 때문입니다.

398 485

400 487

401**해결 방법:**488**해결 방법:**

402 489

4031. **대체 설치 방법 사용**:4901. **몇 분 후 다시 시도합니다**: 이 문제는 종종 일시적입니다. 기다렸다가 원래 명령을 다시 시도합니다.

491

4922. **대체 설치 방법 사용**: 네이티브 설치와 달리 Homebrew 또는 WinGet 설치는 [기본적으로 자동 업데이트되지 않습니다](/docs/ko/setup#auto-updates).

404 493

405 macOS에서는 Homebrew를 통해 설치합니다.494 macOS에서는 Homebrew를 통해 설치합니다.

406 495

416 505

417 그런 다음 `claude --version`을 실행하여 확인합니다. 명령은 `2.1.211 (Claude Code)`와 같은 버전 번호를 출력합니다. 셸에서 `claude`를 찾을 수 없다고 보고하면 새 터미널 창을 열고 다시 시도합니다. 설치한 세션은 이전 `PATH`를 유지합니다.506 그런 다음 `claude --version`을 실행하여 확인합니다. 명령은 `2.1.211 (Claude Code)`와 같은 버전 번호를 출력합니다. 셸에서 `claude`를 찾을 수 없다고 보고하면 새 터미널 창을 열고 다시 시도합니다. 설치한 세션은 이전 `PATH`를 유지합니다.

418 507

4192. **몇 분 후 다시 시도합니다**: 이 문제는 종종 일시적입니다. 기다렸다가 원래 명령을 다시 시도합니다.

~~420~~

421<h3 id="command-not-found-claude-after-installation">508<h3 id="command-not-found-claude-after-installation">

422 설치 후 `command not found: claude`509 설치 후 `command not found: claude`

423</h3>510</h3>

435 522

436그 외의 경우 각 플랫폼의 수정 방법은 [PATH 확인](#verify-your-path)을 참조하세요.523그 외의 경우 각 플랫폼의 수정 방법은 [PATH 확인](#verify-your-path)을 참조하세요.

437 524

525<h3 id="permission-denied-when-adding-to-your-path">

526 PATH에 추가할 때 `permission denied`

527</h3>

528

529`~/.local/bin`을 PATH에 추가하는 `echo` 명령이 `zsh: permission denied: /Users/you/.zshrc` 또는 `bash: /home/you/.bashrc: Permission denied`를 출력하면 현재 사용자가 해당 파일에 쓸 수 없으며 아무것도 저장되지 않은 것입니다. 터미널에서 `~/.zshrc` 대신 사용 중인 셸의 파일 이름을 사용하여 파일 소유자를 확인합니다.

530

531```bash theme={null}

532ls -l ~/.zshrc

533```

534

535출력의 세 번째 필드가 소유자입니다.

536

537* **소유자가 `root`와 같은 다른 사용자인 경우**: 관리자 권한이 필요한 `sudo chown $(whoami) ~/.zshrc`로 소유권을 가져옵니다.

538* **소유자가 본인인 경우**: 파일이 읽기 전용입니다. `chmod u+w ~/.zshrc`로 쓰기 가능하게 만듭니다.

539

540그런 다음 [PATH 확인](#verify-your-path)에 있는 해당 셸용 PATH 명령 두 개를 다시 실행합니다.

541

438<h3 id="curl-56-failure-writing-output-to-destination">542<h3 id="curl-56-failure-writing-output-to-destination">

439 `curl: (56) Failure writing output to destination`543 `curl: (56) Failure writing output to destination`

440</h3>544</h3>

456 560

457Homebrew가 예상보다 오래된 Claude Code 버전을 설치하면 동일한 오래된 인덱스가 보통 원인입니다. `claude-code` cask는 안정 채널을 추적하며 보통 최신 릴리스보다 약 1주일 뒤떨어져 있습니다. 최신 버전을 원하면 `brew install --cask claude-code@latest`를 대신 실행합니다. 두 cask의 차이점은 [릴리스 채널 구성](/docs/ko/setup#configure-release-channel)을 참조하세요.561Homebrew가 예상보다 오래된 Claude Code 버전을 설치하면 동일한 오래된 인덱스가 보통 원인입니다. `claude-code` cask는 안정 채널을 추적하며 보통 최신 릴리스보다 약 1주일 뒤떨어져 있습니다. 최신 버전을 원하면 `brew install --cask claude-code@latest`를 대신 실행합니다. 두 cask의 차이점은 [릴리스 채널 구성](/docs/ko/setup#configure-release-channel)을 참조하세요.

458 562

563<h3 id="cask-is-not-installed">

564 `Cask 'claude-code@latest' is not installed`

565</h3>

566

567Homebrew는 `claude-code`와 `claude-code@latest` 두 가지 cask를 제공합니다. 설치된 cask가 `claude-code@latest`가 아닌데 `brew upgrade --cask claude-code@latest`를 실행하면 `Error: Cask 'claude-code@latest' is not installed.`가 출력됩니다. 어떤 cask가 설치되어 있는지 확인하려면 터미널에서 다음을 실행합니다.

568

569```bash theme={null}

570brew list --cask | grep claude-code

571```

572

573출력된 cask를 업그레이드합니다. 아무것도 출력되지 않으면 두 cask 모두 설치되어 있지 않은 것입니다.

574

459<h3 id="tls-or-ssl-connection-errors">575<h3 id="tls-or-ssl-connection-errors">

460 TLS 또는 SSL 연결 오류576 TLS 또는 SSL 연결 오류

461</h3>577</h3>

467* PowerShell의 `Could not create SSL/TLS secure channel`583* PowerShell의 `Could not create SSL/TLS secure channel`

468* PowerShell의 `Could not establish trust relationship for the SSL/TLS secure channel`584* PowerShell의 `Could not establish trust relationship for the SSL/TLS secure channel`

469 585

586`CRYPT_E_NO_REVOCATION_CHECK` 또는 `CRYPT_E_REVOCATION_OFFLINE`의 경우 4단계로 이동합니다.

587

470**해결 방법:**588**해결 방법:**

471 589

4721. **시스템 CA 인증서 업데이트**:5901. **시스템 CA 인증서 업데이트**:

479 597

480 macOS에서는 시스템 curl이 Keychain 신뢰 저장소를 사용합니다. macOS 자체를 업데이트하면 루트 인증서가 업데이트됩니다.598 macOS에서는 시스템 curl이 Keychain 신뢰 저장소를 사용합니다. macOS 자체를 업데이트하면 루트 인증서가 업데이트됩니다.

481 599

4822. **Windows에서 설치 프로그램을 실행하기 전에 PowerShell에서 TLS 1.2 활성화**:6002. **Windows PowerShell 5.1에서 TLS 1.2 활성화**:

483 ```powershell theme={null}601 ```powershell theme={null}

484 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12602 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

603 ```

604 그런 다음 같은 창에서 설치 프로그램을 실행합니다.

605 ```powershell theme={null}

485 irm https://claude.ai/install.ps1 | iex606 irm https://claude.ai/install.ps1 | iex

486 ```607 ```

487 608

537 658

538설치 프로그램이 다운로드 서버에 도달할 수 없습니다. 이는 보통 `downloads.claude.ai`가 네트워크에서 차단되었음을 의미합니다. [네트워크 연결 확인](#check-network-connectivity)을 참조하세요.659설치 프로그램이 다운로드 서버에 도달할 수 없습니다. 이는 보통 `downloads.claude.ai`가 네트워크에서 차단되었음을 의미합니다. [네트워크 연결 확인](#check-network-connectivity)을 참조하세요.

539 660

661<h3 id="the-connection-dropped-while-downloading-the-update">

662 The connection dropped while downloading the update

663</h3>

664

665`claude install` 또는 `claude update`가 Claude Code 바이너리를 가져오는 동안 다운로드 서버와의 연결이 끊겼고 재시도로도 복구되지 않았습니다. Claude Code는 연결이 끊기거나, 전송이 멈추거나, 다운로드된 파일이 체크섬 검증에 실패하면 총 세 번까지 다운로드를 재시도합니다. 404와 같이 완료된 HTTP 오류는 서버가 이미 응답했으므로 재시도하지 않습니다. v2.1.202 이전에는 연결이 한 번만 끊겨도 재시도하지 않고 단순한 `aborted` 오류와 함께 다운로드가 즉시 실패했습니다.

666

667```text theme={null}

668The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

669```

670

671괄호 안의 텍스트는 어느 시도가 실패했는지와 기본 네트워크 오류를 나타냅니다. `claude update`는 이 메시지 앞에 stderr로 `Error: Failed to install native update`를 출력합니다.

672

673연결은 유지되지만 10분 이내에 완료되지 않는 다운로드는 대신 `Download timed out: exceeded the total deadline`으로 실패합니다. 기한 내에 완료하기에 너무 느린 연결은 즉시 재시도해도 완료되지 않으므로 Claude Code는 시간 초과된 다운로드를 재시도하지 않습니다. 아래 단계는 두 메시지 모두에 적용됩니다.

674

675프록시 또는 게이트웨이는 긴 전송을 완료되기 전에 닫을 수 있으며, Claude Code 바이너리는 용량이 큰 다운로드입니다.

676

677**해결 방법:**

678

679* `claude update`를 다시 실행합니다. 그 외에는 정상적인 네트워크라면 보통 다음 실행에서 다운로드가 성공합니다. 시간 초과 메시지의 경우 더 빠르거나 제한이 덜한 네트워크에서 다시 실행합니다.

680* 네트워크에 프록시가 필요한 경우 설치 프로그램 또는 `claude update`를 실행하기 전에 `HTTPS_PROXY`를 설정합니다. [네트워크 연결 확인](#check-network-connectivity)을 참조하세요.

681* 회사 프록시가 계속 전송을 닫는 경우 네트워크 팀에 `downloads.claude.ai`로부터의 전체 다운로드를 허용하도록 요청합니다. [네트워크 액세스 요구 사항](/docs/ko/network-config#network-access-requirements)을 참조하세요.

682* 셸에서 `claude doctor`를 실행하여 설치 진단을 확인합니다

683

540<h3 id="wrong-install-command-on-windows">684<h3 id="wrong-install-command-on-windows">

541 Windows에서 잘못된 설치 명령685 Windows에서 잘못된 설치 명령

542</h3>686</h3>

543 687

544`'irm' is not recognized`, `The token '&&' is not a valid statement separator`, `A parameter cannot be found that matches parameter name 'fsSL'` 또는 `'bash' is not recognized as the name of a cmdlet`이 표시되면 다른 셸 또는 운영 체제의 설치 명령을 복사했습니다. 명령이 스크립트의 텍스트를 출력하면 일부만 실행했습니다.688`'irm' is not recognized`, `The token '&&' is not a valid statement separator`, `A parameter cannot be found that matches parameter name 'fsSL'` 또는 `'bash' is not recognized as the name of a cmdlet`이 표시되면 다른 셸 또는 운영 체제의 설치 명령을 복사했습니다. 명령이 아무것도 설치하지 않고 스크립트의 텍스트를 출력하면 일부만 실행했습니다.

545 689

546* **`irm` not recognized**: CMD에 있으며 PowerShell이 아닙니다. 두 가지 옵션이 있습니다.690* **`irm` not recognized**: CMD에 있으며 PowerShell이 아닙니다. 두 가지 옵션이 있습니다.

547 691

572 irm https://claude.ai/install.ps1 | iex716 irm https://claude.ai/install.ps1 | iex

573 ```717 ```

574 718

575* **명령이 스크립트 텍스트를 출력합니다**: 실행하는 부분 없이 명령의 다운로드 절반만 실행했습니다. `irm https://claude.ai/install.ps1`은 단독으로 다운로드된 스크립트를 터미널에 출력합니다. `iex`로 파이프하여 실행합니다.719* **명령이 설치하지 않고 스크립트 텍스트를 출력합니다**: 실행하는 부분 없이 명령의 다운로드 절반만 실행했습니다. `irm https://claude.ai/install.ps1`은 단독으로 다운로드된 스크립트를 터미널에 출력합니다. `iex`로 파이프하여 실행합니다.

576 720

577 ```powershell theme={null}721 ```powershell theme={null}

578 irm https://claude.ai/install.ps1 | iex722 irm https://claude.ai/install.ps1 | iex

628 772

629터미널이 Windows에서 Claude Code가 업데이트된 직후 `'claude' is not recognized`를 보고하면 `%USERPROFILE%\.local\bin`에 여전히 `claude.exe`가 포함되어 있는지 확인합니다. 해당 디렉터리가 PATH에 전혀 없으면 대신 [PATH 확인](#verify-your-path)을 참조하세요. Windows에서 업데이트하려면 Claude Code가 기존 `claude.exe`를 백업으로 이름을 바꾸고 새 버전을 제자리에 이동합니다. 새 버전을 제자리에 이동하지 못하고 Claude Code가 백업을 다시 이름을 바꿀 수도 없으면 디렉터리는 백업을 유지하지만 `claude.exe`가 없습니다.773터미널이 Windows에서 Claude Code가 업데이트된 직후 `'claude' is not recognized`를 보고하면 `%USERPROFILE%\.local\bin`에 여전히 `claude.exe`가 포함되어 있는지 확인합니다. 해당 디렉터리가 PATH에 전혀 없으면 대신 [PATH 확인](#verify-your-path)을 참조하세요. Windows에서 업데이트하려면 Claude Code가 기존 `claude.exe`를 백업으로 이름을 바꾸고 새 버전을 제자리에 이동합니다. 새 버전을 제자리에 이동하지 못하고 Claude Code가 백업을 다시 이름을 바꿀 수도 없으면 디렉터리는 백업을 유지하지만 `claude.exe`가 없습니다.

630 774

631백업은 `claude.exe.old.` 다음에 숫자 타임스탬프가 오는 이름으로 시작하는 동일한 디렉토리의 파일입니다. PowerShell에서 다음을 실행하여 최신 백업을 `claude.exe`로 이름을 바꿉니다.775백업은 `claude.exe.old.` 다음에 숫자 타임스탬프가 오는 이름으로 시작하는 동일한 디렉터리의 파일입니다. PowerShell에서 다음을 실행하여 최신 백업을 `claude.exe`로 이름을 바꿉니다.

632 776

633```powershell theme={null}777```powershell theme={null}

682 826

6833. **가능하면 더 큰 인스턴스 사용**. Claude Code는 최소 4GB의 RAM이 필요합니다.8273. **가능하면 더 큰 인스턴스 사용**. Claude Code는 최소 4GB의 RAM이 필요합니다.

684 828

829<h3 id="installation-was-killed-before-it-could-finish">

830 Installation was killed before it could finish

831</h3>

832

833설치 스크립트는 `claude install` 단계가 시그널로 종료되면 이를 보고합니다. Linux에서 종료 코드 137은 프로세스가 SIGKILL을 받았음을 의미하며, 메모리가 부족한 호스트에서는 보통 커널의 OOM(메모리 부족) 킬러가 원인입니다. 스크립트는 다음 설명을 출력하고 코드 137로 종료합니다.

834

835```text theme={null}

836Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.

837Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

838```

839

840그 외의 치명적인 시그널이나 macOS의 종료 코드 137의 경우, 스크립트는 실제 종료 코드와 함께 `Installation was killed before it could finish (exit code <N>)`를 출력하고 메모리 부족 설명은 생략합니다. 이 메시지는 macOS와 Linux에서 사용하는 설치 스크립트에서 출력되며, WSL 내부의 설치도 여기에 포함됩니다. 네이티브 Windows 설치 스크립트는 이 메시지를 출력하지 않습니다. v2.1.200 이전에는 스크립트가 셸의 단순한 `Killed` 줄만 남기고 종료되었습니다.

841

842**해결 방법:**

843

844* 다른 프로세스를 중지하여 메모리를 확보한 다음 설치 프로그램을 다시 실행합니다

845* 스왑 공간을 추가하거나 더 큰 인스턴스로 이동합니다. 스왑 파일 명령은 [메모리 부족 Linux 서버에서 설치 중단](#install-killed-on-low-memory-linux-servers)을 참조하세요.

846

685<h3 id="install-hangs-in-docker">847<h3 id="install-hangs-in-docker">

686 Docker에서 설치 중단848 Docker에서 설치 중단

687</h3>849</h3>

690 852

691**해결 방법:**853**해결 방법:**

692 854

6931. **설치 프로그램을 실행하기 전에 작업 디렉토리 설정**. `/`에서 실행하면 설치 프로그램이 전체 파일 시스템을 스캔하여 과도한 메모리 사용을 유발합니다. `WORKDIR`을 설정하면 스캔이 작은 디렉토리로 제한됩니다.8551. **설치 프로그램을 실행하기 전에 작업 디렉터리 설정**. `/`에서 실행하면 설치 프로그램이 전체 파일 시스템을 스캔하여 과도한 메모리 사용을 유발합니다. `WORKDIR`을 설정하면 스캔이 작은 디렉터리로 제한됩니다.

694 ```dockerfile theme={null}856 ```dockerfile theme={null}

695 WORKDIR /tmp857 WORKDIR /tmp

696 RUN curl -fsSL https://claude.ai/install.sh | bash858 RUN curl -fsSL https://claude.ai/install.sh | bash

702 설치 중 `Raw mode is not supported`864 설치 중 `Raw mode is not supported`

703</h3>865</h3>

704 866

705조직의 [서버 관리 설정](/docs/ko/server-managed-settings)에 [보안 승인](/docs/ko/server-managed-settings#security-approval-dialogs)이 필요한 변경 사항이 포함되어 있으면 v2.1.246 이전의 Claude Code 버전은 `claude install` 중에 승인 대화 상자를 표시하려고 시도합니다. 대화 상자는 stdin의 터미널이 필요합니다. 설치 프로그램이 `curl -fsSL https://claude.ai/install.sh | bash`처럼 파이프에서 `claude install`을 실행하면 stdin은 터미널이 아닌 파이프이므로 설치가 `Raw mode is not supported`를 포함하는 오류로 실패합니다.867조직의 [서버 관리 설정](/docs/ko/server-managed-settings)에 [보안 승인](/docs/ko/server-managed-settings#security-approval-dialogs)이 필요한 변경 사항이 포함되어 있으면 2.1.246 이전의 Claude Code 버전은 `claude install` 중에 승인 대화 상자를 표시하려고 시도합니다. 대화 상자는 stdin의 터미널이 필요합니다. 설치 프로그램이 `curl -fsSL https://claude.ai/install.sh | bash`처럼 파이프에서 `claude install`을 실행하면 stdin은 터미널이 아닌 파이프이므로 설치가 `Raw mode is not supported`를 포함하는 오류로 실패합니다.

706 868

707Claude Code v2.1.246 이상은 `claude install` 또는 `claude update` 중에 대화 상자를 표시하지 않습니다. 명령은 마지막으로 승인한 설정으로 실행되며 Claude Code는 다음 대화형 세션에서 대화 상자를 표시합니다. 조직의 시작 구성이 [설정 가져오기를 기다리는](/docs/ko/server-managed-settings#enforce-fail-closed-startup) 경우(예: `forceRemoteSettingsRefresh`를 설정할 때) 대화 상자는 여전히 이러한 명령 중에 나타나며 파이프에서 실행되는 설치는 여전히 실패합니다.869Claude Code v2.1.246 이상은 `claude install` 또는 `claude update` 중에 대화 상자를 표시하지 않습니다. 명령은 마지막으로 승인한 설정으로 실행되며 Claude Code는 다음 대화형 세션에서 대화 상자를 표시합니다. 조직의 시작 구성이 [설정 가져오기를 기다리는](/docs/ko/server-managed-settings#enforce-fail-closed-startup) 경우(예: `forceRemoteSettingsRefresh`를 설정할 때) 대화 상자는 여전히 이러한 명령 중에 나타나며 파이프에서 실행되는 설치는 여전히 실패합니다.

708 870

728 `claude update` 또는 `claude doctor` 중단890 `claude update` 또는 `claude doctor` 중단

729</h3>891</h3>

730 892

731`claude update` 및 `claude doctor`는 셸 구성 파일에서 오래된 `claude` 별칭을 스캔합니다. `~/.zshrc`, `~/.bashrc` 및 `~/.config/fish/config.fish`, macOS에서는 존재하는 `~/.bash_profile`, `~/.bash_login` 또는 `~/.profile` 중 첫 번째입니다. `ZDOTDIR`을 설정하면 Zsh 파일은 `$ZDOTDIR/.zshrc`입니다. 이러한 경로 중 하나가 디렉토리인 경우 Claude Code는 이를 건너뛰고 두 명령 모두 정상적으로 완료됩니다. v2.1.214 이전에는 이러한 경로의 디렉토리가 두 명령을 중단하게 했으며 `/status`의 System diagnostics 섹션을 비워 두었습니다. `claude doctor`는 출력 없이 중단되었습니다. `claude update`는 `Checking for updates`를 출력한 직후 중단되었습니다.893`claude update` 및 `claude doctor`는 셸 설정 파일에서 오래된 `claude` 별칭을 스캔합니다. `~/.zshrc`, `~/.bashrc` 및 `~/.config/fish/config.fish`, macOS에서는 존재하는 `~/.bash_profile`, `~/.bash_login` 또는 `~/.profile` 중 첫 번째입니다. `ZDOTDIR`을 설정하면 Zsh 파일은 `$ZDOTDIR/.zshrc`입니다. 이러한 경로 중 하나가 디렉터리인 경우 Claude Code는 이를 건너뛰고 두 명령 모두 정상적으로 완료됩니다. v2.1.214 이전에는 이러한 경로의 디렉터리가 두 명령을 중단하게 했으며 `/status`의 System diagnostics 섹션을 비워 두었습니다. `claude doctor`는 출력 없이 중단되었습니다. `claude update`는 `Checking for updates`를 출력한 직후 중단되었습니다.

732 894

733이전 버전에서 중단이 발생하면 디렉토리를 찾습니다. 이 명령의 출력에서 `d`로 시작하는 줄은 해당 경로를 디렉토리로 표시합니다. `No such file or directory` 줄은 해당 경로에 아무것도 없으며 원인이 아님을 의미합니다.895이전 버전에서 중단이 발생하면 디렉터리를 찾습니다. 이 명령의 출력에서 `d`로 시작하는 줄은 해당 경로를 디렉터리로 표시합니다. `No such file or directory` 줄은 해당 경로에 아무것도 없으며 원인이 아님을 의미합니다.

734 896

735```bash theme={null}897```bash theme={null}

736ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish898ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish

737```899```

738 900

739디렉토리를 옆으로 이동하거나 v2.1.214 이상으로 업데이트합니다. `claude update`는 영향을 받는 버전에서 중단되므로 [설치 스크립트](/docs/ko/setup#install-claude-code)를 다시 실행하여 업데이트합니다.901디렉터리를 옆으로 이동하거나 v2.1.214 이상으로 업데이트합니다. `claude update`는 영향을 받는 버전에서 중단되므로 [설치 스크립트](/docs/ko/setup#install-claude-code)를 다시 실행하여 업데이트합니다.

740 902

741<h3 id="claude-desktop-overrides-the-claude-command-on-windows">903<h3 id="claude-desktop-overrides-the-claude-command-on-windows">

742 Claude Desktop이 Windows에서 `claude` 명령을 재정의합니다904 Claude Desktop이 Windows에서 `claude` 명령을 재정의합니다

743</h3>905</h3>

744 906

745이전 버전의 Claude Desktop을 설치했으면 `WindowsApps` 디렉토리에 `Claude.exe`를 등록할 수 있으며, 이는 Claude Code CLI보다 PATH 우선 순위를 가집니다. `claude`를 실행하면 CLI 대신 Desktop 앱이 열립니다.907이전 버전의 Claude Desktop을 설치했으면 `WindowsApps` 디렉터리에 `Claude.exe`를 등록할 수 있으며, 이는 Claude Code CLI보다 PATH 우선 순위를 가집니다. `claude`를 실행하면 CLI 대신 Desktop 앱이 열립니다.

746 908

747Claude Desktop을 최신 버전으로 업데이트하여 이 문제를 해결합니다.909Claude Desktop을 최신 버전으로 업데이트하여 이 문제를 해결합니다.

748 910

752 914

753Git for Windows는 선택 사항입니다. Claude Code는 Git Bash가 없을 때 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)를 사용하므로 이 오류는 어느 셸도 찾을 수 없음을 의미합니다.915Git for Windows는 선택 사항입니다. Claude Code는 Git Bash가 없을 때 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)를 사용하므로 이 오류는 어느 셸도 찾을 수 없음을 의미합니다.

754 916

755**PowerShell이 PATH에서 누락된 경우** 기본 위치는 `C:\Windows\System32\WindowsPowerShell\v1.0\`입니다. 해당 디렉토리를 `PATH`에 추가하거나 `pwsh`를 제공하는 [PowerShell 7](https://aka.ms/powershell)을 설치합니다.917**PowerShell이 PATH에서 누락된 경우** 기본 위치는 `C:\Windows\System32\WindowsPowerShell\v1.0\`입니다. 해당 디렉터리를 `PATH`에 추가하거나 `pwsh`를 제공하는 [PowerShell 7](https://aka.ms/powershell)을 설치합니다.

756 918

757**Git for Windows를 대신 설치하려면** [git-scm.com/downloads/win](https://git-scm.com/downloads/win)에서 다운로드합니다. 설정 중에 "Add to PATH"를 선택합니다. 설치 후 터미널을 다시 시작합니다. 설치하면 Bash 도구가 활성화되어 Bash 기반 스크립트 및 도구로 작업할 때 유용합니다.919**Git for Windows를 대신 설치하려면** [git-scm.com/downloads/win](https://git-scm.com/downloads/win)에서 다운로드합니다. 설정 중에 "Add to PATH"를 선택합니다. 설치 후 터미널을 다시 시작합니다. 설치하면 Bash 도구가 활성화되어 Bash 기반 스크립트 및 도구로 작업할 때 유용합니다.

758 920

7611. 기본 설치 위치 `C:\Program Files\Git` 및 `C:\Program Files (x86)\Git`.9231. 기본 설치 위치 `C:\Program Files\Git` 및 `C:\Program Files (x86)\Git`.

7622. `PATH`의 `git`을 사용하여 해당 Git 설치의 `bin\bash.exe`.9242. `PATH`의 `git`을 사용하여 해당 Git 설치의 `bin\bash.exe`.

763 925

7642단계에서 Claude Code는 Claude Code를 시작한 폴더에 있거나 `node_modules` 또는 `.venv` 또는 `env`와 같은 가상 환경 폴더를 포함하는 경로 아래에 있는 `git`을 건너뜁니다. 예를 들어 `C:\dev\env\myproject`에서 시작했을 때 `C:\dev\env\myproject\Git`. 이는 Claude Code가 프로젝트가 배치한 실행 파일을 실행하지 않도록 합니다. Git이 그러한 위치에 있으면 `CLAUDE_CODE_GIT_BASH_PATH`를 가리킵니다.9262단계에서 Claude Code는 Claude Code를 시작한 폴더에 있거나 `node_modules` 또는 `.venv` 또는 `env`와 같은 가상 환경 폴더를 포함하는 경로 아래에 있는 `git`을 건너뜁니다. 예를 들어 `C:\dev\env\myproject`에서 시작했을 때 `C:\dev\env\myproject\Git`. 이는 Claude Code가 프로젝트가 배치한 실행 파일을 실행하지 않도록 합니다. Git이 그러한 위치에 있으면 `CLAUDE_CODE_GIT_BASH_PATH`가 해당 위치를 가리키도록 설정합니다.

765 927

766**Claude Code를 특정 Git 설치로 가리키려면** PowerShell에서 `where.exe git`을 실행하여 찾은 다음 해당 설치의 `bin\bash.exe` 경로를 [settings.json 파일](/docs/ko/settings)에서 `CLAUDE_CODE_GIT_BASH_PATH`로 설정합니다.928**Claude Code를 특정 Git 설치로 가리키려면** PowerShell에서 `where.exe git`을 실행하여 찾은 다음 해당 설치의 `bin\bash.exe` 경로를 [settings.json 파일](/docs/ko/settings)에서 `CLAUDE_CODE_GIT_BASH_PATH`로 설정합니다.

767 929

773}935}

774```936```

775 937

776**`CLAUDE_CODE_GIT_BASH_PATH`가 올바른 경로로 설정되고 파일이 존재하지만** Claude Code가 여전히 사용하지 않으면 먼저 파일의 이름을 확인합니다. Claude Code는 `bash.exe`, `sh.exe`, `bash` 또는 `sh`라는 이름의 파일만 허용합니다. Git for Windows의 `git-bash.exe` 런처와 같은 다른 이름의 경우 변수를 무시하고 설정되지 않은 것처럼 자동 감지하며 `--debug`로 볼 수 있는 경고를 기록합니다. 존재하지 않는 경로는 동일한 폴백 및 경고를 받습니다. v2.1.219 이전에는 Claude Code가 이름을 확인하지 않고 존재하는 모든 파일을 셸로 사용했으며 경로가 존재하지 않을 때 `Claude Code was unable to find CLAUDE_CODE_GIT_BASH_PATH path`로 시작 시 종료되었습니다.938**`CLAUDE_CODE_GIT_BASH_PATH`가 올바른 경로로 설정되고 파일이 존재하지만** Claude Code가 여전히 사용하지 않으면 먼저 파일의 이름을 확인합니다. Claude Code는 `bash.exe`, `sh.exe`, `bash` 또는 `sh`라는 이름의 파일만 허용합니다. Git for Windows의 `git-bash.exe` 런처와 같은 다른 이름의 경우 변수를 무시하고 설정되지 않은 것처럼 Git Bash를 자동 감지하며 `--debug`로 볼 수 있는 경고를 기록합니다. 존재하지 않는 경로는 동일한 폴백 및 경고를 받습니다. v2.1.219 이전에는 Claude Code가 이름을 확인하지 않고 존재하는 모든 파일을 셸로 사용했으며 경로가 존재하지 않을 때 `Claude Code was unable to find CLAUDE_CODE_GIT_BASH_PATH path`로 시작 시 종료되었습니다.

777 939

778파일의 이름이 맞으면 AppLocker, 그룹 정책 소프트웨어 제한 정책 또는 EDR 에이전트와 같은 엔드포인트 보안 소프트웨어가 간섭할 수 있습니다. IT 팀에 엔드포인트 보호 정책에서 `claude.exe` 및 `cmd.exe` 및 `bash.exe`를 포함한 생성하는 프로세스를 허용 목록에 추가하도록 요청합니다.940파일의 이름이 맞으면 AppLocker, 그룹 정책 소프트웨어 제한 정책 또는 EDR 에이전트와 같은 엔드포인트 보안 소프트웨어가 간섭할 수 있습니다. IT 팀에 엔드포인트 보호 정책에서 `claude.exe` 및 `cmd.exe` 및 `bash.exe`를 포함한 생성하는 프로세스를 허용 목록에 추가하도록 요청합니다.

779 941

884wsl --set-version <DistroName> 21046wsl --set-version <DistroName> 2

885```1047```

886 1048

887WSL1에 머물러야 하면 동적 링커를 통해 바이너리를 호출합니다. WSL 내의 `~/.bashrc`에 이 함수를 추가하고 홈 디렉토리가 다르면 경로를 바꿉니다.1049WSL1에 머물러야 하면 동적 링커를 통해 바이너리를 호출합니다. WSL 내의 `~/.bashrc`에 이 함수를 추가하고 홈 디렉터리가 다르면 경로를 바꿉니다.

888 1050

889```bash theme={null}1051```bash theme={null}

890claude() {1052claude() {

932 설치 중 권한 오류1094 설치 중 권한 오류

933</h3>1095</h3>

934 1096

935네이티브 설치 프로그램이 권한 오류로 실패하면 대상 디렉토리를 쓸 수 없을 수 있습니다. [디렉토리 권한 확인](#check-directory-permissions)을 참조하세요.1097네이티브 설치 프로그램이 권한 오류로 실패하면 대상 디렉터리를 쓸 수 없을 수 있습니다. [디렉터리 권한 확인](#check-directory-permissions)을 참조하세요.

936 1098

937이전에 npm으로 설치했고 npm 특정 권한 오류에 직면하면 네이티브 설치 프로그램으로 전환합니다.1099이전에 npm으로 설치했고 npm 특정 권한 오류에 직면하면 네이티브 설치 프로그램으로 전환합니다.

938 1100

944 npm 설치 후 네이티브 바이너리를 찾을 수 없습니다1106 npm 설치 후 네이티브 바이너리를 찾을 수 없습니다

945</h3>1107</h3>

946 1108

947`@anthropic-ai/claude-code` npm 패키지는 `@anthropic-ai/claude-code-darwin-arm64`와 같은 플랫폼별 선택적 종속성으로 네이티브 바이너리를 다운로드합니다. npm은 패키지의 postinstall 스크립트를 실행하여 해당 바이너리를 `claude` 명령으로 제자리에 복사합니다. 실행될 때까지 `claude`는 자리 표시자 스크립트입니다. 다운로드 또는 postinstall 단계 중 하나가 건너뛰어지면 자리 표시자가 제자리에 남아 있으며 macOS 및 Linux에서 `claude`를 실행하면 다음이 출력됩니다.1109`@anthropic-ai/claude-code` npm 패키지는 `@anthropic-ai/claude-code-darwin-arm64`와 같은 플랫폼별 선택적 의존성으로 네이티브 바이너리를 다운로드합니다. npm은 패키지의 postinstall 스크립트를 실행하여 해당 바이너리를 `claude` 명령으로 제자리에 복사합니다. 실행될 때까지 `claude`는 자리 표시자 스크립트입니다. 다운로드 또는 postinstall 단계 중 하나가 건너뛰어지면 자리 표시자가 제자리에 남아 있으며 macOS 및 Linux에서 `claude`를 실행하면 다음이 출력됩니다.

948 1110

949```text theme={null}1111```text theme={null}

950Error: claude native binary not installed.1112Error: claude native binary not installed.

963 1125

964다음 원인을 확인합니다.1126다음 원인을 확인합니다.

965 1127

966* **선택적 종속성이 비활성화됨.** npm 설치 명령에서 `--omit=optional`을 제거하고 pnpm에서 `--no-optional`을 제거하고 yarn에서 `--ignore-optional`을 제거하고 `.npmrc`가 `optional=false`를 설정하지 않는지 확인합니다. 그런 다음 다시 설치합니다. 네이티브 바이너리는 선택적 종속성으로만 제공되므로 건너뛰어지면 JavaScript 폴백이 없으며 `install.cjs`를 다시 실행해도 다운로드되지 않은 바이너리를 배치할 수 없습니다.1128* **선택적 의존성이 비활성화됨.** npm 설치 명령에서 `--omit=optional`을 제거하고 pnpm에서 `--no-optional`을 제거하고 yarn에서 `--ignore-optional`을 제거하고 `.npmrc`가 `optional=false`를 설정하지 않는지 확인합니다. 그런 다음 다시 설치합니다. 네이티브 바이너리는 선택적 의존성으로만 제공되므로 건너뛰어지면 JavaScript 폴백이 없으며 `install.cjs`를 다시 실행해도 다운로드되지 않은 바이너리를 배치할 수 없습니다.

967* **설치 스크립트가 비활성화됨.** `--ignore-scripts` 및 일부 pnpm 구성은 postinstall 단계를 건너뛰지만 여전히 플랫폼 패키지를 다운로드합니다. 메시지가 제안하는 대로 `node node_modules/@anthropic-ai/claude-code/install.cjs`를 실행하거나 플래그 없이 다시 설치합니다. postinstall이 환경에서 실행될 수 없으면 `node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs`가 다운로드된 패키지를 찾고 시작하며, 각 시작 시 추가 Node 프로세스의 비용이 발생합니다. 래퍼가 `Could not find native binary package`를 출력하면 플랫폼 패키지가 다운로드되지 않았으므로 먼저 위의 선택적 종속성 원인을 수정합니다.1129* **설치 스크립트가 비활성화됨.** `--ignore-scripts` 및 일부 pnpm 구성은 postinstall 단계를 건너뛰지만 여전히 플랫폼 패키지를 다운로드합니다. 메시지가 제안하는 대로 `node node_modules/@anthropic-ai/claude-code/install.cjs`를 실행하거나 플래그 없이 다시 설치합니다. postinstall이 환경에서 실행될 수 없으면 `node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs`가 다운로드된 패키지를 찾고 시작하며, 각 시작 시 추가 Node 프로세스의 비용이 발생합니다. 래퍼가 `Could not find native binary package`를 출력하면 플랫폼 패키지가 다운로드되지 않았으므로 먼저 위의 선택적 의존성 원인을 수정합니다.

968* **지원되지 않는 플랫폼.** 미리 빌드된 바이너리는 `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64` 및 `win32-arm64`에 대해 게시됩니다. Claude Code는 다른 플랫폼에 대한 바이너리를 제공하지 않습니다. [시스템 요구 사항](/docs/ko/setup#system-requirements)을 참조하세요. FreeBSD에서 설치 프로그램은 플랫폼을 지원되지 않는 것으로 보고합니다. v2.1.205 이전에는 FreeBSD를 Linux로 취급하고 실행할 수 없는 바이너리를 다운로드했습니다.1130* **지원되지 않는 플랫폼.** 미리 빌드된 바이너리는 `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64` 및 `win32-arm64`에 대해 게시됩니다. Claude Code는 다른 플랫폼에 대한 바이너리를 제공하지 않습니다. [시스템 요구 사항](/docs/ko/setup#system-requirements)을 참조하세요. FreeBSD에서 설치 프로그램은 플랫폼을 지원되지 않는 것으로 보고합니다. v2.1.205 이전에는 FreeBSD를 Linux로 취급하고 실행할 수 없는 바이너리를 다운로드했습니다.

969* **회사 npm 미러가 플랫폼 패키지를 누락함.** 레지스트리가 메타 패키지 외에도 8개의 `@anthropic-ai/claude-code-*` 플랫폼 패키지를 모두 미러링하는지 확인합니다.1131* **회사 npm 미러가 플랫폼 패키지를 누락함.** 레지스트리가 메타 패키지 외에도 8개의 `@anthropic-ai/claude-code-*` 플랫폼 패키지를 모두 미러링하는지 확인합니다.

970 1132

972 npm 업데이트 또는 재설치 중 `ENOTEMPTY` 오류1134 npm 업데이트 또는 재설치 중 `ENOTEMPTY` 오류

973</h3>1135</h3>

974 1136

975기존 설치에 대해 `npm install -g @anthropic-ai/claude-code`를 실행하면 npm이 이전 패키지 디렉토리를 옆으로 이동하는 동안 실패할 수 있습니다.1137기존 설치에 대해 `npm install -g @anthropic-ai/claude-code`를 실행하면 npm이 이전 패키지 디렉터리를 옆으로 이동하는 동안 실패할 수 있습니다.

976 1138

977```text theme={null}1139```text theme={null}

978npm error code ENOTEMPTY1140npm error code ENOTEMPTY

983npm error ENOTEMPTY: directory not empty, rename '...'1145npm error ENOTEMPTY: directory not empty, rename '...'

984```1146```

985 1147

986`npm error path` 줄은 npm이 이동할 수 없는 디렉토리의 이름을 지정합니다. 해당 디렉토리와 옆에 있는 모든 `.claude-code-*` 디렉토리를 삭제합니다. 이전 중단된 실행이 남길 수 있습니다. 아래 명령은 `npm root -g`로 전역 패키지 디렉토리를 찾습니다. `npm error path` 줄이 이름을 지정하는 디렉토리가 `npm root -g`가 출력하는 디렉토리 아래에 없으면(예: nvm으로 Node 버전을 전환했기 때문에) 오류가 이름을 지정하는 디렉토리를 대신 삭제합니다.1148`npm error path` 줄은 npm이 이동할 수 없는 디렉터리의 이름을 지정합니다. 해당 디렉터리와 옆에 있는 모든 `.claude-code-*` 디렉터리를 삭제합니다. 이전 중단된 실행이 남길 수 있습니다. 아래 명령은 `npm root -g`로 전역 패키지 디렉터리를 찾습니다. `npm error path` 줄이 이름을 지정하는 디렉터리가 `npm root -g`가 출력하는 디렉터리 아래에 없으면(예: nvm으로 Node 버전을 전환했기 때문에) 오류가 이름을 지정하는 디렉터리를 대신 삭제합니다.

987 1149

988<Tabs>1150<Tabs>

989 <Tab title="macOS/Linux">1151 <Tab title="macOS/Linux">

991 rm -rf "$(npm root -g)/@anthropic-ai/claude-code"1153 rm -rf "$(npm root -g)/@anthropic-ai/claude-code"

992 ```1154 ```

993 1155

994 그런 다음 남은 임시 디렉토리를 제거합니다. Zsh가 `no matches found`를 출력하면 제거할 것이 없었습니다.1156 그런 다음 남은 임시 디렉터리를 제거합니다. Zsh가 `no matches found`를 출력하면 제거할 것이 없었습니다.

995 1157

996 ```bash theme={null}1158 ```bash theme={null}

997 rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*1159 rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*

troubleshooting.md +1 −1

Details

11| 증상 | 이동 |11| 증상 | 이동 |

12| :- | :- |12| :- | :- |

13| `command not found`, 설치 실패, PATH 문제, `EACCES`, TLS 오류 | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install) |13| `command not found`, 설치 실패, PATH 문제, `EACCES`, TLS 오류 | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install) |

14| `The connection dropped while downloading the update` 또는 `aborted`로 업데이트 또는 설치 다운로드 실패 | [오류 참조](/docs/ko/errors#the-connection-dropped-while-downloading-the-update) |14| `The connection dropped while downloading the update` 또는 `aborted`로 업데이트 또는 설치 다운로드 실패 | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |

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) |

ultrareview.md +6 −6

Details

56 풀 요청 검토56 풀 요청 검토

57</h3>57</h3>

58 58

~~59로컬 브랜치 대신 GitHub 풀 요청을 검토하려면 PR 번호를 전달합니다:~~59로컬 브랜치 대신 `github.com`의 풀 리퀘스트를 검토하려면 PR 번호를 전달합니다:

60 60

61```text theme={null}61```text theme={null}

62/code-review ultra 123462/code-review ultra 1234

64 64

65명령은 또한 `#1234`, `PR 1234` 및 붙여넣은 PR URL을 허용합니다. 붙여넣은 URL은 현재 디렉토리의 저장소를 가리켜야 합니다.65명령은 또한 `#1234`, `PR 1234` 및 붙여넣은 PR URL을 허용합니다. 붙여넣은 URL은 현재 디렉토리의 저장소를 가리켜야 합니다.

66 66

67PR 모드에서 클라우드 샌드박스는 로컬 작업 트리를 번들로 묶는 대신 호스트에서 직접 풀 요청을 복제합니다. PR 모드는 `github.com`의 저장소 및 관리자가 Claude Code에 연결한 [GitHub Enterprise Server](/docs/ko/github-enterprise-server) 인스턴스에서 작동합니다.67PR 모드에는 `github.com`의 저장소가 필요합니다. [GitHub Enterprise Server](/docs/ko/github-enterprise-server) 인스턴스의 저장소인 경우 PR 번호 없이 `/code-review ultra`를 실행하여 대신 로컬 브랜치를 검토합니다.

68 68

~~69`github.com`의 저장소의 경우 샌드박스는 Claude 계정에 연결된 GitHub 계정으로 복제하므로 계정이 PR의 저장소를 읽을 수 있어야 합니다.~~69PR 모드에서 클라우드 샌드박스는 작업 트리를 업로드하는 대신 `github.com`에서 풀 리퀘스트를 복제합니다. Claude 계정에 연결된 GitHub 계정을 사용하므로 해당 계정에 저장소에 대한 읽기 권한이 있어야 합니다.

70 70

71GitHub CLI 로그인을 Claude 계정에 연결하려면 [`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)을 실행합니다.71GitHub CLI 로그인을 Claude 계정에 연결하려면 [`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)을 실행합니다.

72 72

74 풀 요청에 결과 게시74 풀 요청에 결과 게시

75</h3>75</h3>

76 76

77Claude Code v2.1.227 이상에서 `github.com`의 풀 요청을 검토할 때 Claude가 완료된 결과를 PR에 자신의 GitHub 계정에서 단일 일반 댓글로 게시하도록 할 수 있습니다. 댓글은 리뷰나 승인이 아니며 "Generated by Claude Code" 메모로 끝납니다. 브랜치 또는 GitHub Enterprise Server 풀 요청을 검토할 때 Claude Code는 세션에만 결과를 표시합니다.77Claude Code v2.1.227 이상에서 `github.com`의 풀 리퀘스트를 검토할 때 Claude가 완료된 결과를 PR에 자신의 GitHub 계정에서 단일 일반 댓글로 게시하도록 할 수 있습니다. 댓글은 리뷰나 승인이 아니며 "Generated by Claude Code" 메모로 끝납니다. 브랜치를 검토할 때 Claude Code는 세션에만 결과를 표시합니다.

78 78

79Claude Code는 해당 실행에서 선택하지 않는 한 게시하지 않으며 `--no-post`가 기본값입니다. 게시는 각 실행에 대해 선택하는 사항입니다:79Claude Code는 해당 실행에서 선택하지 않는 한 게시하지 않으며 `--no-post`가 기본값입니다. 게시는 각 실행에 대해 선택하는 사항입니다:

80 80

106Claude Code는 텍스트에 두 개 이상의 단어가 있고 브랜치 이름이나 PR 참조가 아닐 때만 메모로 취급합니다. 단일 단어를 브랜치 이름이나 PR 참조로 읽으므로 오타가 있는 브랜치 이름은 [다른 기본에 대해 검토](#review-against-a-different-base)의 가장 가까운 브랜치 오류를 받습니다. 텍스트가 `check PR 123 again`과 같은 다른 단어와 PR 참조를 결합하면 Claude Code도 시작하지 않습니다. 대신 PR 번호만으로 다시 실행하여 해당 PR을 검토하거나 참조 없이 현재 브랜치를 검토하도록 요청합니다.106Claude Code는 텍스트에 두 개 이상의 단어가 있고 브랜치 이름이나 PR 참조가 아닐 때만 메모로 취급합니다. 단일 단어를 브랜치 이름이나 PR 참조로 읽으므로 오타가 있는 브랜치 이름은 [다른 기본에 대해 검토](#review-against-a-different-base)의 가장 가까운 브랜치 오류를 받습니다. 텍스트가 `check PR 123 again`과 같은 다른 단어와 PR 참조를 결합하면 Claude Code도 시작하지 않습니다. 대신 PR 번호만으로 다시 실행하여 해당 PR을 검토하거나 참조 없이 현재 브랜치를 검토하도록 요청합니다.

107 107

108<Tip>108<Tip>

109 저장소가 너무 커서 번들로 묶을 수 없는 경우 Claude Code는 대신 PR 모드를 사용하도록 요청합니다. 브랜치를 푸시하고 초안 PR을 열고 `/code-review ultra <PR-number>`를 실행합니다.109 저장소가 너무 커서 번들로 묶을 수 없는 경우 Claude Code는 대신 PR 모드를 사용하도록 요청합니다. `github.com`의 저장소인 경우 브랜치를 푸시하고 초안 PR을 연 다음 `/code-review ultra <PR-number>`를 실행합니다.

110</Tip>110</Tip>

111 111

112<h3 id="diff-limits-and-fallbacks">112<h3 id="diff-limits-and-fallbacks">

173claude ultrareview origin/main173claude ultrareview origin/main

174```174```

175 175

176인수 없이 하위 명령은 현재 브랜치와 기본 브랜치 간의 diff를 검토하며, 병합 기반이 없을 때 `/code-review ultra`와 동일한 [전체 저장소 폴백](#diff-limits-and-fallbacks)을 사용합니다. PR 번호를 전달하여 풀 리퀘스트를 검토하거나, 기본 브랜치를 전달하여 해당 브랜치에 대해 검토합니다. [기본 브랜치 처리](#review-against-a-different-base)는 대화형 명령과 일치합니다.176인수 없이 하위 명령은 현재 브랜치와 기본 브랜치 간의 diff를 검토하며, 병합 기반이 없을 때 `/code-review ultra`와 동일한 [전체 저장소 폴백](#diff-limits-and-fallbacks)을 사용합니다. PR 번호를 전달하여 [`github.com`의 풀 리퀘스트를 리뷰](#review-a-pull-request)하거나, 기본 브랜치를 전달하여 해당 브랜치에 대해 검토합니다. [기본 브랜치 처리](#review-against-a-different-base)는 대화형 명령과 일치합니다.

177 177

178하위 명령을 실행하면 전체 저장소 폴백과 청구 및 약관 프롬프트에 동의하므로 입력을 기다리지 않고 실행이 시작됩니다. 직접 실행하는 것이 동의로 간주됩니다. Claude가 예를 들어 Bash 도구를 통해 대신 하위 명령을 실행할 때 Claude Code는 전체 저장소 리뷰를 거부합니다.178하위 명령을 실행하면 전체 저장소 폴백과 청구 및 약관 프롬프트에 동의하므로 입력을 기다리지 않고 실행이 시작됩니다. 직접 실행하는 것이 동의로 간주됩니다. Claude가 예를 들어 Bash 도구를 통해 대신 하위 명령을 실행할 때 Claude Code는 전체 저장소 리뷰를 거부합니다.

179 179

vs-code.md +2 −0

Details

166* **북마크**: 응답 위에 마우스를 올리고 **Bookmark response**를 클릭하여 저장하거나, 저장된 응답에서 **Remove bookmark**를 클릭하여 제거합니다.166* **북마크**: 응답 위에 마우스를 올리고 **Bookmark response**를 클릭하여 저장하거나, 저장된 응답에서 **Remove bookmark**를 클릭하여 제거합니다.

167 167

168 저장된 응답을 검토하려면 Bookmarks 패널을 엽니다. Claude Code 패널 상단의 북마크 아이콘을 클릭하거나, 명령 메뉴의 Context 섹션에서 **Bookmarks**를 선택하거나, `/bookmarks`를 입력합니다. Claude Code v2.1.286 이상이 필요합니다.168 저장된 응답을 검토하려면 Bookmarks 패널을 엽니다. Claude Code 패널 상단의 북마크 아이콘을 클릭하거나, 명령 메뉴의 Context 섹션에서 **Bookmarks**를 선택하거나, `/bookmarks`를 입력합니다. Claude Code v2.1.286 이상이 필요합니다.

169* **Claude가 보낸 파일**: 세션이 [Remote Control](/docs/ko/remote-control#start-a-remote-control-session)에 연결되어 있고 Claude가 [`SendUserFile` 도구](/docs/ko/tools-reference)로 파일을 보내면 대화에 **Sent report.md, chart.png**와 같은 행이 표시됩니다. 파일 이름을 클릭하면 편집기에서 열립니다.

169* **Context indicator**: 프롬프트 상자는 Claude의 컨텍스트 윈도우를 얼마나 사용하고 있는지 보여줍니다. Claude는 필요할 때 자동으로 압축하거나 `/compact`를 수동으로 실행할 수 있습니다.170* **Context indicator**: 프롬프트 상자는 Claude의 컨텍스트 윈도우를 얼마나 사용하고 있는지 보여줍니다. Claude는 필요할 때 자동으로 압축하거나 `/compact`를 수동으로 실행할 수 있습니다.

170* **Prompt cache clock**: 컨텍스트 표시기 옆의 시계 아이콘은 대화의 [prompt cache](/docs/ko/prompt-caching)가 만료되기 전에 남은 시간을 추정합니다. 캐시의 5분 또는 1시간 [수명](/docs/ko/prompt-caching#cache-lifetime)에서 카운트다운되며, 캐시를 사용하는 각 응답은 카운트다운을 다시 시작합니다. 압축과 별개로 [캐시를 무효화하는 작업](/docs/ko/prompt-caching#actions-that-invalidate-the-cache)은 시계를 재설정하지 않으므로 모델을 전환한 후에도 남은 시간을 표시할 수 있습니다.171* **Prompt cache clock**: 컨텍스트 표시기 옆의 시계 아이콘은 대화의 [prompt cache](/docs/ko/prompt-caching)가 만료되기 전에 남은 시간을 추정합니다. 캐시의 5분 또는 1시간 [수명](/docs/ko/prompt-caching#cache-lifetime)에서 카운트다운되며, 캐시를 사용하는 각 응답은 카운트다운을 다시 시작합니다. 압축과 별개로 [캐시를 무효화하는 작업](/docs/ko/prompt-caching#actions-that-invalidate-the-cache)은 시계를 재설정하지 않으므로 모델을 전환한 후에도 남은 시간을 표시할 수 있습니다.

171 * 카운트다운이 끝날 때까지 아이콘은 **12m**과 같이 남은 분을 표시합니다.172 * 카운트다운이 끝날 때까지 아이콘은 **12m**과 같이 남은 분을 표시합니다.

601| `spinnerVerbs` | `{"mode": "append", "verbs": []}` | 턴이 실행되는 동안 대화 스피너가 순환하며 표시하는 동사를 설정합니다. CLI의 [`spinnerVerbs`](/docs/ko/settings-reference#spinnerverbs)와 동일한 `mode` 및 `verbs` 필드를 사용합니다. |

601| `enableReopenClosedSessionShortcut` | `true` | Cmd/Ctrl+Shift+T를 사용하여 가장 최근에 닫은 Claude 세션 탭을 다시 엽니다. 마지막으로 닫은 탭이 Claude 세션이 아닌 경우 바로 가기는 VS Code의 일반 reopen-closed-editor 명령을 대신 실행합니다. |603| `enableReopenClosedSessionShortcut` | `true` | Cmd/Ctrl+Shift+T를 사용하여 가장 최근에 닫은 Claude 세션 탭을 다시 엽니다. 마지막으로 닫은 탭이 Claude 세션이 아닌 경우 바로 가기는 VS Code의 일반 reopen-closed-editor 명령을 대신 실행합니다. |

602| `archiveInactiveSessions` | `14` | [세션을 자동으로 보관](#resume-past-conversations)합니다. 이 많은 일 동안 활동이 없으면: `1`, `2`, `7` 또는 `14`. `0`으로 설정하여 끕니다. Claude Code v2.1.265 이상 필요 |604| `archiveInactiveSessions` | `14` | [세션을 자동으로 보관](#resume-past-conversations)합니다. 이 많은 일 동안 활동이 없으면: `1`, `2`, `7` 또는 `14`. `0`으로 설정하여 끕니다. Claude Code v2.1.265 이상 필요 |

workflows.md +55 −29

Details

264Claude는 목록을 구조화된 데이터로 전달하므로 스크립트는 먼저 구문 분석하지 않고도 `args`에서 배열 및 객체 메서드를 직접 호출할 수 있습니다. `args`가 생략되면 스크립트 내부의 전역 변수는 `undefined`입니다.264Claude는 목록을 구조화된 데이터로 전달하므로 스크립트는 먼저 구문 분석하지 않고도 `args`에서 배열 및 객체 메서드를 직접 호출할 수 있습니다. `args`가 생략되면 스크립트 내부의 전역 변수는 `undefined`입니다.

265 265

266<h2 id="example-workflow-prompts">266<h2 id="example-workflow-prompts">

267 예제 워크플로우 프롬프트267 워크플로 프롬프트 예시

268</h2>268</h2>

269 269

270워크플로우는 작업이 한 에이전트가 컨텍스트에 보유할 수 있는 것보다 크거나, 같은 단계를 많은 항목에 걸쳐 실행해야 할 때 가장 적합합니다. 아래 프롬프트는 일반적인 형태를 보여줍니다. 각각은 Claude에게 해당 작업을 위한 워크플로우를 작성하고 실행하도록 요청합니다; 스크립트를 직접 작성하지 않습니다.270워크플로는 작업이 하나의 에이전트가 컨텍스트에 담을 수 있는 범위보다 크거나, 같은 단계를 여러 항목에 걸쳐 실행해야 할 때 가장 적합합니다. 아래 프롬프트는 일반적인 형태를 보여 줍니다. 각 프롬프트는 Claude에게 해당 작업을 위한 워크플로를 작성하고 실행하도록 요청하므로, 스크립트를 직접 작성할 필요가 없습니다.

271 271

272<h3 id="audit-many-files-for-the-same-issue">272<h3 id="audit-many-files-for-the-same-issue">

273 많은 파일을 같은 문제에 대해 감사하기273 여러 파일에서 같은 문제 감사하기

274</h3>274</h3>

275 275

276파일당 하나의 에이전트를 확산시킨 후 발견 사항을 수집하고 검증합니다.276파일마다 에이전트를 하나씩 분산 실행한 다음, 발견 사항을 수집하고 검증합니다.

277 277

278```text wrap theme={null}278```text wrap theme={null}

279use a workflow to audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting it279use a workflow to audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting it

280```280```

281 281

282<h3 id="keep-fixing-until-a-check-passes">282<h3 id="keep-fixing-until-a-check-passes">

283 검사가 통과할 때까지 계속 수정하기283 검사를 통과할 때까지 계속 수정하기

284</h3>284</h3>

285 285

286검사기를 실행하고, 실패한 것을 수정하며, 통과하거나 진행이 멈출 때까지 반복합니다.286검사기를 실행하고, 실패한 부분을 수정한 뒤, 통과하거나 더 이상 진전이 없을 때까지 반복합니다.

287 287

288```text wrap theme={null}288```text wrap theme={null}

289use a workflow to run npx tsc --noEmit and keep fixing the reported errors until the type check passes or two rounds in a row make no progress289use a workflow to run npx tsc --noEmit and keep fixing the reported errors until the type check passes or two rounds in a row make no progress

290```290```

291 291

292<h3 id="migrate-many-files-in-parallel">292<h3 id="migrate-many-files-in-parallel">

293 많은 파일을 병렬로 마이그레이션하기293 여러 파일을 병렬로 마이그레이션하기

294</h3>294</h3>

295 295

296마이그레이션할 파일을 발견하고, 편집이 충돌하지 않도록 각각을 격리된 복사본에서 변환하며, 각 결과를 검증합니다.296마이그레이션할 파일을 찾고, 편집이 충돌하지 않도록 각 파일을 격리된 사본에서 변환한 다음, 각 결과를 검증합니다.

297 297

298```text wrap theme={null}298```text wrap theme={null}

299use a workflow to migrate every component under src/components/ from JavaScript to TypeScript, working on each file in its own isolated copy299use a workflow to migrate every component under src/components/ from JavaScript to TypeScript, working on each file in its own isolated copy

300```300```

301 301

302<h3 id="review-every-changed-file-and-write-one-summary">302<h3 id="review-every-changed-file-and-write-one-summary">

303 모든 변경된 파일을 검토하고 하나의 요약 작성하기303 변경된 모든 파일을 리뷰하고 하나의 요약 작성하기

304</h3>304</h3>

305 305

306파일당 하나의 검토자를 실행한 후 모든 발견 사항을 하나의 에이전트에 전달하여 순위를 매기고 중복을 제거합니다.306파일마다 리뷰어를 실행한 다음, 모든 발견 사항을 하나의 에이전트에 전달하여 순위를 매기고 중복을 제거합니다.

307 307

308```text wrap theme={null}308```text wrap theme={null}

309use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary309use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary

310```310```

311 311

312<h3 id="research-a-topic-across-many-sources">312<h3 id="research-a-topic-across-many-sources">

313 많은 소스에서 주제 연구하기313 여러 출처에 걸쳐 주제 조사하기

314</h3>314</h3>

315 315

316변경 로그, 문제, 문서에 걸쳐 읽기를 확산시킨 후 종합합니다. 번들된 `/deep-research` 워크플로우가 이를 수행합니다; 더 좁은 버전을 설명할 수도 있습니다.316변경 로그, 이슈, 문서에 걸쳐 리더를 분산 실행한 다음 종합합니다. 번들로 제공되는 `/deep-research` 워크플로가 이 작업을 수행하며, 더 좁은 범위의 버전을 직접 설명할 수도 있습니다.

317 317

318```text wrap theme={null}318```text wrap theme={null}

319use a workflow to research how our three competitors handle rate limiting: read their public docs and recent changelog entries in parallel, then compare the approaches319use a workflow to research how our three competitors handle rate limiting: read their public docs and recent changelog entries in parallel, then compare the approaches

320```320```

321 321

322<h3 id="find-issues-until-the-list-stops-growing">322<h3 id="find-issues-until-the-list-stops-growing">

323 목록이 더 이상 증가할 때까지 문제 찾기323 목록이 더 이상 늘어나지 않을 때까지 문제 찾기

324</h3>324</h3>

325 325

326라운드에서 계속 검색하고 새 라운드가 새로운 것을 찾지 못하면 중지합니다.326여러 라운드에 걸쳐 계속 탐색하고, 새 라운드에서 새로운 것이 발견되지 않으면 중단합니다.

327 327

328```text wrap theme={null}328```text wrap theme={null}

329use a workflow to find flaky tests in this repo: run the suite repeatedly, record which tests fail intermittently, and stop once two rounds in a row find nothing new329use a workflow to find flaky tests in this repo: run the suite repeatedly, record which tests fail intermittently, and stop once two rounds in a row find nothing new

330```330```

331 331

332<h3 id="what-the-saved-script-looks-like">332<h3 id="what-the-saved-script-looks-like">

333 저장된 스크립트가 어떻게 보이는지333 저장된 스크립트의 모습

334</h3>334</h3>

335 335

336[워크플로우를 저장](#save-the-workflow-for-reuse)하면 `.claude/workflows/`의 파일은 `meta` 블록 다음에 서브에이전트를 조율하는 스크립트 본문을 보유합니다. 일반적으로 편집할 필요가 없지만, 여기는 Claude가 생성한 것을 인식할 수 있도록 작은 것의 형태입니다:336[워크플로를 저장](#save-the-workflow-for-reuse)하면 `.claude/workflows/`의 파일에는 `meta` 블록과 그 뒤에 서브에이전트를 오케스트레이션하는 스크립트 본문이 담깁니다. 일반적으로 이 파일을 편집할 필요는 없지만, Claude가 생성한 내용을 알아볼 수 있도록 작은 스크립트의 형태를 아래에 보여 드립니다.

337 337

338```javascript theme={null}338```javascript theme={null}

339export const meta = {339export const meta = {

352return audits.filter(Boolean)352return audits.filter(Boolean)

353```353```

354 354

355본문은 최상위 `await`를 포함한 순수 JavaScript입니다. `agent()`는 하나의 서브에이전트를 생성하고, `pipeline()`은 목록의 각 항목당 하나를 실행하며, `parallel()`은 에이전트 작업 집합을 동시에 실행하고 모두가 완료될 때까지 기다립니다.355본문은 최상위 `await`를 사용하는 일반 JavaScript입니다. `agent()`는 서브에이전트 하나를 생성하고, `pipeline()`은 목록의 항목마다 하나씩 실행하며, `parallel()`은 에이전트 작업 집합을 동시에 실행하고 모두 완료될 때까지 기다립니다.

356 356

357`agent()` 호출은 실행 중에 중지하거나 복구 불가능한 API 오류가 발생하면 `null`로 해결됩니다. `pipeline()`은 결과 배열에 각 `null`을 유지하므로, 예제는 해당 항목을 제거하기 위해 `.filter(Boolean)`으로 끝납니다.357사용자가 실행 도중에 `agent()` 호출을 중지하거나 해당 호출이 복구할 수 없는 API 오류를 만나면, 호출은 `null`로 확인됩니다. `pipeline()`은 각 `null`을 결과 배열에 그대로 유지하므로, 예시는 [모든 시도에서 멈춘 에이전트](#when-an-agent-stalls-and-restarts)의 슬롯을 포함한 해당 항목을 제거하기 위해 `.filter(Boolean)`으로 끝납니다.

358 358

359[자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 스크립트가 `agent()`에 전달하는 프롬프트는 분류기가 해당 서브에이전트의 작업을 검토할 때 사용자로부터의 요청으로 계산되지 않습니다. Claude Code는 이를 스크립트가 계산한 텍스트로 표시하기 때문입니다.359[자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 분류기가 서브에이전트의 작업을 검토할 때, 스크립트가 `agent()`에 전달하는 프롬프트는 사용자의 요청으로 간주되지 않습니다. Claude Code가 이를 스크립트가 계산한 텍스트로 표시하기 때문입니다.

360 360

361`agent()` 호출에 `schema`를 전달하면, 서브에이전트는 산문 대신 형태와 일치하는 JSON을 반환합니다. Claude Code는 서브에이전트를 시작하기 전에 스키마를 확인합니다: 스키마가 자신과 모순된다는 것을 증명할 수 있을 때, 호출은 모순을 명명하는 오류로 실패하며, 서브에이전트는 시작되지 않습니다. 증명할 수 있는 한 가지 모순은 `additionalProperties: false`가 제외하는 `required` 키입니다.361`agent()` 호출에 `schema`를 전달하면, 해당 서브에이전트는 산문 대신 그 형태에 맞는 JSON을 반환합니다. Claude Code는 서브에이전트를 시작하기 전에 스키마를 검사합니다. 스키마가 자기모순임을 증명할 수 있으면 호출은 해당 모순을 명시한 오류와 함께 실패하며, 서브에이전트는 시작되지 않습니다. 증명할 수 있는 모순의 한 예는 `additionalProperties: false`가 배제하는 `required` 키입니다.

362 362

363서브에이전트의 출력이 5번의 시도 후에도 검증에 실패하면, 호출은 마지막 검증 실패를 포함하는 오류로 실패합니다. 시도 횟수를 변경하려면 [`MAX_STRUCTURED_OUTPUT_RETRIES`](/docs/ko/env-vars)를 설정하십시오.363서브에이전트의 출력이 다섯 번 시도한 후에도 여전히 검증에 실패하면, 호출은 마지막 검증 실패 내용을 포함한 오류와 함께 실패합니다. 시도 횟수를 변경하려면 [`MAX_STRUCTURED_OUTPUT_RETRIES`](/docs/ko/env-vars)를 설정합니다.

364 364

365<h3 id="edit-a-saved-script">365<h3 id="edit-a-saved-script">

366 저장된 스크립트 편집하기366 저장된 스크립트 편집하기

367</h3>367</h3>

368 368

369[저장한 워크플로우](#save-the-workflow-for-reuse)를 변경하려면 해당 `.js` 파일을 편집하거나 Claude에게 변경을 요청하십시오. 편집하거나 요청하기 전에 `/workflow-authoring` [번들된 스킬](/docs/ko/skills#bundled-skills)을 실행하여 Claude가 작동하는 스크립트 작성 참조를 로드하십시오. 스킬에는 Claude Code v2.1.248 이상이 필요합니다.369[저장한 워크플로](#save-the-workflow-for-reuse)를 변경하려면 해당 `.js` 파일을 편집하거나 Claude에게 변경을 요청합니다. 편집하거나 요청하기 전에 `/workflow-authoring` [번들 스킬](/docs/ko/skills#bundled-skills)을 실행하여 Claude가 참고하는 스크립트 작성 레퍼런스를 로드합니다. 이 스킬에는 Claude Code v2.1.248 이상이 필요합니다.

370 370

371현재 세션에서 편집된 버전을 실행하려면 [`/reload-skills`](/docs/ko/commands#all-commands)를 실행하여 워크플로우 디렉터리를 다시 읽은 후 `/<name>`을 다시 실행하십시오.371현재 세션에서 편집된 버전을 실행하려면 [`/reload-skills`](/docs/ko/commands#all-commands)를 실행하여 워크플로 디렉터리를 다시 읽은 다음, `/<name>`을 다시 실행합니다.

372 372

373Claude Code는 스크립트를 로드하고 실행할 때 파일의 각 부분에 다음 규칙을 적용합니다:373Claude Code는 스크립트를 로드하고 실행할 때 파일의 각 부분에 다음 규칙을 적용합니다.

374 374

375* **`meta` 블록**: `export const meta`를 첫 번째 문으로 유지하고, `name`과 `description`을 포함하는 순수 객체 리터럴로 유지하십시오. 변수, 함수 호출 또는 스프레드와 같은 리터럴 값 이외의 것을 포함하면, Claude Code는 `/` 자동완성에서 `/<name>`을 제거합니다.375* **`meta` 블록**: `export const meta`를 첫 번째 문으로 유지하고, `name`과 `description`을 가진 일반 객체 리터럴로 유지합니다. 변수, 함수 호출, 스프레드처럼 리터럴 값이 아닌 것이 포함되어 있으면 Claude Code는 `/` 자동 완성에서 `/<name>`을 제외합니다.

376* **본문**: `agent()`, `pipeline()`, `parallel()` 외에도 `phase()`를 호출하여 진행 보기에서 다음 에이전트를 제목 아래에 그룹화하고, `log()`를 호출하여 단계 위에 메시지를 표시하며, [`args`](#pass-input-to-a-saved-workflow) 전역을 읽을 수 있습니다. 본문에 구문 오류가 있으면, Claude Code는 워크플로우를 실행할 때 이를 보고합니다.376* **본문**: `agent()`, `pipeline()`, `parallel()` 외에도 `phase()`를 호출하여 이후의 에이전트를 진행 상황 보기에서 하나의 제목 아래로 그룹화하고, `log()`를 호출하여 단계 위에 메시지를 표시하며, [`args`](#pass-input-to-a-saved-workflow) 전역 변수를 읽을 수 있습니다. 본문에 구문 오류가 있으면 Claude Code는 워크플로를 실행할 때 이를 보고합니다.

377* **`phases`**: `meta`에 나열하면, `phase()`에 전달하는 각 항목에 정확히 제목을 지정하십시오. 항목이 없는 `phase()` 제목은 자체 진행 그룹을 가집니다.377* **`phases`**: `meta`에 나열하는 경우, 각 항목에 `phase()`에 전달하는 제목을 정확히 그대로 지정합니다. 항목이 없는 `phase()` 제목은 별도의 진행 상황 그룹을 갖게 됩니다.

378* **타임스탬프 및 무작위성**: Claude Code는 스크립트 내에서 `Date.now()`, `Math.random()`, 인수 없는 `new Date()`를 throw하므로, [재시작된 실행](#resume-after-a-pause)이 동일한 `agent()` 호출을 반복합니다. 대신 `args`를 통해 타임스탬프를 전달하십시오.378* **타임스탬프와 무작위성**: Claude Code는 스크립트 내에서 `Date.now()`, `Math.random()`, 인수 없는 `new Date()`가 예외를 발생시키도록 하여, [다시 시작된 실행](#resume-after-a-pause)이 동일한 `agent()` 호출을 반복하도록 합니다. 대신 `args`를 통해 타임스탬프를 전달합니다.

379 379

380[단일 실행의 스크립트](#how-a-workflow-runs)를 저장된 복사본이 아닌 편집할 수도 있습니다. [일시 중지 후 재개](#resume-after-a-pause)는 편집된 스크립트를 재시작할 때 어떤 에이전트가 다시 실행되는지를 다룹니다. Workflow 도구의 입력에 대해서는 [Agent SDK 참조](/docs/ko/agent-sdk/typescript#workflow)의 항목을 참조하십시오.380저장된 사본 대신 [단일 실행의 스크립트](#how-a-workflow-runs)를 편집할 수도 있습니다. 편집된 스크립트를 다시 시작할 때 어떤 에이전트가 다시 실행되는지는 [일시 중지 후 재개하기](#resume-after-a-pause)에서 다룹니다. Workflow 도구의 입력에 대해서는 [Agent SDK 레퍼런스](/docs/ko/agent-sdk/typescript#workflow)의 해당 항목을 참조하세요.

381 381

382<h2 id="how-a-workflow-runs">382<h2 id="how-a-workflow-runs">

383 워크플로우가 어떻게 실행되는지383 워크플로우가 어떻게 실행되는지

463* 제한이 24시간 이내에 재설정됩니다. 주간 제한은 더 멀리 재설정될 수 있습니다.463* 제한이 24시간 이내에 재설정됩니다. 주간 제한은 더 멀리 재설정될 수 있습니다.

464* 실행이 아직 두 번 대기하지 않았습니다. 세 번째로 제한에 도달하면 에이전트가 실패합니다.464* 실행이 아직 두 번 대기하지 않았습니다. 세 번째로 제한에 도달하면 에이전트가 실패합니다.

465 465

466<h3 id="when-an-agent-stalls-and-restarts">

467 에이전트가 멈추고 다시 시작될 때

468</h3>

469

470출력이 충분히 오랫동안 도착하지 않는 에이전트는 같은 프롬프트로 처음부터 다시 시작합니다. [`/workflows`](#watch-the-run)에서 해당 에이전트의 이름에 `(retry 1)` 접미사가 붙고 세부 정보에 `attempt 2 (stalled)`가 표시됩니다. 재시작은 자동으로 이루어지므로 별도로 조치할 필요가 없습니다.

471

472새 시도는 멈춘 시도의 트랜스크립트 없이 시작됩니다. 멈춘 시도가 이미 변경한 파일은 변경된 상태로 유지되며, 해당 시도가 사용한 토큰은 실행의 총계에 그대로 남습니다. 정체 기간은 Claude Code가 시도를 종료하기 전에 에이전트의 출력을 기다리는 시간입니다. 에이전트가 자체 도구 호출이나 [사용 한도 재설정](#when-a-run-hits-your-usage-limit)을 기다리는 데 보내는 시간은 정체 기간에 포함되지 않습니다.

473

474에이전트는 `r`로 요청한 재시작을 포함하여 최대 다섯 번까지 다시 시작합니다. 여섯 번째 시도도 멈추면 `agent()` 호출이 실패하며, 오류의 시작 부분에 그 이유가 표시됩니다:

475

476* `agent stalled on all 6 attempts`: 모든 시도가 정체 기간 내내 출력 없이 지나갔습니다. 에이전트의 작업 특성상 그만큼 오래 출력이 없는 경우 정체 기간을 늘립니다

477* `agent lost its reply on all 6 attempts`: 모든 시도의 응답 스트림이 멈췄고 Claude Code가 기다리기를 포기했습니다. [스트리밍 유휴 감시](/docs/ko/network-config#streaming-idle-watchdogs)가 먼저 응답을 종료했으므로 정체 기간을 늘려도 도움이 되지 않으며, 해당 감시의 타임아웃은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 설정합니다

478* `agent abandoned after 6 attempts`: 시도들이 서로 다른 방식으로 종료되었으며, 오류에 순서대로 나열됩니다

479

480정체 기간이 끝나기 전에 에이전트가 출력을 생성할 시간을 더 주려면:

481

482* **단일 에이전트**: 해당 에이전트의 `agent()` 호출에 `stallMs`를 밀리초 단위로 전달합니다. 예를 들어 30분의 경우 `agent(prompt, { stallMs: 1800000 })`입니다

483* **모든 에이전트**: [`CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`](/docs/ko/env-vars#variables)를 설정합니다. 이 값은 워크플로 외부의 서브에이전트에도 적용됩니다

484

485실패 후 실행이 계속되는지는 스크립트가 에이전트를 호출한 방식에 따라 달라집니다:

486

487* **[`parallel()` 또는 `pipeline()`](#what-the-saved-script-looks-like) 내부**: 에이전트의 결과 대신 `null`로 실행이 계속됩니다

488* **직접 await한 경우**: 실행이 오류와 함께 종료됩니다

489

490다시 시도하려면 Claude에게 워크플로를 다시 시작하도록 요청합니다. 무엇이 다시 실행되는지는 [일시 중지 후 재개](#resume-after-a-pause)에서 다룹니다.

491

466<h3 id="cost">492<h3 id="cost">

467 비용493 비용

468</h3>494</h3>

worktrees.md +1 −1

Details

104* **Git 리다이렉트**: Claude Code는 git을 메인 체크아웃으로 리다이렉트하는 Bash 또는 Monitor 명령을 차단합니다. 리다이렉트는 `git -C`, `--git-dir`, `GIT_DIR` 또는 `GIT_WORK_TREE` 변수, 또는 git을 실행하기 전에 메인 체크아웃으로 `cd`를 통해 올 수 있습니다.104* **Git 리다이렉트**: Claude Code는 git을 메인 체크아웃으로 리다이렉트하는 Bash 또는 Monitor 명령을 차단합니다. 리다이렉트는 `git -C`, `--git-dir`, `GIT_DIR` 또는 `GIT_WORK_TREE` 변수, 또는 git을 실행하기 전에 메인 체크아웃으로 `cd`를 통해 올 수 있습니다.

105* **명령 형태**: Claude Code는 명령 텍스트에서 명령이 실행하는 모든 git이 worktree 내부에 머물러 있는지 확인할 수 없을 때 Bash 또는 Monitor 명령을 차단합니다. 예를 들어 명령 이름이 런타임에 계산되거나 구문을 파싱할 수 없거나 `${!name}` 또는 `${ command; }`와 같은 확장이 텍스트에서 명시하지 않은 명령을 실행할 수 있을 때 발생합니다. Claude Code는 Claude에게 거부된 명령을 다시 작성하는 방법을 알려줍니다. 예를 들어 이를 일반 별도 명령으로 분할합니다. 이 확인을 끌 수 없습니다.105* **명령 형태**: Claude Code는 명령 텍스트에서 명령이 실행하는 모든 git이 worktree 내부에 머물러 있는지 확인할 수 없을 때 Bash 또는 Monitor 명령을 차단합니다. 예를 들어 명령 이름이 런타임에 계산되거나 구문을 파싱할 수 없거나 `${!name}` 또는 `${ command; }`와 같은 확장이 텍스트에서 명시하지 않은 명령을 실행할 수 있을 때 발생합니다. Claude Code는 Claude에게 거부된 명령을 다시 작성하는 방법을 알려줍니다. 예를 들어 이를 일반 별도 명령으로 분할합니다. 이 확인을 끌 수 없습니다.

106 106

107이러한 확인은 편집이 대상으로 하는 경로, 명령이 실행되는 디렉터리, 명령의 텍스트를 읽습니다. 어느 확인도 셸 명령이 어떤 파일에 쓰는지는 추적하지 않으므로, `cp`나 셸 리다이렉트처럼 메인 체크아웃에서 git을 실행하지 않고 메인 체크아웃에 쓰는 명령은 이 확인으로 거부되지 않습니다. Claude Code는 이러한 명령을 다른 셸 명령과 동일하게 취급하므로, 명령이 실행되는지 또는 확인을 요청하는지는 [권한 모드](/docs/ko/permission-modes)와 규칙에 따라 달라집니다.107이러한 확인은 편집이 대상으로 하는 경로, 명령이 실행되는 디렉터리, 명령의 텍스트를 읽습니다. 어느 확인도 셸 명령이 어떤 파일에 쓰는지는 추적하지 않으므로, `cp`나 셸 리다이렉트처럼 메인 체크아웃에서 git을 실행하지 않고 메인 체크아웃에 쓰는 명령은 이 확인으로 거부되지 않습니다. Claude Code는 이러한 명령을 [권한](/docs/ko/permissions) 및 [샌드박싱](/docs/ko/sandboxing) 설정에 따라 다른 셸 명령과 동일하게 취급합니다.

108 108

109확인은 Claude Code를 실행한 저장소에 적용됩니다. 또한 연결된 worktree가 연결된 메인 체크아웃도 포함합니다. PowerShell 명령의 경우 Claude Code는 작업 디렉토리 확인만 적용합니다.109확인은 Claude Code를 실행한 저장소에 적용됩니다. 또한 연결된 worktree가 연결된 메인 체크아웃도 포함합니다. PowerShell 명령의 경우 Claude Code는 작업 디렉토리 확인만 적용합니다.

110 110

Documentation 2026-10-08 22:58 UTC to 2026-10-09 22:01 UTC