Documentation 2026-10-06 23:59 UTC to 2026-10-07 14:00 UTC

140 ```140 ```

141</CodeGroup>141</CodeGroup>

142 142 

143스크립트를 실행하면 Claude가 `.env` 파일을 생성하려고 시도하고, 훅이 도구 호출을 거부하며, Claude의 최종 응답은 `.env` 파일을 생성할 수 없다고 설명합니다.143두 스크립트 중 어느 것을 실행하든 Claude가 `.env` 파일을 생성하려고 시도하고 훅이 도구 호출을 거부합니다.

144 144 

145<h2 id="available-hooks">145<h2 id="available-hooks">

146 사용 가능한 훅146 사용 가능한 훅

179| `ConfigChange` | 아니오 | 예 | 구성 파일 변경 | 동적으로 설정 다시 로드 |179| `ConfigChange` | 아니오 | 예 | 구성 파일 변경 | 동적으로 설정 다시 로드 |

180| `InstructionsLoaded` | 아니오 | 예 | `CLAUDE.md` 또는 규칙 파일이 컨텍스트에 로드됨 | 어떤 명령 파일이 로드되는지 감사 |180| `InstructionsLoaded` | 아니오 | 예 | `CLAUDE.md` 또는 규칙 파일이 컨텍스트에 로드됨 | 어떤 명령 파일이 로드되는지 감사 |

181| `WorktreeCreate` | 아니오 | 예 | Git worktree 생성 | 격리된 작업 공간 추적 |181| `WorktreeCreate` | 아니오 | 예 | Git worktree 생성 | 격리된 작업 공간 추적 |

182| `WorktreeRemove` | 아니오 | 예 | Git worktree 제거 | 작업 공간 리소스 정리 |182| `WorktreeRemove` | 아니오 | 예 | `WorktreeCreate` 훅으로 생성된 worktree가 제거되는 중 | 워크스페이스 리소스 정리 |

183| `CwdChanged` | 아니오 | 예 | 세션 중 작업 디렉토리가 변경됨 | 디렉토리별 환경 변수 다시 로드 |183| `CwdChanged` | 아니오 | 예 | 세션 중 작업 디렉토리가 변경됨 | 디렉토리별 환경 변수 다시 로드 |

184| `FileChanged` | 아니오 | 예 | 감시 중인 파일이 수정, 생성 또는 삭제됨 | 프로젝트 파일이 변경될 때 구성 다시 로드 |184| `FileChanged` | 아니오 | 예 | 감시 중인 파일이 수정, 생성 또는 삭제됨 | 프로젝트 파일이 변경될 때 구성 다시 로드 |

185| `DirectoryAdded` | 아니오 | 예 | 세션 중 작업 디렉토리가 추가됨 | 세션 중 추가된 저장소에 대한 종속성 설치 |185| `DirectoryAdded` | 아니오 | 예 | 세션 중 작업 디렉토리가 추가됨 | 세션 중 추가된 저장소에 대한 종속성 설치 |

219`hooks` 옵션은 다음과 같은 딕셔너리(Python) 또는 객체(TypeScript)입니다:219`hooks` 옵션은 다음과 같은 딕셔너리(Python) 또는 객체(TypeScript)입니다:

220 220 

221* **키**: [훅 이벤트 이름](#available-hooks)입니다(예: `'PreToolUse'`, `'PostToolUse'`, `'Stop'`).221* **키**: [훅 이벤트 이름](#available-hooks)입니다(예: `'PreToolUse'`, `'PostToolUse'`, `'Stop'`).

222* **값**: [매처](#matchers) 배열이며, 각각 선택적 필터 패턴과 [콜백 함수](#callback-functions)를 포함합니다.222* **값**: [matcher](#matchers) 배열이며, 각각 선택적 필터 패턴과 [콜백 함수](#callback-functions)를 포함합니다.

223 223 

224<h3 id="matchers">224<h3 id="matchers">

225 매처225 Matcher

226</h3>226</h3>

227 227 

228매처를 사용하여 콜백이 발생할 때를 필터링합니다. `matcher` 필드는 훅 이벤트 유형에 따라 다른 값과 일치합니다. 예를 들어 도구 기반 훅은 도구 이름과 일치하고, `Notification` 훅은 알림 유형과 일치합니다.228매처를 사용하여 콜백이 발생할 때를 필터링합니다. `matcher` 필드는 훅 이벤트 유형에 따라 다른 값과 일치합니다. 예를 들어 도구 기반 훅은 도구 이름과 일치하고, `Notification` 훅은 알림 유형과 일치합니다.

259 259 

260콜백은 두 가지 필드 범주를 포함하는 객체를 반환합니다:260콜백은 두 가지 필드 범주를 포함하는 객체를 반환합니다:

261 261 

262* **최상위 필드**는 모든 이벤트에서 동일하게 작동합니다: `systemMessage`는 사용자에게 메시지를 표시하고, `continue`(Python에서는 `continue_`)는 이 훅 후에 에이전트가 계속 실행되는지 여부를 결정합니다. 일부 이벤트는 이들을 버리거나 다른 곳에 전달합니다. 각 [이벤트의 섹션](/docs/ko/hooks#hook-events)에서 훅 페이지에 이들이 어디에 도착하는지 설명합니다.262* **최상위 필드**는 모든 이벤트에서 허용됩니다: `systemMessage`는 사용자에게 메시지를 표시하고, `continue`(Python에서는 `continue_`)는 이 훅 후에 에이전트가 계속 실행되는지 여부를 결정합니다. 일부 이벤트는 이들을 버리거나 다른 곳에 전달합니다. 훅 페이지의 각 [이벤트 섹션](/docs/ko/hooks#hook-events)에서 이들이 어디로 전달되는지 설명합니다.

263* \*\*`hookSpecificOutput`\*\*은 현재 작업을 제어합니다. 내부의 필드는 훅 이벤트 유형에 따라 다릅니다:263* \*\*`hookSpecificOutput`\*\*은 현재 작업을 제어합니다. 내부의 필드는 훅 이벤트 유형에 따라 다릅니다:

264 * `PreToolUse` 훅의 경우 `permissionDecision`(`"allow"`, `"deny"`, `"ask"`, 또는 `"defer"`), `permissionDecisionReason`, `updatedInput`을 설정하는 곳입니다. `"defer"`를 반환하면 `stop_reason`이 `"tool_deferred"`인 결과 메시지와 함께 턴이 종료되므로 [나중에 호출을 재개](/docs/ko/hooks#defer-a-tool-call-for-later)할 수 있습니다.264 * `PreToolUse` 훅의 경우 `permissionDecision`(`"allow"`, `"deny"`, `"ask"`, 또는 `"defer"`), `permissionDecisionReason`, `updatedInput`을 설정하는 곳입니다. `"defer"`를 반환하면 `stop_reason`이 `"tool_deferred"`인 결과 메시지와 함께 턴이 종료되므로 [나중에 호출을 재개](/docs/ko/hooks#defer-a-tool-call-for-later)할 수 있습니다.

265 * `PostToolUse` 훅의 경우 `additionalContext`를 설정하여 도구 결과에 정보를 추가할 수 있습니다. 도구의 출력을 Claude가 보기 전에 바꾸려면 `updatedToolOutput`을 설정합니다. 이는 두 SDK 모두에서 모든 도구에 대해 작동합니다. 더 오래된 `updatedMCPToolOutput` 필드는 MCP 도구 출력만 바꾸며 deprecated되었습니다.265 * `PostToolUse` 훅의 경우 `additionalContext`를 설정하여 도구 결과에 정보를 추가할 수 있습니다. 도구의 출력을 Claude가 보기 전에 바꾸려면 `updatedToolOutput`을 설정합니다. 이는 두 SDK 모두에서 모든 도구에 대해 작동합니다. 더 오래된 `updatedMCPToolOutput` 필드는 MCP 도구 출력만 바꿉니다.

266 * TypeScript SDK에서 `PostToolUse` 콜백은 또한 `classifierContext`를 반환할 수 있습니다. 이는 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 권한 분류기를 위한 도구 호출 결과에 대한 짧은 메모입니다. 콜백이 애플리케이션의 자체 프로세스에서 실행되므로 분류기는 메모에서 전달하는 사용자 진술을 사용자 의도로 가중치를 둘 수 있습니다. 이 필드는 TypeScript Agent SDK v0.3.236 이상이 필요합니다. [자동 모드 분류기를 위한 결과 주석 달기](/docs/ko/hooks#annotate-a-result-for-the-auto-mode-classifier)에서 길이 제한, 동기 전용 규칙, 메모에 포함하지 말아야 할 내용을 다룹니다.266 * TypeScript SDK에서 `PostToolUse` 콜백은 또한 `classifierContext`를 반환할 수 있습니다. 이는 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 권한 분류기를 위한 도구 호출 결과에 대한 짧은 메모입니다. 콜백이 애플리케이션의 자체 프로세스에서 실행되므로 분류기는 메모에서 전달하는 사용자 진술을 사용자 의도로 가중치를 둘 수 있습니다. 이 필드는 TypeScript Agent SDK v0.3.236 이상이 필요합니다. [자동 모드 분류기를 위한 결과 주석 달기](/docs/ko/hooks#annotate-a-result-for-the-auto-mode-classifier)에서 길이 제한, 동기 전용 규칙, 메모에 포함하지 말아야 할 내용을 다룹니다.

267 267 

268변경 없이 작업을 허용하려면 `{}`를 반환합니다. SDK 콜백 훅은 [Claude Code 셸 명령 훅](/docs/ko/hooks#json-output)과 동일한 JSON 출력 형식을 사용하며, 이는 모든 필드와 이벤트별 옵션을 문서화합니다. SDK 타입 정의는 [TypeScript](/docs/ko/agent-sdk/typescript#synchookjsonoutput) 및 [Python](/docs/ko/agent-sdk/python#synchookjsonoutput) SDK 참조를 참조하세요.268변경 없이 작업을 허용하려면 `{}`를 반환합니다. SDK 콜백 훅은 [Claude Code 셸 명령 훅](/docs/ko/hooks#json-output)과 동일한 JSON 출력 형식을 사용하며, 이는 모든 필드와 이벤트별 옵션을 문서화합니다. SDK 타입 정의는 [TypeScript](/docs/ko/agent-sdk/typescript#synchookjsonoutput) 및 [Python](/docs/ko/agent-sdk/python#synchookjsonoutput) SDK 참조를 참조하세요.

840* `PreModelSwitch`: Claude Code는 모델 전환을 차단합니다. 응답하지 않는 훅은 전환을 승인하지 않았습니다.840* `PreModelSwitch`: Claude Code는 모델 전환을 차단합니다. 응답하지 않는 훅은 전환을 승인하지 않았습니다.

841* `Notification`, `PreCompact`, `PostModelSwitch` 같은 다른 이벤트: Claude Code는 실패를 기록하고 계속됩니다.841* `Notification`, `PreCompact`, `PostModelSwitch` 같은 다른 이벤트: Claude Code는 실패를 기록하고 계속됩니다.

842 842 

843주 세션에서 `Stop` 또는 `SessionStart` 콜백이 처음 타임아웃되면 Claude Code는 또한 앱이 세션을 구동하는 것이 응답하지 않았다고 말하는 [`SDKInformationalMessage`](/docs/ko/agent-sdk/typescript#sdkinformationalmessage)를 메시지 스트림에 추가합니다. 앱이 응답하지 않은 상태로 유지되는 동안 이후 타임아웃은 해당 메시지를 반복하지 않습니다.843주 세션에서 `Stop` 또는 `SessionStart` 콜백이 처음 타임아웃되면 Claude Code는 또한 세션을 구동하는 앱이 응답하지 않았다는 [`SDKInformationalMessage`](/docs/ko/agent-sdk/typescript#sdkinformationalmessage)를 메시지 스트림에 추가합니다. 앱이 응답하지 않은 상태로 유지되는 동안 이후 타임아웃은 해당 메시지를 반복하지 않습니다.

844 844 

845콜백이 대기 중인 동안 쿼리를 중단하면 Claude Code는 대기 중인 도구 호출을 취소합니다. v2.1.208 이전에는 대기 중인 `PreToolUse` 콜백 중에 중단하면 도구 호출이 진행될 수 있었습니다.845콜백이 대기 중인 동안 쿼리를 중단하면 Claude Code는 대기 중인 도구 호출을 취소합니다. v2.1.208 이전에는 대기 중인 `PreToolUse` 콜백 중에 중단하면 도구 호출이 진행될 수 있었습니다.

846 846 

878 Python에서 세션 훅을 사용할 수 없음878 Python에서 세션 훅을 사용할 수 없음

879</h3>879</h3>

880 880 

881`SessionStart` 및 `SessionEnd`는 TypeScript에서 SDK 콜백 훅으로 등록할 수 있지만 Python SDK에서는 사용할 수 없습니다(`HookEvent` 유형이 이를 생략합니다). Python에서는 설정 파일(예: `.claude/settings.json`)에 정의된 [셸 명령 훅](/docs/ko/hooks#hook-events)으로만 사용 가능합니다. SDK 애플리케이션에서 셸 명령 훅을 로드하려면 [`setting_sources`](/docs/ko/agent-sdk/python#settingsource) 또는 [`settingSources`](/docs/ko/agent-sdk/typescript#settingsource)를 사용하여 적절한 설정 소스를 포함합니다:881`SessionStart` 및 `SessionEnd`는 TypeScript에서 SDK 콜백 훅으로 등록할 수 있지만 Python SDK에서는 사용할 수 없습니다(`HookEvent` 유형이 이를 생략합니다). Python에서는 설정 파일(예: `.claude/settings.json`)에 정의된 [셸 명령 훅](/docs/ko/hooks#hook-events)으로만 사용 가능합니다. SDK 애플리케이션이 어떤 설정 파일을 로드하는지는 [`setting_sources`](/docs/ko/agent-sdk/python#settingsource) 또는 [`settingSources`](/docs/ko/agent-sdk/typescript#settingsource)에 따라 달라집니다. 해당 옵션을 설정하는 경우 훅이 포함된 소스를 포함합니다:

882 882 

883<CodeGroup>883<CodeGroup>

884 ```python Python theme={null}884 ```python Python theme={null}

915 systemMessage가 출력에 나타나지 않음915 systemMessage가 출력에 나타나지 않음

916</h3>916</h3>

917 917 

918`systemMessage` 필드는 사용자에게 메시지를 표시합니다. Claude Code v2.1.227 이상에서는 훅의 `systemMessage`가 메시지 스트림에 [`SDKInformationalMessage`](/docs/ko/agent-sdk/typescript#sdkinformationalmessage)로 표시될 수 있습니다. 표시 여부는 이벤트에 따라 다릅니다. 훅 페이지의 각 [이벤트 섹션](/docs/ko/hooks#hook-events)에서 출력이 어떻게 표시되는지 설명합니다. 대신 모델에 컨텍스트를 전달하려면 [`additionalContext`](/docs/ko/hooks#add-context-for-claude)를 반환합니다.918`systemMessage` 필드는 모델이 아닌 사용자에게 메시지를 표시합니다. Claude Code v2.1.227 이상에서는 훅의 `systemMessage`가 메시지 스트림에 [`SDKInformationalMessage`](/docs/ko/agent-sdk/typescript#sdkinformationalmessage)로 표시될 수 있습니다. 표시 여부는 이벤트에 따라 다릅니다. 훅 페이지의 각 [이벤트 섹션](/docs/ko/hooks#hook-events)에서 출력이 어떻게 표시되는지 설명합니다. 대신 모델에 컨텍스트를 전달하려면 [`additionalContext`](/docs/ko/hooks#add-context-for-claude)를 반환합니다.

919 919 

920v2.1.227 이전에는 SDK가 메시지 스트림에서 훅 출력을 `SessionStart` 및 `Setup` 훅에만 표시했습니다. 다른 이벤트의 경우 출력은 [`includeHookEvents`](/docs/ko/agent-sdk/typescript#options)(`Python에서는 include_hook_events`)가 추가하는 라이프사이클 이벤트에만 나타났습니다. 해당 옵션의 항목은 각 훅 이벤트가 생성하는 라이프사이클 이벤트를 다룹니다.920v2.1.227 이전에는 SDK가 메시지 스트림에서 훅 출력을 `SessionStart` 및 `Setup` 훅에만 표시했습니다. 다른 이벤트의 경우 출력은 [`includeHookEvents`](/docs/ko/agent-sdk/typescript#options)(Python에서는 `include_hook_events`)가 추가하는 라이프사이클 이벤트에만 나타났습니다. 해당 옵션의 항목은 각 훅 이벤트가 생성하는 라이프사이클 이벤트를 다룹니다.

921 921 

922훅 결정을 애플리케이션에 안정적으로 표시해야 하면 별도로 기록하거나 전용 출력 채널을 사용합니다.922훅 결정을 애플리케이션에 안정적으로 표시해야 하면 별도로 기록하거나 전용 출력 채널을 사용합니다.

923 923 

194 `ToolAnnotations`194 `ToolAnnotations`

195</h4>195</h4>

196 196 

197[`tool()`](#tool)의 `annotations` 인수로 전달되는 도구의 동작 힌트입니다. `ToolAnnotations`는 MCP SDK의 `mcp.types.ToolAnnotations`를 `maxResultSizeChars` 필드로 확장하며, 각 힌트를 camelCase 또는 snake\_case로 작성할 수 있습니다: `ToolAnnotations(readOnlyHint=True)`와 `ToolAnnotations(read_only_hint=True)`는 동등합니다. SDK가 주석을 허용하는 곳에 일반 `mcp.types.ToolAnnotations`를 전달할 수도 있습니다.197[`tool()`](#tool)의 `annotations` 인수로 전달되는 도구의 동작 힌트입니다. `ToolAnnotations`는 MCP SDK의 `mcp.types.ToolAnnotations`를 `maxResultSizeChars` 필드로 확장하며, 각 힌트를 camelCase 또는 snake\_case로 작성할 수 있습니다: `ToolAnnotations(readOnlyHint=True)`와 `ToolAnnotations(read_only_hint=True)`는 동등합니다. 객체에서 힌트를 다시 읽으려면 설치된 `mcp` 패키지가 선언하는 표기를 사용합니다: `mcp` 1.x에서는 `.readOnlyHint`, 2.x에서는 `.read_only_hint`를 사용하며, `.maxResultSizeChars`는 두 버전 모두에서 작동합니다. SDK가 주석을 허용하는 곳에 일반 `mcp.types.ToolAnnotations`를 전달할 수도 있습니다.

198 198 

199snake\_case 이름과 타입이 지정된 `maxResultSizeChars` 필드는 Python Agent SDK 0.2.140 이상이 필요합니다. 버전 0.1.31부터 0.2.139까지는 `mcp.types.ToolAnnotations`를 변경하지 않고 다시 내보냅니다. 버전 0.1.55부터 0.2.139까지는 여전히 `maxResultSizeChars`를 키워드 인수로 전달할 수 있습니다: MCP 클래스는 추가 필드를 허용하고 SDK는 값을 Claude Code로 전달합니다.199snake\_case 이름과 타입이 지정된 `maxResultSizeChars` 필드는 Python Agent SDK 0.2.140 이상이 필요합니다. 버전 0.1.31부터 0.2.139까지는 `mcp.types.ToolAnnotations`를 변경하지 않고 다시 내보냅니다. 버전 0.1.55부터 0.2.139까지는 여전히 `maxResultSizeChars`를 키워드 인수로 전달할 수 있습니다: MCP 클래스는 추가 필드를 허용하고 SDK는 값을 Claude Code로 전달합니다.

200 200 

1465| `enabled` | `type`, `budget_tokens`, `display` | 특정 토큰 예산으로 생각 활성화 |1465| `enabled` | `type`, `budget_tokens`, `display` | 특정 토큰 예산으로 생각 활성화 |

1466| `disabled` | `type` | 생각 비활성화 |1466| `disabled` | `type` | 생각 비활성화 |

1467 1467 

1468선택적 `display` 필드는 생각 텍스트가 `"summarized"` 또는 `"omitted"`로 반환되는지 제어합니다. Claude Opus 4.7 이상에서 API 기본값은 `"omitted"`이므로, [`ThinkingBlock`](#thinkingblock) 출력에서 생각 콘텐츠를 받으려면 `"summarized"`를 설정합니다. Claude Code는 Amazon Bedrock 또는 Google Cloud의 Agent Platform에 `display`를 전송하지 않으므로, 이 공급자에서 Opus 4.7 이상은 `display`를 `"summarized"`로 설정하더라도 빈 `ThinkingBlock` 출력을 반환합니다.1468선택적 `display` 필드는 사고 텍스트가 `"summarized"` 또는 `"omitted"`로 반환되는지 제어합니다. Claude Opus 4.7 이상에서 API 기본값은 `"omitted"`이므로, [`ThinkingBlock`](#thinkingblock) 출력에서 사고 콘텐츠를 받으려면 `"summarized"`를 설정합니다. Claude Code는 Amazon Bedrock 및 Google Cloud의 Agent Platform과 같은 일부 공급자에 대한 요청에서 `display`를 제외합니다. 이러한 공급자에서 Opus 4.7 이상은 `display`를 `"summarized"`로 설정하더라도 빈 `ThinkingBlock` 출력을 반환합니다.

1469 1469 

1470이들은 `TypedDict` 클래스이므로 런타임에 일반 dict입니다. dict 리터럴로 구성하거나 클래스를 생성자처럼 호출합니다. 둘 다 `dict`를 생성합니다. `config.budget_tokens`가 아닌 `config["budget_tokens"]`로 필드에 접근합니다:1470이들은 `TypedDict` 클래스이므로 런타임에 일반 dict입니다. dict 리터럴로 구성하거나 클래스를 생성자처럼 호출합니다. 둘 다 `dict`를 생성합니다. `config.budget_tokens`가 아닌 `config["budget_tokens"]`로 필드에 접근합니다:

1471 1471 

1875| `maxOutputTokens` | `int` | 이 모델의 최대 출력 토큰 제한입니다. |1875| `maxOutputTokens` | `int` | 이 모델의 최대 출력 토큰 제한입니다. |

1876| `canonicalModel` | `str` | 가격 조회에 사용된 정규 모델 ID입니다. 공급자별 ID 또는 별칭과 같은 원본 모델 문자열과 다를 수 있습니다. 항상 존재하지는 않습니다. |1876| `canonicalModel` | `str` | 가격 조회에 사용된 정규 모델 ID입니다. 공급자별 ID 또는 별칭과 같은 원본 모델 문자열과 다를 수 있습니다. 항상 존재하지는 않습니다. |

1877| `provider` | `str` | 이 모델을 제공한 API 공급자입니다 (예: `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle` 또는 `gateway`). 항상 존재하지는 않습니다. |1877| `provider` | `str` | 이 모델을 제공한 API 공급자입니다 (예: `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle` 또는 `gateway`). 항상 존재하지는 않습니다. |

1878| `costBasis` | `str` | 이 모델의 최신 요청 가격을 책정한 가격표입니다: 정가의 경우 `list`, [`modelPricing`](/docs/ko/settings-reference#modelpricing) 테이블의 경우 `managed`, 둘 다 모델 ID와 일치하지 않는 경우 `unknown`입니다. 항상 존재하지는 않으며, TypedDict에 선언되지 않으므로 `.get()`으로 읽으십시오. Claude Code v2.1.246 이상이 필요합니다. |

1878 1879 

1879<h3 id="streamevent">1880<h3 id="streamevent">

1880 `StreamEvent`1881 `StreamEvent`

2166 """Base error for Claude SDK."""2167 """Base error for Claude SDK."""

2167```2168```

2168 2169 

2169단일 `query()`가 오류 결과로 끝날 때(예: 턴 제한 오류), SDK는 최종 결과 메시지를 생성한 후 [`ResultError`](#resulterror)를 발생시킵니다. Python Agent SDK 0.2.140 이전 버전은 `ClaudeSDKError` 서브클래스가 아닌 일반 `Exception`을 발생시켰습니다.2170단일 `query()`가 오류 결과로 끝나면(예: 턴 제한 오류) SDK는 [`ResultError`](#resulterror)를 발생시킵니다.

2170 2171 

2171<h3 id="clinotfounderror">2172<h3 id="clinotfounderror">

2172 `CLINotFoundError`2173 `CLINotFoundError`

2216 `ResultError`2217 `ResultError`

2217</h3>2218</h3>

2218 2219 

2219Claude Code 프로세스가 턴 제한 오류 또는 API 오류와 같은 오류 결과로 실행이 종료되어 최종 [`ResultMessage`](#resultmessage) 후에 발생합니다. `ResultError`는 `ProcessError`의 서브클래스이므로 기존 `except ProcessError` 핸들러도 이를 포착합니다. 해당 속성은 결과 메시지의 필드를 포함하므로 메시지 텍스트를 구문 분석하지 않고도 실행이 실패한 이유에 따라 분기할 수 있습니다. Python Agent SDK 0.2.140 이상이 필요합니다.2220턴 제한 오류 또는 API 오류와 같은 오류 [결과 메시지](#resultmessage)로 실행이 끝나 Claude Code 프로세스가 종료될 때 발생합니다. `ResultError`는 `ProcessError`의 서브클래스이므로 기존 `except ProcessError` 핸들러도 이를 포착합니다. 해당 속성은 결과 메시지의 필드를 포함하므로 메시지 텍스트를 구문 분석하지 않고도 실행이 실패한 이유에 따라 분기할 수 있습니다. Python Agent SDK 0.2.140 이상이 필요합니다.

2220 2221 

2221```python theme={null}2222```python theme={null}

2222class ResultError(ProcessError):2223class ResultError(ProcessError):

2649 hookEventName: Literal["PostToolUse"]2650 hookEventName: Literal["PostToolUse"]

2650 additionalContext: NotRequired[str]2651 additionalContext: NotRequired[str]

2651 updatedToolOutput: NotRequired[Any]2652 updatedToolOutput: NotRequired[Any]

2652 updatedMCPToolOutput: NotRequired[Any] # Deprecated: use updatedToolOutput, which works for all tools2653 updatedMCPToolOutput: NotRequired[Any] # MCP tools only. Prefer updatedToolOutput, which works for all tools

2653 2654 

2654 2655 

2655class PostToolUseFailureHookSpecificOutput(TypedDict):2656class PostToolUseFailureHookSpecificOutput(TypedDict):

2767 도구 입력/출력 타입2768 도구 입력/출력 타입

2768</h2>2769</h2>

2769 2770 

2770모든 기본 Claude Code 도구의 입력/출력 스키마 문서입니다. Python SDK는 이들을 타입으로 내보내지 않지만, 메시지의 도구 입력 및 출력 구조를 나타냅니다.2771기본 제공 Claude Code 도구의 입력/출력 스키마 문서입니다. Python SDK는 이들을 타입으로 내보내지 않지만, 메시지의 도구 입력 및 출력 구조를 나타냅니다.

2771 2772 

2772각 출력은 해당 도구에 대해 [`UserMessage.tool_use_result`](#usermessage)에서 읽는 값입니다. 키 이름은 Claude Code가 내보내는 그대로 나타납니다. `| None`으로 주석이 달린 키와 "present when" 또는 "optional" 주석이 있는 키는 적용되지 않을 때 생략됩니다.2773각 출력은 해당 도구에 대해 [`UserMessage.tool_use_result`](#usermessage)에서 읽는 값입니다. 키 이름은 Claude Code가 내보내는 그대로 나타납니다. `| None`으로 주석이 달린 키와 "present when" 또는 "optional" 주석이 있는 키는 적용되지 않을 때 생략됩니다.

2773 2774 

60 60 

61구조화된 출력을 사용하려면 원하는 데이터의 형태를 설명하는 [JSON Schema](https://json-schema.org/understanding-json-schema/about)를 정의한 다음, `outputFormat` 옵션(TypeScript) 또는 `output_format` 옵션(Python)을 통해 `query()`에 전달합니다. 에이전트가 완료되면 결과 메시지에 스키마와 일치하는 검증된 데이터가 포함된 `structured_output` 필드가 포함됩니다.61구조화된 출력을 사용하려면 원하는 데이터의 형태를 설명하는 [JSON Schema](https://json-schema.org/understanding-json-schema/about)를 정의한 다음, `outputFormat` 옵션(TypeScript) 또는 `output_format` 옵션(Python)을 통해 `query()`에 전달합니다. 에이전트가 완료되면 결과 메시지에 스키마와 일치하는 검증된 데이터가 포함된 `structured_output` 필드가 포함됩니다.

62 62 

63아래 예제는 에이전트에 Anthropic을 조사하고 회사명, 설립 연도 및 본사를 구조화된 출력으로 반환하도록 요청합니다.63이 페이지의 예제를 실행하기 전에 [빠른 시작](/docs/ko/agent-sdk/quickstart#setup)에 따라 Claude Agent SDK를 설치합니다. 아래 예제는 에이전트에 Anthropic을 조사하고 회사명, 설립 연도 및 본사를 구조화된 출력으로 반환하도록 요청합니다.

64 64 

65<CodeGroup>65<CodeGroup>

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

388 오류 처리388 오류 처리

389</h2>389</h2>

390 390 

391구조화된 출력 생성은 에이전트가 스키마와 일치하는 유효한 JSON을 생성할 수 없을 때 실패할 수 있습니다. 이는 일반적으로 스키마가 작업에 너무 복잡하거나, 작업 자체가 모호하거나, 에이전트가 검증 오류를 수정하려고 시도하는 동안 재시도 제한에 도달할 때 발생합니다. 또한 검증 실패 없이도 발생할 수 있습니다: [모델 폴백](/docs/ko/model-config#automatic-model-fallback)은 이미 완료된 출력을 스트림 중간에 취소할 수 있으며, 재시도가 이를 대체하지 않으면 실행이 동일한 오류로 종료됩니다. 디버깅하기 전에 결과 메시지의 `errors` 목록을 확인하여 두 가지 원인을 구분하십시오.391구조화된 출력 생성은 에이전트가 스키마와 일치하는 유효한 JSON을 생성할 수 없을 때 실패할 수 있습니다. 이는 일반적으로 스키마가 작업에 너무 복잡하거나, 작업 자체가 모호하거나, 에이전트가 검증 오류를 수정하려고 시도하는 동안 재시도 제한에 도달할 때 발생합니다. 또한 검증 실패 없이도 발생할 수 있습니다: [모델 폴백](/docs/ko/model-config#automatic-model-fallback)은 이미 완료된 출력을 스트림 중간에 취소할 수 있으며, 재시도가 이를 대체하지 않으면 실행이 동일한 오류로 종료됩니다. 스키마를 디버깅하기 전에 오류 결과 메시지의 `errors` 목록을 확인하여 두 가지 원인을 구분하십시오.

392 392 

393오류가 발생하면 결과 메시지에 무엇이 잘못되었는지 나타내는 `subtype`이 있습니다:393오류가 발생하면 결과 메시지에 무엇이 잘못되었는지 나타내는 `subtype`이 있습니다:

394 394 

186 console.error("Claim failed:", error.message);186 console.error("Claim failed:", error.message);

187});187});

188 188 

189for await (const message of claimedQuery) {189try {

190 for await (const message of claimedQuery) {

190 console.log(message);191 console.log(message);

192 }

193} catch (error) {

194 // 클레임이 거부된 후, 클레임된 쿼리는 오류 결과를 생성한 뒤 throw합니다

195 console.error(`Session ended with an error: ${error}`);

191}196}

192```197```

193 198 

717| `accountInfo()` | 계정 정보를 반환합니다 |722| `accountInfo()` | 계정 정보를 반환합니다 |

718| `reconnectMcpServer(serverName)` | 이름으로 MCP 서버를 다시 연결합니다. 이름이 `.mcp.json` 또는 `~/.claude.json`과 같은 설정 파일의 항목과도 일치하는 경우, Claude Code는 설정 파일 항목이 아니라 [`mcpServers`](#options) 또는 `setMcpServers()`를 통해 구성한 서버를 다시 연결합니다. 이 확인 순서는 Claude Code v2.1.257 이상이 필요합니다 |723| `reconnectMcpServer(serverName)` | 이름으로 MCP 서버를 다시 연결합니다. 이름이 `.mcp.json` 또는 `~/.claude.json`과 같은 설정 파일의 항목과도 일치하는 경우, Claude Code는 설정 파일 항목이 아니라 [`mcpServers`](#options) 또는 `setMcpServers()`를 통해 구성한 서버를 다시 연결합니다. 이 확인 순서는 Claude Code v2.1.257 이상이 필요합니다 |

719| `toggleMcpServer(serverName, enabled)` | `reconnectMcpServer()`와 동일한 이름 확인 방식으로, 이름으로 MCP 서버를 활성화하거나 비활성화합니다. 서버를 비활성화하면 연결이 끊기고 해당 도구가 제거됩니다. 서버 종류별로 필요한 Claude Code 버전은 [`toggleMcpServer()`](#togglemcpserver)를 참조하세요 |724| `toggleMcpServer(serverName, enabled)` | `reconnectMcpServer()`와 동일한 이름 확인 방식으로, 이름으로 MCP 서버를 활성화하거나 비활성화합니다. 서버를 비활성화하면 연결이 끊기고 해당 도구가 제거됩니다. 서버 종류별로 필요한 Claude Code 버전은 [`toggleMcpServer()`](#togglemcpserver)를 참조하세요 |

720| `setMcpServers(servers)` | 이 세션의 MCP 서버 집합을 동적으로 교체합니다. 추가 및 제거된 서버와 오류를 알려 주는 [`McpSetServersResult`](#mcpsetserversresult)로 resolve됩니다 |725| `setMcpServers(servers)` | 이 메서드가 관리하는 MCP 서버, 즉 이 메서드로 추가한 서버와 [인프로세스 SDK 서버](#createsdkmcpserver)를 교체합니다. 추가 및 제거된 서버와 오류를 명시하는 [`McpSetServersResult`](#mcpsetserversresult)로 resolve됩니다. 연결 상태가 유지되는 다른 서버는 해당 섹션에서 설명합니다 |

721| `readMcpResource(serverName, uri)` | *Alpha.* 애플리케이션이 도구의 위젯을 렌더링할 수 있도록 연결된 MCP 서버에서 MCP Apps `ui://` 리소스 하나를 읽습니다. [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse)로 resolve됩니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다 |726| `readMcpResource(serverName, uri)` | *Alpha.* 애플리케이션이 도구의 위젯을 렌더링할 수 있도록 연결된 MCP 서버에서 MCP Apps `ui://` 리소스 하나를 읽습니다. [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse)로 resolve됩니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다 |

722| `streamInput(stream)` | 멀티턴 대화를 위해 입력 메시지를 쿼리로 스트리밍합니다 |727| `streamInput(stream)` | 멀티턴 대화를 위해 입력 메시지를 쿼리로 스트리밍합니다 |

723| `stopTask(taskId)` | ID로 실행 중인 백그라운드 작업을 중지합니다 |728| `stopTask(taskId)` | ID로 실행 중인 백그라운드 작업을 중지합니다 |

844 849 

845`options.cwd`는 필수입니다. 클레임에서는 `additionalDirectories`, `model`, `permissionMode`, `maxThinkingTokens`, `settings`의 플래그 설정 오버레이, `appendSystemPrompt`, `title`, `agents`, `env`의 세션별 토큰도 설정할 수 있습니다.850`options.cwd`는 필수입니다. 클레임에서는 `additionalDirectories`, `model`, `permissionMode`, `maxThinkingTokens`, `settings`의 플래그 설정 오버레이, `appendSystemPrompt`, `title`, `agents`, `env`의 세션별 토큰도 설정할 수 있습니다.

846 851 

847Claude Code는 존재하지 않는 폴더나 프로젝트 설정에서 `env`, `agent` 또는 `model`을 설정하는 폴더 등에 대해 클레임을 거부할 수 있습니다. `claimed`가 `option_not_applied`로 시작하는 메시지와 함께 reject되면, 세션은 요청한 `model` 또는 `maxThinkingTokens` 없이 실행 중입니다. 그 외의 거부 이후에는 프롬프트가 실행되지 않았으므로, 대신 `query()`로 세션을 시작하세요.852Claude Code는 존재하지 않는 폴더나 프로젝트 설정이 `env`, `agent` 또는 `model`을 설정하는 폴더 등에 대해 claim을 거부할 수 있습니다. 거부된 후에는 `claim()`이 이미 보낸 프롬프트가 `not_claimed`로 시작하는 텍스트의 오류 결과를 받고, 반환된 쿼리는 예외를 발생시킵니다. 예외 이후에도 계속 진행하려면 쿼리의 루프를 try 블록으로 감싸세요. `claimed`가 `option_not_applied`로 시작하는 메시지와 함께 reject되면, 세션은 요청한 `model` 또는 `maxThinkingTokens` 없이 실행 중입니다. 그 외의 reject 이후에는 프롬프트가 실행되지 않았으므로 대신 `query()`로 세션을 시작하세요.

848 853 

849<h3 id="sdkcontrolinitializeresponse">854<h3 id="sdkcontrolinitializeresponse">

850 `SDKControlInitializeResponse`855 `SDKControlInitializeResponse`

1337| `mcpServer` | `{ name: string; source: string }` | `mcp__*` 도구의 경우, 해당 도구를 제공하는 MCP 서버와 그 서버 정의의 출처로, [`McpServerProvenance`](#mcpserverprovenance)의 필드를 가집니다. 다른 도구에서는 없습니다. Agent SDK v0.3.274 이상이 필요합니다 |1342| `mcpServer` | `{ name: string; source: string }` | `mcp__*` 도구의 경우, 해당 도구를 제공하는 MCP 서버와 그 서버 정의의 출처로, [`McpServerProvenance`](#mcpserverprovenance)의 필드를 가집니다. 다른 도구에서는 없습니다. Agent SDK v0.3.274 이상이 필요합니다 |

1338| `decisionReason` | `string` | 이 권한 요청이 트리거된 이유를 설명 |1343| `decisionReason` | `string` | 이 권한 요청이 트리거된 이유를 설명 |

1339| `defaultToNo` | `boolean` | `true`이면 실수로 누른 키 하나로 이 요청이 승인되어서는 안 됩니다. 프롬프트를 거부 옵션에 포커스된 상태로 열고, 승인을 미리 선택하지 말며, 한 번의 키 입력으로 승인하는 단축키를 제공하지 마세요. Agent SDK v0.3.268 이상이 필요합니다 |1344| `defaultToNo` | `boolean` | `true`이면 실수로 누른 키 하나로 이 요청이 승인되어서는 안 됩니다. 프롬프트를 거부 옵션에 포커스된 상태로 열고, 승인을 미리 선택하지 말며, 한 번의 키 입력으로 승인하는 단축키를 제공하지 마세요. Agent SDK v0.3.268 이상이 필요합니다 |

1340| `suppressAlwaysAllowRule` | `boolean` | `true`이면 이 요청에 대해 영구적인 항상 허용 선택지를 제공하지 마세요. 해당 선택지가 기록할 규칙이 요청 자체의 작업보다 더 많은 권한을 부여하기 때문입니다. Agent SDK v0.3.268 이상이 필요합니다 |1345| `suppressAlwaysAllowRule` | `boolean` | `true`이면 이 요청에 대해 영구적인 항상 허용 선택지를 제공하지 마세요. Agent SDK v0.3.268 이상이 필요합니다 |

1341| `toolUseID` | `string` | 어시스턴트 메시지 내에서 이 특정 도구 호출의 고유 식별자 |1346| `toolUseID` | `string` | 어시스턴트 메시지 내에서 이 특정 도구 호출의 고유 식별자 |

1342| `agentID` | `string` | 서브에이전트 내에서 실행 중인 경우, 서브에이전트의 ID |1347| `agentID` | `string` | 서브에이전트 내에서 실행 중인 경우, 서브에이전트의 ID |

1343| `requestId` | `string` | `control_request` 엔벨로프의 `request_id`. 서명된 HTTP POST처럼 애플리케이션이 SDK 외부에서 보내는 `control_response`는 Claude Code 프로세스가 응답을 요청과 매칭할 수 있도록 이 값을 그대로 포함해야 합니다 |1348| `requestId` | `string` | `control_request` 엔벨로프의 `request_id`. 서명된 HTTP POST처럼 애플리케이션이 SDK 외부에서 보내는 `control_response`는 Claude Code 프로세스가 응답을 요청과 매칭할 수 있도록 이 값을 그대로 포함해야 합니다 |

5457 | { type: "disabled" }; // 확장 사고 없음5462 | { type: "disabled" }; // 확장 사고 없음

5458```5463```

5459 5464 

5460선택적 `display` 필드는 사고 텍스트가 `"summarized"` 또는 `"omitted"`로 반환되는지 제어합니다. Claude Opus 4.7 이상에서 API 기본값은 `"omitted"`이므로, `thinking` 블록에서 사고 콘텐츠를 받으려면 `"summarized"`를 설정하세요. Claude Code는 Amazon Bedrock 또는 Google Cloud의 Agent Platform에 `display`를 전송하지 않으므로, 이러한 제공자에서 Opus 4.7 이상은 `display`를 `"summarized"`로 설정한 경우에도 빈 `thinking` 블록을 반환합니다.5465선택적 `display` 필드는 사고 텍스트가 `"summarized"` 또는 `"omitted"`로 반환되는지 제어합니다. Claude Opus 4.7 이상에서 API 기본값은 `"omitted"`이므로, `thinking` 블록에서 사고 콘텐츠를 받으려면 `"summarized"`를 설정하세요. Claude Code는 Amazon Bedrock 및 Google Cloud의 Agent Platform 같은 일부 제공자에 대한 요청에서 `display`를 생략합니다. 이러한 제공자에서 Opus 4.7 이상은 `display`를 `"summarized"`로 설정한 경우에도 빈 `thinking` 블록을 반환합니다.

5461 5466 

5462<h3 id="spawnedprocess">5467<h3 id="spawnedprocess">

5463 `SpawnedProcess`5468 `SpawnedProcess`

5528 5533 

5529`setMcpServers()`를 호출할 때, Claude Code는 다음 규칙을 적용합니다:5534`setMcpServers()`를 호출할 때, Claude Code는 다음 규칙을 적용합니다:

5530 5535 

5531* **호출이 이름을 지정하지 않는 서버**: Claude Code는 플러그인 제공 서버를 계속 실행합니다. Agent SDK v0.3.210 이상이 필요합니다.5536* **호출이 이름을 지정하지 않는 서버**: [클라우드 세션](/docs/ko/claude-code-on-the-web) 외부에서 Claude Code는 이전 `setMcpServers()` 호출이 추가한 서버와 인프로세스 SDK 서버의 연결을 끊고 이를 `removed`에 나열합니다. 다른 서버는 계속 실행되며 `removed`에 나열되지 않습니다. 여기에는 [`mcpServers`](#options) 옵션의 stdio, HTTP 및 SSE 서버, 설정 파일의 서버, 플러그인 제공 서버가 포함됩니다.

5532* **호출이 이름을 지정하는 서버**: CLI가 시작 시 시작한 기본 제공 서버를 제외하고, Claude Code는 구성이 전달한 것과 다를 때만 실행 중인 서버를 교체합니다.5537* **호출이 이름을 지정하는 서버**: Claude Code는 이전 `setMcpServers()` 호출이 추가한 stdio, HTTP 또는 SSE 서버를 해당 구성이 전달한 것과 다를 때만 교체합니다. 해당 이름으로 이미 등록된 인프로세스 SDK 서버는 그대로 유지되므로, 이를 교체하려면 한 호출에서 제외한 다음 호출에서 추가하세요.

5533* **CLI가 시작 시 시작한 기본 제공 서버**: 호출이 하나를 이름으로 지정하면, Claude Code는 해당 항목을 삭제하고 `errors`에서 보고합니다.5538* **CLI가 시작 시 시작한 기본 제공 서버**: 호출이 하나를 이름으로 지정하면, Claude Code는 해당 항목을 삭제하고 `errors`에서 보고합니다.

5534 5539 

5535프로미스는 새로 추가된 stdio, HTTP 및 SSE 서버가 연결되거나 실패한 후 해결되므로, 연결된 서버의 도구는 다음 턴에서 사용 가능합니다.5540프로미스는 새로 추가된 stdio, HTTP 및 SSE 서버가 연결되거나 실패한 후 해결되므로, 연결된 서버의 도구는 다음 턴에서 사용 가능합니다.

819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 푸시되지 않은 커밋으로 인해 삭제가 거부된 세션을 삭제하고, worktree와 해당 브랜치 및 커밋을 함께 삭제합니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.260 이상 필요 |819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 푸시되지 않은 커밋으로 인해 삭제가 거부된 세션을 삭제하고, worktree와 해당 브랜치 및 커밋을 함께 삭제합니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.260 이상 필요 |

820| `claude rm <id> --force-remove-worktree <worktree-id>` | git 또는 `WorktreeRemove` 훅이 worktree를 제거할 수 없어 삭제가 거부된 세션을 삭제하고, worktree 디렉터리를 어쨌든 삭제하며 해당 브랜치는 저장소에 남겨둡니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.268 이상 필요 |820| `claude rm <id> --force-remove-worktree <worktree-id>` | git 또는 `WorktreeRemove` 훅이 worktree를 제거할 수 없어 삭제가 거부된 세션을 삭제하고, worktree 디렉터리를 어쨌든 삭제하며 해당 브랜치는 저장소에 남겨둡니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.268 이상 필요 |

821| `claude daemon status` | [감독자](#the-supervisor-process)의 상태, 버전, 소켓 디렉터리 및 워커 수 인쇄 |821| `claude daemon status` | [감독자](#the-supervisor-process)의 상태, 버전, 소켓 디렉터리 및 워커 수 인쇄 |

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

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

823 824 

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

20 20 

21이 작업을 지원하지만 에이전트를 실행하는 방식이 아닌 세 가지 추가 도구가 있습니다:21이 작업을 지원하지만 에이전트를 실행하는 방식이 아닌 세 가지 추가 도구가 있습니다:

22 22 

23* [Worktrees](/docs/ko/worktrees)는 각 세션에 별도의 git 체크아웃을 제공하므로 병렬 세션이 동일한 파일을 편집하지 않습니다. 직접 실행하는 세션에 사용하세요. 에이전트 뷰에서 디스패치된 세션은 [파일을 편집하기 전에 자신의 worktree로 이동](/docs/ko/agent-view#how-file-edits-are-isolated)하고, 생성하는 서브에이전트도 각각 하나씩 얻을 수 있습니다.23* [Worktrees](/docs/ko/worktrees)는 각 세션에 별도의 git 체크아웃을 제공하므로 병렬 세션이 각자 자신의 파일 사본을 편집합니다. 직접 실행하는 세션에 사용하세요. 에이전트 뷰에서 디스패치된 세션은 [파일을 편집하기 전에 자신의 worktree로 이동](/docs/ko/agent-view#how-file-edits-are-isolated)하고, 생성하는 서브에이전트도 각각 하나씩 얻을 수 있습니다.

24* [크로스 세션 메시징](/docs/ko/cross-session-messaging)을 통해 Claude는 이 머신의 다른 Claude Code 세션, 다른 머신의 세션, 또는 [웹의 Claude Code](/docs/ko/claude-code-on-the-web)의 세션을 나열하고 메시지를 보낼 수 있으므로, 직접 실행하는 세션들이 결과와 상태를 서로 전달할 수 있습니다.24* [크로스 세션 메시징](/docs/ko/cross-session-messaging)을 통해 Claude는 이 머신의 다른 Claude Code 세션, 다른 머신의 세션, 또는 [웹의 Claude Code](/docs/ko/claude-code-on-the-web)의 세션을 나열하고 메시지를 보낼 수 있으므로, 직접 실행하는 세션들이 결과와 상태를 서로 전달할 수 있습니다.

25* [`/batch`](/docs/ko/commands)는 Claude가 하나의 큰 변경을 5\~30개의 worktree 격리 서브에이전트로 분할하는 [스킬](/docs/ko/skills)입니다. 이는 서브에이전트와 worktree의 패키지된 사용이지, 별도의 조율 스타일이 아닙니다.25* [`/batch`](/docs/ko/commands)는 Claude가 하나의 큰 변경을 5\~30개의 worktree 격리 서브에이전트로 분할하는 [스킬](/docs/ko/skills)입니다. 이는 서브에이전트와 worktree의 패키지된 사용이지, 별도의 조율 스타일이 아닙니다.

26 26 

682 682 

683Amazon Bedrock은 `InvokeModelWithResponseStream` 응답을 `Content-Type: application/vnd.amazon.eventstream` 헤더가 있는 바이너리 이벤트 스트림 형식으로 스트리밍합니다. Claude Code와 Amazon Bedrock 사이의 게이트웨이 또는 프록시는 응답 본문과 `Content-Type`을 포함한 헤더를 Amazon Bedrock이 보낸 그대로 전달해야 합니다.683Amazon Bedrock은 `InvokeModelWithResponseStream` 응답을 `Content-Type: application/vnd.amazon.eventstream` 헤더가 있는 바이너리 이벤트 스트림 형식으로 스트리밍합니다. Claude Code와 Amazon Bedrock 사이의 게이트웨이 또는 프록시는 응답 본문과 `Content-Type`을 포함한 헤더를 Amazon Bedrock이 보낸 그대로 전달해야 합니다.

684 684 

685게이트웨이가 `Content-Type`을 다른 값으로 다시 쓰면 Claude Code는 `Bedrock streaming response has content-type`으로 시작하는 오류로 응답을 거부하며, 수신한 값을 이름으로 지정합니다. 일반적인 다시 쓰기는 스트림을 서버 전송 이벤트로 다시 내보내는 통합에서 `text/event-stream`입니다.685게이트웨이가 `Content-Type`을 다른 값으로 다시 쓰면 Claude Code는 `Bedrock streaming response has content-type`으로 시작하는 오류로 응답을 거부하며, 수신한 값을 이름으로 지정합니다. 일반적인 다시 쓰기는 스트림을 서버 전송 이벤트로 다시 내보내는 통합에서 `text/event-stream`입니다. 오류 메시지에 언급된 `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` 변수에 대해서는 [Bedrock streaming response has an unexpected content-type](/docs/ko/errors#bedrock-streaming-response-has-an-unexpected-content-type)을 참조하십시오.

686 686 

687게이트웨이가 헤더를 삭제하거나 비우면 Claude Code는 본문이 Amazon Bedrock의 이벤트 스트림이라고 가정하고 디코딩하므로 게이트웨이가 수정되지 않은 상태로 전달한 본문은 계속 스트리밍됩니다.687게이트웨이가 헤더를 삭제하거나 비우면 Claude Code는 본문이 Amazon Bedrock의 이벤트 스트림이라고 가정하고 디코딩하므로 게이트웨이가 수정되지 않은 상태로 전달한 본문은 계속 스트리밍됩니다.

688 688 

351}351}

352```352```

353 353 

354사용자 정의 `allow`, `soft_deny` 및 `hard_deny` 규칙에 대한 AI 피드백을 받습니다:354사용자 정의 `allow`, `soft_deny`, `hard_deny` 및 `environment` 항목에 대한 AI 피드백을 받습니다:

355 355 

356```bash theme={null}356```bash theme={null}

357claude auto-mode critique357claude auto-mode critique

343 343 

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

345| - | - | - |345| - | - | - |

346| "브라우저 확장 프로그램이 연결되지 않음" | 네이티브 메시징 호스트가 확장 프로그램에 도달할 수 없거나, 조직의 IP 허용 목록이 `bridge.claudeusercontent.com`에 대한 연결을 거부함 | Chrome과 Claude Code를 다시 시작한 후 `/chrome`을 실행하여 다시 연결합니다. 조직에서 IP 허용 목록을 사용하고 오류가 지속되면 [조직 IP 허용 목록 및 프록시 egress](/docs/ko/network-config#organization-ip-allowlists-and-proxy-egress)를 참조합니다. |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)를 참조합니다. |

347| `/chrome`에서 확장 프로그램이 "감지되지 않음"으로 표시됨 | Chrome 확장 프로그램이 설치되지 않았거나 비활성화됨 | `chrome://extensions`에서 확장 프로그램을 설치하거나 활성화합니다. |347| `/chrome`에서 확장 프로그램이 "감지되지 않음"으로 표시됨 | Chrome 확장 프로그램이 설치되지 않았거나 비활성화됨 | `chrome://extensions`에서 확장 프로그램을 설치하거나 활성화합니다. |

348| "사용 가능한 탭 없음" | Claude가 탭이 준비되기 전에 작동하려고 시도함 | Claude에게 새 탭을 만들고 다시 시도하도록 요청합니다. |348| "사용 가능한 탭 없음" | Claude가 탭이 준비되기 전에 작동하려고 시도함 | Claude에게 새 탭을 만들고 다시 시도하도록 요청합니다. |

349| "수신 끝이 존재하지 않음" | 확장 프로그램 서비스 워커가 유휴 상태가 됨 | `/chrome`을 실행하고 "확장 프로그램 다시 연결"을 선택합니다. |349| "수신 끝이 존재하지 않음" | 확장 프로그램 서비스 워커가 유휴 상태가 됨 | `/chrome`을 실행하고 "확장 프로그램 다시 연결"을 선택합니다. |

75| - | - |75| - | - |

76| Claude Code v2.1.195 이상 | `claude gateway` 서브명령 및 게이트웨이 로그인 흐름은 v2.1.195에서 제공됩니다. 이전 공개 빌드는 이를 포함하지 않습니다. 게이트웨이 서버를 실행하는 머신과 각 개발자의 머신 모두 v2.1.195 이상이어야 합니다; `claude update`를 실행하여 최신 릴리스를 받으세요. [Claude Platform on AWS 업스트림](/docs/ko/claude-apps-gateway-config#claude-platform-on-aws)은 게이트웨이 서버에서 Claude Code v2.1.198 이상이 필요합니다. |76| Claude Code v2.1.195 이상 | `claude gateway` 서브명령 및 게이트웨이 로그인 흐름은 v2.1.195에서 제공됩니다. 이전 공개 빌드는 이를 포함하지 않습니다. 게이트웨이 서버를 실행하는 머신과 각 개발자의 머신 모두 v2.1.195 이상이어야 합니다; `claude update`를 실행하여 최신 릴리스를 받으세요. [Claude Platform on AWS 업스트림](/docs/ko/claude-apps-gateway-config#claude-platform-on-aws)은 게이트웨이 서버에서 Claude Code v2.1.198 이상이 필요합니다. |

77| OpenID Connect (OIDC) ID 제공자 | Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex 또는 PingFederate와 같은 다른 OIDC 호환 IdP. 게이트웨이는 표준 OIDC 검색 및 인증 코드 흐름을 이에 대해 실행합니다. SAML 및 LDAP는 지원되지 않습니다. |77| OpenID Connect (OIDC) ID 제공자 | Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex 또는 PingFederate와 같은 다른 OIDC 호환 IdP. 게이트웨이는 표준 OIDC 검색 및 인증 코드 흐름을 이에 대해 실행합니다. SAML 및 LDAP는 지원되지 않습니다. |

78| PostgreSQL 14 이상 | 브라우저 콜백이 쓰고 폴링 CLI가 읽는 장치 로그인 흐름, 그리고 속도 제한 카운터를 지원합니다. 가장 작은 계층을 포함한 모든 관리 Postgres가 작동합니다. 지출 제한이 구성되지 않으면 게이트웨이는 몇 KB의 단기 인증 상태를 저장합니다; [지출 제한](/docs/ko/claude-apps-gateway-spend-limits)을 사용하면 백업해야 하는 지속적인 지출, 감사 및 ID 테이블도 보유합니다. `?sslmode=require`를 통한 TLS가 권장됩니다. |78| PostgreSQL 11 이상 | 장치 로그인 흐름과 속도 제한 카운터를 지원합니다. 가장 작은 계층을 포함한 관리형 PostgreSQL 서비스가 작동합니다; [지원되는 데이터베이스](/docs/ko/claude-apps-gateway-deploy#postgres)를 참조하세요. [지출 제한](/docs/ko/claude-apps-gateway-spend-limits)을 사용하면 백업해야 하는 지속적인 지출, 감사 및 ID 테이블도 보유합니다. `?sslmode=require`를 통한 TLS가 권장됩니다. PostgreSQL 11, 12, 13은 게이트웨이 서버에서 Claude Code v2.1.290 이상이 필요합니다. PostgreSQL 프로젝트는 더 이상 해당 버전을 유지 관리하지 않으므로 가능하면 더 새로운 버전을 사용하세요. |

79| 모델 업스트림 | Amazon Bedrock 자격증명, Claude Platform on AWS 자격증명, Google Cloud 자격증명, Microsoft Foundry 리소스 또는 Anthropic API 키. 장애 조치를 사용한 여러 업스트림이 지원됩니다. |79| 모델 업스트림 | Amazon Bedrock 자격 증명, Claude Platform on AWS 자격 증명, Google Cloud 자격 증명, Microsoft Foundry 리소스 또는 Anthropic API 키. 장애 조치를 사용한 여러 업스트림이 지원됩니다. |

80| HTTPS | 게이트웨이는 개발자 노트북과 로그인에 사용되는 모든 브라우저에서 `https://`를 통해 도달 가능해야 합니다; 게이트웨이는 동일한 리스너에서 장치 확인 페이지를 제공합니다. `listen.tls`를 통해 TLS 인증서를 제공하거나, TLS 종료 수신 대기 뒤에서 실행하고, 두 경우 모두 `listen.public_url`을 외부 원본으로 설정하세요. 일반 `http://` 원본은 게이트웨이 호스트가 루프백인 경우에만 허용됩니다: `localhost`, `127.0.0.1` 또는 `::1`. |80| HTTPS | 게이트웨이는 개발자 노트북과 로그인에 사용되는 모든 브라우저에서 `https://`를 통해 도달 가능해야 합니다; 게이트웨이는 동일한 리스너에서 장치 확인 페이지를 제공합니다. `listen.tls`를 통해 TLS 인증서를 제공하거나, TLS 종료 수신 대기 뒤에서 실행하고, 두 경우 모두 `listen.public_url`을 외부 원본으로 설정하세요. `/login`에서 Claude Code는 게이트웨이 호스트가 루프백인 경우에만 일반 `http://` 원본을 허용합니다: `localhost`, `127.0.0.1` 또는 `::1`. |

81| 개인 네트워크 주소 | `/login`에서 Claude Code는 게이트웨이의 호스트명 또는 IP 주소가 개인 주소로만 확인되도록 요구합니다: RFC 1918, 링크 로컬, CGNAT `100.64.0.0/10`, IPv6 ULA `fc00::/7` 또는 루프백. 호스팅하는 게이트웨이의 경우 선언한 블록 외의 모든 공개 주소는 거부됩니다; 배포 가이드의 [위협 모델](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)을 참조하세요. 개발자 머신이 HTTPS를 회사 프록시를 통해 라우팅하는 경우, 로그인은 프록시 호스트도 개인 주소로 확인되도록 요구합니다; 그렇지 않으면 게이트웨이 호스트를 `NO_PROXY`에 추가하여 CLI가 직접 연결하도록 하세요. 내부 네트워크가 조직이 소유한 공개 IPv4 공간에서 번호가 지정된 경우 [해당 블록을 선언](#allow-a-gateway-on-public-address-space-you-own)하여 `/login`이 거기서 게이트웨이를 수락하도록 하세요. |81| 개인 네트워크 주소 | `/login`에서 Claude Code는 게이트웨이의 호스트명 또는 IP 주소가 개인 주소로만 확인되도록 요구합니다: RFC 1918, 링크 로컬, CGNAT `100.64.0.0/10`, IPv6 ULA `fc00::/7` 또는 루프백. 호스팅하는 게이트웨이의 경우 선언한 블록 외의 모든 공개 주소는 거부됩니다; 배포 가이드의 [위협 모델](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)을 참조하세요. 개발자 머신이 HTTPS를 회사 프록시를 통해 라우팅하는 경우, 로그인은 프록시 호스트도 개인 주소로 확인되도록 요구합니다; 그렇지 않으면 게이트웨이 호스트를 `NO_PROXY`에 추가하여 CLI가 직접 연결하도록 하세요. 내부 네트워크가 조직이 소유한 공개 IPv4 공간에서 번호가 지정된 경우 [해당 블록을 선언](#allow-a-gateway-on-public-address-space-you-own)하여 `/login`이 거기서 게이트웨이를 수락하도록 하세요. |

82| Linux 런타임 | 게이트웨이 서버는 네이티브 Linux 바이너리에서만 실행됩니다. macOS는 로컬 개발에 작동합니다. Windows는 서버 플랫폼으로 지원되지 않습니다. |82| Linux 런타임 | 게이트웨이 서버는 네이티브 Linux 바이너리에서만 실행됩니다. macOS는 로컬 개발에 작동합니다. Windows는 서버 플랫폼으로 지원되지 않습니다. |

83 83 

91 </Step>91 </Step>

92 92 

93 <Step title="PostgreSQL 데이터베이스 프로비저닝">93 <Step title="PostgreSQL 데이터베이스 프로비저닝">

94 가장 작은 관리 계층을 포함한 모든 Postgres 14 이상이 작동합니다. 게이트웨이는 부팅 시 자체 스키마 마이그레이션을 실행하므로 데이터베이스 역할은 테이블을 생성하고 변경할 권한이 필요합니다; [`store`](/docs/ko/claude-apps-gateway-config#store)를 참조하세요.94 PostgreSQL 11 이상을 사용하세요. 가장 작은 관리형 계층으로 충분합니다. 게이트웨이는 부팅 시 자체 스키마 마이그레이션을 실행하므로 데이터베이스 역할은 테이블을 생성하고 변경할 권한이 필요합니다; [`store`](/docs/ko/claude-apps-gateway-config#store)를 참조하세요.

95 </Step>95 </Step>

96 96 

97 <Step title="gateway.yaml 작성">97 <Step title="gateway.yaml 작성">

117 ttl_hours: 1 # IdP 프로비저닝 해제 시 취소 지연도 제한117 ttl_hours: 1 # IdP 프로비저닝 해제 시 취소 지연도 제한

118 118 

119 store:119 store:

120 postgres_url: ${GATEWAY_POSTGRES_URL} # 관리 Postgres의 경우 ?sslmode=require 추가120 postgres_url: ${GATEWAY_POSTGRES_URL} # 관리형 Postgres의 경우 ?sslmode=require 추가

121 121 

122 upstreams:122 upstreams:

123 - provider: bedrock123 - provider: bedrock

124 region: us-east-1124 region: us-east-1

125 auth: {} # 비어있음: AWS 기본 자격증명 체인125 auth: {} # 비어있음: AWS 기본 자격 증명 체인

126 # (IRSA, EC2/ECS 작업 역할, 환경 변수, ~/.aws)126 # (IRSA, EC2/ECS 작업 역할, 환경 변수, ~/.aws)

127 127 

128 # 모델은 업스트림별로 자동으로 변환됩니다. 기본 제공 카탈로그128 # 모델은 업스트림별로 자동으로 변환됩니다. 기본 제공 카탈로그

132 auto_include_builtin_models: true132 auto_include_builtin_models: true

133 ```133 ```

134 134 

135 이 구성은 기본 Bedrock 모델 카탈로그로 작동하는 로그인 루프에 충분합니다. 실행되면 [`managed.policies`](/docs/ko/claude-apps-gateway-config#managed)를 통해 그룹별 RBAC 및 관리 설정을 추가하고, [`telemetry`](/docs/ko/claude-apps-gateway-config#telemetry)를 통해 텔레메트리 팬아웃을 추가하고, [`models`](/docs/ko/claude-apps-gateway-config#models)를 통해 다중 업스트림 장애 조치, 프로비저닝된 처리량 ARN 또는 미국 이외 지역을 추가하세요.135 이 구성은 기본 Amazon Bedrock 모델 카탈로그로 작동하는 로그인 루프에 충분합니다. 실행되면 [`managed.policies`](/docs/ko/claude-apps-gateway-config#managed)를 통해 그룹별 RBAC 및 관리형 설정을 추가하고, [`telemetry`](/docs/ko/claude-apps-gateway-config#telemetry)를 통해 텔레메트리 팬아웃을 추가하고, [`models`](/docs/ko/claude-apps-gateway-config#models)를 통해 다중 업스트림 장애 조치, 프로비저닝된 처리량 ARN 또는 미국 이외 지역을 추가하세요.

136 136 

137 <Note>137 <Note>

138 Amazon Bedrock 업스트림은 `bedrock:InvokeModel` 및 `bedrock:InvokeModelWithResponseStream`을 `inference-profile/us.anthropic.*` ARN과 기본 `foundation-model/anthropic.*` ARN 모두에 가진 AWS 주체가 필요합니다. 또한 Bedrock 콘솔의 모델 카탈로그에서 계정에 대해 제출된 Anthropic의 일회성 사용 사례 양식이 필요합니다.138 Amazon Bedrock 업스트림은 `bedrock:InvokeModel` 및 `bedrock:InvokeModelWithResponseStream`을 `inference-profile/us.anthropic.*` ARN과 기본 `foundation-model/anthropic.*` ARN 모두에 가진 AWS 주체가 필요합니다. 또한 Bedrock 콘솔의 모델 카탈로그에서 계정에 대해 제출된 Anthropic의 일회성 사용 사례 양식이 필요합니다.

139 139 

140 정적 키보다는 EKS의 IRSA, ECS 작업 역할 또는 EC2 인스턴스 프로필을 사용하여 자격증명을 제공하세요. [`upstreams` 참조](/docs/ko/claude-apps-gateway-config#upstreams)는 전체 IAM 세부사항, 클라우드 간 자격증명 매트릭스, 다른 제공자의 `auth` 블록을 가집니다.140 정적 키보다는 EKS의 IRSA, ECS 작업 역할 또는 EC2 인스턴스 프로필을 사용하여 자격 증명을 제공하세요. [`upstreams` 참조](/docs/ko/claude-apps-gateway-config#upstreams)는 전체 IAM 세부사항, 클라우드 간 자격 증명 매트릭스, 다른 제공자의 `auth` 블록을 가집니다.

141 </Note>141 </Note>

142 </Step>142 </Step>

143 143 

154 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}154 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}

155 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}155 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}

156 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway156 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway

157 # AWS 자격증명: 프로덕션에서는 이를 생략하고 인스턴스157 # AWS 자격 증명: 프로덕션에서는 이를 생략하고 인스턴스

158 # 역할을 사용하세요. 로컬 Compose 테스트의 경우 자신의 것을 전달하세요:158 # 역할을 사용하세요. 로컬 Compose 테스트의 경우 자신의 것을 전달하세요:

159 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}159 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}

160 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}160 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}

172 volumes: { pgdata: }172 volumes: { pgdata: }

173 ```173 ```

174 174 

175 게이트웨이는 구성을 읽고, Postgres에 연결하고 스키마 마이그레이션을 적용하고, IdP에 대해 OIDC 검색을 실행하고, 업스트림 클라이언트를 빌드하고, 수신 대기를 시작하는 단일 Linux 바이너리입니다. 부팅은 구성, Postgres 연결, OIDC 검색 및 업스트림 클라이언트 구성에 대해 실패 폐쇄됩니다. 이 중 하나가 도달 불가능하거나 잘못 구성된 경우, 게이트웨이는 저하된 상태에서 트래픽을 제공하는 대신 오류로 종료됩니다.175 게이트웨이는 구성을 읽고, Postgres에 연결하고 스키마 마이그레이션을 적용하고, IdP에 대해 OIDC 검색을 실행하고, 업스트림 클라이언트를 빌드하고, 수신 대기를 시작하는 단일 Linux 바이너리입니다.

176 176 

177 성공적인 부팅은 Amazon Bedrock 및 Google Cloud의 Agent Platform 인스턴스 자격증명이 부팅 시가 아닌 첫 요청에서 확인되기 때문에 추론 경로를 검증하지 않습니다.177 부팅은 구성, Postgres 연결, OIDC 검색 및 업스트림 클라이언트 구성에 대해 실패 폐쇄됩니다. 이 중 하나가 도달 불가능하거나 잘못 구성된 경우, 게이트웨이는 저하된 상태에서 트래픽을 제공하는 대신 오류로 종료됩니다.

178 

179 성공적인 부팅은 Amazon Bedrock 및 Google Cloud의 Agent Platform 인스턴스 자격 증명이 부팅 시가 아닌 첫 요청에서 확인되기 때문에 추론 경로를 검증하지 않습니다.

178 180 

179 부팅 시퀀스에 대해 stderr를 감시하세요. 로그 라인은 `[gateway] <timestamp> <level> <message>` 형식을 사용하고, 감사 이벤트는 `evt` 필드가 있는 단일 라인 JSON이며, 시작 배너(아래 생략됨)는 마이그레이션과 수신 대기 라인 사이에 인쇄됩니다. 신규 데이터베이스는 스키마 마이그레이션당 하나의 `migration N applied` 라인을 인쇄합니다; 이미 마이그레이션된 데이터베이스는 없습니다. 순서대로 다음을 볼 수 있습니다:181 부팅 시퀀스에 대해 stderr를 감시하세요. 로그 라인은 `[gateway] <timestamp> <level> <message>` 형식을 사용하고, 감사 이벤트는 `evt` 필드가 있는 단일 라인 JSON이며, 시작 배너(아래 생략됨)는 마이그레이션과 수신 대기 라인 사이에 인쇄됩니다. 신규 데이터베이스는 스키마 마이그레이션당 하나의 `migration N applied` 라인을 인쇄합니다; 이미 마이그레이션된 데이터베이스는 없습니다. 순서대로 다음을 볼 수 있습니다:

180 182 

187 [gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080189 [gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080

188 ```190 ```

189 191 

190 게이트웨이는 또한 `access_control.allow_cidrs`가 비어있다는 경고를 기록합니다. 게이트웨이가 제공하는 클라이언트 주소를 제한하는 것이 없기 때문에 여기서는 예상됩니다. [`access_control` 참조](/docs/ko/claude-apps-gateway-config#http-tuning)는 권장 범위를 가집니다.192 게이트웨이는 또한 `access_control.allow_cidrs`가 비어있다는 경고를 기록합니다. 허용 목록을 설정하기 전까지는 게이트웨이가 제공하는 클라이언트 주소를 제한하는 것이 없기 때문에 여기서는 예상된 동작입니다. [`access_control` 참조](/docs/ko/claude-apps-gateway-config#http-tuning)는 권장 범위를 가집니다.

191 193 

192 부팅이 `claude gateway listening on` 라인 전에 종료되면, stderr의 마지막 라인이 문제를 이름 지정합니다:194 부팅이 `claude gateway listening on` 라인 전에 종료되면, stderr의 마지막 라인이 문제를 이름 지정합니다:

193 195 

253 </Step>255 </Step>

254 256 

255 <Step title="개발자 로그인">257 <Step title="개발자 로그인">

256 이 마지막 단계는 서버가 아닌 개발자 머신에서 발생합니다. 해당 머신의 [관리 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)에서 `forceLoginMethod`를 `"gateway"`로 설정하고 `forceLoginGatewayUrl`을 게이트웨이의 `public_url`로 설정한 다음 `/login`을 실행하고, **Cloud gateway** 화면에서 Enter를 누르고, 브라우저 로그인을 완료하세요. [게이트웨이 URL 설정](#set-the-gateway-url) 아래는 두 키를 모든 개발자 머신에 배포하는 것을 다룹니다.258 이 마지막 단계는 서버가 아닌 개발자 머신에서 발생합니다. 해당 머신의 [관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)에서 `forceLoginMethod`를 `"gateway"`로 설정하고 `forceLoginGatewayUrl`을 게이트웨이의 `public_url`로 설정한 다음 `/login`을 실행하고, **Cloud gateway** 화면에서 Enter를 누르고, 브라우저 로그인을 완료하세요. [게이트웨이 URL 설정](#set-the-gateway-url) 아래는 두 키를 모든 개발자 머신에 배포하는 것을 다룹니다.

257 </Step>259 </Step>

258</Steps>260</Steps>

259 261 

158게이트웨이는 부팅 시 키와 인증서를 한 번 읽으므로 변경된 파일은 재시작 후에만 적용됩니다. IdP에 없는 인증서를 제시하는 토큰 요청이 없도록 다음 순서로 회전합니다:158게이트웨이는 부팅 시 키와 인증서를 한 번 읽으므로 변경된 파일은 재시작 후에만 적용됩니다. IdP에 없는 인증서를 제시하는 토큰 요청이 없도록 다음 순서로 회전합니다:

159 159 

1601. 새 인증서를 이전 인증서와 함께 IdP에 업로드합니다.1601. 새 인증서를 이전 인증서와 함께 IdP에 업로드합니다.

1612. `gateway.yaml`이 로드하는 키와 인증서 파일을 교체한 후 게이트웨이를 재시작합니다.1612. `gateway.yaml`이 로드하는 키와 인증서 파일을 교체한 후 게이트웨이를 재시작합니다. 여러 복제본을 실행하는 경우 이전 인증서를 제거할 때까지 IdP에 두 인증서가 모두 있으므로 [롤링 재시작](/docs/ko/claude-apps-gateway-deploy#upgrades)을 사용할 수 있습니다.

1623. IdP에서 이전 인증서를 제거합니다.1623. 모든 복제본이 재시작된 후 IdP에서 이전 인증서를 제거합니다.

163 163 

164<h4 id="idp-requests-through-a-forward-proxy">164<h4 id="idp-requests-through-a-forward-proxy">

165 전방 프록시를 통한 IdP 요청165 전방 프록시를 통한 IdP 요청

227 227 

228| 필드 | 필수 | 설명 |228| 필드 | 필수 | 설명 |

229| - | - | - |229| - | - | - |

230| `postgres_url` | 예 | `postgres://` 또는 `postgresql://` URL입니다. 필수: 장치 부여 랑데부입니다. 브라우저 콜백이 작성하고 폴링 CLI가 읽으므로 교차 복제본 상태가 필요합니다. 게이트웨이는 부팅 및 업그레이드 시 자체 스키마 마이그레이션을 실행하므로 역할은 대상 스키마에서 테이블을 생성하고 변경할 권리가 필요합니다. [업그레이드](/docs/ko/claude-apps-gateway-deploy#upgrades) 및 [Postgres](/docs/ko/claude-apps-gateway-deploy#postgres)를 참조하세요. |230| `postgres_url` | 예 | 쉼표로 구분된 목록이 아닌 하나의 호스트를 가진 `postgres://` 또는 `postgresql://` URL입니다. 게이트웨이는 부팅 및 업그레이드 시 자체 스키마 마이그레이션을 실행하므로 역할은 대상 스키마에서 테이블을 생성하고 변경할 권리가 필요합니다. [업그레이드](/docs/ko/claude-apps-gateway-deploy#upgrades) 및 [Postgres](/docs/ko/claude-apps-gateway-deploy#postgres)를 참조하세요. |

231| `username` | 아니오 | `postgres_url`의 사용자를 재정의합니다. |231| `username` | 아니오 | `postgres_url`의 사용자를 재정의합니다. |

232| `password` | 아니오 | 데이터베이스 자격 증명입니다. 자격 증명이 URL에서 벗어나도록 `postgres_url`이 아닌 여기에 설정합니다. 모든 문자를 수락하고 URL 자격 증명보다 우선합니다. |232| `password` | 아니오 | 데이터베이스 자격 증명입니다. 자격 증명이 URL에서 벗어나도록 `postgres_url`이 아닌 여기에 설정합니다. 모든 문자를 수락하고 URL 자격 증명보다 우선합니다. |

233| `max_connections` | 아니오 | 복제본당 Postgres 연결 풀 크기입니다. 기본값 `5`로 보수적이고 공유 데이터베이스에 친화적입니다. [지출 제한](#admin)이 활성화되면 핫 경로는 추론 요청당 몇 가지 작업을 수행하므로 로드 아래의 전용 데이터베이스에 대해 이를 높이고 복제본 × 이를 데이터베이스의 `max_connections` 아래로 유지합니다. |233| `max_connections` | 아니오 | 복제본당 Postgres 연결 풀 크기입니다. 기본값 `5`로 보수적이고 공유 데이터베이스에 친화적입니다. [지출 제한](#admin)이 활성화되면 핫 경로는 추론 요청당 몇 가지 작업을 수행하므로 로드 아래의 전용 데이터베이스에 대해 이를 높이고 복제본 × 이를 데이터베이스의 `max_connections` 아래로 유지합니다. |

313 프록시를 실행하는 경우 사용자별 ID 헤더313 프록시를 실행하는 경우 사용자별 ID 헤더

314</h5>314</h5>

315 315 

316`provider: anthropic` 업스트림의 `base_url`을 Anthropic API 대신 실행하는 프록시로 지정할 수 있습니다. 해당 프록시에 각 요청을 보낸 개발자를 알리려면 해당 업스트림에 `forward_user_identity: true`를 설정합니다. 그러면 프록시는 개발자별로 지출을 기인할 수 있습니다. 게이트웨이 v2.1.233 이상을 실행해야 합니다.316`provider: anthropic` 업스트림의 `base_url`을 Anthropic API 대신 실행하는 프록시로 지정할 수 있습니다. 해당 프록시에 각 요청을 보낸 개발자를 알리려면 해당 업스트림에 `forward_user_identity: true`를 설정합니다. 그러면 프록시는 개발자별로 지출을 기인할 수 있습니다. Claude Code v2.1.233 이상을 실행하는 게이트웨이가 필요합니다.

317 317 

318예를 들어 `upstream-gateway.internal.example.com`의 프록시의 경우:318예를 들어 `upstream-gateway.internal.example.com`의 프록시의 경우:

319 319 

413 413 

414Bedrock 업스트림에 `assume_role`을 설정하면 게이트웨이는 자체 AWS 신원을 사용하여 이름을 지정하는 역할에 대해서만 `sts:AssumeRole`을 호출합니다. 이는 게이트웨이와 다른 AWS 계정에 있을 수 있습니다. 해당 업스트림의 모든 Bedrock 요청은 STS가 반환하는 1시간 자격 증명으로 서명되므로 장기 액세스 키가 계정을 교차하지 않습니다.414Bedrock 업스트림에 `assume_role`을 설정하면 게이트웨이는 자체 AWS 신원을 사용하여 이름을 지정하는 역할에 대해서만 `sts:AssumeRole`을 호출합니다. 이는 게이트웨이와 다른 AWS 계정에 있을 수 있습니다. 해당 업스트림의 모든 Bedrock 요청은 STS가 반환하는 1시간 자격 증명으로 서명되므로 장기 액세스 키가 계정을 교차하지 않습니다.

415 415 

416게이트웨이 v2.1.281 이상을 실행해야 합니다. 이전 게이트웨이는 키를 찾으면 시작을 거부합니다.416Claude Code v2.1.281 이상을 실행하는 게이트웨이가 필요합니다. 이전 게이트웨이는 키를 찾으면 시작을 거부합니다.

417 417 

418```yaml theme={null}418```yaml theme={null}

419upstreams:419upstreams:

470 470 

471기본적으로 게이트웨이는 모든 Bedrock 요청을 하나의 자격 증명으로 서명하므로 AWS는 모든 개발자의 요청을 단일 IAM 주체 아래에서 봅니다. [`assume_role`](#bedrock-in-another-aws-account)에 `session_name: email`을 추가하면 게이트웨이는 개발자당 시간당 한 번 `sts:AssumeRole`을 호출하고 세션 이름을 해당 개발자의 이메일로 설정하며 반환된 자격 증명으로 요청에 서명하므로 각 개발자의 요청은 자신의 가정된 역할 세션 아래에서 AWS에 도달합니다. 역할은 게이트웨이의 자체 계정에 있을 수 있습니다.471기본적으로 게이트웨이는 모든 Bedrock 요청을 하나의 자격 증명으로 서명하므로 AWS는 모든 개발자의 요청을 단일 IAM 주체 아래에서 봅니다. [`assume_role`](#bedrock-in-another-aws-account)에 `session_name: email`을 추가하면 게이트웨이는 개발자당 시간당 한 번 `sts:AssumeRole`을 호출하고 세션 이름을 해당 개발자의 이메일로 설정하며 반환된 자격 증명으로 요청에 서명하므로 각 개발자의 요청은 자신의 가정된 역할 세션 아래에서 AWS에 도달합니다. 역할은 게이트웨이의 자체 계정에 있을 수 있습니다.

472 472 

473게이트웨이 v2.1.281 이상을 실행해야 합니다. [AWS의 비용 기인](/docs/ko/claude-apps-gateway-on-aws#cost-attribution)은 IAM 역할과 AWS 청구가 세션을 표시하는 위치를 다룹니다.473Claude Code v2.1.281 이상을 실행하는 게이트웨이가 필요합니다. [AWS의 비용 기인](/docs/ko/claude-apps-gateway-on-aws#cost-attribution)은 IAM 역할과 AWS 청구가 세션을 표시하는 위치를 다룹니다.

474 474 

475```yaml theme={null}475```yaml theme={null}

476upstreams:476upstreams:

586 586 

587빈 `auth` 블록은 Application Default Credentials를 사용합니다: `GOOGLE_APPLICATION_CREDENTIALS`, GCE 메타데이터 또는 GKE Workload Identity. 서비스 계정 JSON 키 파일은 지원되지만 권장되지 않습니다. Workload Identity를 사용하거나 GCE 또는 Cloud Run 인스턴스에 서비스 계정을 연결합니다.587빈 `auth` 블록은 Application Default Credentials를 사용합니다: `GOOGLE_APPLICATION_CREDENTIALS`, GCE 메타데이터 또는 GKE Workload Identity. 서비스 계정 JSON 키 파일은 지원되지만 권장되지 않습니다. Workload Identity를 사용하거나 GCE 또는 Cloud Run 인스턴스에 서비스 계정을 연결합니다.

588 588 

589Google Cloud의 Agent Platform에 대해 [전역 엔드포인트](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)를 사용하려면 `region: global`을 설정합니다. Google은 각 요청을 사용 가능한 지역으로 라우팅하므로 지역별 모델 가용성을 추적하지 않습니다. 특정 지역을 설정하면 모든 요청이 이에 고정됩니다.589지역 엔드포인트 대신 [Google Cloud의 Agent Platform용 전역 엔드포인트](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)를 사용하려면 `region: global`을 설정합니다. Google은 각 요청을 사용 가능한 지역으로 라우팅하므로 지역별 모델 가용성을 추적하지 않습니다. 특정 지역을 설정하면 모든 요청이 이에 고정됩니다.

590 590 

591| 설정 | 방법 |591| 설정 | 방법 |

592| - | - |592| - | - |

221* **[지출 제한 적용](/docs/ko/claude-apps-gateway-spend-limits#postgres-availability)**: 중단 중에 기본적으로 열린 상태로 실패하므로 추론이 계속 흐릅니다. 계량되지 않은 상태로 실행하기보다는 차단하려면 닫힌 상태로 전환합니다221* **[지출 제한 적용](/docs/ko/claude-apps-gateway-spend-limits#postgres-availability)**: 중단 중에 기본적으로 열린 상태로 실패하므로 추론이 계속 흐릅니다. 계량되지 않은 상태로 실행하기보다는 차단하려면 닫힌 상태로 전환합니다

222* **준비 상태**: 기본적으로 `/readyz`는 Postgres에 도달할 수 없게 되자마자 준비되지 않음으로 보고하므로, 모든 복제본이 한 번에 준비 상태 확인에 실패합니다. 트래픽이 확인을 통과한 복제본에만 도달하는 경우, 게이트웨이가 여전히 처리할 수 있는 추론을 포함한 모든 트래픽은 Postgres가 복구될 때까지 실패합니다. `/healthz`의 생존성 프로브는 전체 기간 동안 계속 통과합니다.222* **준비 상태**: 기본적으로 `/readyz`는 Postgres에 도달할 수 없게 되자마자 준비되지 않음으로 보고하므로, 모든 복제본이 한 번에 준비 상태 확인에 실패합니다. 트래픽이 확인을 통과한 복제본에만 도달하는 경우, 게이트웨이가 여전히 처리할 수 있는 추론을 포함한 모든 트래픽은 Postgres가 복구될 때까지 실패합니다. `/healthz`의 생존성 프로브는 전체 기간 동안 계속 통과합니다.

223 223 

224Postgres가 다운되는 동안 생존성 프로브는 계속 통과합니다.

225 

226IdP가 다운되면, 기존 세션은 `ttl_hours`까지 작동하고 새로운 로그인은 실패합니다. 세션 새로고침은 다시 시도 답변을 받고 IdP가 돌아오면 성공합니다. IdP에 빈번한 유지 보수 창이 있으면 더 긴 `ttl_hours`를 설정합니다.224IdP가 다운되면, 기존 세션은 `ttl_hours`까지 작동하고 새로운 로그인은 실패합니다. 세션 새로고침은 다시 시도 답변을 받고 IdP가 돌아오면 성공합니다. IdP에 빈번한 유지 보수 창이 있으면 더 긴 `ttl_hours`를 설정합니다.

227 225 

228<h4 id="readiness-grace-period">226<h4 id="readiness-grace-period">

251 Postgres249 Postgres

252</h3>250</h3>

253 251 

252게이트웨이는 상태를 PostgreSQL 데이터베이스에 저장합니다:

253 

254* **데이터베이스**: 자체 호스팅 또는 관리형 PostgreSQL 자체이며, [최소 버전](/docs/ko/claude-apps-gateway#prerequisites) 이상이어야 합니다. 분산 SQL 데이터베이스처럼 Postgres 프로토콜만 구현하는 데이터베이스는 지원되지 않습니다.

255* **주소**: `store.postgres_url`은 하나의 호스트를 받습니다. 데이터베이스에 여러 노드가 있으면, 관리형 서비스의 엔드포인트, 로드 밸런서 또는 가상 IP와 같이 노드 앞에 있는 주소를 사용합니다. 장애 조치가 걸리는 시간보다 긴 [준비 상태 유예 기간](#readiness-grace-period)을 설정합니다.

256 

254게이트웨이는 부팅 시간 마이그레이션으로 생성된 5개의 데이터 테이블과 `_migrations` 테이블을 보유합니다:257게이트웨이는 부팅 시간 마이그레이션으로 생성된 5개의 데이터 테이블과 `_migrations` 테이블을 보유합니다:

255 258 

256| 테이블 | 내용 | 보존 |259| 테이블 | 내용 | 보존 |

398| CLI `/login`: `Could not resolve the configured HTTP proxy` | `HTTPS_PROXY` 또는 `HTTP_PROXY`의 호스트명이 개발자 머신에서 확인되지 않음. 일반적으로 회사 네트워크에 연결되지 않았기 때문 | 개발자가 네트워크 또는 VPN에 연결하고 다시 시도하거나 프록시 URL을 수정하도록 하세요 |401| CLI `/login`: `Could not resolve the configured HTTP proxy` | `HTTPS_PROXY` 또는 `HTTP_PROXY`의 호스트명이 개발자 머신에서 확인되지 않음. 일반적으로 회사 네트워크에 연결되지 않았기 때문 | 개발자가 네트워크 또는 VPN에 연결하고 다시 시도하거나 프록시 URL을 수정하도록 하세요 |

399| CLI `/login`: `Could not resolve gateway host <host>` | 머신이 gateway의 내부 DNS 이름을 확인할 수 없음. 일반적으로 회사 네트워크에 없기 때문 | 개발자가 네트워크 또는 VPN에 연결한 후 `/login`을 다시 시도하도록 하세요 |402| CLI `/login`: `Could not resolve gateway host <host>` | 머신이 gateway의 내부 DNS 이름을 확인할 수 없음. 일반적으로 회사 네트워크에 없기 때문 | 개발자가 네트워크 또는 VPN에 연결한 후 `/login`을 다시 시도하도록 하세요 |

400| 부트가 `store.postgres_url`을 이름으로 지정하는 구성 검증 오류로 종료됨 | Postgres가 구성되지 않음. gateway는 Postgres를 요구함 | `store.postgres_url`을 설정하세요. 로컬 개발의 경우 일회용 컨테이너를 사용하세요: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |403| 부트가 `store.postgres_url`을 이름으로 지정하는 구성 검증 오류로 종료됨 | Postgres가 구성되지 않음. gateway는 Postgres를 요구함 | `store.postgres_url`을 설정하세요. 로컬 개발의 경우 일회용 컨테이너를 사용하세요: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |

404| 부트 종료: `store.postgres_url in <path> is not a URL the gateway can read`, 또는 v2.1.290 이전에서는 단순한 `Invalid URL` 또는 `URI error` | URL을 파싱할 수 없음. 예를 들어 둘 이상의 호스트를 나열하거나 비밀번호에 인코딩되지 않은 `/`, `?`, `#`, `%`가 포함된 경우 | [하나의 호스트](#postgres)를 지정하고 비밀번호를 [`store.password`](/docs/ko/claude-apps-gateway-config#store)로 옮기세요 |

401| 부트 종료: `requires the native binary` | Node 대신 네이티브 바이너리에서 실행 중 | [독립 실행형 설치 방법](/docs/ko/setup) 중 하나로 Claude Code를 설치하세요 |405| 부트 종료: `requires the native binary` | Node 대신 네이티브 바이너리에서 실행 중 | [독립 실행형 설치 방법](/docs/ko/setup) 중 하나로 Claude Code를 설치하세요 |

402| 부트가 `config.load` 후 OIDC 검색 오류로 종료됨 | `oidc.issuer`에 도달할 수 없거나 TLS 체인을 신뢰하지 않음 | 발급자가 포드에서 도달 가능하고 `/.well-known/openid-configuration`을 제공하는지 확인하세요. 비공개 PKI의 경우 `ca_cert_pem`을 설정하세요. 포드가 정방향 프록시를 통해서만 IdP에 도달하는 경우 [`oidc.use_proxy: true`](/docs/ko/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)를 설정하세요. v2.1.227 이전 버전에서는 대신 포드에 IdP의 각 엔드포인트에 대한 직접 경로를 제공하세요. 포드가 IdP의 호스트명을 확인할 수 없거나 프록시가 IP 주소에 대한 `CONNECT`를 거부하는 경우 [프록시 전용 송신](/docs/ko/claude-apps-gateway-config#proxy-only-egress)을 참조하세요. v2.1.277 이상이 필요합니다. |406| 부트가 `config.load` 후 OIDC 검색 오류로 종료됨 | `oidc.issuer`에 도달할 수 없거나 TLS 체인을 신뢰하지 않음 | 발급자가 포드에서 도달 가능하고 `/.well-known/openid-configuration`을 제공하는지 확인하세요. 비공개 PKI의 경우 `ca_cert_pem`을 설정하세요. 포드가 정방향 프록시를 통해서만 IdP에 도달하는 경우 [`oidc.use_proxy: true`](/docs/ko/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)를 설정하세요. v2.1.227 이전 버전에서는 대신 포드에 IdP의 각 엔드포인트에 대한 직접 경로를 제공하세요. 포드가 IdP의 호스트명을 확인할 수 없거나 프록시가 IP 주소에 대한 `CONNECT`를 거부하는 경우 [프록시 전용 송신](/docs/ko/claude-apps-gateway-config#proxy-only-egress)을 참조하세요. v2.1.277 이상이 필요합니다. |

403| 부트가 Postgres 권한 오류로 종료됨 | 데이터베이스 역할이 스키마에 대한 DDL 권한이 없음 | 부트 시 테이블을 생성하고 변경할 수 있도록 gateway 스키마에 대해 역할에 `CREATE` 권한을 부여하세요 |407| 부트가 Postgres 권한 오류로 종료됨 | 데이터베이스 역할이 스키마에 대한 DDL 권한이 없음 | 부트 시 테이블을 생성하고 변경할 수 있도록 gateway 스키마에 대해 역할에 `CREATE` 권한을 부여하세요 |

404| 로그: `could not connect to Postgres at boot, attempt 1 of 3` | gateway가 시작될 때 데이터베이스에 도달할 수 없었음. 예를 들어 네트워크가 아직 시작 중인 콜드 인스턴스 | gateway가 부팅을 완료하면 조치가 필요하지 않습니다. 데이터베이스에 도달할 수 없을 때 gateway는 종료되기 전에 2초 간격으로 연결을 3번 시도합니다. `could not connect to Postgres`로 종료되면 `store.postgres_url`과 데이터베이스로의 네트워크 경로를 확인하세요. 시도가 거부되지 않고 시간 초과되면 각 시도에 더 많은 시간을 주기 위해 [`store.connect_timeout_seconds`](/docs/ko/claude-apps-gateway-config#store)를 높이세요. |408| 로그: `could not connect to Postgres at boot, attempt 1 of 3` | gateway가 시작될 때 데이터베이스에 도달할 수 없었음. 예를 들어 네트워크가 아직 시작 중인 콜드 인스턴스 | gateway가 부팅을 완료하면 조치가 필요하지 않습니다. 데이터베이스에 도달할 수 없을 때 gateway는 종료되기 전에 2초 간격으로 연결을 3번 시도합니다. `could not connect to Postgres`로 종료되면 `store.postgres_url`(하나의 호스트를 지정하는지 포함)과 데이터베이스로의 네트워크 경로를 확인하세요. 시도가 거부되지 않고 시간 초과되면 각 시도에 더 많은 시간을 주기 위해 [`store.connect_timeout_seconds`](/docs/ko/claude-apps-gateway-config#store)를 높이세요. |

405| `/oauth/callback`이 "Sign-in could not be completed"를 표시함 | 이메일 도메인이 거부됨, id\_token 검증 실패, 또는 `email_verified`가 명시적으로 `false`이며 gateway는 항상 재정의 없이 거부함 | `allowed_email_domains`을 확인하고 IdP가 확인된 `email` 클레임을 반환하는지 확인하세요. `email_verified: false`의 경우 IdP 측 검증을 수정하세요. IdP가 다른 클레임 이름 아래에서 이메일을 내보내는 경우 `oidc.email_claim`을 설정하세요. |409| `/oauth/callback`이 "Sign-in could not be completed"를 표시함 | 이메일 도메인이 거부됨, id\_token 검증 실패, 또는 `email_verified`가 명시적으로 `false`이며 gateway는 항상 재정의 없이 거부함 | `allowed_email_domains`을 확인하고 IdP가 확인된 `email` 클레임을 반환하는지 확인하세요. `email_verified: false`의 경우 IdP 측 검증을 수정하세요. IdP가 다른 클레임 이름 아래에서 이메일을 내보내는 경우 `oidc.email_claim`을 설정하세요. |

406| 로그: `token exchange failed request_id=<id>: id_token missing email claim` | IdP가 기본적으로 id\_token에 `email`을 포함하지 않음. 이 거부는 `allowed_email_domains`이 설정된 경우에만 발생함. 없으면 누락된 이메일이 이메일 없이 세션을 발행함 | IdP를 구성하여 id\_token에 `email`을 내보내도록 하세요. Okta: 사용자 정의 권한 부여 서버의 ID 토큰 클레임에 `email`을 추가하세요. Entra: 앱 등록에서 `email`을 선택적 클레임으로 추가하세요. PingFederate: `email`을 내보내는 OpenID Connect 정책을 활성화하세요. IdP가 userinfo 엔드포인트에서 `email`을 제공하지만 id\_token에 포함하지 않는 경우(예: Okta org 권한 부여 서버) `oidc.userinfo_fallback: true`를 설정하세요. |410| 로그: `token exchange failed request_id=<id>: id_token missing email claim` | IdP가 기본적으로 id\_token에 `email`을 포함하지 않음. 이 거부는 `allowed_email_domains`이 설정된 경우에만 발생함. 없으면 누락된 이메일이 이메일 없이 세션을 발행함 | IdP를 구성하여 id\_token에 `email`을 내보내도록 하세요. Okta: 사용자 정의 권한 부여 서버의 ID 토큰 클레임에 `email`을 추가하세요. Entra: 앱 등록에서 `email`을 선택적 클레임으로 추가하세요. PingFederate: `email`을 내보내는 OpenID Connect 정책을 활성화하세요. IdP가 userinfo 엔드포인트에서 `email`을 제공하지만 id\_token에 포함하지 않는 경우(예: Okta org 권한 부여 서버) `oidc.userinfo_fallback: true`를 설정하세요. |

407| 로그: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, 개발자가 매 `session.ttl_hours`마다 `Cloud gateway session expired`를 봄 | IdP가 새로 고침 토큰을 수락했지만 함께 id\_token을 반환하지 않았으므로 gateway가 IdP의 userinfo 엔드포인트에 사용자의 클레임을 요청했습니다. IdP가 새로 고쳐진 액세스 토큰을 거기서 거부했습니다. gateway가 `temporarily_unavailable`으로 응답하므로 Claude Code는 새로 고침 토큰을 유지하지만 세션을 갱신할 수 없습니다. v2.1.260 이전의 gateway 버전은 `(at …)` 세부 정보 없이 동일한 줄을 기록합니다. | [`oidc.scope_on_refresh: true`](/docs/ko/claude-apps-gateway-config#oidc)를 설정하세요. gateway v2.1.260 이상에서 사용 가능하므로 새로 고침 요청이 `openid`를 다시 요청합니다. Okta와 같은 일부 IdP는 요청할 때만 새로 고침 시 id\_token을 반환합니다. PingFederate에서는 대신 **Applications > OAuth > OpenID Connect Policy Management** 아래에서 **Return ID Token On Refresh Grant**를 활성화하세요. 키는 PingFederate의 동작을 변경하지 않습니다. 여전히 생략하는 다른 IdP의 경우 userinfo 엔드포인트가 새로 고침으로 발급된 액세스 토큰을 수락하는지 확인하세요. 임시 방편으로 [`session.ttl_hours`](/docs/ko/claude-apps-gateway-config#session)를 높이세요. 프로비저닝 해제 트레이드오프는 [Identity provider setup](#identity-provider-setup)을 참조하세요. |411| 로그: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, 개발자가 매 `session.ttl_hours`마다 `Cloud gateway session expired`를 봄 | IdP가 새로 고침 토큰을 수락했지만 함께 id\_token을 반환하지 않았으므로 gateway가 IdP의 userinfo 엔드포인트에 사용자의 클레임을 요청했습니다. IdP가 새로 고쳐진 액세스 토큰을 거기서 거부했습니다. gateway가 `temporarily_unavailable`으로 응답하므로 Claude Code는 새로 고침 토큰을 유지하지만 세션을 갱신할 수 없습니다. v2.1.260 이전의 gateway 버전은 `(at …)` 세부 정보 없이 동일한 줄을 기록합니다. | [`oidc.scope_on_refresh: true`](/docs/ko/claude-apps-gateway-config#oidc)를 설정하세요. gateway v2.1.260 이상에서 사용 가능하므로 새로 고침 요청이 `openid`를 다시 요청합니다. Okta와 같은 일부 IdP는 요청할 때만 새로 고침 시 id\_token을 반환합니다. PingFederate에서는 대신 **Applications > OAuth > OpenID Connect Policy Management** 아래에서 **Return ID Token On Refresh Grant**를 활성화하세요. 키는 PingFederate의 동작을 변경하지 않습니다. 여전히 생략하는 다른 IdP의 경우 userinfo 엔드포인트가 새로 고침으로 발급된 액세스 토큰을 수락하는지 확인하세요. 임시 방편으로 [`session.ttl_hours`](/docs/ko/claude-apps-gateway-config#session)를 높이세요. 프로비저닝 해제 트레이드오프는 [Identity provider setup](#identity-provider-setup)을 참조하세요. |

169 </Step>169 </Step>

170 170 

171 <Step title="PostgreSQL용 Amazon RDS 프로비저닝">171 <Step title="PostgreSQL용 Amazon RDS 프로비저닝">

172 인스턴스는 공개 주소가 없는 프라이빗 서브넷에서 실행되며 스토리지 암호화가 켜져 있습니다. 엔진 버전은 Postgres 16으로 고정되어 있으며, 이는 게이트웨이의 지원되는 최소값인 PostgreSQL 14를 충족하고 아래 매개변수 그룹 패밀리가 인스턴스가 실행하는 엔진 주 버전과 일치함을 보장합니다.172 인스턴스는 프라이빗 서브넷에서 Postgres 16을 실행하며, 공개 주소가 없고 스토리지 암호화가 켜져 있습니다.

173 173 

174 먼저 프라이빗 서브넷에 데이터베이스를 배치하는 서브넷 그룹과 `rds.force_ssl=1`을 사용하는 매개변수 그룹을 생성하여 서버가 일반 텍스트 연결을 거부하도록 합니다. 엔진 버전은 매개변수 그룹의 패밀리가 인스턴스가 실행하는 엔진 주 버전과 일치해야 하므로 한 번만 고정됩니다:174 먼저 프라이빗 서브넷에 데이터베이스를 배치하는 서브넷 그룹과 `rds.force_ssl=1`을 사용하는 매개변수 그룹을 생성하여 서버가 일반 텍스트 연결을 거부하도록 합니다. 엔진 버전은 매개변수 그룹의 패밀리가 인스턴스가 실행하는 엔진 주 버전과 일치해야 하므로 한 번만 고정됩니다:

175 175 

201 --no-publicly-accessible --storage-encrypted201 --no-publicly-accessible --storage-encrypted

202 ```202 ```

203 203 

204 리터럴 `--master-user-password` 인수는 명령이 실행되는 동안 프로세스 테이블 및 감사/EDR 로그에 표시됩니다. 공유 또는 모니터링되는 호스트에서는 번들의 `setup.sh`가 하는 방식처럼 `0600` 파일에서 `--cli-input-json`을 통해 암호를 전달하십시오.204 리터럴 `--master-user-password` 인수는 명령이 실행되는 동안 프로세스 테이블 및 감사/EDR 로그에 표시되며, 이는 비밀 단계의 참고 사항이 다루는 것과 동일한 노출입니다. 공유 또는 모니터링되는 호스트에서는 번들의 `setup.sh`가 하는 방식처럼 `0600` 파일에서 `--cli-input-json`을 통해 암호를 전달하십시오.

205 205 

206 인스턴스가 시작될 때까지 기다리십시오. 몇 분이 걸릴 수 있습니다. 그런 다음 프라이빗 엔드포인트를 읽고 게이트웨이가 사용할 연결 문자열을 조합하십시오:206 인스턴스가 시작될 때까지 기다리십시오. 몇 분이 걸릴 수 있습니다. 그런 다음 프라이빗 엔드포인트를 읽고 게이트웨이가 사용할 연결 문자열을 조합하십시오:

207 207 

220 <Step title="gateway.yaml 작성">220 <Step title="gateway.yaml 작성">

221 `upstreams` 블록은 `auth: {}`로 Bedrock을 가리키므로 게이트웨이는 ECS의 작업 역할 또는 EKS의 IRSA 역할에서 AWS 기본 자격 증명 체인을 통해 인증합니다. 모든 필드는 [구성 참조](/docs/ko/claude-apps-gateway-config)를 참조하십시오.221 `upstreams` 블록은 `auth: {}`로 Bedrock을 가리키므로 게이트웨이는 ECS의 작업 역할 또는 EKS의 IRSA 역할에서 AWS 기본 자격 증명 체인을 통해 인증합니다. 모든 필드는 [구성 참조](/docs/ko/claude-apps-gateway-config)를 참조하십시오.

222 222 

223 2개의 `listen` 필드는 게이트웨이 앞에 있는 것에 따라 다릅니다:223 2개의 `listen` 필드는 게이트웨이 앞단에 무엇이 있는지를 설명합니다:

224 224 

225 * `public_url`: 외부 `https://` 원점이며, 비루프백 바인드에 필수입니다. [listen 참조](/docs/ko/claude-apps-gateway-config#listen)를 참조하십시오. 게이트웨이는 IdP `redirect_uri`와 검색 문서를 이 값에서만 빌드하며, `X-Forwarded-*` 헤더에서는 빌드하지 않습니다.225 * `public_url`: 외부 `https://` 원점이며, 비루프백 바인드에 필수입니다. [`listen` 참조](/docs/ko/claude-apps-gateway-config#listen)를 참조하십시오. 게이트웨이는 IdP `redirect_uri`와 검색 문서를 이 값에서만 빌드하며, `X-Forwarded-*` 헤더에서는 빌드하지 않습니다.

226 * `trusted_proxies`: 프론트 엔드의 소스 범위입니다. 게이트웨이는 TCP 피어가 이 목록에 있을 때만 `X-Forwarded-For`를 준수하고, 신뢰할 수 있는 홉을 지나 체인을 걷습니다. 따라서 IP별 로그인 속도 제한 및 감사 이벤트는 로드 밸런서의 IP가 아닌 개발자 IP를 기록합니다.226 * `trusted_proxies`: 프론트 엔드의 소스 범위입니다. 게이트웨이는 TCP 피어가 이 목록에 있을 때만 `X-Forwarded-For`를 준수하고, 신뢰할 수 있는 홉을 지나 체인을 걷습니다. 따라서 IP별 로그인 속도 제한 및 감사 이벤트는 로드 밸런서의 IP가 아닌 개발자 IP를 기록합니다.

227 227 

228 두 트랙 모두에서 프론트 엔드는 직접 생성되거나 AWS Load Balancer Controller에 의해 생성되는 내부 ALB이며, ALB의 노드는 연결된 서브넷에서 주소를 가져오므로 `trusted_proxies`를 해당 서브넷의 CIDR로 설정하십시오. 이는 해당 서브넷의 모든 호스트를 프록시로 신뢰합니다. ALB의 수신 소스인 회사 CIDR이 이들과 겹치지 않도록 유지하고, 신뢰할 수 없는 워크로드와 서브넷을 공유하지 마십시오. 이들은 `X-Forwarded-For`를 통해 클라이언트 IP를 스푸핑할 수 있습니다.228 두 트랙 모두에서 프론트 엔드는 직접 생성되거나 AWS Load Balancer Controller에 의해 생성되는 내부 ALB이며, ALB의 노드는 연결된 서브넷에서 주소를 가져오므로 `trusted_proxies`를 해당 서브넷의 CIDR로 설정하십시오. 이는 해당 서브넷의 모든 호스트를 프록시로 신뢰합니다. ALB의 수신 소스인 회사 CIDR이 이들과 겹치지 않도록 유지하고, 신뢰할 수 없는 워크로드와 서브넷을 공유하지 마십시오. 이들은 `X-Forwarded-For`를 통해 클라이언트 IP를 스푸핑할 수 있습니다.

244 # Okta org 인증 서버는 이메일과 그룹을 생략하는 얇은 id_token을 반환합니다.244 # Okta org 인증 서버는 이메일과 그룹을 생략하는 얇은 id_token을 반환합니다.

245 # 게이트웨이는 /userinfo에서 이들을 채웁니다.245 # 게이트웨이는 /userinfo에서 이들을 채웁니다.

246 userinfo_fallback: true246 userinfo_fallback: true

247 # Okta는 `groups` 범위가 요청되고 앱의 그룹 클레임 필터가 이를 허용할 때만 그룹을 내보냅니다.247 # Okta는 `groups` 범위가 요청되고 앱의 그룹 클레임 필터가

248 # 이를 허용할 때만 그룹을 내보냅니다.

248 scopes: [openid, profile, email, offline_access, groups]249 scopes: [openid, profile, email, offline_access, groups]

249 250 

250 session:251 session:

251 jwt_secret: ${GATEWAY_JWT_SECRET} # EKS: ${file:/secrets/jwt-secret}252 jwt_secret: ${GATEWAY_JWT_SECRET} # EKS: ${file:/secrets/jwt-secret}

252 ttl_hours: 8 # 프로비저닝 해제 지연을 제한합니다. 더 엄격한 취소를 위해 1로 낮추십시오.253 ttl_hours: 8 # 프로비저닝 해제 지연을 제한합니다. 더 엄격한 취소를 위해

254 # 1에 가깝게 낮추십시오.

253 255 

254 store:256 store:

255 postgres_url: ${GATEWAY_POSTGRES_URL} # EKS: ${file:/secrets/postgres-url}257 postgres_url: ${GATEWAY_POSTGRES_URL} # EKS: ${file:/secrets/postgres-url}

256 # readiness_grace_seconds: 300 # RDS 장애 조치를 통해 상태 확인을 계속 통과합니다.258 # readiness_grace_seconds: 300 # RDS 장애 조치 중에도

259 # 상태 확인을 계속 통과합니다.

257 260 

258 upstreams:261 upstreams:

259 - provider: bedrock262 - provider: bedrock

260 region: <your-region> # IAM 정책의 ARN이 이를 포함하도록 $AWS_REGION과 일치합니다.263 region: <your-region> # IAM 정책의 ARN이 이를 포함하도록

261 auth: {} # AWS 기본 자격 증명 체인: ECS 작업 역할 또는 EKS의 IRSA264 # $AWS_REGION과 일치시킵니다.

265 auth: {} # AWS 기본 자격 증명 체인:

266 # ECS 작업 역할 또는 EKS의 IRSA

262 ```267 ```

263 268 

264 <Note>269 <Note>

307 ENV NODE_EXTRA_CA_CERTS=/etc/claude/rds-global-bundle.pem312 ENV NODE_EXTRA_CA_CERTS=/etc/claude/rds-global-bundle.pem

308 ```313 ```

309 314 

310 ECR 리포지토리를 생성하고 Docker를 로그인하십시오. 불변 태그는 배포 단계가 고정하는 `<version>` 태그를 나중에 다른 이미지로 자동으로 다시 가리킬 수 없음을 의미합니다:315 ECR 저장소를 생성하고 Docker를 로그인하십시오. 불변 태그는 배포 단계가 고정하는 `<version>` 태그를 나중에 다른 이미지로 자동으로 다시 가리킬 수 없음을 의미합니다:

311 316 

312 ```bash theme={null}317 ```bash theme={null}

313 aws ecr create-repository --repository-name claude-gateway \318 aws ecr create-repository --repository-name claude-gateway \

396 401 

397 HTTPS 리스너를 추가합니다. `--ssl-policy`는 최신 TLS 하한을 고정합니다. 생략하면 여전히 TLS 1.0/1.1을 허용하는 레거시 `ELBSecurityPolicy-2016-08` 기본값으로 돌아갑니다.402 HTTPS 리스너를 추가합니다. `--ssl-policy`는 최신 TLS 하한을 고정합니다. 생략하면 여전히 TLS 1.0/1.1을 허용하는 레거시 `ELBSecurityPolicy-2016-08` 기본값으로 돌아갑니다.

398 403 

399 ALB는 기본적으로 60초 동안 데이터가 없는 연결을 닫습니다. 게이트웨이의 keepalive 핑은 스트림을 해당 기본값 내에 유지하므로 시간 초과를 높이면 핑 주기 위에 여유를 추가합니다. [문제 해결](#troubleshooting) 행에서 끊어진 스트림을 다룹니다. 아래 명령은 리스너를 추가하고 시간 초과를 높입니다:404 ALB는 기본적으로 60초 동안 데이터가 없는 연결을 닫습니다. 게이트웨이의 keepalive 핑은 스트림을 해당 기본값 내에 유지하므로 타임아웃을 높이면 핑 주기 위에 여유를 추가합니다. 끊어진 스트림에 대한 [문제 해결](#troubleshooting) 행에서 그 메커니즘과 이전 게이트웨이에 대해 다룹니다. 아래 명령은 리스너를 추가하고 타임아웃을 높입니다:

400 405 

401 ```bash theme={null}406 ```bash theme={null}

402 aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" \407 aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" \

420 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"425 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"

421 ```426 ```

422 427 

423 60초 유예 기간은 콜드 작업이 이미지를 가져오고, 저장소에 연결하고, 첫 번째 상태 확인에 응답할 시간을 제공합니다. ECS가 배포에 대한 실패를 계산하기 시작하기 전입니다. 대상 그룹의 `GET /readyz`에 대한 상태 확인은 저장소에 도달할 수 있는지 확인하므로 Postgres에 도달할 수 없는 작업은 회전에 들어가지 않습니다. [중단 동작](/docs/ko/claude-apps-gateway-deploy#outage-behavior)에서 트레이드오프와 `/healthz` 대안을 참조하십시오.428 60초 유예 기간은 ECS가 배포에 대한 실패를 계산하기 시작하기 전에 콜드 작업이 이미지를 가져오고, 저장소에 연결하고, 첫 번째 상태 확인에 응답할 시간을 제공합니다.

429 

430 대상 그룹의 `GET /readyz`에 대한 상태 확인은 저장소에 도달할 수 있는지 확인하므로 Postgres에 도달할 수 없는 작업은 회전에 들어가지 않습니다. RDS 장애 조치와 같은 짧은 데이터베이스 중단 동안에도 작업이 상태 확인을 계속 통과하도록 하려면 [중단 동작](/docs/ko/claude-apps-gateway-deploy#outage-behavior)에 설명된 대로 `store.readiness_grace_seconds`를 설정하십시오. 해당 문서에서는 `/healthz` 대안도 다룹니다.

424 431 

425 작업은 공개 IP가 없는 프라이빗 서브넷에서 실행되므로 모든 이그레스(Bedrock, IdP, Secrets Manager, ECR, CloudWatch Logs로)는 NAT 게이트웨이를 통해 이동합니다. Bedrock 트래픽을 공개 경로에서 벗어나게 하려면 `bedrock-runtime` 인터페이스 VPC 엔드포인트를 생성하고 업스트림의 `base_url`을 가리키십시오. [Bedrock 업스트림 참조](/docs/ko/claude-apps-gateway-config#amazon-bedrock)에 표시됩니다. IdP는 여전히 인터넷 이그레스가 필요합니다.432 작업은 공개 IP가 없는 프라이빗 서브넷에서 실행되므로 모든 이그레스(Bedrock, IdP, Secrets Manager, ECR, CloudWatch Logs로)는 NAT 게이트웨이를 통해 이동합니다. Bedrock 트래픽을 공개 경로에서 벗어나게 하려면 `bedrock-runtime` 인터페이스 VPC 엔드포인트를 생성하고 업스트림의 `base_url`을 가리키십시오. [Bedrock 업스트림 참조](/docs/ko/claude-apps-gateway-config#amazon-bedrock)에 표시됩니다. IdP는 여전히 인터넷 이그레스가 필요합니다.

426 433 

471 </Step>478 </Step>

472 479 

473 <Step title="게이트웨이 URL을 개발자 머신에 푸시">480 <Step title="게이트웨이 URL을 개발자 머신에 푸시">

474 게이트웨이가 이제 실행 중이지만 개발자는 게이트웨이 URL이 머신에 있을 때까지 `/login`에서 도달할 수 없습니다. [관리형 설정 파일](/docs/ko/claude-apps-gateway#set-the-gateway-url)에서 `forceLoginMethod` 및 `forceLoginGatewayUrl`을 설정하고 MDM을 통해 각 디바이스에 배포하십시오. 개발자가 수동으로 선택할 수 있는 로그인 선택기의 게이트웨이 옵션이 없습니다.481 게이트웨이가 이제 실행 중이지만 개발자는 게이트웨이 URL이 머신에 있을 때까지 `/login`에서 도달할 수 없습니다. MDM을 통해 각 디바이스에 배포하는 [관리형 설정 파일](/docs/ko/claude-apps-gateway#set-the-gateway-url)에서 `forceLoginMethod` 및 `forceLoginGatewayUrl`을 설정하십시오. 개발자가 수동으로 선택할 수 있는 로그인 선택기의 게이트웨이 옵션이 없습니다.

475 </Step>482 </Step>

476</Steps>483</Steps>

477 484 

442`claude --cloud` 및 `claude --teleport`는 claude.ai 계정으로 로그인해야 합니다. API 키로 인증하거나 저장된 계정 세부 정보가 오래된 경우 다음 중 하나가 표시됩니다.442`claude --cloud` 및 `claude --teleport`는 claude.ai 계정으로 로그인해야 합니다. API 키로 인증하거나 저장된 계정 세부 정보가 오래된 경우 다음 중 하나가 표시됩니다.

443 443 

444* `Unable to get organization UUID`444* `Unable to get organization UUID`

445* API 키 인증이 충분하지 않다는 메시지445* ``Cloud sessions need a claude.ai sign-in. Run `claude auth login` (or /login in a local session), then try again.``

446* 세션 ID 없이 `claude --teleport`를 실행할 때 세션 선택기에 표시되는 `Error loading Claude Code sessions`446* 세션 ID 없이 `claude --teleport`를 실행할 때 세션 선택기에 표시되는 `Error loading Claude Code sessions`

447 447 

448`/login`을 실행하여 claude.ai 계정으로 로그인한 다음 명령을 다시 시도하세요. 오류가 제공자의 이름을 지정하면 [오류 표](#errors-when-sending-to-a-cloud-session)를 참조하세요: 클라우드 세션을 타사 제공자를 통해 사용할 수 없습니다.448셸에서 [`claude auth login`](/docs/ko/cli-reference#cli-commands)을 실행하여 claude.ai 계정으로 로그인한 다음 명령을 다시 시도하세요. 실행 중인 세션 안에서는 `/login`이 같은 역할을 합니다. 오류가 대신 제공자의 이름을 표시하면 [오류 표](#errors-when-sending-to-a-cloud-session)를 참조하세요: 클라우드 세션을 타사 제공자를 통해 사용할 수 없습니다.

449 

450v2.1.274부터 v2.1.289까지는 로그인 메시지가 `Claude Code cloud sessions require authentication with a Claude.ai account. API key authentication is not sufficient. Please run /login to authenticate, or check your authentication status with /status.`로 표시되었습니다.

449 451 

450<h3 id="remote-control-session-expired-or-access-denied">452<h3 id="remote-control-session-expired-or-access-denied">

451 Remote Control 세션 만료 또는 액세스 거부453 Remote Control 세션 만료 또는 액세스 거부

34 oneLiner: 'Project instructions Claude reads every session',34 oneLiner: 'Project instructions Claude reads every session',

35 when: 'Loaded into context at the start of every session',35 when: 'Loaded into context at the start of every session',

36 description: 'Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here so Claude operates with the same assumptions your team does.',36 description: 'Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here so Claude operates with the same assumptions your team does.',

37 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/docs/en/skills">skill</A> or a path-scoped <A href="/docs/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>, <>If your repo already has an <C>AGENTS.md</C> for other coding agents, Claude Code <A href="/docs/en/memory#agents-md">can read that</A> on its own or alongside CLAUDE.md</>],37 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/docs/en/skills">skill</A> or a path-scoped <A href="/docs/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>, <>If your repo already has an <C>AGENTS.md</C> for other coding agents, Claude Code <A href="/docs/en/memory#agents-md">can read that</A> in place of a <C>CLAUDE.md</C></>],

38 exampleIntro: 'This example is for a TypeScript and React project. It lists the build and test commands, the framework conventions Claude should follow, and project-specific rules like export style and file layout.',38 exampleIntro: 'This example is for a TypeScript and React project. It lists the build and test commands, the framework conventions Claude should follow, and project-specific rules like export style and file layout.',

39 example: `# Project conventions39 example: `# Project conventions

40 40 

1434 1434 

1435Windows에서 `~/.claude`는 `%USERPROFILE%\.claude`로 확인됩니다. [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)을 설정하면, 이 페이지의 모든 `~/.claude` 경로가 대신 해당 디렉토리 아래에 있습니다.1435Windows에서 `~/.claude`는 `%USERPROFILE%\.claude`로 확인됩니다. [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)을 설정하면, 이 페이지의 모든 `~/.claude` 경로가 대신 해당 디렉토리 아래에 있습니다.

1436 1436 

1437대부분의 사용자는 `CLAUDE.md`와 `settings.json`만 편집합니다. 리포지토리에 이미 다른 코딩 에이전트용 `AGENTS.md`가 있는 경우, Claude Code는 [자체적으로 또는 `CLAUDE.md`와 함께 읽을 수 있습니다](/docs/ko/memory#agents-md). 디렉토리의 나머지는 선택 사항입니다. 필요에 따라 skills, rules, subagents를 추가합니다.1437대부분의 사용자는 `CLAUDE.md`와 `settings.json`만 편집합니다. 저장소에 이미 다른 코딩 에이전트용 `AGENTS.md`가 있는 경우, Claude Code는 `CLAUDE.md` 대신 [해당 파일을 읽을 수 있습니다](/docs/ko/memory#agents-md). 디렉터리의 나머지는 선택 사항입니다. 필요에 따라 스킬, 규칙, 서브에이전트를 추가합니다.

1438 1438 

1439<h2 id="explore-the-directory">1439<h2 id="explore-the-directory">

1440 디렉토리 탐색1440 디렉토리 탐색

1454| - | - | - |1454| - | - | - |

1455| `managed-settings.json` | 시스템 수준, OS에 따라 다름 | 재정의할 수 없는 엔터프라이즈 강제 설정입니다. [좁은 예외](/docs/ko/settings#security-keys-where-the-stricter-value-applies)를 제외하고는 재정의할 수 없습니다. [파일을 저장할 위치](/docs/ko/managed-settings#deploy-a-managed-settings-file) 및 [Claude Code가 사용하는 관리되는 소스](/docs/ko/managed-settings#precedence-within-the-managed-tier)를 참조하세요. |1455| `managed-settings.json` | 시스템 수준, OS에 따라 다름 | 재정의할 수 없는 엔터프라이즈 강제 설정입니다. [좁은 예외](/docs/ko/settings#security-keys-where-the-stricter-value-applies)를 제외하고는 재정의할 수 없습니다. [파일을 저장할 위치](/docs/ko/managed-settings#deploy-a-managed-settings-file) 및 [Claude Code가 사용하는 관리되는 소스](/docs/ko/managed-settings#precedence-within-the-managed-tier)를 참조하세요. |

1456| `CLAUDE.local.md` | 프로젝트 루트 | 이 프로젝트에 대한 개인 기본 설정으로, CLAUDE.md와 함께 로드됩니다. 수동으로 생성하고 `.gitignore`에 추가합니다. |1456| `CLAUDE.local.md` | 프로젝트 루트 | 이 프로젝트에 대한 개인 기본 설정으로, CLAUDE.md와 함께 로드됩니다. 수동으로 생성하고 `.gitignore`에 추가합니다. |

1457| `AGENTS.md` | 프로젝트 루트, `.claude/`, 또는 모든 디렉터리 | AI 코딩 에이전트를 위해 작성하는 프로젝트 지침입니다. Claude Code는 [이를 로드](/docs/ko/memory#agents-md)할 수 있으며, `CLAUDE.md`와 함께 로드할 수도 있습니다. |1457| `AGENTS.md` | 프로젝트 루트, `.claude/`, 또는 모든 디렉터리 | AI 코딩 에이전트를 위해 작성하는 프로젝트 지침입니다. Claude Code는 `CLAUDE.md` 대신 [이를 로드](/docs/ko/memory#agents-md)할 수 있습니다. |

1458| 설치된 플러그인 | `~/.claude/plugins` | 복제된 마켓플레이스, 설치된 플러그인 버전, `installed_plugins.json` 설치 기록, 플러그인별 데이터로, `claude plugin` 명령으로 관리됩니다. [claude.ai 계정에서 동기화된](/docs/ko/plugins/loading#synced-plugins) 플러그인은 `~/.claude/plugins/synced/`로 다운로드됩니다. 마켓플레이스 [`command` 소스](/docs/ko/plugins/marketplace-reference#command-plugin-source)에서 링크 모드로 설치된 플러그인의 경우, Claude Code는 복사본 대신 여기에 링크를 저장하고, 플러그인의 파일은 명령이 출력하는 디렉터리에 남아 있습니다. `command` 소스는 Claude Code v2.1.229 이상이 필요합니다. 로컬 경로에서 추가한 마켓플레이스에 상대 경로로 나열된 플러그인도 캐시 복사본이 아닌 소스 디렉터리에서 [제자리에 로드](/docs/ko/plugins/loading#find-plugins-on-disk)됩니다. [플러그인 캐싱](/docs/ko/plugins/loading#find-plugins-on-disk)에서 고아 버전이 정리되는 방식을 참조하세요. |1458| 설치된 플러그인 | `~/.claude/plugins` | 복제된 마켓플레이스, 설치된 플러그인 버전, `installed_plugins.json` 설치 기록, 플러그인별 데이터로, `claude plugin` 명령으로 관리됩니다. [claude.ai 계정에서 동기화된](/docs/ko/plugins/loading#synced-plugins) 플러그인은 `~/.claude/plugins/synced/`로 다운로드됩니다. 마켓플레이스 [`command` 소스](/docs/ko/plugins/marketplace-reference#command-plugin-source)에서 링크 모드로 설치된 플러그인의 경우, Claude Code는 복사본 대신 여기에 링크를 저장하고, 플러그인의 파일은 명령이 출력하는 디렉터리에 남아 있습니다. `command` 소스는 Claude Code v2.1.229 이상이 필요합니다. 로컬 경로에서 추가한 마켓플레이스에 상대 경로로 나열된 플러그인도 캐시 복사본이 아닌 소스 디렉터리에서 [제자리에 로드](/docs/ko/plugins/loading#find-plugins-on-disk)됩니다. [플러그인 캐싱](/docs/ko/plugins/loading#find-plugins-on-disk)에서 고아 버전이 정리되는 방식을 참조하세요. |

1459 1459 

1460`~/.claude`는 또한 작업할 때 Claude Code가 작성하는 데이터를 보유합니다. 트랜스크립트, 프롬프트 기록, 파일 스냅샷, 캐시, 로그입니다. 아래의 [애플리케이션 데이터](#application-data)를 참조하세요.1460`~/.claude`는 또한 작업할 때 Claude Code가 작성하는 데이터를 보유합니다. 트랜스크립트, 프롬프트 기록, 파일 스냅샷, 캐시, 로그입니다. 아래의 [애플리케이션 데이터](#application-data)를 참조하세요.

31| `claude attach <id\|name>` | 이 터미널에서 [백그라운드 세션](/docs/ko/agent-view#manage-sessions-from-the-shell)에 연결합니다. ID 대신 실행 중인 세션 이름의 일부를 전달하려면 Claude Code v2.1.290 이상이 필요합니다 | `claude attach 7c5dcf5d` |31| `claude attach <id\|name>` | 이 터미널에서 [백그라운드 세션](/docs/ko/agent-view#manage-sessions-from-the-shell)에 연결합니다. ID 대신 실행 중인 세션 이름의 일부를 전달하려면 Claude Code v2.1.290 이상이 필요합니다 | `claude attach 7c5dcf5d` |

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` |

35| `claude daemon run` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)를 이 터미널의 포그라운드에서 실행하고 로그를 인쇄합니다 | `claude daemon run` |

34| `claude daemon status` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)의 상태, 버전, 소켓 디렉토리 및 진단을 위한 워커 수를 인쇄합니다. 감독자가 실행 중이 아니면 1로 종료됩니다 | `claude daemon status` |36| `claude daemon status` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)의 상태, 버전, 소켓 디렉토리 및 진단을 위한 워커 수를 인쇄합니다. 감독자가 실행 중이 아니면 1로 종료됩니다 | `claude daemon status` |

35| `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` |

36| `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` |

1586 1586 

1587세션은 대표적인 토큰 수를 포함한 현실적인 흐름을 따릅니다:1587세션은 대표적인 토큰 수를 포함한 현실적인 흐름을 따릅니다:

1588 1588 

1589* **아무것도 입력하기 전**: CLAUDE.md, 자동 메모리, MCP 도구 이름, 그리고 스킬 설명이 모두 컨텍스트에 로드됩니다. [AGENTS.md 파일](/docs/ko/memory#agents-md)도 자신의 것으로 또는 CLAUDE.md와 함께 로드될 수 있습니다. 사용자의 설정에 따라 [출력 스타일](/docs/ko/output-styles) 또는 [`--append-system-prompt`](/docs/ko/cli-reference)의 텍스트와 같이 추가 항목이 있을 수 있습니다.1589* **아무것도 입력하기 전**: CLAUDE.md, 자동 메모리, MCP 도구 이름, 그리고 스킬 설명이 모두 컨텍스트에 로드됩니다. [AGENTS.md 파일](/docs/ko/memory#agents-md)이 CLAUDE.md 대신 로드될 수도 있습니다. 사용자의 설정에 따라 [출력 스타일](/docs/ko/output-styles) 또는 [`--append-system-prompt`](/docs/ko/cli-reference)의 텍스트와 같이 추가 항목이 있을 수 있습니다.

1590* **Claude가 작업할 때**: 각 파일 읽기가 컨텍스트에 추가되고, [경로 범위 규칙](/docs/ko/memory#path-specific-rules)이 일치하는 파일과 함께 자동으로 로드되며, [PostToolUse 훅](/docs/ko/hooks-guide)이 각 편집 후에 실행됩니다.1590* **Claude가 작업할 때**: 각 파일 읽기가 컨텍스트에 추가되고, [경로 범위 규칙](/docs/ko/memory#path-specific-rules)이 일치하는 파일과 함께 자동으로 로드되며, [PostToolUse 훅](/docs/ko/hooks-guide)이 각 편집 후에 실행됩니다.

1591* **후속 프롬프트**: [서브에이전트](/docs/ko/sub-agents)가 자신의 별도 컨텍스트 윈도우에서 연구를 처리하므로 대용량 파일 읽기가 사용자의 윈도우에서 벗어납니다. 요약과 작은 메타데이터 트레일러만 돌아옵니다.1591* **후속 프롬프트**: [서브에이전트](/docs/ko/sub-agents)가 자신의 별도 컨텍스트 윈도우에서 연구를 처리하므로 대용량 파일 읽기가 사용자의 윈도우에서 벗어납니다. 요약과 작은 메타데이터 트레일러만 돌아옵니다.

1592* **끝에서**: `/compact`가 대화를 구조화된 요약으로 바꿉니다. 대부분의 시작 콘텐츠는 자동으로 다시 로드됩니다. 아래 표는 각 메커니즘에 어떤 일이 발생하는지 보여줍니다.1592* **끝에서**: `/compact`가 대화를 구조화된 요약으로 바꿉니다. 대부분의 시작 콘텐츠는 자동으로 다시 로드됩니다. 아래 표는 각 메커니즘에 어떤 일이 발생하는지 보여줍니다.

1092실행 중인 데스크톱 앱의 버전을 보려면:1092실행 중인 데스크톱 앱의 버전을 보려면:

1093 1093 

1094* **macOS**: 메뉴 모음에서 **Claude**를 클릭한 다음 **About Claude**를 클릭합니다1094* **macOS**: 메뉴 모음에서 **Claude**를 클릭한 다음 **About Claude**를 클릭합니다

1095* **Windows**: **Help**를 클릭한 다음 **About**을 클릭합니다1095* **Windows**: **Help**를 클릭한 다음 **About Claude**를 클릭합니다

1096 1096 

1097버전 번호를 클릭하여 클립보드에 복사합니다.1097버전 번호를 클릭하여 클립보드에 복사합니다.

1098 1098 

92* **Cmd+S**로 스크린샷 또는 **Cmd+R**로 화면 녹화 저장 (창의 캡처 버튼 또는 단축키 사용, 파일은 Desktop에 저장됨)92* **Cmd+S**로 스크린샷 또는 **Cmd+R**로 화면 녹화 저장 (창의 캡처 버튼 또는 단축키 사용, 파일은 Desktop에 저장됨)

93* **Detach simulator**를 클릭하여 기기 스트리밍 중지 (종료하지 않음), 창을 **Attach simulator** 상태로 반환93* **Detach simulator**를 클릭하여 기기 스트리밍 중지 (종료하지 않음), 창을 **Attach simulator** 상태로 반환

94 94 

95시뮬레이터의 비디오 스트림을 조정하려면 창의 **Display** 메뉴를 엽니다. Mac에 부담이 되면 **Frame rate** 또는 **Resolution**을 낮춥니다. 두 설정 모두 창이 기기를 표시하는 방식을 변경하며, 앱 실행 방식은 변경하지 않습니다.95창에 **Display** 메뉴가 표시되면 이 메뉴를 사용하여 시뮬레이터의 비디오 스트림을 조정합니다. Mac에 부담이 되면 **Frame rate** 또는 **Resolution**을 낮춥니다. 두 설정 모두 창이 기기를 표시하는 방식을 변경하며, 앱 실행 방식은 변경하지 않습니다.

96 96 

97사용자와 Claude가 동일한 기기를 제어하므로 탭이 Claude가 보는 앱 상태를 변경합니다. Claude가 특정 화면을 확인하도록 하려면 탭하여 이동한 후 요청합니다. Claude가 기기를 제어하는 동안 창은 화면 위에 **Claude is using this device** 배지를 표시합니다. 배지가 사라질 때까지 탭을 기다려 결과가 입력이 아닌 앱을 반영하도록 합니다.97사용자와 Claude가 동일한 기기를 제어하므로 탭이 Claude가 보는 앱 상태를 변경합니다. Claude가 특정 화면을 확인하도록 하려면 탭하여 이동한 후 요청합니다. Claude가 기기를 제어하는 동안 창은 화면 위에 **Claude is using this device** 배지를 표시합니다. 배지가 사라질 때까지 탭을 기다려 결과가 입력이 아닌 앱을 반영하도록 합니다.

98 98 

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

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

356| `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)를 참조하세요 |356| `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)를 참조하세요 |

357| `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)를 참조하세요 |

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

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

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

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) |

198| `Cloud sessions are disabled by your organization's policy` | [명령줄 오류](#cloud-sessions-are-disabled-by-your-organizations-policy) |198| `Cloud sessions are disabled by your organization's policy` | [명령줄 오류](#cloud-sessions-are-disabled-by-your-organizations-policy) |

199| `Couldn't verify your organization's policy for cloud sessions` | [명령줄 오류](#cloud-sessions-are-disabled-by-your-organizations-policy) |199| `Couldn't verify your organization's policy for cloud sessions` | [명령줄 오류](#cloud-sessions-are-disabled-by-your-organizations-policy) |

200| `Cloud sessions need a claude.ai sign-in` | [조직 UUID를 가져올 수 없음](/docs/ko/claude-code-on-the-web#unable-to-get-organization-uuid) |

200| `Error: --json-schema is not a valid JSON Schema` | [명령줄 오류](#the-json-schema-value-is-not-a-valid-json-schema) |201| `Error: --json-schema is not a valid JSON Schema` | [명령줄 오류](#the-json-schema-value-is-not-a-valid-json-schema) |

201| `Error: Invalid --agents configuration:` | [명령줄 오류](#invalid-agents-configuration) |202| `Error: Invalid --agents configuration:` | [명령줄 오류](#invalid-agents-configuration) |

202| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [명령줄 오류](#invalid-agents-configuration) |203| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [명령줄 오류](#invalid-agents-configuration) |

387* 요청 중간에 컴퓨터가 절전 모드로 전환되어 끊어졌다고 Claude Code가 감지한 연결. Claude Code는 이를 위의 규칙에 따른 끊어진 연결로 계산합니다. 재시도 레이블이 특정 이유를 명시하면 `Connection lost while your computer was asleep`로 표시되며, Claude가 사고를 마친 후 텍스트나 도구 호출을 시작하기 전에 턴이 종료되면 메시지는 `Your computer went to sleep 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`로 표시됩니다.

388* 응답 헤더는 도착했지만 Claude의 응답이 도착하지 않았거나, Claude가 사고를 마쳤지만 텍스트나 도구 호출을 시작하지 않은 경우의 정체된 응답 스트림: Claude Code는 정체된 연결을 중단하고 위의 10회 시도 예산 외에 최대 1회까지 요청을 다시 발행합니다. Claude가 사고를 마친 후 텍스트나 도구 호출을 시작하기 전에 응답이 두 번째로 정체되면 Claude Code는 `The response stalled before a response was produced`로 턴을 종료합니다.389* 응답 헤더는 도착했지만 Claude의 응답이 도착하지 않았거나, Claude가 사고를 마쳤지만 텍스트나 도구 호출을 시작하지 않은 경우의 정체된 응답 스트림: Claude Code는 정체된 연결을 중단하고 위의 10회 시도 예산 외에 최대 1회까지 요청을 다시 발행합니다. Claude가 사고를 마친 후 텍스트나 도구 호출을 시작하기 전에 응답이 두 번째로 정체되면 Claude Code는 `The response stalled before a response was produced`로 턴을 종료합니다.

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

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

390* 임시 429 스로틀, 하지만 게이트웨이의 지출 한도 `429`는 아닙니다. 이는 스로틀이 아닙니다. [Spend limit reached](#spend-limit-reached)를 참조하세요.392* 임시 429 스로틀, 하지만 게이트웨이의 지출 한도 `429`는 아닙니다. 이는 스로틀이 아닙니다. [Spend limit reached](#spend-limit-reached)를 참조하세요.

391 * claude.ai 구독으로 로그인한 경우, 여기에는 플랜의 할당량 헤더를 전달하지 않는 429 스로틀이 포함됩니다. v2.1.199 이전에는 Claude Code가 API 키 및 Enterprise 로그인에 대해서만 해당 스로틀을 재시도했습니다.393 * claude.ai 구독으로 로그인한 경우, 여기에는 플랜의 할당량 헤더를 전달하지 않는 429 스로틀이 포함됩니다. v2.1.199 이전에는 Claude Code가 API 키 및 Enterprise 로그인에 대해서만 해당 스로틀을 재시도했습니다.

392* 입력 더하기 `max_tokens`이 컨텍스트 한도를 초과하기 때문에 거부된 요청. 변경하지 않고 다시 보내면 같은 방식으로 실패하므로 Claude Code는 감소된 `max_tokens`으로 재시도하고, 두 가지 경우에 재시도를 중지하고 대신 압축합니다:394* 입력 더하기 `max_tokens`이 컨텍스트 한도를 초과하기 때문에 거부된 요청. 변경하지 않고 다시 보내면 같은 방식으로 실패하므로 Claude Code는 감소된 `max_tokens`으로 재시도하고, 두 가지 경우에 재시도를 중지하고 대신 압축합니다:

405* [Amazon Bedrock streaming response with an unexpected content-type](#bedrock-streaming-response-has-an-unexpected-content-type), 게이트웨이 또는 프록시가 응답을 다시 쓰면 재시도도 같은 방식으로 다시 쓸 것이기 때문입니다. Claude Code v2.1.208 이상이 필요합니다.407* [Amazon Bedrock streaming response with an unexpected content-type](#bedrock-streaming-response-has-an-unexpected-content-type), 게이트웨이 또는 프록시가 응답을 다시 쓰면 재시도도 같은 방식으로 다시 쓸 것이기 때문입니다. Claude Code v2.1.208 이상이 필요합니다.

406* 실패한 스트리밍 요청의 비스트리밍 재시도가 성공 상태를 받지만 [no Claude API message in the body](#api-returned-an-empty-or-malformed-response). Claude Code는 해당 오류로 턴을 종료합니다.408* 실패한 스트리밍 요청의 비스트리밍 재시도가 성공 상태를 받지만 [no Claude API message in the body](#api-returned-an-empty-or-malformed-response). Claude Code는 해당 오류로 턴을 종료합니다.

407* 조직의 정책 검사가 거부한 요청, 이는 거부 메시지를 전달하는 `API Error:` 줄로 표시됩니다. 조직의 관리자는 Claude Enterprise 기능인 [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks)로 검사를 설정하고, 메시지는 구성한 지침으로 끝나거나 기본적으로 관리자에게 연락하도록 안내합니다. Claude Code는 거부가 모델이 아닌 요청의 내용에 관한 것이므로 거부된 요청을 동일한 모델이나 [폴백 모델](/docs/ko/model-config#fallback-model-chains)로 다시 보내지 않습니다. v2.1.239 이전에는 Claude Code가 거부를 표시하기 전에 거부된 요청을 스트리밍 없이 또는 구성된 폴백 모델에서 다시 보낼 수 있었습니다.409* 조직의 정책 검사가 거부한 요청, 이는 거부 메시지를 전달하는 `API Error:` 줄로 표시됩니다. 조직의 관리자는 Claude Enterprise 기능인 [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks)로 검사를 설정하고, 메시지는 구성한 지침으로 끝나거나 기본적으로 관리자에게 연락하도록 안내합니다. Claude Code는 거부가 모델이 아닌 요청의 내용에 관한 것이므로 거부된 요청을 동일한 모델이나 [폴백 모델](/docs/ko/model-config#fallback-model-chains)로 다시 보내지 않습니다. v2.1.239 이전에는 Claude Code가 거부를 표시하기 전에 거부된 요청을 스트리밍 없이 또는 구성된 폴백 모델에서 다시 보낼 수 있었습니다.

408* API의 출력 콘텐츠 필터가 차단한 응답. Claude Code는 즉시 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)를 표시하며 해당 요청을 재시도하거나 다시 보내지 않습니다.

409 410 

410<h3 id="what-you-see-while-claude-code-retries-or-waits">411<h3 id="what-you-see-while-claude-code-retries-or-waits">

411 Claude Code가 재시도하거나 대기하는 동안 보는 것412 Claude Code가 재시도하거나 대기하는 동안 보는 것

2905API Error: Output blocked by content filtering policy2906API Error: Output blocked by content filtering policy

2906```2907```

2907 2908 

2908Claude Code는 차단이 도착하는 즉시 오류를 표시하고 해당 요청을 종료합니다. 요청을 재시도하거나, 스트리밍 없이 다시 보내거나, [폴백 모델](/docs/ko/model-config#fallback-model-chains)로 전환하지 않습니다. v2.1.285 이전에는 Claude Code가 차단된 요청을 다시 보내고 재시도할 수 있었으며, 때로는 몇 분 동안 그렇게 한 후에야 오류를 표시했습니다.

2909 

2910**할 일:**2909**할 일:**

2911 2910 

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

130 130 

131Claude를 위해 작성하는 지속적인 지침의 마크다운 파일이며, 시스템 프롬프트 이후 사용자 메시지로 모든 세션의 시작 시 로드됩니다. 프로젝트 규칙, 아키텍처 노트 및 "항상 X를 수행" 규칙을 여기에 넣습니다. 프로젝트 루트 CLAUDE.md는 [컴팩션](#compaction)을 견디고 이후 디스크에서 새로 다시 읽습니다.131Claude를 위해 작성하는 지속적인 지침의 마크다운 파일이며, 시스템 프롬프트 이후 사용자 메시지로 모든 세션의 시작 시 로드됩니다. 프로젝트 규칙, 아키텍처 노트 및 "항상 X를 수행" 규칙을 여기에 넣습니다. 프로젝트 루트 CLAUDE.md는 [컴팩션](#compaction)을 견디고 이후 디스크에서 새로 다시 읽습니다.

132 132 

133CLAUDE.md를 프로젝트 범위에서 `./CLAUDE.md` 또는 `./.claude/CLAUDE.md`에, 사용자 범위에서 `~/.claude/CLAUDE.md`에, 또는 조직의 [관리 정책](#managed-settings)으로 배치할 수 있습니다. 발견된 모든 파일은 서로를 재정의하지 않고 연결되며, 가장 광범위한 범위에서 가장 구체적인 범위로 정렬됩니다. Claude Code는 또한 프로젝트의 [AGENTS.md](#agents-md) 파일을 자체적으로 또는 CLAUDE.md와 함께 로드할 수 있습니다.133CLAUDE.md를 프로젝트 범위에서 `./CLAUDE.md` 또는 `./.claude/CLAUDE.md`에, 사용자 범위에서 `~/.claude/CLAUDE.md`에, 또는 조직의 [관리형 정책](#managed-settings)으로 배치할 수 있습니다. 발견된 모든 파일은 서로를 재정의하지 않고 컨텍스트에 연결되며, 가장 광범위한 범위에서 가장 구체적인 범위로 정렬됩니다. Claude Code는 또한 CLAUDE.md 대신 프로젝트의 [AGENTS.md](#agents-md) 파일을 로드할 수 있습니다.

134 134 

135자세히 알아보기: [CLAUDE.md 파일](/docs/ko/memory#claude-md-files)135자세히 알아보기: [CLAUDE.md 파일](/docs/ko/memory#claude-md-files)

136 136 

210export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1210export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

211```211```

212 212 

213대부분의 모델 버전에는 해당하는 `VERTEX_REGION_CLAUDE_*` 변수가 있습니다. 전체 목록은 [환경 변수 참조](/docs/ko/env-vars)를 참조하세요. [Google Cloud의 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)을 확인하여 어떤 모델이 글로벌 엔드포인트를 지원하는지 또는 지역 전용인지 확인합니다.213대부분의 모델 버전에는 해당하는 `VERTEX_REGION_CLAUDE_*` 변수가 있습니다. 전체 목록은 [환경 변수 참조](/docs/ko/env-vars#variables)를 참조하세요. [Google Cloud의 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)을 확인하여 어떤 모델이 글로벌 엔드포인트를 지원하는지 또는 지역 전용인지 확인합니다.

214 214 

215지역 값이 지역 또는 위치 이름처럼 보이지 않으면 Claude Code는 이를 설정되지 않은 것으로 취급합니다. 예를 들어 Claude Code는 슬래시, 점 또는 공백을 포함하는 값을 설정되지 않은 것으로 취급합니다. Claude Code는 각 변수에 대해 다른 소스로 폴백합니다:215지역 값이 지역 또는 위치 이름처럼 보이지 않으면 Claude Code는 이를 설정되지 않은 것으로 취급합니다. 예를 들어 Claude Code는 슬래시, 점 또는 공백을 포함하는 값을 설정되지 않은 것으로 취급합니다. Claude Code는 각 변수에 대해 다른 소스로 폴백합니다:

216 216 

366* 지정된 위치에서 모델을 사용할 수 있는지 확인합니다. 일부 모델은 특정 지역이 아닌 `global` 또는 `eu` 및 `us`와 같은 다중 지역 위치에서만 제공됩니다366* 지정된 위치에서 모델을 사용할 수 있는지 확인합니다. 일부 모델은 특정 지역이 아닌 `global` 또는 `eu` 및 `us`와 같은 다중 지역 위치에서만 제공됩니다

367* `CLOUD_ML_REGION=global`을 사용하는 경우 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)의 "지원되는 기능" 아래에서 모델이 전역 엔드포인트를 지원하는지 확인합니다. 전역 엔드포인트를 지원하지 않는 모델의 경우:367* `CLOUD_ML_REGION=global`을 사용하는 경우 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)의 "지원되는 기능" 아래에서 모델이 전역 엔드포인트를 지원하는지 확인합니다. 전역 엔드포인트를 지원하지 않는 모델의 경우:

368 * `ANTHROPIC_MODEL` 또는 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 통해 지원되는 모델을 지정하거나,368 * `ANTHROPIC_MODEL` 또는 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 통해 지원되는 모델을 지정하거나,

369 * `VERTEX_REGION_<MODEL_NAME>` 환경 변수를 사용하여 지역 또는 다중 지역 위치를 설정합니다369 * [환경 변수 참조](/docs/ko/env-vars#variables)에 나열된 해당 모델의 `VERTEX_REGION_CLAUDE_*` 변수를 사용하여 지역 또는 다중 지역 위치를 설정합니다

370 370 

371429 오류가 발생하는 경우:371429 오류가 발생하는 경우:

372 372 

63| `DirectoryAdded` | 작업 디렉토리가 세션 중에 `/add-dir` 또는 SDK `register_repo_root` 제어 요청을 통해 추가될 때 |63| `DirectoryAdded` | 작업 디렉토리가 세션 중에 `/add-dir` 또는 SDK `register_repo_root` 제어 요청을 통해 추가될 때 |

64| `FileChanged` | 감시 중인 파일이 디스크에서 변경될 때. `matcher` 필드는 감시할 파일명을 지정합니다 |64| `FileChanged` | 감시 중인 파일이 디스크에서 변경될 때. `matcher` 필드는 감시할 파일명을 지정합니다 |

65| `WorktreeCreate` | 워크트리가 `--worktree`, `isolation: "worktree"`를 통해 생성되거나 백그라운드 세션을 위해 생성될 때. 기본 git 동작을 대체합니다 |65| `WorktreeCreate` | 워크트리가 `--worktree`, `isolation: "worktree"`를 통해 생성되거나 백그라운드 세션을 위해 생성될 때. 기본 git 동작을 대체합니다 |

66| `WorktreeRemove` | 워크트리가 세션 종료 시, 서브에이전트가 완료될 때, 또는 백그라운드 세션을 삭제할 때 제거될 때 |66| `WorktreeRemove` | `WorktreeCreate` 훅이 생성한 워크트리가 제거될 때 |

67| `PreCompact` | 컨텍스트 압축 전 |67| `PreCompact` | 컨텍스트 압축 전 |

68| `PostCompact` | 컨텍스트 압축이 완료된 후 |68| `PostCompact` | 컨텍스트 압축이 완료된 후 |

69| `PreModelSwitch` | Claude Code가 사용자 또는 클라이언트가 요청한 모델 전환을 적용하기 전. 전환을 차단할 수 있음 |69| `PreModelSwitch` | Claude Code가 사용자 또는 클라이언트가 요청한 모델 전환을 적용하기 전. 전환을 차단할 수 있음 |

3274 WorktreeRemove3274 WorktreeRemove

3275</h3>3275</h3>

3276 3276 

3277worktree가 제거될 때 실행됩니다. [WorktreeCreate](#worktreecreate)에 대응하는 정리용 이벤트입니다. 이 이벤트는 다음 경우에 발생합니다.3277Claude Code가 [`WorktreeCreate`](#worktreecreate) 훅으로 생성된 worktree를 정리할 때 실행됩니다. 이 이벤트는 다음 경우에 발생합니다.

3278 3278 

3279* `--worktree` 세션을 종료하면서 제거를 선택한 경우3279* `--worktree` 세션을 종료하면서 worktree 제거를 선택한 경우

3280* `isolation: "worktree"`가 설정된 서브에이전트가 완료된 경우3280* 해당 worktree에서 실행되는 [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제한 경우

3281* 훅이 생성한 worktree를 사용하는 [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제한 경우

3282 3281 

3283git 기반 worktree의 경우 Claude Code가 `git worktree remove`로 정리를 자동으로 처리합니다. WorktreeCreate 훅을 구성했다면 WorktreeRemove 훅과 함께 사용하여 해당 훅이 생성한 워크트리의 정리를 제어하십시오.3282git 기반 worktree의 경우 Claude Code가 `git worktree remove`로 정리를 자동으로 처리합니다. WorktreeCreate 훅을 구성했다면 WorktreeRemove 훅과 함께 사용하여 해당 훅이 생성한 워크트리의 정리를 제어하십시오.

3284 3283 

526| `DirectoryAdded` | 작업 디렉토리가 세션 중에 `/add-dir` 또는 SDK `register_repo_root` 제어 요청을 통해 추가될 때 |526| `DirectoryAdded` | 작업 디렉토리가 세션 중에 `/add-dir` 또는 SDK `register_repo_root` 제어 요청을 통해 추가될 때 |

527| `FileChanged` | 감시 중인 파일이 디스크에서 변경될 때. `matcher` 필드는 감시할 파일명을 지정합니다 |527| `FileChanged` | 감시 중인 파일이 디스크에서 변경될 때. `matcher` 필드는 감시할 파일명을 지정합니다 |

528| `WorktreeCreate` | 워크트리가 `--worktree`, `isolation: "worktree"`를 통해 생성되거나 백그라운드 세션을 위해 생성될 때. 기본 git 동작을 대체합니다 |528| `WorktreeCreate` | 워크트리가 `--worktree`, `isolation: "worktree"`를 통해 생성되거나 백그라운드 세션을 위해 생성될 때. 기본 git 동작을 대체합니다 |

529| `WorktreeRemove` | 워크트리가 세션 종료 시, 서브에이전트가 완료될 때, 또는 백그라운드 세션을 삭제할 때 제거될 때 |529| `WorktreeRemove` | `WorktreeCreate` 훅이 생성한 워크트리가 제거될 때 |

530| `PreCompact` | 컨텍스트 압축 전 |530| `PreCompact` | 컨텍스트 압축 전 |

531| `PostCompact` | 컨텍스트 압축이 완료된 후 |531| `PostCompact` | 컨텍스트 압축이 완료된 후 |

532| `PreModelSwitch` | Claude Code가 사용자 또는 클라이언트가 요청한 모델 전환을 적용하기 전. 전환을 차단할 수 있음 |532| `PreModelSwitch` | Claude Code가 사용자 또는 클라이언트가 요청한 모델 전환을 적용하기 전. 전환을 차단할 수 있음 |

76* **프로젝트.** 디렉토리 및 하위 디렉토리의 파일, 그리고 허가를 받은 다른 곳의 파일.76* **프로젝트.** 디렉토리 및 하위 디렉토리의 파일, 그리고 허가를 받은 다른 곳의 파일.

77* **터미널.** 실행할 수 있는 모든 명령: 빌드 도구, git, 패키지 관리자, 시스템 유틸리티, 스크립트. 명령줄에서 할 수 있는 것이면 Claude도 할 수 있습니다.77* **터미널.** 실행할 수 있는 모든 명령: 빌드 도구, git, 패키지 관리자, 시스템 유틸리티, 스크립트. 명령줄에서 할 수 있는 것이면 Claude도 할 수 있습니다.

78* **git 상태.** 현재 브랜치, 커밋되지 않은 변경 사항, 최근 커밋 기록.78* **git 상태.** 현재 브랜치, 커밋되지 않은 변경 사항, 최근 커밋 기록.

79* **[CLAUDE.md](/docs/ko/memory).** 프로젝트별 지침, 규칙, Claude가 매 세션마다 알아야 할 컨텍스트를 저장하는 마크다운 파일. 저장소에 다른 코딩 에이전트를 위한 AGENTS.md가 있으면 Claude는 [자체적으로 또는 CLAUDE.md와 함께](/docs/ko/memory#agents-md) 읽을 수 있습니다.79* **[CLAUDE.md](/docs/ko/memory).** 프로젝트별 지침, 규칙, Claude가 매 세션마다 알아야 할 컨텍스트를 저장하는 마크다운 파일. 저장소에 다른 코딩 에이전트를 위한 AGENTS.md가 있으면 Claude는 CLAUDE.md 대신 [이를 읽을 수 있습니다](/docs/ko/memory#agents-md).

80* **[자동 메모리](/docs/ko/memory#auto-memory).** Claude가 작업하면서 자동으로 저장하는 학습 내용(프로젝트 패턴 및 사용자 선호도 등). MEMORY.md의 처음 200줄 또는 25KB 중 먼저 도달하는 것이 각 세션 시작 시 로드됩니다.80* **[자동 메모리](/docs/ko/memory#auto-memory).** Claude가 작업하면서 자동으로 저장하는 학습 내용(프로젝트 패턴 및 사용자 선호도 등). MEMORY.md의 처음 200줄 또는 25KB 중 먼저 도달하는 것이 각 세션 시작 시 로드됩니다.

81* **구성한 확장.** 외부 서비스를 위한 [MCP servers](/docs/ko/mcp), 워크플로우를 위한 [skills](/docs/ko/skills), 위임된 작업을 위한 [subagents](/docs/ko/sub-agents), 브라우저 상호작용을 위한 [Claude in Chrome](/docs/ko/chrome).81* **구성한 확장.** 외부 서비스를 위한 [MCP servers](/docs/ko/mcp), 워크플로우를 위한 [skills](/docs/ko/skills), 위임된 작업을 위한 [subagents](/docs/ko/sub-agents), 브라우저 상호작용을 위한 [Claude in Chrome](/docs/ko/chrome).

82 82 

8 8 

9각 Claude Code 세션은 새로운 컨텍스트 윈도우로 시작됩니다. 두 가지 메커니즘이 세션 간에 지식을 전달합니다:9각 Claude Code 세션은 새로운 컨텍스트 윈도우로 시작됩니다. 두 가지 메커니즘이 세션 간에 지식을 전달합니다:

10 10 

11* **CLAUDE.md 파일**: Claude에 지속적인 컨텍스트를 제공하기 위해 작성하는 지침. Claude는 또한 저장소의 [`AGENTS.md` 파일](#agents-md)을 CLAUDE.md와 함께 또는 단독으로 읽을 수 있습니다11* **CLAUDE.md 파일**: Claude에 지속적인 컨텍스트를 제공하기 위해 작성하는 지침. Claude는 또한 CLAUDE.md 대신 저장소의 [`AGENTS.md` 파일](#agents-md)을 읽을 수 있습니다

12* **자동 메모리**: 수정 및 선호도에 따라 Claude가 자신을 위해 작성하는 노트12* **자동 메모리**: 수정 및 선호도에 따라 Claude가 자신을 위해 작성하는 노트

13 13 

14이 페이지에서는 다음을 다룹니다:14이 페이지에서는 다음을 다룹니다:

15 15 

16* [CLAUDE.md 파일 작성 및 구성](#claude-md-files)16* [CLAUDE.md 파일 작성 및 구성](#claude-md-files)

17* [기존 AGENTS.md를 프로젝트 지침으로 사용](#agents-md)하기 (단독으로 또는 CLAUDE.md와 함께)17* [기존 AGENTS.md를 프로젝트 지침으로 사용](#agents-md)하기

18* [`.claude/rules/`를 사용하여 특정 파일 유형에 규칙 범위 지정](#organize-rules-with-claude/rules/)18* [`.claude/rules/`를 사용하여 특정 파일 유형에 규칙 범위 지정](#organize-rules-with-claude/rules/)

19* [자동 메모리 구성](#auto-memory)하여 Claude가 자동으로 노트를 작성하도록 함19* [자동 메모리 구성](#auto-memory)하여 Claude가 자동으로 노트를 작성하도록 함

20* [지침이 따라지지 않을 때 문제 해결](#troubleshoot-memory-issues)20* [지침이 따라지지 않을 때 문제 해결](#troubleshoot-memory-issues)

163 claude "commit my changes with a descriptive message"163 claude "commit my changes with a descriptive message"

164 ```164 ```

165 165 

166 CI에서 [GitHub Actions](/docs/ko/github-actions) 또는 [GitLab CI/CD](/docs/ko/gitlab-ci-cd)를 사용하여 코드 검토 및 이슈 분류를 자동화할 수 있습니다.166 CI에서 [GitHub Actions](/docs/ko/github-actions) 또는 [GitLab CI/CD](/docs/ko/gitlab-ci-cd)를 사용하여 코드 리뷰 및 이슈 분류를 자동화할 수 있습니다.

167 </Accordion>167 </Accordion>

168 168 

169 <Accordion title="MCP로 도구 연결" icon="plug">169 <Accordion title="MCP로 도구 연결" icon="plug">

170 [Model Context Protocol (MCP)](/docs/ko/mcp)는 AI 도구를 외부 데이터 소스에 연결하기 위한 개방형 표준입니다. MCP를 사용하면 Claude Code는 Google Drive에서 설계 문서를 읽고, Jira에서 티켓을 업데이트하고, Slack에서 데이터를 가져오거나, 자신의 커스텀 도구를 사용할 수 있습니다. [MCP 빠른 시작](/docs/ko/mcp-quickstart)은 첫 번째 서버를 처음부터 끝까지 연결합니다.170 [Model Context Protocol (MCP)](/docs/ko/mcp)는 AI 도구를 외부 데이터 소스에 연결하기 위한 개방형 표준입니다. MCP를 사용하면 Claude Code는 Google Drive에서 설계 문서를 읽고, Jira에서 티켓을 업데이트하고, Slack에서 데이터를 가져오거나, 자신의 커스텀 도구를 사용할 수 있습니다. [MCP 빠른 시작](/docs/ko/mcp-quickstart)은 첫 번째 서버를 처음부터 끝까지 연결합니다.

171 </Accordion>171 </Accordion>

172 172 

173 <Accordion title="지침, skills 및 hooks로 사용자 정의" icon="sliders">173 <Accordion title="지침, 스킬 및 훅으로 사용자 정의" icon="sliders">

174 [`CLAUDE.md`](/docs/ko/memory)는 프로젝트 루트에 추가하는 마크다운 파일로 Claude Code가 모든 세션의 시작 부분에서 읽습니다. 이를 사용하여 코딩 표준, 아키텍처 결정, 선호하는 라이브러리 및 검토 체크리스트를 설정합니다. 리포지토리에 이미 다른 코딩 에이전트용 `AGENTS.md`가 있는 경우 Claude Code는 [자체적으로 읽을 수 있습니다](/docs/ko/memory#agents-md) 또는 `CLAUDE.md`와 함께 읽을 수 있습니다. Claude는 또한 작업할 때 [자동 메모리](/docs/ko/memory#auto-memory)를 구축하여 세션 전체에서 학습 내용을 저장하므로 아무것도 작성할 필요가 없습니다.174 [`CLAUDE.md`](/docs/ko/memory)는 프로젝트 루트에 추가하는 마크다운 파일로 Claude Code가 모든 세션의 시작 부분에서 읽습니다. 이를 사용하여 코딩 표준, 아키텍처 결정, 선호하는 라이브러리 및 검토 체크리스트를 설정합니다. 저장소에 이미 다른 코딩 에이전트용 `AGENTS.md`가 있는 경우 Claude Code는 `CLAUDE.md` 대신 [해당 파일을 읽을 수 있습니다](/docs/ko/memory#agents-md). Claude는 또한 작업할 때 [자동 메모리](/docs/ko/memory#auto-memory)를 구축하여 세션 전체에서 학습 내용을 저장하므로 아무것도 작성할 필요가 없습니다.

175 175 

176 [skills](/docs/ko/skills)를 생성하여 팀이 공유할 수 있는 반복 가능한 워크플로우를 패키징합니다(예: `/review-pr` 또는 `/deploy-staging`).176 [skills](/docs/ko/skills)를 생성하여 팀이 공유할 수 있는 반복 가능한 워크플로우를 패키징합니다(예: `/review-pr` 또는 `/deploy-staging`).

177 177 

733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

734```734```

735 735 

736이 에이전트는 `my-plugin:security-reviewer`로 이름 지정되고, 사용자는 `@agent-my-plugin:security-reviewer`로 [명시적으로 호출](/docs/ko/sub-agents#invoke-subagents-explicitly)할 수 있습니다. 이름 형식은 `<plugin>:<name>`이며, `<name>`은 frontmatter에서 오거나 없을 때 파일 이름에서 옵니다.736이 에이전트는 `my-plugin:security-reviewer`로 이름 지정되고, 사용자는 `@agent-my-plugin:security-reviewer`로 [명시적으로 호출](/docs/ko/sub-agents#invoke-subagents-explicitly)할 수 있습니다. 이름 형식은 `<plugin>:<name>`이며, `<name>`은 frontmatter `name` 필드에서 오거나, 해당 필드가 없을 때 파일 이름에서 옵니다.

737 737 

738`agents` manifest 키는 `agents/` 스캔을 대체합니다.738`agents` manifest 키는 `agents/` 스캔을 대체합니다.

739 739 

428 428 

429| 요소 | 그리는 내용 | 사용 위치 |429| 요소 | 그리는 내용 | 사용 위치 |

430| :- | :- | :- |430| :- | :- | :- |

431| `Box` | flex 컨테이너입니다. `flexDirection`, `columnGap`, `padding`, `borderStyle`, `width` 같은 레이아웃 prop을 받습니다. | 모든 곳 |431| `Box` | flex 컨테이너입니다. `flexDirection`, `columnGap`, `padding`, [`borderStyle`](/docs/ko/plugins/mods/reference#box-border-styles), `width` 같은 레이아웃 prop을 받습니다. | 모든 곳 |

432| `Text` | 스타일이 적용된 텍스트입니다. `color`, `bold`, `dimColor`, `italic`, `wrap`을 받습니다. `color`는 테마 키 또는 `'red'` 같은 색상입니다. `wrap`은 `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'`, `'truncate-end'` 중 하나입니다. | 모든 곳 |432| `Text` | 스타일이 적용된 텍스트입니다. `color`, `bold`, `dimColor`, `italic`, `wrap`을 받습니다. `color`는 테마 키 또는 `'red'` 같은 색상입니다. `wrap`은 `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'`, `'truncate-end'` 중 하나입니다. | 모든 곳 |

433| `Button` | `onPress`를 호출하는 컨트롤 | 모든 곳 |433| `Button` | `onPress`를 호출하는 컨트롤 | 모든 곳 |

434| `Link`, `Code`, `Markdown` | `href`와 선택적 `label`을 갖는 링크, 코드 블록, 그리고 Claude의 응답과 같은 방식으로 서식이 지정된 텍스트입니다. `Markdown`은 내용을 `children`이 아닌 `text` prop으로 받으며, `onLinkPress`를 전달할 때는 `key`가 필요합니다. | 모든 곳 |434| `Link`, `Code`, `Markdown` | `href`와 선택적 `label`을 갖는 링크, 코드 블록, 그리고 Claude의 응답과 같은 방식으로 서식이 지정된 텍스트입니다. `Markdown`은 내용을 `children`이 아닌 `text` prop으로 받으며, `onLinkPress`를 전달할 때는 `key`가 필요합니다. | 모든 곳 |

563많은 창은 텍스트 필드 아래에 목록이 있는 형태입니다. 이 섹션의 예시는 메모 창입니다. 메모를 입력하고 Enter를 눌러 추가하며, 각 메모에는 메모를 삭제하는 `x` 버튼이 있습니다. 메모 두 개를 추가하면 터미널은 창을 다음과 같이 그립니다.563많은 창은 텍스트 필드 아래에 목록이 있는 형태입니다. 이 섹션의 예시는 메모 창입니다. 메모를 입력하고 Enter를 눌러 추가하며, 각 메모에는 메모를 삭제하는 `x` 버튼이 있습니다. 메모 두 개를 추가하면 터미널은 창을 다음과 같이 그립니다.

564 564 

565```text theme={null}565```text theme={null}

566╭──────────────────────────────────────────────────────────╮566╭────────────────────────────────────────────────────────✕─╮

567│ Note: Type a note and press Enter ⏎ add ✕ │567│ Note: Type a note and press Enter ⏎ add │

568│ x buy milk │568│ x buy milk │

569│ x call bob │569│ x call bob │

570╰──────────────────────────────────────────────────────────╯570╰──────────────────────────────────────────────────────────╯

571```571```

572 572 

573위쪽 테두리의 `✕`는 창을 닫기 위한 Claude Code 자체의 표시입니다.

574 

573이 예시는 다음 기법을 사용합니다.575이 예시는 다음 기법을 사용합니다.

574 576 

575* **입력 받기**: `Input`은 사용자가 Enter를 누르면 필드의 텍스트로 `onSubmit(value)`를 호출하고, 변경이 있을 때마다 `onInput(value)`를 호출합니다577* **입력 받기**: `Input`은 사용자가 Enter를 누르면 필드의 텍스트로 `onSubmit(value)`를 호출하고, 변경이 있을 때마다 `onInput(value)`를 호출합니다

242트리를 해당 지점에 맞추려면 훅에서 다음 prop을 읽습니다.242트리를 해당 지점에 맞추려면 훅에서 다음 prop을 읽습니다.

243 243 

244* **`Pane` 또는 밴드의 너비**: `e.props.bodyColumns`에 맞춰 그립니다244* **`Pane` 또는 밴드의 너비**: `e.props.bodyColumns`에 맞춰 그립니다

245* **트랜스크립트 옆에 있는 `Pane`의 높이**: `e.props.placement`가 `'dock'`인 경우 `e.props.scroll.bodyRows`는 창이 가진 행 수입니다245* **트랜스크립트 옆에 있는 `Pane`의 높이**: `e.props.placement`가 `'dock'`인 경우 `e.props.scroll.bodyRows`는 창이 트리에 제공하는 행 수입니다

246* **프롬프트 위에 있는 `Pane`의 높이**: `e.props.placement`가 `'inline'`인 경우 창은 트리에 맞춰 한도까지 커지며, `bodyRows`가 그 한도입니다. [`$.ui.open`의 `rows` 필드](/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)로 다른 한도를 요청할 수 있습니다.246* **프롬프트 위에 있는 `Pane`의 높이**: `e.props.placement`가 `'inline'`인 경우 창은 트리에 맞춰 한도까지 커지며, `bodyRows`가 그 한도입니다. [`$.ui.open`의 `rows` 필드](/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)로 다른 한도를 요청할 수 있습니다.

247 247 

248창보다 높은 트리는 전체가 하나로 스크롤됩니다.248창보다 높은 트리는 전체가 하나로 스크롤됩니다.

255 255 

256| 요소 | 주요 prop | 터미널 | 데스크톱 |256| 요소 | 주요 prop | 터미널 | 데스크톱 |

257| :- | :- | :-: | :-: |257| :- | :- | :-: | :-: |

258| [`Box`](/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `key`, flex 레이아웃, `gap`, `padding`, `margin`, `width`, `height`, `borderStyle`, `backgroundColor`, `position`, `hover` | ✓ | ✓ |258| [`Box`](/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `key`, flex 레이아웃, `gap`, `padding`, `margin`, `width`, `height`, [`borderStyle`](#box-border-styles), `backgroundColor`, `position`, `hover` | ✓ | ✓ |

259| [`Text`](/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, `bold`, `italic`, `underline`, `dimColor`, `inverse`, `wrap` | ✓ | ✓ |259| [`Text`](/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, `bold`, `italic`, `underline`, `dimColor`, `inverse`, `wrap` | ✓ | ✓ |

260| [`Button`](/docs/ko/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action` | ✓ | ✓ |260| [`Button`](/docs/ko/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action` | ✓ | ✓ |

261| `Link` | `href`, `label` | ✓ | ✓ |261| `Link` | `href`, `label` | ✓ | ✓ |

270 270 

271`Button`에 대한 추가 규칙: `action`은 Claude Code 자체의 [키보드 단축키 액션](/docs/ko/keybindings) 중 하나를 지정하며, 해당 액션에 대한 사용자의 바인딩이 코드(chord) 또는 수정자 키 조합인 경우 그 바인딩으로 버튼이 눌립니다. 밴드에 있는 버튼의 숫자 `hotkey`는 사용자가 빈 프롬프트에 해당 숫자만 입력하고 잠시 멈출 때도 실행됩니다. 하나의 그리기에서 두 버튼이 동일한 `hotkey`를 지정하면 나중의 버튼이 이를 가져갑니다. `autoFocus`는 모든 컨트롤에서 `true`만 허용하므로, 이를 끄려면 해당 prop을 생략하십시오.271`Button`에 대한 추가 규칙: `action`은 Claude Code 자체의 [키보드 단축키 액션](/docs/ko/keybindings) 중 하나를 지정하며, 해당 액션에 대한 사용자의 바인딩이 코드(chord) 또는 수정자 키 조합인 경우 그 바인딩으로 버튼이 눌립니다. 밴드에 있는 버튼의 숫자 `hotkey`는 사용자가 빈 프롬프트에 해당 숫자만 입력하고 잠시 멈출 때도 실행됩니다. 하나의 그리기에서 두 버튼이 동일한 `hotkey`를 지정하면 나중의 버튼이 이를 가져갑니다. `autoFocus`는 모든 컨트롤에서 `true`만 허용하므로, 이를 끄려면 해당 prop을 생략하십시오.

272 272 

273<h3 id="box-border-styles">

274 `Box` 테두리 스타일

275</h3>

276 

277`Box` 주위에 테두리를 그리려면 `borderStyle: 'round'`처럼 `borderStyle`을 다음 이름 중 하나로 설정하십시오. 각 행은 해당 이름에 대해 터미널이 그리는 내용을 설명하고 테두리의 위쪽 가장자리를 보여 줍니다.

278 

279| `borderStyle` | 터미널이 그리는 내용 | 위쪽 가장자리 |

280| :- | :- | :- |

281| `'single'` | 모서리가 각진 가는 선 | `┌──┐` |

282| `'double'` | 이중선 | `╔══╗` |

283| `'round'` | 모서리가 둥근 가는 선 | `╭──╮` |

284| `'bold'` | 굵은 선 | `┏━━┓` |

285| `'singleDouble'` | 위아래는 가는 선, 양옆은 이중선 | `╓──╖` |

286| `'doubleSingle'` | 위아래는 이중선, 양옆은 가는 선 | `╒══╕` |

287| `'classic'` | ASCII 문자 `+`, `-`, `\|` | `+--+` |

288| `'arrow'` | `Box` 안쪽을 가리키는 화살표 | `↘↓↓↙` |

289| `'dashed'` | 모서리가 비어 있는 점선 | `╌╌` |

290| `'quote'` | 왼쪽에 세로로 이어지는 막대 `▎`와 나머지 세 면의 빈 셀 | 빈칸 |

291 

292`borderStyle`에 `'rounded'`처럼 그 밖의 이름을 지정한 `Box`는 테두리 없이 그려집니다.

293 

273<h2 id="limits">294<h2 id="limits">

274 제한295 제한

275</h2>296</h2>

17 17 

18 * **범위, 캐시 및 우선순위가 작동하는 방식**: [플러그인 로딩 참조](/docs/ko/plugins/loading)를 읽습니다.18 * **범위, 캐시 및 우선순위가 작동하는 방식**: [플러그인 로딩 참조](/docs/ko/plugins/loading)를 읽습니다.

19 * **플래그, 필드 또는 명령 조회**: [플러그인 명령 참조](/docs/ko/plugins/cli-reference), [매니페스트 참조](/docs/ko/plugins/manifest-reference) 또는 [마켓플레이스 참조](/docs/ko/plugins/marketplace-reference)를 사용합니다.19 * **플래그, 필드 또는 명령 조회**: [플러그인 명령 참조](/docs/ko/plugins/cli-reference), [매니페스트 참조](/docs/ko/plugins/manifest-reference) 또는 [마켓플레이스 참조](/docs/ko/plugins/marketplace-reference)를 사용합니다.

20 * **`hooks module not loaded` 또는 `hooks module did not load` 메시지**: 해당 플러그인은 [mod](/docs/ko/plugins/mods/overview)이므로 [mod가 로드되지 않음](/docs/ko/plugins/mods/troubleshoot#the-mod-doesn’t-load)을 읽습니다.

20</Note>21</Note>

21 22 

22본 페이지에서 본 정확한 메시지를 검색합니다. 각 메시지는 이를 생성하는 단계 아래에 나열되며, 이는 항상 실행한 명령이 아닙니다. 예를 들어, 마켓플레이스가 누락되어 설치가 실패할 수 있으므로 해당 메시지는 [마켓플레이스 추가](#add-a-marketplace) 아래에 있습니다.23본 페이지에서 본 정확한 메시지를 검색합니다. 각 메시지는 이를 생성하는 단계 아래에 나열되며, 이는 항상 실행한 명령이 아닙니다. 예를 들어, 마켓플레이스가 누락되어 설치가 실패할 수 있으므로 해당 메시지는 [마켓플레이스 추가](#add-a-marketplace) 아래에 있습니다.

33 <Tab title="기본 설치 (권장)">33 <Tab title="기본 설치 (권장)">

34 **macOS, Linux, WSL:**34 **macOS, Linux, WSL:**

35 35 

36 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}36 ```bash theme={null}

37 curl -fsSL https://claude.ai/install.sh | bash37 curl -fsSL https://claude.ai/install.sh | bash

38 ```38 ```

39 39 

40 **Windows PowerShell:**40 **Windows PowerShell:**

41 41 

42 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}42 ```powershell theme={null}

43 irm https://claude.ai/install.ps1 | iex43 irm https://claude.ai/install.ps1 | iex

44 ```44 ```

45 45 

46 **Windows CMD:**46 **Windows CMD:**

47 47 

48 ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}48 ```batch theme={null}

49 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd49 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

50 ```50 ```

51 51 

63 </Tab>63 </Tab>

64 64 

65 <Tab title="Homebrew">65 <Tab title="Homebrew">

66 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}66 ```bash theme={null}

67 brew install --cask claude-code67 brew install --cask claude-code

68 ```68 ```

69 69 

75 </Tab>75 </Tab>

76 76 

77 <Tab title="WinGet">77 <Tab title="WinGet">

78 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}78 ```powershell theme={null}

79 winget install Anthropic.ClaudeCode79 winget install Anthropic.ClaudeCode

80 ```80 ```

81 81 

104 예제 스크립트104 예제 스크립트

105</h2>105</h2>

106 106 

107아래 스크립트는 `$CLAUDE_TEST_ENVIRONMENT_ID`에 대해 전체 루프를 실행합니다. 이는 테스트 환경의 `ccpool_...` ID이며, 관리 페이지의 환경 상세 대화상자에 표시되거나 [환경 생성 호출](#create-a-dedicated-test-environment)에서 반환됩니다. 각 응답의 센티널 구문을 어설션합니다. 캡처 훅이 설치되고 `E2E_REPLY_DIR`이 내보내진 이 호스트에서 러너를 시작한 후, 작업하려는 저장소의 git 체크아웃에서 실행합니다.107아래 스크립트는 `$CLAUDE_TEST_ENVIRONMENT_ID`에 대해 전체 루프를 실행합니다. 이는 테스트 환경의 `ccpool_...` ID이며, 관리 페이지의 환경 상세 대화상자에 표시되거나 [환경 생성 호출](#create-a-dedicated-test-environment)에서 반환됩니다. 각 응답의 센티널 구문을 어설션합니다. 캡처 훅이 설치되고 `E2E_REPLY_DIR`이 내보내진 이 호스트에서 러너를 시작한 후, 작업하려는 저장소의 git 체크아웃에서 실행합니다. 먼저 [CI에서 인증하기](#authenticate-from-ci)에 설명된 대로 스크립트를 실행하는 머신에서 claude.ai 계정으로 로그인합니다. 로그인하지 않으면 첫 번째 디스패치가 `Unable to get organization UUID for cloud session creation`과 같은 오류와 함께 실패합니다.

108 108 

109```bash theme={null}109```bash theme={null}

110#!/usr/bin/env bash110#!/usr/bin/env bash

43 <Step title="관리 콘솔 열기">43 <Step title="관리 콘솔 열기">

44 claude.ai 콘솔에서 [**조직 설정 > Claude Code > 관리형 설정**](https://claude.ai/admin-settings/claude-code)으로 이동합니다.44 claude.ai 콘솔에서 [**조직 설정 > Claude Code > 관리형 설정**](https://claude.ai/admin-settings/claude-code)으로 이동합니다.

45 45 

46 링크가 Claude Code 페이지 대신 다른 조직 설정 페이지로 리디렉션되면 계정에 필요한 역할이 없습니다. Admin 및 Owner가 아닌 기타 역할은 관리형 설정을 보거나 편집할 수 없으므로 조직의 Owner 또는 Primary Owner에게 변경을 요청하십시오. [액세스 제어](#access-control)를 참조하십시오.46 Team 또는 Enterprise 조직에서 페이지에 액세스 권한이 없다고 표시되면 [Owner 또는 Primary Owner](#access-control)에게 변경을 요청하십시오.

47 </Step>47 </Step>

48 48 

49 <Step title="설정 정의">49 <Step title="설정 정의">

83* 터미널: `claude --continue`, `claude --resume <session-id>` 또는 이름이 한 세션과 일치할 때 `-p` 없이 `claude --resume <name>`. Claude Code는 세션이 있던 권한 모드를 복원합니다. 단, 표의 경우는 제외됩니다. `--permission-mode` 또는 `--dangerously-skip-permissions`를 전달하여 복원된 모드를 재정의합니다.83* 터미널: `claude --continue`, `claude --resume <session-id>` 또는 이름이 한 세션과 일치할 때 `-p` 없이 `claude --resume <name>`. Claude Code는 세션이 있던 권한 모드를 복원합니다. 단, 표의 경우는 제외됩니다. `--permission-mode` 또는 `--dangerously-skip-permissions`를 전달하여 복원된 모드를 재정의합니다.

84* 비대화형: `claude -p --resume` 또는 `claude -p --continue`. Claude Code는 새로운 `claude -p` 실행이 시작될 권한 모드로 실행을 시작합니다. 단, 계획 모드에서 종료된 세션은 [아래 조건](#resume-in-plan-mode-with-p)에서 계획 모드로 재개됩니다.84* 비대화형: `claude -p --resume` 또는 `claude -p --continue`. Claude Code는 새로운 `claude -p` 실행이 시작될 권한 모드로 실행을 시작합니다. 단, 계획 모드에서 종료된 세션은 [아래 조건](#resume-in-plan-mode-with-p)에서 계획 모드로 재개됩니다.

85* VS Code: 확장의 대화 패널입니다. 표는 계획 모드에서 종료된 대화만 다룹니다. 나머지는 [과거 대화 재개](/docs/ko/vs-code#resume-past-conversations)를 참조하세요.85* VS Code: 확장의 대화 패널입니다. 표는 계획 모드에서 종료된 대화만 다룹니다. 나머지는 [과거 대화 재개](/docs/ko/vs-code#resume-past-conversations)를 참조하세요.

86* 시작 시 세션 선택기: `claude --resume` 단독, `claude --from-pr` 또는 이름이 여러 세션과 일치할 때 [세션 선택기](#use-the-session-picker)에서 선택한 세션입니다. Claude Code는 저장된 권한 모드를 복원하지 않습니다. 동일한 명령줄에서 새 세션을 시작할 권한 모드로 세션을 시작합니다.86* 시작 시 세션 선택기: `claude --resume` 단독, `claude --from-pr` 또는 여러 세션과 일치하는 이름 중 어느 방법으로 열었든 [세션 선택기](#use-the-session-picker)에서 선택한 세션입니다. Claude Code는 동일한 명령줄에서 새 세션을 시작할 권한 모드로 세션을 시작합니다. 단, 플랜 모드에서 종료된 세션은 `--permission-mode`, `--dangerously-skip-permissions` 또는 `--fork-session`을 전달하지 않는 한 플랜 모드로 재개됩니다. 그 외의 저장된 권한 모드는 복원되지 않습니다.

87* 세션 내 `/resume`(인수 있음 또는 없음): Claude Code는 저장된 권한 모드를 복원하지 않습니다. 전환하는 대화는 현재 세션이 있는 권한 모드에서 계속됩니다.87* 세션 내 `/resume`(인수 있음 또는 없음): 전환하는 대화는 현재 세션이 있는 권한 모드에서 계속됩니다. 단, 플랜 모드에서 종료된 대화는 `--permission-mode` 또는 `--dangerously-skip-permissions`로 Claude Code를 시작했더라도 플랜 모드로 재개됩니다. 해당 대화가 이번 Claude Code 실행에서 이미 열린 적이 있다면(예: 처음 시작한 대화나 `/clear` 또는 `/resume`으로 떠난 대화) 대신 현재 권한 모드에서 계속됩니다.

88 88 

89비대화형 및 VS Code 경로에서 계획 모드 복원은 Claude Code v2.1.246 이상이 필요합니다. 각 행은 세션이 종료된 권한 모드, 재개하는 터미널, 비대화형 및 VS Code 경로 중 어느 것인지, 그리고 Claude Code가 재개된 세션을 시작하는 권한 모드를 나타냅니다.89비대화형 및 VS Code 경로에서 계획 모드 복원은 Claude Code v2.1.246 이상이 필요합니다. 각 행은 세션이 종료된 권한 모드, 재개하는 터미널, 비대화형 및 VS Code 경로 중 어느 것인지, 그리고 Claude Code가 재개된 세션을 시작하는 권한 모드를 나타냅니다.

90 90 

91| 세션이 종료된 모드 | 재개 방식 | 재개 후 권한 모드 |91| 세션이 종료된 모드 | 재개 방식 | 재개 후 권한 모드 |

92| :- | :- | :- |92| :- | :- | :- |

93| `bypassPermissions` | 터미널 | 새 세션이 시작될 권한 모드입니다. [권한을 다시 우회](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)하려면 시작 시 해당 플래그 중 하나 또는 [사용자, `--settings` 또는 관리 설정](/docs/ko/settings-reference#permissions-defaultmode)의 `permissions.defaultMode: "bypassPermissions"`로 활성화합니다 |93| `bypassPermissions` | 터미널 | 새 세션이 시작될 권한 모드입니다. [권한을 다시 우회](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)하려면 시작 시 해당 플래그 중 하나 또는 [사용자, `--settings` 또는 관리 설정](/docs/ko/settings-reference#permissions-defaultmode)의 `permissions.defaultMode: "bypassPermissions"`로 활성화합니다 |

94| `plan` | 터미널 | 새 세션이 시작될 권한 모드입니다 |94| `plan` | 터미널 | 플랜 모드입니다. `--fork-session`을 사용하면 새 세션이 시작될 권한 모드입니다 |

95| `auto` | 터미널 | `auto`(계정이 여전히 [자동 모드 요구 사항](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)을 충족하는 경우에만) |95| `auto` | 터미널 | `auto`(계정이 여전히 [자동 모드 요구 사항](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)을 충족하는 경우에만) |

96| Manual | 터미널 | 새 세션이 [기본 제공 기본값](/docs/ko/permission-modes#which-mode-a-session-starts-in)에서 자동 모드로 시작될 때 수동입니다. 설정 파일의 `defaultMode`가 [적용](/docs/ko/permission-modes#which-mode-a-session-starts-in)되면 Claude Code는 재개된 세션을 해당 모드로 시작합니다 |96| Manual | 터미널 | 새 세션이 [기본 제공 기본값](/docs/ko/permission-modes#which-mode-a-session-starts-in)에서 자동 모드로 시작될 때 수동입니다. 설정 파일의 `defaultMode`가 [적용](/docs/ko/permission-modes#which-mode-a-session-starts-in)되면 Claude Code는 재개된 세션을 해당 모드로 시작합니다 |

97| `plan` | 비대화형([아래 조건](#resume-in-plan-mode-with-p)에서) | 계획 모드 |97| `plan` | 비대화형([아래 조건](#resume-in-plan-mode-with-p)에서) | 계획 모드 |

310 310 

311| 필드 | 필수 | 설명 |311| 필드 | 필수 | 설명 |

312| :- | :- | :- |312| :- | :- | :- |

313| `name` | 예 | `code-reviewer` 또는 `reviewer-v2`와 같은 고유 식별자. [Hooks](/docs/ko/hooks#subagentstart)는 이 값을 `agent_type`으로 받습니다. 파일 이름이 일치할 필요는 없습니다. 이름은 `:`를 포함할 수 없습니다. `:`는 `my-plugin:reviewer`와 같은 [플러그인 범위 식별자](/docs/ko/plugins/overview)에 예약되어 있습니다. Claude Code는 이름을 포함하는 파일을 로드하지 않고 디버그 로그에 오류를 기록합니다. v2.1.218 이전에는 이러한 이름이 허용되었습니다 |313| `name` | 예 | `code-reviewer` 또는 `reviewer-v2`와 같은 최대 256자의 고유 식별자. [훅](/docs/ko/hooks#subagentstart)은 이 값을 `agent_type`으로 받습니다. 파일 이름이 일치할 필요는 없습니다. 이름은 `:`를 포함할 수 없습니다. `:`는 `my-plugin:reviewer`와 같은 [플러그인 범위 식별자](/docs/ko/plugins/overview)에 예약되어 있습니다 |

314| `description` | 예 | Claude가 이 서브에이전트에 위임해야 할 때 |314| `description` | 예 | Claude가 이 서브에이전트에 위임해야 할 때 |

315| `tools` | 아니오 | 서브에이전트가 사용할 수 있는 [도구](#available-tools). `Read, Grep, Bash`와 같은 쉼표로 구분된 문자열 또는 YAML 목록입니다. 생략하면 서브에이전트가 사용 가능한 모든 도구를 상속합니다. 목록의 항목이 도구로 확인되지 않으면, 서브에이전트는 일반적으로 항목을 이름 지정하는 오류로 [시작에 실패](/docs/ko/errors#agent-would-be-spawned-with-zero-tools)합니다. 스킬을 컨텍스트에 미리 로드하려면 여기에 `Skill`을 나열하는 대신 `skills` 필드를 사용하세요 |315| `tools` | 아니오 | 서브에이전트가 사용할 수 있는 [도구](#available-tools). `Read, Grep, Bash`와 같은 쉼표로 구분된 문자열 또는 YAML 목록입니다. 생략하면 서브에이전트가 사용 가능한 모든 도구를 상속합니다. 목록의 항목이 도구로 확인되지 않으면, 서브에이전트는 일반적으로 항목을 이름 지정하는 오류로 [시작에 실패](/docs/ko/errors#agent-would-be-spawned-with-zero-tools)합니다. 스킬을 컨텍스트에 미리 로드하려면 여기에 `Skill`을 나열하는 대신 `skills` 필드를 사용하세요 |

316| `disallowedTools` | 아니오 | 거부할 도구. 상속되거나 지정된 목록에서 제거됩니다. `tools`와 동일한 형식입니다. `Bash(git push *)`와 같은 지정자가 있는 항목은 여전히 [전체 도구를 제거합니다](#available-tools) |316| `disallowedTools` | 아니오 | 거부할 도구. 상속되거나 지정된 목록에서 제거됩니다. `tools`와 동일한 형식입니다. `Bash(git push *)`와 같은 지정자가 있는 항목은 여전히 [전체 도구를 제거합니다](#available-tools) |

348 348 

349* **`name` 없음**: Claude Code는 파일을 에이전트 옆에 보관된 문서로 취급합니다.349* **`name` 없음**: Claude Code는 파일을 에이전트 옆에 보관된 문서로 취급합니다.

350* **파일의 첫 번째 줄이 아닌 여는 `---`**: Claude Code는 파일을 프론트매터가 없는 것으로 읽고 문서로 취급합니다.350* **파일의 첫 번째 줄이 아닌 여는 `---`**: Claude Code는 파일을 프론트매터가 없는 것으로 읽고 문서로 취급합니다.

351* **`-`로 시작하거나 `:`를 포함하는 `name`**: Claude Code는 파일을 건너뛰고 디버그 로그에 오류를 씁니다. 위의 `name` 행을 참조하세요.351* **`-`로 시작하거나, `:`를 포함하거나, 256자보다 긴 `name`**: Claude Code는 파일을 건너뛰고 디버그 로그에 오류를 기록합니다.

352* **`name`이지만 `description` 없음**: Claude Code는 파일을 건너뛰고 이유를 디버그 로그에 씁니다.352* **`name`이지만 `description` 없음**: Claude Code는 파일을 건너뛰고 이유를 디버그 로그에 씁니다.

353* **파싱되지 않는 YAML**: Claude Code는 파일에서 필드를 읽지 않고, 건너뛰고, 파싱 오류를 디버그 로그에 씁니다.353* **파싱되지 않는 YAML**: Claude Code는 파일에서 필드를 읽지 않고, 건너뛰고, 파싱 오류를 디버그 로그에 씁니다.

354 354 

606| `environmentVariables` | `[]` | Claude 프로세스에 대한 환경 변수를 설정합니다. 공유 구성의 경우 Claude Code 설정을 대신 사용합니다. [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars) 항목은 값이 절대 경로인 경우에만 적용됩니다. 확장 프로그램은 `~`를 확장하지 않으며 상대 경로 값은 무시합니다. |606| `environmentVariables` | `[]` | Claude 프로세스에 대한 환경 변수를 설정합니다. 공유 구성의 경우 Claude Code 설정을 대신 사용합니다. [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars) 항목은 값이 절대 경로인 경우에만 적용됩니다. 확장 프로그램은 `~`를 확장하지 않으며 상대 경로 값은 무시합니다. |

607| `disableLoginPrompt` | `false` | 인증 프롬프트 건너뛰기(타사 공급자 설정의 경우) |607| `disableLoginPrompt` | `false` | 인증 프롬프트 건너뛰기(타사 공급자 설정의 경우) |

608| `allowDangerouslySkipPermissions` | `false` | 모드 선택기에 권한 무시를 추가합니다. 인터넷 접근이 없는 샌드박스에서만 사용합니다. |608| `allowDangerouslySkipPermissions` | `false` | 모드 선택기에 권한 무시를 추가합니다. 인터넷 접근이 없는 샌드박스에서만 사용합니다. |

609| `claudeProcessWrapper` | - | Claude 프로세스를 실행하는 데 사용되는 실행 파일입니다. 번들된 바이너리 경로는 존재할 때 인수로 전달됩니다. 확장 프로그램 빌드가 플랫폼에 포함되지 않은 경우 별도로 설치된 `claude` 바이너리로 설정합니다. 래핑된 설정에서는 `initialPermissionMode`를 설정하거나 이전 대화에서 Manual, Edit automatically 또는 Auto를 선택하지 않는 한 대화가 Manual 모드에서 시작됩니다. 확장 프로그램이 설정 및 기본 제공 기본값 단계를 건너뛰기 때문입니다. [권한 모드 전환](/docs/ko/permission-modes#switch-permission-modes)을 참조하세요. 활성화 시 "Unsupported platform" 오류는 플랫폼에 번들된 바이너리가 없음을 의미합니다. [어떤 플랫폼에 미리 빌드된 바이너리가 있는지](/docs/ko/troubleshoot-install#native-binary-not-found-after-npm-install) 참조하세요. |609| `claudeProcessWrapper` | - | Claude 프로세스를 실행하는 데 사용되는 실행 파일입니다. 번들된 바이너리 경로는 존재할 때 인수로 전달됩니다. 확장 프로그램 빌드에 해당 플랫폼용 바이너리가 포함되어 있지 않은 경우 별도로 설치된 `claude` 바이너리로 설정합니다. |

610 610 

611<h2 id="use-a-screen-reader">611<h2 id="use-a-screen-reader">

612 화면 읽기 프로그램 사용612 화면 읽기 프로그램 사용

6 6 

7> git worktree에서 병렬 Claude Code 세션을 격리하여 변경 사항이 충돌하지 않도록 합니다. `--worktree` 플래그, 서브에이전트 격리, `.worktreeinclude`, 정리 및 비git VCS 훅을 다룹니다.7> git worktree에서 병렬 Claude Code 세션을 격리하여 변경 사항이 충돌하지 않도록 합니다. `--worktree` 플래그, 서브에이전트 격리, `.worktreeinclude`, 정리 및 비git VCS 훅을 다룹니다.

8 8 

9[git worktree](https://git-scm.com/docs/git-worktree)는 자체 파일과 브랜치를 가진 별도의 작업 디렉토리이며, 메인 체크아웃과 동일한 저장소 히스토리 및 원격을 공유합니다. 각 Claude Code 세션을 자체 worktree에서 실행하면 한 세션의 편집이 다른 세션의 파일을 건드리지 않으므로, 한 세션이 기능을 구축하는 동안 두 번째 세션이 버그를 수정할 수 있습니다.9[git worktree](https://git-scm.com/docs/git-worktree)는 자체 파일과 브랜치를 가진 별도의 작업 디렉터리이며, 메인 체크아웃과 동일한 저장소 히스토리 및 원격을 공유합니다. 각 Claude Code 세션을 자체 worktree에서 실행하면 세션마다 편집할 파일의 별도 사본이 주어지므로, 한 세션이 기능을 구축하는 동안 두 번째 세션이 버그를 수정할 수 있습니다.

10 10 

11<Note>11<Note>

12 Worktree는 git 저장소가 필요합니다. 다른 버전 관리 시스템의 경우 [훅을 구성하여 git 로직을 대체](#non-git-version-control)합니다. [데스크톱 앱](/docs/ko/desktop#work-in-parallel-with-sessions)에서는 세션을 시작할 때 **worktree** 옵션을 선택하여 자체 worktree를 제공합니다.12 Worktree는 git 저장소가 필요합니다. 다른 버전 관리 시스템의 경우 [훅을 구성하여 git 로직을 대체](#non-git-version-control)합니다. [데스크톱 앱](/docs/ko/desktop#work-in-parallel-with-sessions)에서는 세션을 시작할 때 **worktree** 옵션을 선택하여 자체 worktree를 제공합니다.

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)와 규칙에 따라 달라집니다.

108 

107확인은 Claude Code를 실행한 저장소에 적용됩니다. 또한 연결된 worktree가 연결된 메인 체크아웃도 포함합니다. PowerShell 명령의 경우 Claude Code는 작업 디렉토리 확인만 적용합니다.109확인은 Claude Code를 실행한 저장소에 적용됩니다. 또한 연결된 worktree가 연결된 메인 체크아웃도 포함합니다. PowerShell 명령의 경우 Claude Code는 작업 디렉토리 확인만 적용합니다.

108 110 

109Claude는 각 거부를 worktree의 이름을 지정하고 진행 방법을 설명하는 도구 오류로 봅니다. 거부된 명령의 경우 [거부 메시지의 의미와 이를 해결하는 방법](/docs/ko/errors#command-blocked-by-the-worktree-isolation-checks)을 참조하세요.111Claude는 각 거부를 worktree의 이름을 지정하고 진행 방법을 설명하는 도구 오류로 봅니다. 거부된 명령의 경우 [거부 메시지의 의미와 이를 해결하는 방법](/docs/ko/errors#command-blocked-by-the-worktree-isolation-checks)을 참조하세요.